样例查询
高频 / 标准问题预先写好"标准答案",用户提问向量命中即直接返回,跳过检索和大模型生成。
这是 SparkX 的一个"省钱提速"利器,对应数据库里的 sample_query 表、sample_query_config 配置,以及入库阶段的 SampleQueryIndexer。
1. 它解决什么问题
普通的 RAG 流程,每个问题都要走完整条链路:
用户提问 → 改写 → 意图分类 → 向量检索 → 重排 → 大模型生成回答
↑
这一步最贵、最慢(要调 LLM)
但实际业务中,有大量问题是高频重复的(比如"年假怎么算"“WiFi 密码是多少”“报销流程”)。这些问题的答案是固定、标准的,每次都让大模型重新生成一遍,既慢又费钱,还可能每次回答得不太一样。
样例查询就是针对这类问题做的优化:
用户提问 → 向量匹配样例库 → 命中? ─ 是 → 直接返回标准答案(零 LLM 调用)
│
└─ 否 → 走正常 RAG 流程
2. 核心作用
| 作用 | 说明 |
|---|---|
| ⚡ 提速 | 高频问题秒回,不用等大模型生成 |
| 💰 省钱 | 命中样例 = 0 次 LLM 调用 = 0 token 消耗 |
| 🎯 稳定 | 标准问题永远返回完全一致的标准答案,不会"每次答得不一样" |
| 🛡️ 可控 | 关键问题(如政策、制度)由人工把关答案,避免模型"自由发挥" |
3. 工作原理
- 录入阶段:在知识库的「样例查询」管理里,人工录入「问题 + 标准答案」
- 入库阶段:系统用向量模型把每个样例问题转成向量存入
sample_query表(对应SampleQueryIndexer) - 查询阶段:用户提问时,先拿问题去样例库做向量匹配
- 命中判断:相似度超过阈值 → 直接返回标准答案;未超过 → 进入正常 RAG 流程
💡 样例查询在 RAG 流水线里优先级很高(对应
pipeline/stages/里 Order=5 的样例命中阶段),排在检索、重排、生成之前,属于"快速短路"。
⚠️ 前置条件:录入的问题必须完成向量化
这是使用样例查询最容易踩的坑,务必先理解:
你录入的"问题 + 答案"只是普通文字,系统必须先把问题转成向量,样例查询才能真正生效。
为什么必须向量化
样例查询的命中判断,本质是用户问题和样例问题做向量相似度比较:
用户问题 ──向量化──► 向量A ┐
├── 算相似度 ──► ≥ 阈值? ── 命中,返回标准答案
样例问题 ──向量化──► 向量B ┘
- 如果样例问题没有向量化,库里就只有文字、没有向量
- 用户提问时无法做向量比较 → 永远命中不了 → 样例查询形同虚设
录入后的操作
在「样例查询」管理页录入问题后,必须点「向量化」(或保存触发向量化),让系统用知识库的向量模型把每个样例问题转成向量存入 sample_query 表。
| 状态 | 表现 |
|---|---|
| 录入了但没向量化 | 🔴 样例查询永不命中,等于白录 |
| 录入并已完成向量化 | 🟢 可被向量匹配,样例查询生效 |
⚠️ 修改了样例问题内容后,也要重新向量化,否则库里还是旧问题的向量,匹配的是旧问题。
和向量模型的关系
样例问题的向量化用的是知识库绑定的向量模型,因此:
- 样例查询跟随知识库的向量模型(换向量模型 → 样例向量作废,需重新向量化)
- 这点和知识库文档入库完全一致
4. 在智能体中如何开启
样例查询是知识库维度的能力,但每个智能体可以单独控制是否启用。在 创建智能体 表单的「样例查询」标签页里:
| 配置项 | 默认值 | 说明 |
|---|---|---|
| 样例查询开关 | 关闭 | 是否启用样例优先匹配 |
| 匹配阈值 | 0.85 | 相似度 ≥ 此值才算命中;留空则回退全局配置 |
⚠️ 即使开关打开了,如果该智能体绑定的知识库里没有录入样例,也不会有任何命中。样例需要先在「样例查询」管理页向量化后才能被匹配。
5. 适合录入什么样例
| ✅ 适合 | ❌ 不适合 |
|---|---|
| 高频问题(占流量大头) | 偶尔问一次的问题 |
| 答案固定、标准的问题 | 答案因人而异、因时而变的问题 |
| 政策 / 制度类(答案要权威) | 开放式、探讨性问题 |
| 数字 / 流程类(如"年假天数") | 需要综合多文档推理的问题 |
6. 注意事项
- ⚠️ 样例问题也要用知识库的向量模型生成向量,所以它和知识库绑定,跟随向量模型(换了向量模型,样例向量也要重新生成)
- ⚠️ 命中阈值要设合理:
- 太低会把不相关问题误判为命中(答非所问)
- 太高又形同虚设(什么都命中不了)
- 💡 建议从 Top10 ~ Top20 高频问题起步录入,观察命中率和回答效果,再逐步扩充
- 💡 样例答案是人工维护的,文档更新后记得同步更新对应样例答案,否则会过时
- 💡 样例查询和兜底策略是两回事:样例查询是"命中就直返",兜底是"检索不到时怎么办",不要混淆
7. 与正常 RAG 的关系
样例查询不是替代 RAG,而是在 RAG 前面加了一道"快速通道":
用户提问
│
▼
[样例查询] ──命中──► 直接返回标准答案(结束)
│
未命中
▼
[正常 RAG 流程] 改写 → 检索 → 重排 → 生成
- 大部分长尾问题依然走 RAG
- 少数高频问题走样例直返
- 两者互补,共同覆盖全部提问
