03 AI 助手调优:让回答少一点无关引用
一句话结论
联调通过只证明 sources → token → done 能走通,不证明回答可信。这一轮没有换模型,也没有改 SSE 协议,而是把问题拆到检索层:过滤低相关切片、限制同一篇文章占用的上下文、跳过只有标题的切片,并把文章标题与章节路径补进 embedding 文本。调整后,无关问题不会再带出一堆来源,相关问题仍能稳定命中。
它解决什么问题
前端聊天页和全站浮窗已经通过同源代理接到 FastAPI,事件顺序、增量文本、来源列表和停止生成都能工作。真正暴露出来的是回答内容本身:
- 问一个站点完全没写过的问题,回答虽然会说“资料不足”,但
sources里仍列出几篇不相关文章。 - 问“多阶段构建解决了什么问题”,top-k 几乎被同一篇长文的不同章节占满,其他相关文章没有机会进入上下文。
- 索引里有一些切片只有一行
## 我怎么试的,没有正文;它们会被相似度检索命中,却不能提供任何事实。 - 切片向量只包含正文,没有文章标题和章节路径。正文里没出现主题词时,召回会偏弱。
这些问题的共同点是:模型还没开始生成,上下文已经被污染或挤窄了。 所以先不急着改提示词,而是把 retrieval 和 context selection 拆开看。
先定位:问题出在检索还是生成
我按三层排查:
- 检索层:
/api/search返回什么?分数分布是否合理?低分结果是否也被返回? - 上下文层:
select_context()把哪些切片送进提示词?是否被单一文档垄断? - 生成层:system prompt 是否允许模型在资料不足时拒答?引用编号是否和
sources对齐?
这一轮先处理前两层。生成层只保留原有约束:只依据资料回答、用 [n] 引用、资料不足时直接说明。没有足够评测数据前,不把“换提示词”当成主要手段。
四个调整
1. 低相关切片不再进入上下文和 sources
新增配置 RAG_MIN_SCORE,默认 0(不过滤),范围 0–1。graph.retrieve() 在调用 select_context() 前先过滤:
relevant = [hit for hit in hits if hit.score >= min_score]
if len(relevant) < len(hits):
logger.info(
"检索过滤低相关切片:保留 %d 条,丢弃 %d 条(阈值 %.3f)",
len(relevant),
len(hits) - len(relevant),
min_score,
)
return {"chunks": select_context(relevant, max_context_chars)}
过滤发生在 sources 事件之前,所以低分切片既不会进入提示词,也不会出现在前端来源列表。全部被过滤时,chunks 为空,图走 refuse 分支,固定返回“提供的资料不足以回答这个问题”,不调用模型。
2. 同一篇文章最多取两个切片
原来 select_context() 只按分数顺序取,直到上下文长度上限。一篇长文如果有多个章节都相关,就会占满 top-k,其他文章被挤掉。现在增加 max_per_document,默认 2:
for chunk in chunks:
if per_document.get(chunk.slug, 0) >= max_per_document:
continue
length = len(chunk.text)
if selected and total + length > max_chars:
break
selected.append(chunk)
total += length
per_document[chunk.slug] = per_document.get(chunk.slug, 0) + 1
这不是为了让来源“看起来多样”,而是为了让上下文覆盖不同文档。代价是同一篇长文里第三、第四相关的章节可能被跳过;如果问题确实需要该文的多段细节,这个上限会损失信息。当前先取 2,后续应该用评测集验证 1、2、3 的差异。
3. 跳过只有标题、没有正文的切片
切片按标题边界生成,有些章节只有标题,正文都在下一级标题里。例如:
## 我怎么试的
### 1. 先画三个阶段
...
## 我怎么试的 这一节在下一个标题前没有正文,却会被切成一个独立片段。它没有事实,只有标题词,容易在相似度检索里制造噪声。
新增 _has_body():只要片段里有一行非空、且不以 # 开头,就认为有正文;否则跳过。
def _has_body(piece: str) -> bool:
return any(
line.strip() and not line.lstrip().startswith("#")
for line in piece.splitlines()
)
4. embedding 文本补上文章标题和章节路径
入库时不再只 embed chunk.text,而是:
def embedding_text(document: Document, chunk: Chunk) -> str:
headings = " / ".join(chunk.heading_path)
return f"{document.title}\n{headings}\n{chunk.text}"
这样同样一段正文,向量里会带上“它属于哪篇文章、哪一节”。对“ACR VPC 回滚”“Lighthouse 怎么测”这类问题,标题和路径本身就是强信号。
注意:这只改变入库向量,不改变 chunk.text。检索结果和引用展示仍然是正文,标题与路径继续通过 heading_path 字段返回。
我怎么试的
1. 标题切片到底有多少
用当前 content/ 统计切片,并绕过 _has_body() 复现调整前的数量:
documents: 18
chunks after skip: 131
chunks before skip: 140
heading-only pieces: 9
('build-practice-05-deployment-docker', ('我怎么试的',), '## 我怎么试的')
('build-practice-06-deployment-acr', ('我怎么试的',), '## 我怎么试的')
('build-practice-07-ci-quality-gate', ('我怎么试的',), '## 我怎么试的')
...
9 个标题切片全部来自 ## 我怎么试的,调整后索引从 140 个切片降到 131 个。这不是“越多越好”的优化,而是去掉了不能回答问题的片段。
2. 无关问题与相关问题的分数分布
用真实 embedding 查询当前索引,阈值取本地联调值 0.45:
query: 你好 | threshold: 0.45
0.3790 context7 ('适合谁',)
0.3721 build-log-01-background-scope ('01 需求:...',)
0.3620 build-log-01-background-scope ('01 需求:...', '适合谁')
...
query: 今天天气怎么样? | threshold: 0.45
0.2830 build-log-01-background-scope ('01 需求:...', '我怎么试的')
0.2703 build-log-01-background-scope ('01 需求:...',)
...
query: 多阶段构建解决了什么问题? | threshold: 0.45
0.6014 build-practice-05-deployment-docker ()
0.5488 build-practice-05-deployment-docker ('它解决什么问题',)
0.5212 build-practice-05-deployment-docker ('我怎么试的', '1. 先画三个阶段')
0.5102 build-practice-05-deployment-docker ('适合谁',)
0.4614 build-practice-05-deployment-docker ('我怎么试的', '6. 为什么不在服务器上构建')
“你好”和“今天天气”的最高分都低于 0.45,过滤后为空,走拒答;相关问题有多条高于阈值。这只能说明这组内容在这个模型上的分数分布,不能说明 0.45 是通用阈值。
3. 一篇长文占满 top-k
同一个问题取前 8 条,前 5 条全部来自 build-practice-05-deployment-docker:
0.5999 build-practice-05-deployment-docker ()
0.5482 build-practice-05-deployment-docker ('它解决什么问题',)
0.5200 build-practice-05-deployment-docker ('我怎么试的', '1. 先画三个阶段')
0.5092 build-practice-05-deployment-docker ('适合谁',)
0.4607 build-practice-05-deployment-docker ('我怎么试的', '6. 为什么不在服务器上构建')
0.4307 openspec ('适合谁',)
0.4277 build-log-01-background-scope ('01 需求:...', '我怎么试的')
0.4243 build-practice-06-deployment-acr ('它解决什么问题',)
不加上限时,select_context() 会把这 8 条全部纳入(在字符上限内);加上“每篇最多 2 条”后,只保留该文前两条,再继续取 openspec、build-log-01-background-scope、build-practice-06-deployment-acr。如果同时启用 0.45 阈值,后三条分数不够,会先被过滤掉,最终上下文只剩该文两条。两个参数会互相影响,不能只看其中一个。
4. 标题与路径进入向量后的分数
用文章标题作为 query,对比“只 embed 正文”和“embed 标题 + 路径 + 正文”:
ACR VPC 回滚 old: (1, 0.5390) new: (1, 0.6907)
Lighthouse 怎么测 old: (1, 0.7257) new: (1, 0.8035)
Context7 是什么 old: (1, 0.6393) new: (1, 0.6606)
MCP Inspector 怎么调试 old: (1, 0.8442) new: (1, 0.8703)
这些 query 原本就能把目标文档排在第一,所以变化不是“从找不到到找到”,而是分数余量变大,在阈值附近更不容易被误杀。对更难的、标题词不出现在正文里的 query,收益需要另外构造评测集验证。
调整后的调用链
Settings.rag_min_score
→ app.chat()
→ make_rag_graph(min_score=...)
→ retrieve()
→ retriever(query, top_k)
→ 过滤 score < min_score
→ select_context(max_chars, max_per_document=2)
→ generate() 或 refuse()
入库侧:
load_documents()
→ chunk_document() 跳过 heading-only
→ embedding_text() 标题 + 路径 + 正文
→ provider.embed_documents()
→ 写入 chunks.embedding
SSE 协议没有变化:sources 仍然先发,token 仍然是增量,done / error 的终态语义不变。前端不需要因为这次调优改解析器。
坑和限制
- 阈值不是通用参数。 0.45 来自当前 Qwen3-Embedding-0.6B、当前 18 篇内容和这组查询。换模型、换语言或内容分布变化后,要重新看分数分布。把阈值调得过高会把“勉强相关”也拒掉,表现为过度拒答。
- 单篇上限会丢信息。 如果一个问题确实需要同一篇文章的多个章节,最多 2 条会截断上下文。它是控制垄断的手段,不是固定答案。
- embedding 文本变化不会触发索引元信息校验。
index_meta只比较 provider、model、dimension,没有记录 embedding 文本的格式版本。改了embedding_text()后必须重新入库;否则数据库里仍是旧向量,代码看起来更新了,检索却没有变。 - 这次没有系统评测回答质量。 实验验证的是来源过滤、上下文选择和分数变化,不是“答案更正确”。要证明后者,需要固定问题集、标注相关资料、分别评估召回、引用正确率和拒答准确率。
- 测试假设需要同步。 单元测试 58 项通过;集成测试里有两个用原始
chunk.text做精确匹配的旧断言,在 embedding 文本加入标题和路径后不再成立,需要改成与embedding_text()相同的查询文本。这是调整入库文本时必须一起处理的迁移项。 - 安全边界没变。
/api/chat仍然没有鉴权、配额和限流,会产生真实模型费用;前端聊天入口默认关闭,生产代理 fail-closed。调优不改变这个事实。
适合谁
适合已经跑通 RAG 问答、开始遇到“来源不准、回答被一篇长文带偏、资料不足还列来源”的人。重点不是照抄这四个参数,而是学会把坏回答拆成检索、上下文和生成三层,再用真实查询和分数分布验证每一次调整。