1. 为什么“最好的 LLM 也只有 59% 正确率”这件事值得单独聊第一次看到“最好的 LLM 只有 59% 的时间能写出正确的 ES|QL”这个结论时我的反应不是惊讶而是“终于有人把这件事量化出来了”。过去一年多我一直在做 Text-to-SQL 相关的落地项目从最早的 MySQL、PostgreSQL 到后来的 ClickHouse、Elasticsearch踩过的坑基本能写一本小册子。而 ES|QL 这个场景恰恰是所有 SQL 方言里最容易被大模型“自信地写错”的一类。先把结论摆在前面59% 这个数字不是模型能力的天花板而是“通用 LLM 零上下文 单轮生成”这套组合的天花板。换句话说如果你直接把用户问题丢给 GPT-4 或 Claude让它凭空写一段 ES|QL能对一半多一点已经是超常发挥了。剩下那 41% 的错误绝大多数不是模型“不会写 SQL”而是它根本不了解 ES|QL 这套 DSL 的语法约束、字段语义和索引结构。这篇文章我想聊的不是“哪个模型最强”而是把这 41% 的错误拆开来看它们到底错在哪、为什么会错、以及一个工程化的 Text-to-ES|QL 系统应该怎么设计才能把正确率从 59% 拉到 90% 以上。内容会覆盖 ES|QL 的语法特性、LOOKUP JOIN 的坑、Schema 注入策略、Few-shot 设计、结果校验与重试机制以及我自己在项目里验证过的一些参数和配置。适合正在做 LLM Elasticsearch 结合、或者准备把自然语言查询接入 ES 的同学参考小白也能看懂因为我会尽量用生活化的类比把原理讲清楚。2. ES|QL 到底特殊在哪先搞懂它和标准 SQL 的差异2.1 ES|QL 不是 SQL它是“管道式查询语言”很多人第一次接触 ES|QL会下意识把它当成“Elasticsearch 版的 SQL”。这个认知是 41% 错误的第一大来源。ES|QL 的全称是 Elasticsearch Query Language它的设计哲学和标准 SQL 完全不同——它是**管道式piped**的数据从左边流到右边每一步用|连接。举个最直观的例子。标准 SQL 里你要先SELECT ... FROM ... WHERE ... GROUP BY ... ORDER BY ...子句顺序是固定的。而 ES|QL 是这样写的FROM logs-2024.01.* | WHERE status_code 500 | STATS error_count COUNT(*) BY service.name | SORT error_count DESC | LIMIT 10看到区别了吗没有 SELECT没有 FROM 后面跟子查询聚合用 STATS 而不是 GROUP BY排序字段直接跟在 SORT 后面。这套语法对熟悉 Unix 管道的人来说很自然但对训练语料里 99% 都是标准 SQL 的 LLM 来说就是“方言污染”的重灾区。我实测过一个很典型的案例让模型写“统计每个服务的错误数并排序”十个模型里有七个会写成SELECT service.name, COUNT(*) FROM logs WHERE status_code 500 GROUP BY service.name ORDER BY COUNT(*) DESC。语法上完全正确但 ES|QL 根本不认。这就是那 41% 里占比最高的一类错误——语法迁移错误。2.2 字段引用、时间范围和索引模式的三重陷阱除了语法结构ES|QL 在三个细节上和标准 SQL 差异极大而这三个细节恰好是 LLM 最容易翻车的地方。第一是字段引用。标准 SQL 里字段名带点号通常需要引号比如service.name。ES|QL 里点号字段是原生支持的service.name直接写就行但如果你写成service_name或者加反引号就会报字段不存在。模型经常在“要不要加引号”这件事上反复横跳。第二是时间范围。标准 SQL 用WHERE timestamp 2024-01-01ES|QL 更推荐用timestamp配合NOW() - 1 day这种相对时间表达式而且时间字段的命名在不同索引里可能是timestamp、timestamp、event_time模型如果不知道具体索引的 mapping基本靠猜。第三是索引模式。ES|QL 的FROM后面跟的是索引模式index pattern可以是logs-*、logs-2024.01.*这种通配符也可以是具体索引名。模型经常把表名和索引名搞混写出FROM logs_table这种在 ES 里根本不存在的引用。提示如果你在做 Text-to-ES|QLSchema 信息里必须明确告诉模型“这是索引模式不是表名”“时间字段叫什么”“点号字段不需要引号”否则这三类错误会反复出现。2.3 LOOKUP JOINES|QL 里最容易写错的高级特性热词里出现了 LOOKUP JOIN这确实是 ES|QL 的一个特色功能也是错误率最高的语法点之一。标准 SQL 的 JOIN 是JOIN ... ON ...而 ES|QL 的 LOOKUP JOIN 语法是这样的FROM logs-* | LOOKUP JOIN service_metadata ON service.name | WHERE team platform注意几个关键点LOOKUP JOIN 后面直接跟索引名没有 ON 关键字后面的等号表达式而是直接写关联字段。而且 LOOKUP JOIN 是左连接语义右表必须是 lookup 类型的索引。我见过太多模型写成LOOKUP JOIN service_metadata ON logs.service.name service_metadata.service.name这在 ES|QL 里是语法错误。更麻烦的是LOOKUP JOIN 对字段类型有要求关联字段必须是 keyword 类型如果是 text 类型会直接报错。模型不知道你的 mapping写出来的 JOIN 十有八九跑不通。这也是为什么我在项目里会把 LOOKUP JOIN 单独做成一个“高风险语法”在 Prompt 里给出明确的模板和反例。3. 那 41% 的错误到底错在哪六类高频错误拆解3.1 语法迁移错误把 SQL 习惯带进 ES|QL这是占比最高的一类我粗略统计过自己项目里的失败样本大约 35% 属于这一类。典型表现包括用 SELECT 而不是 FROM 开头、用 GROUP BY 而不是 STATS、用 ORDER BY 而不是 SORT、用 LIMIT 位置放错、子查询写法完全不兼容。有意思的是这类错误和模型规模关系不大。我对比过 7B 和 70B 的模型在“知道 ES|QL 语法”这件事上大模型并没有明显优势因为它们训练语料里 ES|QL 的样本本来就少。真正拉开差距的是是否在 Prompt 里给了足够的语法示例。3.2 字段幻觉编造不存在的字段名第二大类是字段幻觉占比大约 25%。模型会根据问题“合理推测”字段名比如问“统计每个用户的订单金额”它会写STATS total SUM(order.amount) BY user.id但你的索引里可能根本没有order.amount这个字段实际叫order_amount或者transaction.value。这类错误的根源是Schema 信息缺失。如果你只给模型一个索引名它只能靠猜。解决办法很简单也很有效把索引的 mapping 精简后注入 Prompt只保留字段名、类型和一句话描述。我实测下来光是加上 Schema 注入字段幻觉类错误能下降 60% 以上。3.3 时间语义错误相对时间和时区处理第三类是时间处理占比约 15%。ES|QL 里NOW()返回的是 UTC 时间如果你的业务数据是本地时区直接比较会差 8 小时。模型经常写出WHERE timestamp NOW() - 1 day这种看似正确但时区不对的查询。还有一个坑是日期格式。ES|QL 的日期字面量推荐用TO_DATETIME(2024-01-01T00:00:00Z)这种显式转换而不是直接写字符串。模型经常偷懒写WHERE timestamp 2024-01-01在某些版本上能跑在某些版本上直接报类型错误。3.4 聚合与分组错误STATS 的用法细节ES|QL 的 STATS 支持多字段聚合、条件聚合、百分位等高级功能但语法和标准 SQL 差异很大。比如计算 P95 延迟标准 SQL 可能是PERCENTILE_CONT(0.95)ES|QL 是PERCENTILE(latency, 95)。再比如条件计数ES|QL 用COUNT(*) WHERE status 500这种写法而不是SUM(CASE WHEN ...)。这类错误占比约 10%但排查起来最费劲因为语法看起来“差不多对”跑出来的结果却是错的属于静默错误比直接报错更危险。3.5 LOOKUP JOIN 关联错误字段类型和连接语义前面提过的 LOOKUP JOIN单独拿出来说是因为它的错误率实在太高。我统计过凡是涉及 JOIN 的查询首次生成正确率不到 30%。主要问题有三个关联字段类型不匹配、ON 后面写法错误、以及不知道 LOOKUP JOIN 只能左连接。3.6 结果校验缺失模型不知道自己错了最后一类也是最隐蔽的模型生成了一段语法正确、能跑通、但结果不符合用户意图的查询。比如用户问“最近一周的销售额”模型写成了“最近一周的订单数”。这类错误占比约 15%而且单靠语法校验发现不了必须引入语义校验或者让用户确认。下面这张表是我整理的六类错误速查表方便你对照排查错误类型占比典型表现核心解法语法迁移错误35%用 SELECT/GROUP BYPrompt 注入 ES字段幻觉25%编造字段名Schema 注入 字段白名单时间语义错误15%时区、日期格式明确时间字段和时区规则聚合分组错误10%STATS 用法错误提供聚合函数对照表LOOKUP JOIN 错误10%ON 写法、类型不匹配单独模板 类型校验语义偏差15%结果对但意图错语义校验 用户确认注意占比加起来超过 100% 是因为部分样本同时命中多类错误实际统计时按主因归类。4. 把正确率从 59% 拉到 90%我的工程化方案4.1 核心思路不要让模型“裸写”要给它搭脚手架我试过很多方案最后发现最有效的不是换更强的模型而是改变整个生成流程。裸写 ES|QL 就像让一个刚学外语的人直接写作文正确率当然低。正确的做法是把它拆成“理解意图 → 检索 Schema → 生成草稿 → 语法校验 → 执行验证 → 失败重试”这样一条流水线。这套思路的核心是把 LLM 不擅长的事情记语法、记字段交给外部系统把 LLM 擅长的事情理解自然语言意图留给模型。下面我分几个关键环节讲具体怎么做。4.2 Schema 注入只给模型“够用”的信息Schema 注入不是把整个 mapping 塞进去那样 token 爆炸而且噪音太多。我的做法是三步精简第一步只保留查询可能用到的字段。通过一个轻量的字段检索模块可以用 BM25 或者向量检索根据用户问题召回 Top 20 相关字段。第二步字段描述用一句话说清楚。比如status_code: integer, HTTP 响应状态码5xx 表示服务端错误。这句话比单纯给类型有用得多模型能据此判断该用 500还是 error。第三步明确标注特殊字段。时间字段、关联字段、lookup 索引都要单独标记。我通常会在 Prompt 里加一段索引: logs-* 时间字段: timestamp (UTC) 关联字段: service.name (keyword) 可用 lookup 索引: service_metadata (关联字段 service.name)实测下来这套 Schema 注入能让字段幻觉类错误下降 60% 到 70%。4.3 Few-shot 设计示例要“少而精”覆盖高频模式Few-shot 不是越多越好。我试过塞 20 个示例结果模型反而被干扰正确率不升反降。后来精简到 5 到 8 个每个都覆盖一类高频查询模式效果最好。示例的选择有讲究必须包含至少一个 STATS 聚合、一个 LOOKUP JOIN、一个时间范围过滤、一个 SORT LIMIT。这四类覆盖了 80% 的实际查询。另外每个示例最好配一个“反例”告诉模型“这样写是错的”。比如正确: FROM logs-* | STATS cnt COUNT(*) BY service.name 错误: SELECT service.name, COUNT(*) FROM logs GROUP BY service.name反例的作用比正例还大因为它直接切断了模型的 SQL 迁移路径。4.4 语法校验与自动重试把错误挡在执行之前生成完 ES|QL 后不要直接执行先过一遍校验。我的校验分三层第一层是语法解析。ES|QL 有官方的解析器可以直接调用验证语法。这一步能拦下 35% 的语法迁移错误。第二层是字段白名单校验。把生成的查询里所有字段提取出来和 Schema 里的字段列表比对不在白名单里的直接标记为可疑。第三层是类型校验。检查聚合函数和字段类型是否匹配比如对 text 字段做 SUM 就是错的。校验失败后把错误信息回传给模型让它重新生成。我实测下来一次重试能把正确率提升 15 到 20 个百分点两次重试后基本收敛。重试的 Prompt 要包含原始问题、上一次的错误查询、以及具体的错误信息这样模型才能针对性修正。4.5 执行验证与结果合理性检查语法过了不代表结果对。我还会做一层执行验证先加LIMIT 1跑一下确认能返回数据再跑完整查询。如果返回空结果要区分是“真的没数据”还是“查询条件写错了”。这里有个小技巧对时间范围查询先跑一个宽范围确认有数据再逐步收窄。比如用户问“最近一小时”先跑“最近一天”确认索引里有数据再收窄到一小时。这样能避免因为时间字段写错导致空结果。5. 实操全流程从用户问题到可执行 ES|QL5.1 完整流程拆解我把整个流程拆成七个步骤每一步都有明确的输入输出和校验点意图识别判断用户问题是查询、聚合还是关联查询决定用哪种模板。字段召回根据问题检索相关字段生成精简 Schema。Prompt 组装把 Schema、Few-shot、语法规则拼成完整 Prompt。首次生成调用 LLM 生成 ES|QL 草稿。语法校验解析器验证失败则带错误重试。字段与类型校验白名单比对失败则重试。执行验证LIMIT 1 试跑空结果则调整时间范围重试。这套流程听起来复杂但实际工程里就是几个函数串起来核心代码量不大。关键是每一步都要有明确的失败处理逻辑不能让它静默失败。5.2 关键参数与配置我在项目里用到的几个关键参数直接给出来供参考Few-shot 数量5 到 8 个超过 10 个效果下降。Schema 字段数Top 20超过 30 个 token 成本上升明显且噪音增加。重试次数最多 2 次第 3 次基本无收益。温度参数生成 ES|QL 时用 0 到 0.2不要用高温度会引入随机语法错误。超时设置单次生成 10 秒重试总时长不超过 30 秒。这些参数不是拍脑袋定的是我在几百个测试样本上反复调出来的。不同模型可能略有差异但量级上差不多。5.3 一个完整的生成示例假设用户问“帮我查一下最近一天每个服务的 5xx 错误数按错误数降序排前 10。”经过意图识别聚合查询、字段召回service.name、status_code、timestamp组装出的 Prompt 大致是你是 ES|QL 专家。根据以下 Schema 生成查询。 索引: logs-* 字段: - timestamp: date, 日志时间 (UTC) - service.name: keyword, 服务名 - status_code: integer, HTTP 状态码 规则: 1. 用 FROM 开头不要用 SELECT 2. 聚合用 STATS不要用 GROUP BY 3. 排序用 SORT不要用 ORDER BY 4. 时间用 NOW() - 1 day 示例: FROM logs-* | WHERE status_code 500 | STATS cnt COUNT(*) BY service.name | SORT cnt DESC | LIMIT 10 问题: 最近一天每个服务的 5xx 错误数降序前 10模型生成的查询基本就是这个示例的变体正确率很高。你看关键不是模型多强而是 Prompt 里把该说的都说清楚了。6. 常见问题与排查技巧实录6.1 模型总是用 SELECT 开头怎么办这是最高频的问题。我的解法是在 Prompt 最前面加一句强约束“ES|QL 没有 SELECT 关键字所有查询必须以 FROM 开头。”并且给一个反例。如果还不行就在后处理阶段做一次字符串替换把开头的 SELECT 相关子句重写成 FROM 形式。不过后处理只能救急根治还是要靠 Prompt。6.2 LOOKUP JOIN 一直报字段类型错误九成是关联字段类型不匹配。ES|QL 的 LOOKUP JOIN 要求关联字段是 keyword 类型如果你的字段是 text 类型需要先做 mapping 调整或者用.keyword子字段。排查方法很简单先单独跑FROM index | LIMIT 1看字段类型确认后再写 JOIN。6.3 生成的查询能跑但结果不对这类问题最难排查因为语法和字段都没错。我的经验是先确认时间范围再确认聚合维度。很多时候是模型把“最近一周”理解成了“最近 7 天”但时区差了 8 小时或者把“按天聚合”写成了“按小时聚合”。解决办法是在 Prompt 里明确时间语义并且让用户确认关键参数。6.4 空结果到底是没数据还是查错了我的排查顺序是先去掉所有 WHERE 条件跑一次确认索引有数据再逐个加回条件定位是哪个条件导致空结果。这个方法虽然笨但最可靠。另外ES|QL 的WHERE对 null 值的处理比较特殊字段为 null 的记录会被过滤掉这点也要注意。6.5 重试还是不成功怎么办如果两次重试都失败不要再让模型硬试了。我的做法是降级到模板查询预置一批常见查询模板把用户问题映射到最接近的模板让用户手动填参数。这样虽然不够智能但至少能保证可用性。工程系统里可用性永远比智能性优先。7. 我对这套方案的一些个人体会做 Text-to-ES|QL 这一年多最大的体会是不要指望模型一次写对要设计一个能容错的系统。59% 这个数字看着吓人但它衡量的是“裸写”的能力。一旦你把 Schema 注入、Few-shot、语法校验、自动重试这套组合拳打出来正确率上 90% 是完全可行的。另一个体会是ES|QL 的语法特性决定了它比标准 SQL 更需要外部约束。标准 SQL 模型见得多裸写正确率能到 80% 以上ES|QL 语料少裸写就只有 59%。但这个差距恰恰是工程手段能补上的——你补的越多模型表现越好。最后分享一个小技巧把每次失败的查询和错误信息存下来定期回灌到 Few-shot 里。我每个月会做一次这样的迭代把高频错误变成新的反例。坚持三个月你会发现系统的正确率在稳步爬升而且爬升的斜率比换模型还明显。这套方法不依赖特定模型换任何 LLM 都能用算是比较通用的工程实践了。