跳到主要内容
Ed. notes

03 AI 助手调优:让回答少一点无关引用

长文 · 2026-11-12 · 合集第 4 / 4 篇

  • RAG
  • 检索调优
  • Embedding
  • SSE
第 4 / 4 篇 · 查看全部章节 → 当前:03 AI 助手调优:让回答少一点无关引用

一句话结论

联调通过只证明 sources → token → done 能走通,不证明回答可信。这一轮没有换模型,也没有改 SSE 协议,而是把问题拆到检索层:过滤低相关切片、限制同一篇文章占用的上下文、跳过只有标题的切片,并把文章标题与章节路径补进 embedding 文本。调整后,无关问题不会再带出一堆来源,相关问题仍能稳定命中。

它解决什么问题

前端聊天页和全站浮窗已经通过同源代理接到 FastAPI,事件顺序、增量文本、来源列表和停止生成都能工作。真正暴露出来的是回答内容本身:

  • 问一个站点完全没写过的问题,回答虽然会说“资料不足”,但 sources 里仍列出几篇不相关文章。
  • 问“多阶段构建解决了什么问题”,top-k 几乎被同一篇长文的不同章节占满,其他相关文章没有机会进入上下文。
  • 索引里有一些切片只有一行 ## 我怎么试的,没有正文;它们会被相似度检索命中,却不能提供任何事实。
  • 切片向量只包含正文,没有文章标题和章节路径。正文里没出现主题词时,召回会偏弱。

这些问题的共同点是:模型还没开始生成,上下文已经被污染或挤窄了。 所以先不急着改提示词,而是把 retrieval 和 context selection 拆开看。

先定位:问题出在检索还是生成

我按三层排查:

  1. 检索层:/api/search 返回什么?分数分布是否合理?低分结果是否也被返回?
  2. 上下文层:select_context() 把哪些切片送进提示词?是否被单一文档垄断?
  3. 生成层: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 问答、开始遇到“来源不准、回答被一篇长文带偏、资料不足还列来源”的人。重点不是照抄这四个参数,而是学会把坏回答拆成检索、上下文和生成三层,再用真实查询和分数分布验证每一次调整。