03 上下文质量:阈值、混合检索与预算
一句话结论
检索质量由三件事决定:分数怎么读、上下文怎么选、prompt 有多长。余弦分数不可跨模型比较,必须用自己的数据标定;词法检索补精确标识符,向量检索补同义改写;历史按 token 预算裁,而不是按条数。
它解决什么问题
链路跑通后,常见的坏回答有三类:
- 问站里没有的东西,回答仍带出一堆弱相关来源;
- 一个问题需要多篇文章,top-k 却被同一篇长文的多个章节占满;
- 聊到第五轮,首 token 明显变慢,偶尔还触发每日额度。
它们分别对应:阈值缺失、上下文选择单一、历史预算失控。
1. 余弦相似度不是准确率
score = 1 - cosine_distance,范围大约 0~1,但它不是概率,也不跨模型可比。同一个 0.62,在不同 embedding 模型上可能一个表示「高度相关」,一个只是「同一个大领域」。
所以阈值不能拍脑袋,只能用自己的数据看分布:
相关切片:0.55 0.61 0.72 0.48 ...
无关切片:0.31 0.44 0.39 0.52 ...
两组会重叠,没有完美阈值。你只能在「误拒站内问题」和「放进噪音」之间选一个工作点。本仓库的实测记录里,使用 Qwen3-Embedding-0.6B 时「你好」最高约 0.379、「今天天气」约 0.283、站内问题约 0.601,本地联调把阈值放在 0.45。这只是那组模型和内容的分布,不是通用值。
2. 三级分级,而不是二值判断
def grade(chunks, min_score: float, good_score: float) -> str:
if not chunks or chunks[0].score < min_score:
return "empty"
if chunks[0].score < good_score:
return "weak"
return "good"
| grade | 处理 | 理由 |
|---|---|---|
good |
正常生成 | 资料够 |
weak |
生成,但要求「只答覆盖部分,并说明没覆盖什么」 | 有线索但不完整,诚实优于硬编 |
empty |
不调模型,走范围说明或推荐 | 没资料时,任何生成都是编 |
weak 只需要在 system prompt 加一句:
如果资料只能回答部分问题,请先回答能回答的部分,再明确说明「资料未覆盖 X」。
3. 混合检索:词法 + 向量
两种检索的失败方式互补:
| 查询类型 | 向量检索 | 词法检索 |
|---|---|---|
| 「怎么减少镜像体积」 | 强 | 词可能不重合 |
| 「Qwen3-Embedding-0.6B 多少维」 | 弱 | 强 |
| 「build-practice-05」 | 弱 | 强 |
| 同义改写、口语 | 强 | 弱 |
中文词法的麻烦
Postgres 的 tsvector 默认按空格和标点切词,中文整句会变成一个超长 token,等于没分词。要正确分词得装 zhparser 或 pg_jieba,需要编译扩展。
务实替代是 pg_trgm:按字符三元组切,不依赖分词。
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE INDEX IF NOT EXISTS documents_title_trgm_idx
ON documents USING gin (title gin_trgm_ops);
SELECT slug, title, url, similarity(title, %s) AS score
FROM documents
WHERE title %% %s
ORDER BY score DESC
LIMIT 3;
它不完美(不理解词边界),但对子串匹配、拼写容错和专名检索足够好,而且零额外依赖。
用 RRF 融合,而不是把分数相加
向量分数和 trigram 分数量纲不同,不能直接相加,也很难可靠归一化。用 RRF(Reciprocal Rank Fusion)只看名次:
RRF(d) = Σ 1 / (k + rank_i(d)) k 通常取 60
from collections import defaultdict
def rrf_fuse(*rankings, k: int = 60):
scores: dict[str, float] = defaultdict(float)
items: dict[str, object] = {}
for ranking in rankings:
for rank, item in enumerate(ranking, start=1):
scores[item.id] += 1.0 / (k + rank)
items[item.id] = item
return [items[i] for i in sorted(scores, key=scores.get, reverse=True)]
k = 60 的作用是压平头部差距,避免某一个列表的 top1 独占结果。RRF 不需要训练、不需要调权重,是工业界最常用的融合基线。
落地顺序:
- 加扩展和索引;
- 在
repository.py增加search_chunks_keyword(); - 两路查询 + RRF + 截断
top_k; - 接口不变:仍返回
ChunkHit[],graph 不用改。
代价是多一次数据库查询(约 10~30 毫秒),没有模型成本。
4. 去重与邻接扩展
- 重叠切片可能同时入选(切片时保留了约 160 字重叠),按
content_hash和相邻position去重。 - 某个切片命中后,可以把它前后相邻的切片一起带上,提高上下文连续性,对「答案被切断」很有效。
另外,select_context() 遇到第一个放不下的切片就 break,可能少装几条;改成 continue 能填得更满,但牺牲一点分数顺序。二选一,用评测定。
5. token 经济学与历史预算
模型按 token 处理文本:英文约 4 字符/token,中文约 1~1.7 字符/token。输入 token 便宜但影响首 token 延迟,输出 token 贵且串行生成。
最坏情况很容易算出来:
历史 6 条 × 2000 字 = 12000 字
上下文 6000 字
系统提示 ~200 字
────────────────────────
约 18000 字 ≈ 12000 token
prompt 越长,首 token 越晚,不只是更贵。裁剪历史同时降低成本和延迟。
按预算裁,而不是按条数:
def trim_history(history, max_chars=1800):
kept, total = [], 0
for message in reversed(history):
content = _CITATION.sub("", message["content"]).strip()
if not content:
continue
if kept and total + len(content) > max_chars:
break
kept.append({**message, "content": content})
total += len(content)
return list(reversed(kept))
- 从最新往回取,保证最近上下文一定在;
- 第一条即使超预算也保留,否则可能一条都不剩;
- 用同一个估算函数,保持全链路口径一致。
摘要和裁掉的取舍:现在选裁掉。摘要要等服务端会话落地后才有意义,否则每次请求都要重算。
我怎么试的
1. 标定阈值
# 站内问题
curl -s -X POST http://127.0.0.1:8000/api/search \
-H 'content-type: application/json' \
-d '{"query":"多阶段构建解决了什么问题","limit":3}' | jq '.results[].score'
# 站外问题
curl -s -X POST http://127.0.0.1:8000/api/search \
-H 'content-type: application/json' \
-d '{"query":"今天天气怎么样","limit":3}' | jq '.results[].score'
各收集 20~30 条,看两组分布的重叠区,把阈值放在重叠区偏保守的一侧。同时记录两个错误率:
| 错误 | 后果 | 指标 |
|---|---|---|
| 阈值太高 | 站内问题被误拒 | 误拒率 |
| 阈值太低 | 站外问题被硬答 | 越界回答率 |
2. 混合检索只测「精确标识符」这一组
在评测集里单列一组仓库名、版本号、slug、报错原文。如果这组 recall@5 提升明显、其它组不掉,融合就是对的;如果整体提升但精确组没变,说明问题不在检索方式,而在内容或切片。
坑和限制
- 阈值不可通用。 换模型、换语言、内容分布变化后都要重标。把阈值调得过高,表现是过度拒答。
- RRF 会改变
score的语义。 融合后的分数不再表示余弦相似度;建议改名为rank_score,同时保留原始vectorScore/keywordScore供调试。 - pg_trgm 不是中文分词。 它按字符切,理解不了词边界;对长句的语义检索帮助有限,主要救专名和子串。
- 改 embedding 文本格式后必须重建索引。
index_meta只比较 provider、model、dimension,不记录文本格式版本;代码更新了但向量没重建,检索不会变。 - 单篇上限会丢信息。 同一篇文章最多取 2 条能防止垄断,但问题确实需要多章节时会截断上下文;1、2、3 应该用评测定,而不是拍脑袋。
- 不要把所有资料塞进 prompt。 上下文预算和
top_k是两个独立参数,任何一个失控都会让延迟和成本一起爆。
适合谁
适合已经能稳定检索、但回答经常「带错来源」或「漏掉另一篇文章」的人。重点不是照抄某个阈值,而是学会看分数分布、把检索拆成向量和词法两路,并用固定评测集验证每一次参数变化。
下一篇换一个角度:当检索结果确实为空时,系统应该怎样收场。