从这里开始:本地证据检索助手
从零搭建第一个证据检索助手:完整本地基线
把一组小文档变成确定性、可追溯来源的响应系统。先理解契约,实现检索与拒答,再用这条基线判断加入语言模型或 Agent 是否真正改善系统。
来源与版本详情
本文目录
1. 问题与交付目标
假设值班工程师用 “timeout retry” 搜索操作手册。在做对话 Agent 之前,先把简单系统做好:找到公开段落,保留来源 ID;没有词法证据时不返回段落。这个助手返回文档原文,不生成自由文本。它是未来 AI 应用的信息检索基线,不是 LLM、语义搜索引擎或安全生产服务。
交付物是一份可运行 Python 程序和独立测试文件。你将解释响应结构,手算一次排序,复现一个已知失败,并指出未来模型推理可以接入的位置。建议安排一到两个专注学习时段;这是计划建议,不是实测完成时间。
2. 先修知识及其作用
Python 函数把输入变成输出,字典给输出字段命名。集合去掉重复词,所以重复查询词不会在本算法中增加权重。文档 ID 是稳定引用;列表位置会随排序变化。冻结的 dataclass 能阻止意外字段赋值,却不能验证数据来源,也不能阻止调用方替换整个集合。
基线是行为固定、刻意简化的比较对象。拒答表示没有满足明确规则的证据,不代表证明答案不存在。轨迹记录候选如何排序。这些定义很重要:流畅的生成回答可能掩盖检索失败,高分也可能选中无关段落。
3. 架构与数据契约
语料包括 D1 重试说明、D2 密钥轮换说明、D3 受限事故记录。命令行把查询交给 answer(),程序先校验类型与长度,再分词。仅公开文档的过滤发生在评分和轨迹构造之前,避免受限 ID 通过诊断结果泄露。这个过滤是教学策略,不是基于身份的授权;程序没有登录或租户系统。
输出包含 status、text、source 和 trace。status 为 evidence 或 abstain;拒答时 text 与 source 都为 null。分数无量纲,source 是 ID 而不是 URL。非法输入抛出 ValueError,不伪装成成功的空回答。程序无网络、持久化或副作用,不需要重试与事务机制;以后加 HTTP 服务时,应在边界实现认证、配额、期限与脱敏。
4. 推导评分并手算实例
令 Q 为归一化查询词集合,D 为候选文档词集合。分数是查询词被文档覆盖的比例。这个量不对称:额外文档词不会受罚。“timeout retry” 的 Q 有两个词,D1 包含两者,得 2/2=1;D2 一个都没有,得 0/2=0。D3 被过滤,不是被打零分。阈值为 0.5,恰好等于阈值也会接受。
“timeout missing” 使 D1 得 1/2,即使半个问题没有支持仍返回证据。“connection stalled” 得分全零,尽管人可能联想到超时。这是方法反例,不是算术错误。降低阈值会增加返回量,也增加弱匹配;提高阈值不能解决同义词。覆盖率不能被包装成置信度或答案正确率。
| ID | Q ∩ D | s(Q,D) |
|---|---|---|
| D1 | timeout, retry | 2/2 = 1 |
| D2 | ∅ | 0/2 = 0 |
5. 实现选择与适用边界
terms() 转小写并提取 ASCII 字母和数字,是这个英文样例的词法切分器,不是模型 tokenizer。它没有中日文分词、词干提取、Unicode 归一化或停用词删除。五语教材共享英文测试数据,以保持预期输出一致。真实多语言系统需要合适的文本分析与新的评测集。
N 个可用文档、平均 L 字符时,每次查询约重新切分 N×L 个字符,并用 O(N log N) 排序。三个文档可接受,大语料不可照搬。可先预计算文档词集合,再引入倒排索引,并将索引与原文共同版本化;过期索引可能指向已不存在的证据。按 ID 处理同分,保证输入顺序变化时行为稳定。
6. 理解基线后再扩展
BM25 引入词频、稀有度和长度影响,稠密检索引入基于表示的相似度;两者都不能自动证明证据回答了问题。若加入生成器,只传入允许访问的检索文本,并在独立结构化字段中保留来源 ID。文档里的指令是不可信数据,不能执行;要核对生成引用,而非接受模型编造的 ID。完整 RAG 还需要摄取、新鲜度、访问校验与证据充分性。
下一步不是“把所有框架加上”。读 RAG 综述选择一项检索改进,读 SDE 教程理解模型调用边界;只有需要工具和有状态动作时再进入 SRE Agent 教程。比较版本时保持相同留出任务,否则数据变化可能伪装成架构进步。
7. 实践与验证
新建空目录,把下面两份文件保存为 assistant.py 和 test_assistant.py。使用 Python 3.11 或更高版本;无需第三方依赖、下载或 API Key。不使用随机采样,因此无需随机种子。从该目录执行命令。源码和测试完整给出,没有隐藏 helper 或远程数据集。
assistant.py
下载 assistant.py"""Offline, deterministic retrieval baseline. Python 3.11+, standard library only."""
import json
import re
import sys
from dataclasses import dataclass
@dataclass(frozen=True)
class Document:
id: str
text: str
audience: str = "public"
DOCS = (
Document("D1", "Retry timeout requests with backoff."),
Document("D2", "Rotate access keys every month."),
Document("D3", "Private incident recovery password.", "restricted"),
)
def terms(text):
return set(re.findall(r"[a-z0-9]+", text.lower()))
def answer(query, docs=DOCS, threshold=0.5):
if not isinstance(query, str) or len(query) > 2000:
raise ValueError("query must be a string of at most 2000 characters")
if not 0 < threshold <= 1:
raise ValueError("threshold must be in (0, 1]")
if len({d.id for d in docs}) != len(docs):
raise ValueError("duplicate document ID")
q = terms(query)
candidates = []
for doc in docs:
if doc.audience != "public":
continue # Filter before ranking or constructing the trace.
score = len(q & terms(doc.text)) / len(q) if q else 0.0
candidates.append((score, doc.id, doc.text))
candidates.sort(key=lambda row: (-row[0], row[1]))
trace = [{"id": d, "score": s} for s, d, _ in candidates]
if not candidates or candidates[0][0] < threshold:
return {"status": "abstain", "text": None, "source": None, "trace": trace}
_, doc_id, text = candidates[0]
return {"status": "evidence", "text": text, "source": doc_id, "trace": trace}
if __name__ == "__main__":
query = " ".join(sys.argv[1:]) or "timeout retry"
print(json.dumps(answer(query), indent=2))
test_assistant.py
下载 test_assistant.pyimport unittest
from assistant import answer, Document
class ContractTests(unittest.TestCase):
def test_known(self):
r = answer("timeout retry")
self.assertEqual((r["status"], r["source"]), ("evidence", "D1"))
self.assertEqual(r["trace"][0]["score"], 1.0)
def test_unknown_and_empty(self):
for query in ("", "quasar orbit", "日本語"):
self.assertEqual(answer(query)["status"], "abstain")
def test_no_private_trace(self):
r = answer("private incident recovery password")
self.assertEqual(r["status"], "abstain")
self.assertNotIn("D3", str(r))
def test_stable_tie(self):
docs = (Document("B", "retry"), Document("A", "retry"))
self.assertEqual(answer("retry", docs)["source"], "A")
def test_boundaries(self):
self.assertEqual(answer("timeout missing")["status"], "evidence")
self.assertEqual(answer("timeout missing extra")["status"], "abstain")
self.assertEqual(answer("retry", ())["status"], "abstain")
def test_invalid(self):
for query in (None, "x" * 2001):
with self.assertRaises(ValueError): answer(query)
with self.assertRaises(ValueError): answer("retry", threshold=0)
with self.assertRaises(ValueError): answer("retry", (Document("A", "x"), Document("A", "y")))
def test_lexical_failure_is_visible(self):
# Semantically similar wording is intentionally NOT solved by this baseline.
self.assertEqual(answer("connection stalled")["status"], "abstain")
if __name__ == "__main__":
unittest.main()
python3 assistant.py "timeout retry"
python3 assistant.py "quasar orbit"
python3 -m unittest -v test_assistant.py预期:默认查询返回
公平比较:固定语料、查询列表与权限。先只把阈值从 0.5 改为 0.75,再还原阈值并预计算文档词集合。前者改变行为,后者应保持行为。分别记录返回证据、不充分返回和拒答。在开发集选阈值,用新留出集报告最终结果;这里的小样例是单元测试,不是部署质量证据。
原创模拟面试题——非公司面试真题
为什么 1 分不代表答案正确?
提示:比较词覆盖与语义。答案:“do not retry timeout requests” 包含全部查询词,却改变了指令。本方法不理解否定或蕴含;应加入反例与证据支持检查。
为什么轨迹构造前就要过滤?
提示:诊断也是输出。答案:只隐藏原文不够,私有 ID 和分数也可能泄露。先过滤可从所有结果通道移除这些候选,但仍未实现身份认证授权。
如何在不改变答案的前提下加速?
提示:找重复计算。答案:为不可变语料版本缓存词集合,验证各查询排序分数和同分处理不变。文档或分词器变化时失效。先证明等价再测性能。
评分:1 分——复述定义;2 分——完成手算;3 分——运行并解释全部测试;4 分——增加新的失败案例与公平比较;5 分——独立实现扩展、保持契约并解释剩余失败模式。这是学习标准,不是职业认证。