语义搜索
知识库简介
语义搜索的输入不是“一个字符串”，而是带身份、时间和业务条件的信息需求；输出不是最终答案，而是一组可追溯、已授权、足够高召回的证据候选。完整的第一阶段检索通常组合：
- 关键词/BM25 等词面信号；
- Embedding 产生的稠密向量信号；
- 可选的学习式稀疏表示；
- tenant、ACL、状态、语言、产品和有效期等硬过滤；
- RRF 或经校准的分数融合；
- query—document relevance judgment 与离线/在线评测。
语义搜索不等于向量相似度：错误码、型号、数字、否定和专名常需要词面通道；“语义相似”也不等于“回答了问题”。检索系统必须能解释每个候选来自哪一路、满足什么权限、使用哪个表示版本，以及在本地 query 集上是否改善业务相关性。
能力边界
在总路线中的位置
本库位于“检索与数据”知识域。在 RAG 角色路径中，文档解析、Chunking策略 和 知识库构建 产生可追溯检索单元，Embedding 与 向量数据库 提供稠密表示和执行基础。本库把这些组件组合为可评测的召回系统，再进入 Reranking；这里表达集成顺序，不新增整门课程硬前置。
学习目标
完成本库后，你应能：
- 区分用户原话、信息需求、query、document/chunk、qrels 与最终答案；
- 为不对称检索定义 query/document 编码、文本拼接、截断和版本契约；
- 解释 BM25 的词频、文档频率和长度归一化直觉；
- 正确使用 cosine、dot/L2，拒绝跨模型直接比较原始分数；
- 比较 sparse/keyword、dense 和 hybrid 三条独立基线；
- 用 RRF 融合不可比的通道排名，并理解 rank window 与候选预算；
- 从可信身份构造 tenant/ACL filter，使空权限和异常状态 fail-closed；
- 设计包含同义改写、错误码、数字、否定、多语言、无答案和权限边界的 query 集；
- 区分 ANN recall、业务 Recall@k/Hit@k、MRR、nDCG 与安全门禁；
- 用可重复实验判断 query 改写、过滤、融合或模型升级是否真正改善系统。
前置知识
- 向量基础：余弦、点积、距离与 top-k；
- Embedding：模型角色、空间契约与迁移；
- 向量数据库：exact/ANN、payload filter 与索引；
- 数据标注：标注规范、一致性与 adjudication；
- 评测体系：后续会把离线检索指标纳入系统级评测。
只需会运行 Python 3 标准库脚本；本库不要求真实模型、数据库或 API key。
核心术语
| 术语 | 初学者解释 | 不能混淆 |
|---|---|---|
| information need | 用户真正想解决的问题 | 不等于原始字符串 |
| query | 一次可回放检索请求，含文本、身份、过滤和版本 | 改写后仍须保留 original query |
| document / passage | 可被返回、评判并追溯来源的检索单元 | 应与线上返回单位一致 |
| qrels | query 对 document 的相关性标注 | 不是数据库权限表 |
| sparse / lexical | 由词项及权重表示，适合倒排索引 | BM25 与学习式 sparse 不是同一算法 |
| dense | 固定维向量近邻检索 | 相似度不是相关概率 |
| first-stage retrieval | 廉价地产生较大候选集 | 不追求最终完美排序 |
| fusion | 合并多路候选 | 原始分数不能默认直接相加 |
| rank window | 每路进入融合的最大候选数 | 不等于最终 top-k |
| hard filter | tenant、ACL、状态、有效期等不可违反条件 | 不能在生成后补救 |
推荐学习顺序
| 顺序 | 课程 | 学习产出 |
|---|---|---|
| 1 | 边界与检索单元 | query/document/qrels、相关性等级和无答案规则 |
| 2 | Query 与 Document 表示 | sparse/dense 输入、编码与版本契约 |
| 3 | 相似度、分数与阈值 | 分数方向、候选预算、阈值与去重实验 |
| 4 | 稀疏、稠密与混合检索 | BM25、dense、RRF 三条可比较基线 |
| 5 | Query 处理与过滤 | 可降级 query pipeline 与 fail-closed filter |
| 6 | 召回与离线评测 | 分层 query/qrels、指标、错误分类与发布门禁 |
| 7 | 项目：离线混合检索 | 严格 fixture 上的 BM25 + toy dense + RRF 实验 |
前两课先定义“搜什么”和“如何表示”，第 3～5 课构造安全召回管线，第 6 课建立证据，最后通过项目复现结果。
动手实践入口
- semantic-search-fixture.json：10 条文档、7 条 query、graded qrels、tenant/ACL/status 和手工单位向量；
- toy_semantic_search.py：严格加载、中文二字符/BM25、exact dense、RRF、指标与
protected_audit安全报告； - test_toy_semantic_search.py：34 项契约、数学、检索、权限、评测和 CLI 测试；覆盖重复排名拒绝与完整候选窗口安全审计。
从项目根目录（同时包含 docs/ 与 .website/）运行：
$env:PYTHONDONTWRITEBYTECODE = '1'
python -B -W error '.\docs\语义搜索\examples\toy_semantic_search.py' `
--fixture '.\docs\语义搜索\examples\semantic-search-fixture.json' `
--top-k 3 `
--rank-window 5 `
--rrf-constant 60Fixture 中的 dense 向量是人为一热向量，只用于验证管线因果关系；它不是 Embedding 模型，也不能证明中文语义质量。fixture 里的 tenant/ACL 是教学数据，真实身份、授权、撤权、缓存失效和审计访问控制必须由系统边界另行实现；项目的 protected_audit envelope 含 qrels、禁返集与完整候选窗，不能直接投影给用户。
掌握标准
- 我能写出线上 query/document 单元、相关性等级和无答案规则。
- Query/document 表示具有模型、revision、前缀、截断、归一化与 metric 契约。
- 我能解释 BM25 为什么偏好稀有匹配并抑制长文词频堆叠。
- Sparse、dense、hybrid 分别评测，融合记录每路 rank/score。
- Tenant、ACL、status 和有效期在评分前生效，空身份 fail-closed。
- 我不会把 cosine 阈值、RRF 常数或厂商默认写成普适真理。
- Query 集覆盖真实频率、高风险长尾、hard negatives 与权限边界。
- 报告 Recall/MRR/nDCG、p95/p99、no-result、安全错误与索引新鲜度。
- 模型或 query pipeline 升级能回放旧请求、分层比较并回滚。
与其他知识库的关系
| 知识库 | 关系 |
|---|---|
| Chunking策略 | 决定 document/passages 的边界、上下文和去重单元 |
| Embedding | 提供 dense query/document 表示及兼容性契约 |
| 向量数据库 | 执行 exact/ANN、payload filter、分片和生命周期 |
| Reranking | 在召回候选上联合判断 query—document relevance |
| RAG | 消费已授权候选，组织引用和生成 |
| 评测体系 | 将检索指标、安全门禁与端到端任务质量联结 |
| 运行监控 | 监测延迟、无结果、通道贡献、漂移和新鲜度 |
主要参考资料
- Robertson & Zaragoza, The Probabilistic Relevance Framework: BM25 and Beyond
- Karpukhin et al., Dense Passage Retrieval
- Cormack, Clarke & Buettcher, Reciprocal Rank Fusion
- Thakur et al., BEIR
- Muennighoff et al., MTEB
- Sentence Transformers: Semantic Search
- Elasticsearch: Reciprocal rank fusion
- Qdrant: Hybrid and Multi-Stage Queries
来源获取/复核日期：2026-07-22。模型、SDK、产品 API、融合参数和默认值会变化；锁定版本后仍须用本地 query/qrels 复验。