SQLBot/docs/agents/knowledge-enhancement.md

# 知识增强

术语、SQL 示例和自定义提示词在问数流程中按作用域注入模型上下文。概念定义见根目录 `CONTEXT.md`；本文记录作用域、命中和组合的行为规则，修改相关知识逻辑前先对照本文确认预期行为。

## 作用域规则

三类知识的作用域维度不完全一致：

| 维度 | 术语 | SQL 示例 | 自定义提示词 |
|---|---|---|---|
| 工作空间级（全局） | 支持 | 不支持 | 支持 |
| 数据源级 | 支持多选 | 仅单选 | 支持多选 |
| 高级应用级 | 支持 | 支持 | 支持 |
| 任务环节分类 | 无 | 无 | 生成 SQL / 分析 / 预测 |

- SQL 示例必须绑定一个数据源或一个高级应用，没有工作空间级示例；两者都为空时不注入任何示例。
- 数据源场景取并集：工作空间级知识 + 绑定当前数据源的知识。
- 高级应用场景取替换：只注入绑定该高级应用的知识，工作空间级知识不生效。这是有意设计，不是缺陷。
- 作用域的工作空间解析：普通小助手按助手所属工作空间；页面嵌入助手按当前用户的工作空间；高级应用按助手所属工作空间并使用应用绑定。

## 命中与组合规则

- 组合语义是“命中即注入”：命中多少条注入多少条，不做全局排序或择优。
- 术语：优先用 LLM 提取的关键词匹配（无关键词时用原始问题），按逗号拆分逐词匹配；同义词命中归并到主词条目。
- SQL 示例：用完整问题做双向包含匹配（问题包含示例问题，或示例问题包含问题）。
- 自定义提示词：不做问题匹配，作用域内全部注入。
- 关键词/包含匹配与 embedding 召回是并集关系，不是优先级关系：embedding 只是补充召回渠道，不淘汰关键词命中的结果。
- `EMBEDDING_ENABLED=false` 时退化为纯关键词/包含匹配。
- embedding 召回按相似度降序取 top N（默认 5）、相似度阈值默认 0.4，由 `EMBEDDING_*_SIMILARITY` / `EMBEDDING_*_TOP_COUNT` 配置。
- 注入顺序固定：自定义提示词 → 术语 → SQL 示例，各自独立成段附在 schema 信息之后。
- 术语另有一个独立用途：提取的关键词经术语同义词扩展后用于表匹配，与术语注入互不影响。

## 已知边界

- 关键词/包含匹配的命中数量没有上限，极端情况下可能注入大量内容（token 风险）；只有 embedding 召回受 top N 限制。

## 代码入口

- 命中与作用域查询：`backend/apps/terminology/curd/terminology.py`、`backend/apps/data_training/curd/data_training.py`、`sqlbot-xpack/src/sqlbot_xpack/custom_prompt/curd/custom_prompt.py`。
- 注入编排：`backend/apps/chat/task/llm.py` 的 `filter_terminology_template` / `filter_training_template` / `filter_custom_prompts`。
- `backend/apps/settings/models/setting_models.py` 的 `term_model` 是无引用的遗留代码，与术语功能无关，不要在其上扩展。