Token Lab搜索

从这里开始:本地证据检索助手

从零搭建第一个证据检索助手:完整本地基线

把一组小文档变成确定性、可追溯来源的响应系统。先理解契约,实现检索与拒答,再用这条基线判断加入语言模型或 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” 得分全零,尽管人可能联想到超时。这是方法反例,不是算术错误。降低阈值会增加返回量,也增加弱匹配;提高阈值不能解决同义词。覆盖率不能被包装成置信度或答案正确率。

IDQ ∩ Ds(Q,D)
D1timeout, retry2/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.py
import 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

预期:默认查询返回 、,、;D3 不出现。测试报告 7 tests 和 OK。“quasar orbit” 返回 abstain,text/source 为 null。unittest 时间取决于机器,不是性能结论。

公平比较:固定语料、查询列表与权限。先只把阈值从 0.5 改为 0.75,再还原阈值并预计算文档词集合。前者改变行为,后者应保持行为。分别记录返回证据、不充分返回和拒答。在开发集选阈值,用新留出集报告最终结果;这里的小样例是单元测试,不是部署质量证据。

原创模拟面试题——非公司面试真题

为什么 1 分不代表答案正确?

提示:比较词覆盖与语义。答案:“do not retry timeout requests” 包含全部查询词,却改变了指令。本方法不理解否定或蕴含;应加入反例与证据支持检查。

为什么轨迹构造前就要过滤?

提示:诊断也是输出。答案:只隐藏原文不够,私有 ID 和分数也可能泄露。先过滤可从所有结果通道移除这些候选,但仍未实现身份认证授权。

如何在不改变答案的前提下加速?

提示:找重复计算。答案:为不可变语料版本缓存词集合,验证各查询排序分数和同分处理不变。文档或分词器变化时失效。先证明等价再测性能。

评分:1 分——复述定义;2 分——完成手算;3 分——运行并解释全部测试;4 分——增加新的失败案例与公平比较;5 分——独立实现扩展、保持契约并解释剩余失败模式。这是学习标准,不是职业认证。

参考资料与下一篇教程

AI/LM 系统课程:学习、实现与解释 →
学习指南与本课目录学习目标与验收

理解 → 实现 → 研究

目标:解释本课机制、复现一个例子、测试一个失败案例。读完不自动代表掌握。

预测、检验与证据记录

展开答案前先预测一个结果;练习后记录差异和迁移测试。记录仅存本地,在不同语言版本间共用。

打开记录/导出/清除 →

数学复核范围逐篇记录,不代表完成论文实证复现;可在笔记中记录疑似错误。 复核范围