模块五-AI系统架构设计 | 第34讲：RAG 架构深度优化 - 分块策略、混合检索、重排序在代码场景的实践
本讲目标：解释基础 RAG 在代码审核场景为何容易失效；掌握面向代码的进阶检索链路：混合检索（向量 + BM25）、交叉编码器重排序、查询变换与上下文窗口管理；理解 AST 感知分块、import 感知扩展、调用图感知扩展在系统架构中的落点；交付 CodeSentinel
HybridRetriever、BM25IndexBuilder、CrossEncoderReranker（可降级）、ContextAssembler的可运行 Python 实现；给出「基础 RAG vs 优化 RAG」的离线评测框架。读完你应能把第33讲的索引结果，升级为「高证据密度、低噪声、可塞进窗口」的上下文包。
先修提示：建议完成第32～33讲；本讲假设你已能把代码切分为
CodeChunk并写入向量库。
交付物建议：学完后输出一页「RAG 优化架构图 + 开关表 + 降级策略」，贴到 CodeSentinel 的 RFC 或 ADR 目录；这比保存一堆脚本更能推动团队对齐。建议同时附一张「指标看板草图」，明确每周要看的核心曲线与告警阈值。
开场：文本相似 ≠ 代码相关
很多人把 RAG 理解为「embedding 一下然后 topK」。在散文问答里这或许够用，在代码审核里却经常翻车：变量名不同但逻辑相同的实现可能向量很近；真正相关的调用点却因为缺少共享 token 而向量很远；注释里的关键词能骗过向量检索，却骗不过安全规则。更麻烦的是，代码高度结构化：语法边界、类型信息、调用关系才是「相关性」的重要组成部分，而纯向量检索把这些结构信息打碎了。
还有一个容易被忽略的维度：时间。仓库里的「旧实现」可能仍然向量相似，但早已不被使用；没有版本与分支元数据，检索会把过期模式当成现网真相。CodeSentinel 在优化 RAG 时，应把 branch、commit_sha、indexed_at 纳入过滤或 rerank 特征，让系统优先呈现与目标变更同一时间切片的证据。否则你会看到模型引用「半年前已删除的文件逻辑」，评论看似专业，实则与现实运行态脱节。
因此 CodeSentinel 的 RAG 不是单层检索，而是一个 候选生成 → 过滤 → 重排序 → 上下文拼装 的流水线。混合检索用 BM25 补齐「标识符与精确关键字」；重排序用 cross-encoder 或强特征打分把 topK 从「像」变成「对」；查询变换把工程师的自然语言问题改写成更贴近代码库的检索 query；上下文拼装则在 token 预算内最大化证据密度。AST 感知分块与 import/调用图扩展属于「结构化增强」，哪怕你暂时没有完整调用图服务，也可以用轻量启发式先拿到 80 分体验。
本讲会给你完整可运行示例：在内存构建 BM25 索引，同时调用 Chroma 向量检索，融合分数后重排，再用 tokenizer 近似计数把结果装进上下文。你也可以把 CrossEncoder 换成 sentence-transformers，示例里提供可选路径。
从系统角度看，RAG 优化不是「加模型」而是 加约束与减噪声。代码审核最昂贵的成本通常是工程师阅读评论的时间：如果上下文里塞满低相关片段，模型会努力把它们都解释成问题，误报会飙升；如果上下文漏掉关键文件，模型会凭记忆补全，漏报会上升。优化检索的本质，是在固定 token 预算下最大化 可验证证据 的密度。为此，CodeSentinel 会把「检索日志」与「最终评论」关联起来：当用户标记某条评论为误报时，团队应能回溯「当时 topK 是什么、rerank 后是什么、assembler 丢了什么」。
全局视角：CodeSentinel RAG 优化流水线（Mermaid）
flowchart LR
Q[用户/Agent 查询] --> QT[QueryTransform\n扩展/改写]
QT --> V[向量检索\nChroma]
QT --> B[BM25 检索\n关键词]
V --> F[Fusion 融合\nRRF/加权]
B --> F
F --> RR[Rerank\nCrossEncoder/启发式]
RR --> EXP[结构化扩展\nimport/调用图]
EXP --> ASM[ContextAssembler\nTokenBudget]
ASM --> LLM[LLM 生成/判定]
策略对比：基础 RAG vs 优化 RAG（Mermaid）
flowchart TB
subgraph BR[基础RAG]
b1[单路向量topK] --> b2[直接拼接上下文] --> b3[LLM]
end
subgraph OR[优化RAG]
o1[多路召回] --> o2[融合去重] --> o3[重排序] --> o4[预算拼装] --> o5[LLM]
end
BR -->|常见问题: 漏召回/噪声大| X[误报与幻觉]
OR -->|更贵更复杂| Y[更高上限]
核心原理：为什么基础 RAG 在代码场景失败
1. 代码相关性不是单一语义距离
审核问答常混合三类信息：自然语言描述、精确符号（函数/类/配置键）、结构关系（调用、继承、配置引用）。向量擅长第一类与部分第二类；BM25 擅长第二类；图结构擅长第三类。只做向量，等于默认「相关=语义近」，这在代码世界经常不成立。
2. 分块策略与检索质量强耦合
函数级 chunk 能提升聚焦，但可能丢调用上下文；文件级 chunk 噪声大。AST 感知分块能把「逻辑单元」保留下来，减少无意义切断。CodeSentinel 建议：分块负责生成高质量单元；检索负责把多个单元组合成证据链。
3. 混合检索：向量 + BM25
常见融合方法：
- 线性加权：对两路分数归一化后加权求和，简单但对分数尺度敏感。
- RRF（Reciprocal Rank Fusion）：只看排名，鲁棒性更好，工程上更常用。
混合检索能显著降低「只命中注释、不命中实现」的概率。
4. 重排序：从召回率转向精确率
向量与 BM25 的第一阶段目标是高召回；进入 LLM 前必须提高精确率。Cross-Encoder 以 (query, doc) 联合编码输出相关性分数，比双塔向量相似度更准，但成本更高。生产常用 两阶段：先 cheap 召回 50～200，再 rerank 到 5～15。
5. 查询变换：扩展、分解、HyDE（谨慎）
- 扩展：把「OAuth 回调」扩展成
state、PKCE、redirect_uri等同义词。 - 分解：把复合问题拆成子查询分别检索再合并。
- HyDE：让模型先生成「假想答案」再检索，对代码场景要谨慎，容易引入不存在 API 名称，反而污染检索。
6. 上下文窗口管理：token 预算不是字数预算
代码 token 密度高，必须把「diff 主轴证据」优先保留，其次才是历史相似片段。ContextAssembler 应支持：按分数排序装入、按路径去重、按模块配额、保留引用头（路径/行号/符号）。
7. import 感知扩展
当检索命中某函数，若 metadata 有 imports，可把同文件相关符号或同目录文件作为二级扩展候选（需限制深度，避免爆炸）。
8. 调用图感知扩展（架构落点）
理想形态：图为单独服务，检索命中节点后拉取 1-hop 调用者与 callee。没有图时可用启发式：同字符串符号名、同测试文件命名模式等低配替代。
9. 评测：基础 vs 优化
离线集建议记录：Recall@K（是否包含人工标注相关文件）、nDCG@K（排序质量）、以及 LLM 下游任务准确率（最终 finding 是否正确）。没有下游指标，优化检索可能「分数好看但评论没用」。
10. RRF 为什么会比「强行归一化分数」更稳
向量距离、BM25 原始分数、以及不同版本 embedding 的尺度都可能变化。你若把它们线性加权，往往要不断手工调权重。RRF 只使用排名，天然对尺度不敏感，更适合作为第一版融合基线。缺点是：它忽略「第一名比第二名强很多」这种置信差异。工程上常见演进是：先用 RRF 上线，再收集数据训练 Learning-to-Rank 或轻量线性模型，把多路特征合成最终排序。
11. 上下文拼装：diff 优先还是检索优先
CodeSentinel 推荐策略是：diff 与静态分析摘要永远占固定配额（例如 40%～60% token），剩余再给 RAG 证据；若 Agent 需要扩检索，应减少解释性文字而不是动 diff 配额。否则会出现「模型没看到真实变更却看到一堆历史代码」的危险组合。ContextAssembler 可以显式接收 primary_blocks 与 secondary_blocks 两个列表，本讲示例为简化合并为一个列表，你在落地时应拆分。
12. 噪声源：测试代码、样例数据与生成文件
混合检索很容易把「测试里的假密钥、样例 JSON」当成高相关文本，因为它们共享大量关键字。治理办法不是简单 ban 掉测试目录，而是 metadata 标记 is_test/generated/vendor，在 rerank 或 fusion 前做 通道过滤或降权。这与第33讲的索引策略一脉相承：检索优化从索引第一天就要开始，而不是最后打补丁。
13. 负样本：优化检索也要收集「不该命中」的例子
离线评测不仅要标注「应该检索到什么」，还要收集「明确不该检索到什么」：例如无关语言、无关服务目录、或已废弃模块。负样本能直接暴露 BM25 过拟合关键字、或向量模型对注释噪声敏感的问题。CodeSentinel 若只优化正样本 Hit@K，很容易把上下文撑满「看似相关但其实误导」的片段。把负样本纳入回归集，是成熟团队的分水岭。
代码实战：HybridRetriever + BM25 + Rerank + ContextAssembler
依赖
chromadb>=0.5.0
rank-bm25>=0.2.2
可选（更强 rerank）：
sentence-transformers>=3.0.0
完整可运行示例（rag_optimized_pipeline.py）
"""
CodeSentinel 优化 RAG：Chroma 向量检索 + BM25 + 融合 + 重排序 + Token 预算拼装
运行: python rag_optimized_pipeline.py
"""
from __future__ import annotations
import hashlib
import os
import re
from dataclasses import dataclass
from pathlib import Path
from typing import Dict, Iterable, List, Optional, Sequence, Tuple
import chromadb
from chromadb.api.models.Collection import Collection
from chromadb.api.types import Documents, EmbeddingFunction, Embeddings
from rank_bm25 import BM25Okapi
class HashingEmbedding(EmbeddingFunction):
def __init__(self, dim: int = 128) -> None:
self.dim = dim
def __call__(self, input: Documents) -> Embeddings:
out: Embeddings = []
for text in list(input):
h = hashlib.sha256(text.encode("utf-8")).digest()
vec = []
for i in range(self.dim):
b = h[i % len(h)]
vec.append((b / 255.0) * 2 - 1.0)
out.append(vec)
return out
@dataclass
class RetrievedDoc:
doc_id: str
text: str
metadata: Dict
scores: Dict[str, float]
def tokenize(s: str) -> List[str]:
s = s.lower()
return re.findall(r"[a-z0-9_]+", s)
class BM25IndexBuilder:
def __init__(self, docs: Sequence[RetrievedDoc]) -> None:
self.docs = list(docs)
corpus = [tokenize(d.text) for d in self.docs]
self.bm25 = BM25Okapi(corpus)
def query(self, q: str, k: int) -> List[Tuple[int, float]]:
scores = self.bm25.get_scores(tokenize(q))
ranked = sorted(range(len(scores)), key=lambda i: scores[i], reverse=True)
out: List[Tuple[int, float]] = []
for i in ranked[:k]:
out.append((i, float(scores[i])))
return out
def rrf_fuse(rank_lists: List[List[str]], k: int = 60) -> List[Tuple[str, float]]:
"""Reciprocal Rank Fusion: 只看排名，融合多路 id。"""
scores: Dict[str, float] = {}
for ids in rank_lists:
for r, doc_id in enumerate(ids, start=1):
scores[doc_id] = scores.get(doc_id, 0.0) + 1.0 / (k + r)
return sorted(scores.items(), key=lambda x: x[1], reverse=True)
class HybridRetriever:
def __init__(self, coll: Collection, bm25_builder: BM25IndexBuilder, id_list: Sequence[str]) -> None:
self.coll = coll
self.bm25_builder = bm25_builder
# doc_id -> index in bm25 docs order (assumed aligned)
self.id_to_pos = {doc_id: i for i, doc_id in enumerate(id_list)}
def retrieve(self, query: str, vector_k: int = 10, bm25_k: int = 10) -> List[RetrievedDoc]:
vres = self.coll.query(query_texts=[query], n_results=vector_k)
v_ids = vres["ids"][0]
v_dist = vres.get("distances", [[None] * len(v_ids)])[0]
bm25_ranked = self.bm25_builder.query(query, k=bm25_k)
b_ids = [self.bm25_builder.docs[i].doc_id for i, _ in bm25_ranked]
bm25_scores = {self.bm25_builder.docs[i].doc_id: float(sc) for i, sc in bm25_ranked}
fused = rrf_fuse([v_ids, b_ids])
fused_ids = [fid for fid, _ in fused]
# 组装 RetrievedDoc，合并分数信息
doc_map: Dict[str, RetrievedDoc] = {d.doc_id: d for d in self.bm25_builder.docs}
out: List[RetrievedDoc] = []
for fid in fused_ids:
base = doc_map[fid]
scores = dict(base.scores)
if fid in v_ids:
idx = v_ids.index(fid)
dist = v_dist[idx]
if dist is not None:
scores["vector_dist"] = float(dist)
if fid in bm25_scores:
scores["bm25"] = bm25_scores[fid]
out.append(
RetrievedDoc(
doc_id=base.doc_id,
text=base.text,
metadata=dict(base.metadata),
scores=scores,
)
)
return out
class CrossEncoderReranker:
def __init__(self) -> None:
self.model = None
if os.getenv("USE_CROSS_ENCODER", "0") == "1":
try:
from sentence_transformers import CrossEncoder
model_name = os.getenv("CROSS_ENCODER_MODEL", "cross-encoder/ms-marco-MiniLM-L-6-v2")
self.model = CrossEncoder(model_name)
except Exception:
self.model = None
def rerank(self, query: str, docs: Sequence[RetrievedDoc], top_n: int) -> List[RetrievedDoc]:
if self.model is not None:
pairs = [[query, d.text] for d in docs]
scores = self.model.predict(pairs)
ranked = sorted(range(len(docs)), key=lambda i: float(scores[i]), reverse=True)
return [docs[i] for i in ranked[:top_n]]
# 启发式：token overlap + 路径包含关系
qtok = set(tokenize(query))
def score(d: RetrievedDoc) -> float:
dtok = set(tokenize(d.text))
overlap = len(qtok & dtok)
path = d.metadata.get("path", "")
bonus = 2 if any(t in path.lower() for t in qtok if len(t) > 3) else 0
return overlap + bonus
ranked = sorted(range(len(docs)), key=lambda i: score(docs[i]), reverse=True)
return [docs[i] for i in ranked[:top_n]]
class ContextAssembler:
def __init__(self, max_tokens: int = 800) -> None:
self.max_tokens = max_tokens
def approx_tokens(self, s: str) -> int:
# 近似：代码密度高，用 len/3 保守估计 token
return max(1, len(s) // 3)
def assemble(self, query: str, docs: Sequence[RetrievedDoc]) -> str:
header = f"[USER QUERY]\n{query}\n\n[EVIDENCE]\n"
budget = self.max_tokens - self.approx_tokens(header)
parts: List[str] = []
used = 0
seen_paths = set()
for d in docs:
path = d.metadata.get("path", "")
sym = d.metadata.get("symbol", "")
key = (path, sym)
if key in seen_paths:
continue
seen_paths.add(key)
block = f"### {path} :: {sym}\n{d.text}\n"
t = self.approx_tokens(block)
if used + t > budget:
remain = budget - used
if remain > 50:
parts.append(block[: remain * 3])
break
parts.append(block)
used += t
return header + "\n".join(parts)
def seed_collection() -> Tuple[chromadb.PersistentClient, Collection, List[RetrievedDoc]]:
persist = os.getenv("CHROMA_DIR", ".chroma_codesentinel_rag_opt")
client = chromadb.PersistentClient(path=persist)
use_real = os.getenv("USE_CHROMA_DEFAULT_EMBEDDINGS", "1") == "1"
if use_real:
coll = client.get_or_create_collection("codesentinel_rag_demo", metadata={"hnsw:space": "cosine"})
else:
coll = client.get_or_create_collection(
"codesentinel_rag_demo",
embedding_function=HashingEmbedding(128),
metadata={"hnsw:space": "cosine"},
)
docs = [
RetrievedDoc(
doc_id="a1",
text="def verify_state(expected: str, actual: str) -> None:\n assert secrets.compare_digest(expected, actual)\n",
metadata={"path": "app/auth/state.py", "symbol": "verify_state", "language": "python"},
scores={},
),
RetrievedDoc(
doc_id="a2",
text="LOG.info('token=%s', access_token) # FIXME: sensitive\n",
metadata={"path": "app/auth/callback.py", "symbol": "handle_callback", "language": "python"},
scores={},
),
RetrievedDoc(
doc_id="a3",
text="class OAuthSettings(BaseModel):\n redirect_allowlist: list[str]\n",
metadata={"path": "app/settings.py", "symbol": "OAuthSettings", "language": "python"},
scores={},
),
]
coll.upsert(
ids=[d.doc_id for d in docs],
documents=[d.text for d in docs],
metadatas=[d.metadata for d in docs],
)
return client, coll, docs
def import_aware_expand(docs: Sequence[RetrievedDoc], all_docs: Dict[str, RetrievedDoc]) -> List[RetrievedDoc]:
"""教学版：若文本出现 import 片段，尝试把同路径前缀的另一个符号拼进来。"""
expanded = list(docs)
for d in docs:
path = str(d.metadata.get("path", ""))
prefix = path.rsplit("/", 1)[0] if "/" in path else path
for cand in all_docs.values():
cp = str(cand.metadata.get("path", ""))
if cp.startswith(prefix) and cand.doc_id not in {x.doc_id for x in expanded}:
expanded.append(cand)
break
return expanded
def main() -> None:
_, coll, docs = seed_collection()
id_list = [d.doc_id for d in docs]
bm25 = BM25IndexBuilder(docs)
hybrid = HybridRetriever(coll, bm25, id_list)
query = "OAuth callback state validation and logging risk"
cand = hybrid.retrieve(query, vector_k=5, bm25_k=5)
reranker = CrossEncoderReranker()
cand2 = reranker.rerank(query, cand, top_n=3)
all_map = {d.doc_id: d for d in docs}
cand3 = import_aware_expand(cand2, all_map)
asm = ContextAssembler(max_tokens=int(os.getenv("CTX_TOKEN_BUDGET", "800")))
ctx = asm.assemble(query, cand3)
print(ctx)
if __name__ == "__main__":
main()
与 CodeSentinel 组件映射
HybridRetriever：对接第33讲索引产出与 Chroma collection。BM25IndexBuilder：可用增量方式仅对变更文件重建局部索引，或用 Lucene/OpenSearch 替换。CrossEncoderReranker：建议异步批处理；大流量时用更小模型或蒸馏模型。ContextAssembler：与 Agent 的「预算器」共享 token 计数实现。
生产环境实战
1. 分数尺度与融合参数
RRF 的 k 默认 60 通常可用，但仍建议离线扫参。若一路检索质量明显更差，应降低该路权重或先过滤噪声源（例如注释-only chunk）。
2. 延迟预算
混合 + 重排会增加 20～200ms（视模型与规模）。CodeSentinel 应对 PR 审核定义 p95 预算，并在超时下降级为单路向量。
3. 安全：查询注入与数据外泄
检索 query 可能包含工程师粘贴的栈追踪与密钥片段；日志必须脱敏。扩展查询时避免把敏感 token 写进审计日志明文。
4. 观测
记录每阶段候选数量、去重率、rerank 前后排名变化、最终上下文 token 数。没有这些指标，你无法定位「是检索烂还是生成烂」。
5. 资源与并发：重模型的位置
CrossEncoder 不建议放在 Web 请求线程内同步调用。更合理的部署是：在线检索先返回「够用」的上下文；对高风险目录或用户点击「深度分析」再异步触发重模型 rerank。CodeSentinel 可以把深度模式做成显式产品能力，既控制成本，也管理用户预期。
6. 数据隐私与留存
检索中间结果可能包含代码片段与查询文本。日志留存周期、脱敏规则、以及跨租户隔离必须与代码托管权限一致。否则会出现「检索日志比 PR 本身泄露面更大」的悖论。
基准思路：基础 RAG vs 优化 RAG
准备一个标注集：每条包含 query、gold_file、gold_symbol（可选）。比较：
- Hit@K：gold 是否出现在前 K 个 doc_id。
- MRR：首个命中排名倒数均值。
- 下游：同一上下文输入给判定模型，比较 finding F1。
教学代码未内置数据集，但你可以用第33讲索引的真实仓库快速构造 50 条起步。
结果解读：如何避免「指标变好、体验变差」
一种典型偏差是：你把 K 提得很高，Recall@K 上升，但 Assembler 只能装下前几条，真正进入 LLM 的还是老样子；另一种偏差是：rerank 过拟合短文档，长文件永远进不了最终上下文，导致「结构性问题」被系统性忽略。建议在评测报告同时打印 进入 LLM 的最终列表 的 Hit@K，而不只看召回池。对 CodeSentinel，还可以统计 评论引用路径是否命中 gold，这比抽象向量分数更接近产品价值。
本讲小结（Mermaid mindmap）
mindmap
root((第34讲 RAG优化))
痛点
文本相似≠相关
标识符与结构
混合检索
向量
BM25
RRF融合
重排序
CrossEncoder
启发式降级
上下文
token预算
路径去重
结构化增强
import扩展
调用图服务
评测
Hit@K
下游F1
思考题
- 为什么 HyDE 在代码场景风险更高？你在什么条件下才会启用？
- 如果 BM25 强烈偏向短文件，导致长文件永远进不了 topK，你如何修正？
- rerank 模型与生成模型不一致时，可能出现何种排序偏差？
对照实验模板：一周内做出「可汇报」的结论
你可以按下面模板组织实验，避免团队陷入无休止讨论。样本：至少 30 条真实查询（从事故复盘、常见审核问题、以及工程师在 PR 里常问的问题收集）。变量：基础向量 topK vs 混合检索 vs 混合+rerank。固定：同一 embedding 模型、同一 chunk 规则、同一 token 预算。指标：Hit@10、进入 LLM 的最终 5 条命中率、以及人工对「上下文是否有帮助」的二元标注。成本：记录平均延迟与单次费用。结论格式：只允许三种输出——「显著更好」「无显著差异」「变差需回滚」。没有数据就不升级，这是工程纪律。
下一讲预告
模块五后续将继续把 CodeSentinel 的 AI 子系统与治理策略平台化：监控检索质量、构建离线回放、与规则引擎/静态分析结果对齐，形成可审计的「证据链闭环」。你也可以把本讲实现的 EvidencePack 思路（检索→重排→拼装）作为监控对象：每次线上评论都记录 pack 的摘要哈希，用于对比离线回放是否一致。
深入讨论：查询变换在工程上的「边界」
查询变换（扩写、拆解、翻译）能提升召回，但也可能引入 查询漂移：模型把问题改写成仓库里不存在的 API 名称，BM25 反而命中错误文件。CodeSentinel 建议默认保守：对自然语言问题做轻量扩展，对包含精确符号的查询跳过改写。同时保留 original_query 与 rewritten_queries 双字段写入 trace，便于复盘。若你使用 LLM 做改写，务必加温度=0与短输出约束，并把改写结果经 白名单词表（安全、OAuth、并发等域词）校验后再检索。
另一个常见需求是多语言仓库：查询中文但代码英文。可以增设一步「翻译为英文关键词 + 保留中文原查询并行检索」，再用 RRF 融合。关键是不要丢失中文问题里的业务语境词，否则检索会偏向通用英文词导致泛滥命中。
再补一条实践建议：查询日志要分层存储。高频查询可以沉淀为「检索模板」或「同义词表」，反过来减少 LLM 改写次数；低频但高风险的查询（安全、合规）应保留完整文本用于审计，但要脱敏。CodeSentinel 如果只做检索不做沉淀，团队会反复在提示词里堆规则，系统复杂度会隐性上升。
代码导读：实现里刻意保留的「工程缝隙」
HybridRetriever.retrieve 为了教学清晰，重复计算了 BM25 分数；生产应缓存 get_scores 结果。import_aware_expand 只扩展一个候选，真实系统应按分数与深度预算扩展多个，并记录扩展原因供评论引用。ContextAssembler 的 token 估计非常粗，生产应使用与线上模型一致的 tokenizer（例如 tiktoken 或 HF tokenizer），否则预算会系统性偏差。
CrossEncoderReranker 默认启发式打分不是让你停留在启发式，而是保证 无重型依赖也能跑通 CI。上线前应用小样本对比启发式与 cross-encoder 的 nDCG 差异，决定是否在 GPU worker 上启用重模型。
运行提示：如何快速验证脚本
- 安装依赖后运行
python rag_optimized_pipeline.py。 - 若 CI 无外网：设置
USE_CHROMA_DEFAULT_EMBEDDINGS=0，并关注输出是否包含三段证据块。 - 想体验 CrossEncoder：安装
sentence-transformers后设置USE_CROSS_ENCODER=1（首次会下载模型）。
如果你发现 BM25 分数全为 0，通常是分词后词表与文档不匹配：可把 tokenize 换成更适配代码的正则（保留大写标识符）再做对比实验。
与 AST / 调用图协同的架构建议
当你已经有 AST chunk（第33讲），可以在 rerank 特征里加入 结构特征：候选与 PR diff 文件是否同目录、是否共享 import、是否在测试目录出现镜像文件命名。无需神经网络，这些特征对代码审核特别有效。调用图若可用，把「1-hop 邻居」作为独立检索通道，与向量/BM25 并列做 RRF，通常比单纯增大 topK 更稳。
把这些特征串起来，你会得到一个很实用的经验法则：先用便宜特征去掉明显不相关，再用昂贵模型做细排。便宜特征包括路径、模块、语言、测试标记、变更共现；昂贵模型包括 cross-encoder 与大模型二次判别。CodeSentinel 若跳过便宜特征直接上大模型，成本与延迟都会吃亏，而且会把「排序问题」伪装成「生成问题」，排障时更难。
最后提醒：优化的敌人是无止境。每增加一路检索与一个模型，都会增加故障点。CodeSentinel 的架构师要为每条增强链路定义 可关闭开关 与 默认降级路径，并在事故时一键回到「单路向量 + 小上下文」，保证审核服务可用性优先于极致智能。
落地路线图：从 0 到 1 的四阶段建议
阶段 A：单路向量 + 强 Assembler（1 周内可完成）——先解决上下文噪声与 diff 配额问题，通常就能降低一批明显误报。阶段 B：加 BM25 与 RRF（1～2 周）——成本低，收益对「标识符敏感问题」立竿见影。阶段 C：加 rerank（2～4 周）——引入 GPU/异步 worker 与评测门槛，确保不是负优化。阶段 D：结构化扩展与调用图（持续）——进入平台工程范畴，需要图数据库或静态分析管线输出。路线图的意义在于：你可以向管理层解释每一步的依赖与风险，而不是「一次性上大杂烩」。
与第31讲 Agentic RAG 的衔接说明
第31讲强调 Agent 循环与工具调用；本讲优化的 RAG 实际上是 Agent 的「观察质量增强器」。当观察输入更可靠，Agent 更少陷入反复检索；当 Assembler 明确预算，Agent 更少浪费步数去压缩上下文。建议在编排层定义统一接口：retrieve_evidence(query, constraints) -> EvidencePack，其中 constraints 包含允许的仓库、路径、语言、最大 token、以及是否需要深度 rerank。Agent 只负责提出 constraints 与解释需求，不负责直接拼接 SQL/向量参数，从而降低提示词注入与参数错配风险。
故障演练：当一路检索全挂时你怎么审？
做一次红队演练：向量库不可用、BM25 索引损坏、CrossEncoder 超时。你的系统应能：
- 降级为关键词 grep（内部受限 API）+ 当前 diff；
- 明确在评论中标注「证据受限，结论置信度下降」；
- 将任务重新排队，待检索恢复后自动重跑（可选）。
没有降级策略的「智能审核」在事故时往往变成「完全不可用」，而传统规则审核至少还能跑。CodeSentinel 的架构目标应是 智能增强的可降级系统，而不是单点智能。
术语小抄：把沟通成本降下来
- 召回（Recall）：相关文档有没有出现在候选池里。
- 精确率（Precision）：候选池里有多少真相关。
- 融合（Fusion）：把多路排序合成一个排序。
- 重排序（Rerank）：在较小候选集上精细打分。
- 预算拼装（Budgeting）：在 token 限制内选择最终上下文。
- 证据链（Evidence trail）：评论结论可回溯到哪些检索片段与工具输出。
当团队用同一套术语对话时，你会发现大量争论其实是「把生成问题误判为检索问题」或相反。CodeSentinel 的排障流程建议固定一句开场：先看 evidence trail，再看模型输出。
