一、为什么要做这个工具？
写 Elasticsearch DSL 是个体力活。我在生产环境中经常遇到这些问题：
手写 DSL 容易出错
括号对不齐、字段名写错、语法记不清，调试半天才发现少了个逗号。
翻官方文档太慢
每次都要查 bool query 怎么写、aggs 怎么嵌套，文档翻来翻去效率低。
复杂查询难调试
多层嵌套的聚合，写完自己都看不懂，改一个地方可能影响全局。
市面上虽然有些转换工具，但都有个致命问题：不能保证生成的 DSL 100% 正确。
于是我写了这个工具，核心思路就一条：生成后立即 Elasticsearch 或者 Easysearch 验证，错了就重新生成。
二、整体设计思路
2.1 核心流程
整个工具的工作流程很清晰：
用户输入自然语言 → 调用 DeepSeek API 生成 DSL → 在本地 Elasticsearch 上验证 → 验证通过就返回 → 验证失败就把错误信息反馈给 DeepSeek 重新生成 → 最多迭代 5 次确保成功
这个流程的关键在于本地验证。
很多工具只管生成，不管对不对。
我这个工具会创建临时索引、写入测试数据、真实执行 DSL，确保能跑通才返回给用户。
2.2 技术选型
后端用 Flask，轻量够用，不需要重框架。
LLM 选 DeepSeek API，性价比高，调用成本是 OpenAI 的十分之一，对于这种需要多次调用的场景很划算。
搜索引擎用 Elasticsearch 9.0+，也兼容 Easysearch 2.0+。
https://www.infinilabs.cn/
前端直接用原生 HTML/CSS/JS 加 CodeMirror 编辑器，没用 React、Vue，就是为了让代码简单直接。
Easysearch UI vs Kibana——可视化工具选型指南
三、四大核心功能
3.1 自然语言转 DSL
这是整个系统的核心。用户输入类似"查询包含测试的文档"这样的描述，系统会调用 DeepSeek API 生成标准的 Elasticsearch DSL。 Prompt 设计很关键。我花了不少时间调优 Prompt，核心要点是：
明确告诉模型只输出 JSON 格式，不要任何解释文字
不要用 Markdown 代码块包裹
指定 Elasticsearch 版本（避免使用废弃语法）
提供常见查询模式作为参考
实测下来，这样配置的 Prompt，首次生成准确率能到 95% 以上。
3.2 本地验证机制
这是保证 100% 正确的核心功能。验证流程分四步：
第一步：创建临时测试索引。
索引名用时间戳生成，比如 text2dsl_test_1705234567，避免冲突。
第二步：定义 Mapping。
预设常用字段类型：text、keyword、integer、double、boolean、date。这样能覆盖大部分查询场景。
第三步：写入测试数据。
自动生成 3-5 条样例数据，包含各种字段类型的值，确保查询有数据可以匹配。
第四步：执行 DSL。
真实调用 Elasticsearch、Easysearch 的 search API，捕获执行结果或错误信息。无论成功失败，最后都会删除临时索引。
这套机制的好处是，生成的 DSL 如果有任何语法错误、字段类型不匹配、逻辑问题，都会被立即发现。
3.3 迭代优化流程
如果验证失败，系统会自动进入优化循环。
把错误信息（比如"field [count] is not sortable"）反馈给 DeepSeek，让它根据错误修复 DSL。
一般 1-2 次迭代就能成功。实际使用中遇到过最复杂的查询，迭代了 3 次才通过。
设置最大迭代次数为 5 次，避免死循环，也控制 API 调用成本。
每次迭代都会记录下来，用户可以看到 DSL 是如何一步步优化的，这对学习 Elasticsearch 也有帮助。
3.4 前端界面
界面分四个区域：
输入区：一个文本框输入自然语言描述，一个下拉框选择操作类型（查询或聚合），一个生成按钮。
DSL 展示区：用 CodeMirror 编辑器展示生成的 DSL，支持 JSON 语法高亮和格式化。
结果展示区：显示 Elasticsearch 的执行结果，也是 JSON 格式，便于查看命中了哪些文档、聚合统计数据等。
迭代历史区：展示优化过程，显示迭代次数和每次优化的原因。
整个界面响应式设计，PC 和移动端都能用。
四、实际使用案例
案例 1：基础查询
输入："查询标题包含 Elasticsearch 的文档"
生成的 DSL 是标准的 match 查询，验证通过，0 次迭代。
这种简单查询基本一次就能生成正确。
案例 2：组合查询
输入："查找标题包含"测试"且浏览次数大于100的文档"
案例 3：多条件OR组合 + 排序
输入：查找作者是"张三"或"李四"的文档，按发布时间倒序排列
POST text2dsl_test_1769781798/_search{ "query": { "bool": { "should": [ { "term": { "author": "张三" } }, { "term": { "author": "李四" } } ] } }, "sort": [ { "publish_time": { "order": "desc" } } ]}案例 4：复杂嵌套逻辑 + 聚合 + 脚本字段 + 分页
测试用例：查找满足以下条件的文档：
查找标题包含"测试"或"验证"，
且状态为"已发布"，
且浏览次数大于100的文档。
按浏览次数降序排列，
每页显示10条，取第2页，
统计每个分类的文档数量。
这种复杂查询能自动修复，确实省了不少调试时间。
POST text2dsl_test_1769784751/_search{ "query": { "bool": { "must": [ { "match": { "title": "测试" } }, { "term": { "status": "已发布" } }, { "range": { "views": { "gt": 100 } } } ] } }, "sort": [ { "views": { "order": "desc" } } ], "from": 10, "size": 10, "aggs": { "category_count": { "terms": { "field": "category" } } }}五、踩过的坑
坑 1：DeepSeek 输出带 Markdown 包裹
虽然在 Prompt 里明确说了"不要用代码块包裹"，但偶尔还是会输出带反引号的内容。
解决方法是在代码里做清理，去掉反引号和 json 标记，再解析 JSON。
坑 2：测试索引未删除导致冲突
早期版本验证失败时，测试索引没删除干净，下次创建同名索引会报错。
现在用时间戳生成唯一索引名，加上异常处理确保无论成功失败都会删除索引。
坑 3：聚合查询忘记设置 size
早期版本生成的聚合查询经常忘记设置 size: 0，导致返回大量文档内容。
在 Prompt 里加了专门提示："聚合查询如果只需要聚合结果，设置 size: 0"。现在这个问题基本不会出现。
六、使用效果
实际使用下来，准确率基本能到 95% 以上。剩下 5% 需要 1-2 次迭代优化。
对于常见的 match、term、range、bool 查询，基本一次生成就能用。
对于复杂的嵌套聚合、多条件组合查询，可能需要迭代 1-2 次。
效率提升至少 3 倍。以前写一个复杂查询可能要 5-10 分钟（翻文档、写代码、调试），现在 1-2 分钟就搞定。
对于不熟悉 Elasticsearch 的同学，比如产品经理、项目经理等使用这个工具更有价值。直接说需求，工具帮你生成标准 DSL，还能学习 ES 的查询语法。
七、后续规划
7.1 DSL 模板库
积累常见查询模式，用户可以直接选择模板修改。
7.2 历史查询保存
记录用户的查询历史，方便复用和分享。
7.3 代码导出功能
除了 JSON 格式，还能导出 Python、Java、curl 等语言的调用代码。
八、总结
这个工具的核心价值是：生成 + 验证。
生成 DSL 靠 DeepSeek API，验证 DSL 靠本地 Elasticsearch，迭代优化保证 100% 正确。
对于经常写 Elasticsearch 查询的同学，这个工具能显著提升效率。不用再翻文档，不用再调试 JSON 格式，直接说人话就行。
工具已经在团队内部使用了 2 个月，反馈都很不错。代码优化后会发布到知识星球，欢迎试用反馈。
基于 Easysearch + Flip 的多模态图像搜索引擎系统实战指南
打造你的企业级智能文档问答系统——Everything plus RAG 实战指南
)
)
)
