守株阁

技术文档的信息不全在文字里。一份 API 文档中的架构图、一篇论文里的实验结果表格、一页 PDF 中的流程图——这些视觉元素承载的信息量常常超过周围的文字描述。传统的文本检索管线对这些内容视而不见：OCR 提取的文字丢失版式信息，表格变成无结构的字符串，流程图直接被忽略。 多模态 embedding 模型提供了另一条路径：直接把页面图像编码为向量，跳过 OCR，保留视觉结构。 OCR 管线的局限 PDF 文档检索的传统做法： 1PDF → 逐页渲染为图像 → OCR 提取文字 → 文字进入倒排索引/embedding 这条管线在纯文字 PDF 上效果尚可，但遇到以下内容时问题显著： 表格：OCR 把表格读成一行行文字，丢失行列关系。“性能 | 100ms | 200ms"变成"性能 100ms 200ms”——搜"性能低于 150ms 的方案"时，无法区分哪个数字属于哪个方案。 图表：流程图、架构图中的文字被 OCR 提取出来，但箭头、连线、布局信息全部丢失。"A → B → C"的流程关系在纯文字中不存在。 扫描件：...

主线第 18 篇把整篇文档压缩成一个 512 维向量。这个"池化"操作不可避免地丢失信息：一篇同时讨论"线程池配置"和"垃圾回收调优"的长文档，其单向量是两个主题的模糊平均——搜任何一个主题都不会得到高分，搜两个主题的交集反而可能命中。 ColBERT（Khattab & Zaharia, 2020）提出了不同的方案：不池化，保留每个 token 的独立向量，在检索时做 token 级的细粒度匹配。 单向量的信息瓶颈 把一篇 200 个 token 的文档压缩成 1 个向量，信息压缩比是 200:1。对短文档（标题、摘要）这个损失可以接受；对长文档（技术文章、API 文档），关键细节可能被淹没。 具体场景： 123456789文档: "ConcurrentHashMap 使用分段锁实现线程安全。 初始容量默认 16，负载因子 0.75。 Java 8 之后改用 CAS + synchronized 替代分段锁。"单向量: [0.12, -0.34, 0.56, ...] ...

BM25 靠精确词匹配召回文档。用户搜"怎样并行处理"，文档里写的是"多线程编程"——BM25 一条也召不回来。dense retrieval 用向量弥补词汇鸿沟，但丢掉了精确匹配的优势：搜错误码 NullPointerException，dense 模型可能把它和所有异常类文档混在一起。 学习稀疏检索（learned sparse retrieval）试图兼得两头：保留倒排索引的精确匹配和可解释性，同时用模型扩展词汇覆盖范围。 词汇鸿沟的代价 回顾 BM25 的召回逻辑：query 中的 term 必须出现在文档中，文档才能进入候选集。这意味着： 同义词缺失：用户搜"取消订单"，文档写的是"订单退回"→ 无命中 上下位词：搜"数据库"，文档讨论的是"PostgreSQL"→ 无命中 缩写/全称：搜"JVM"，文档写的是"Java 虚拟机"→ 无命中 传统解法是同义词表。第 13 篇介绍的同义词扩展能缓解部分问题，但...

30 篇文章构建了一个完整的搜索引擎：从爬虫到倒排索引，从 BM25 到向量搜索，从单机到分片，从权限过滤到相关性迭代。 本篇把所有组件打包成一个可以从空目录启动的完整系统，写清楚 README，固定测试数据，提供完整运行脚本，并诚实列出限制。最终演示覆盖查询、修改、删除、模型停机、进程重启、重新查询的全过程。 项目结构 目录布局 1234567891011121314151617181920search-engine/├── README.md├── pom.xml├── run.sh # 一键启动脚本├── demo.sh # 全流程演示脚本├── data/│ ├── seed-corpus.jsonl # 固定测试语料│ └── eval-queries.jsonl # 评测查询集├── config/│ └── search-config.yaml # 配置文件├── src/main/java/search/│ ├── crawl/ ...

前 28 篇构建了一个功能完整的搜索系统。但"能跑"和"搜得好"之间还有距离。搜索相关性需要持续迭代——改了分词器、加了同义词、调了 BM25 参数，怎么判断是变好了还是变差了？ 本篇建立可重复的相关性迭代流程：归因失败查询、做盲评、写离线实验报告、设计 A/B 实验。每次变更都有证据支撑接受或拒绝的决定。 失败查询归因 什么是失败查询 评测集中 nDCG@10 = 0 的查询是明确的失败查询——Top-10 中没有相关文档。但更多失败是隐性的： nDCG@10 < 0.3：有相关文档但排位很低 Recall@100 = 0：相关文档根本不在召回集中 用户从搜索结果页直接退出（线上才能观测到） 四类失败 1234567891011121314151617181920212223242526272829303132333435363738enum FailureType { COVERAGE, // 相关文档不在索引中 RECALL, // 在索引中但未被召回 RANKING, ...

搜索引擎返回的结果必须尊重访问权限——用户不该看到无权访问的文档，哪怕那个文档与查询高度相关。同时需要过滤垃圾页和限制恶意查询，防止低质量内容和滥用行为影响系统。 本篇在检索内部实现权限过滤，而不是在结果页面上隐藏。同时处理租户隔离、垃圾页过滤、查询限额和缓存泄漏。 文档级权限过滤 为什么必须在检索阶段过滤 错误做法：先检索 Top-10，再过滤掉无权限的文档。 问题：如果 Top-10 中有 8 条无权限，过滤后只剩 2 条结果。用户看到的结果数量不可预测，体验极差。更严重的是，排序位置本身就泄露了信息——"第一条结果被过滤了"告诉用户那个位置有内容存在。 正确做法：在 Lucene 检索遍历倒排列表和 HNSW 图时过滤。过滤后的文档不参与评分和排序，就像它们不存在一样。 权限模型 每个文档存储一个访问控制列表（ACL），记录哪些用户或角色可以访问： 12345678910111213141516171819void indexDocumentWithAcl(IndexWriter writer, String docId, String ...

上一篇把索引拆成了多个分片。分片解决了容量问题，但带来了新问题：一个分片进程挂了，那个分片上的文档就搜不到了。 本篇用只读副本实现读取冗余，用健康检查发现故障节点，用快照备份保证数据可恢复。目标：停一个进程后查询仍然可用（降级），从快照恢复后数据损失可量化（RPO/RTO）。 只读副本 为什么要副本 单个分片只有一个进程时： 进程挂了 → 该分片所有文档不可搜索 升级或重启 → 搜索服务中断 副本让同一个分片的数据存在于多个进程上。主节点负责写入，副本负责查询。 基于已提交快照的同步 主节点 writer.commit() 后，副本从共享目录打开新的 reader： 123456789101112131415161718192021222324252627282930class PrimaryNode { private final IndexWriter writer; private final Path indexDir; void indexAndCommit(Document doc) throws IOException {...

单机索引有容量天花板。内存装不下全部 HNSW 向量时，要么做量化压缩（第 22 篇），要么把索引拆到多个进程上。量化只能压缩 4 倍，而索引拆分没有理论上限。 本篇把索引拆成多个分片，用 scatter/gather 模式分发查询，在 coordinator 上合并全局 Top-K。重点处理分片内 BM25 统计偏差和跨分片评分可比性。 为什么要分片 单机瓶颈 文档数 倒排索引 HNSW(int8) Stored fields 合计 10K 50 MB 23 MB 20 MB ~93 MB 100K 500 MB 230 MB 200 MB ~930 MB 1M 5 GB 2.3 GB 2 GB ~9.3 GB 10M 50 GB 23 GB 20 GB ~93 GB 10M 文档需要 93 GB 内存——超出大多数单机配置。即使装得下，查询延迟也随文档数增长。 分片的收益 将 10M 文档拆成 10 个分片，每个分片 1M 文档： 每个分片只需 ~9.3 GB 内存 查询延迟接近 1M 文档的水平（各分片并行执行） 单个分片故障不影响其他分...

到目前为止，索引中的文档是一次性灌入的。真实搜索引擎的内容不断变化——新页面发布、旧页面修改、过期页面删除。搜索引擎需要持续追踪这些变化，保持索引的新鲜度。 本篇实现持续采集系统：条件请求避免无谓下载，自适应调度控制抓取节奏，有界队列和背压防止资源耗尽，幂等写入保证重试安全，状态持久化保证重启不丢进度。 条件请求 HTTP 条件请求机制 HTTP 协议内置了条件请求机制，避免重复下载未变化的内容。 Last-Modified / If-Modified-Since： 123456789101112131415161718192021222324record CrawlMetadata( String url, String etag, String lastModified, long lastCrawledAt, int consecutiveNotModified, int consecutive404) {}HttpResponse<String> conditionalFetch(CrawlMetada...

搜索系统的各阶段——查询解析、BM25 召回、向量召回、融合、重排——性能特征各不相同。不做测量就不知道瓶颈在哪里，不知道瓶颈就无法有效优化。 本篇为搜索请求建立端到端的性能剖面，用冷热缓存压测暴露真实延迟，用容量账本规划资源预算。 阶段计时 SearchTrace 一个贯穿请求生命周期的计时器，记录每个阶段的耗时： 12345678910111213141516171819202122232425class SearchTrace { private final long requestStartNanos = System.nanoTime(); private final Map<String, Long> stageStartNanos = new LinkedHashMap<>(); private final Map<String, Long> stageDurationMicros = new LinkedHashMap<>(); void stageStart(String sta...