第一次跑通向量检索：一个新手的 7 天踩坑记录

公司接了个新需求，要在搜索功能里加上"语义检索"能力。本人之前只用过传统关键词搜索，Embedding、向量库这些都只是听过没真用过。抱着"边学边做"的心态，花了 7 天把第一个版本跑通了，简单记录一下过程。
Day 1-2：装环境、装库
看了一圈，决定用 BGE-small-zh-v1.5（中文 Embedding 模型，体积小）+ Qdrant（向量数据库）这个组合。
BGE 比较好装，pip 装 sentence-transformers，下载模型权重就完事了。第一次跑模型推理的时候 GPU 显存爆了——同事告诉我小模型也吃显存，把 batch_size 从 32 调到 1 就跑起来了。
Qdrant 也比较友好，docker 一行命令就能起，UI 也能直接看向量数据。
Day 3-4：跑通 demo
按照官方文档抄了一段代码，能把"苹果"和"iPhone"映射到相似向量上，激动了一下。
但是 demo 只能跑通"单条查询 → Top3 文档"这个流程，离真正能用的搜索还差得很远。
最大的坎是：怎么把已有的 100 万条文档批量灌进 Qdrant？一开始我用单条插入，跑了 3 个小时才 5 万条。后来查文档发现 Qdrant 支持批量上传 + 异步写入，重写代码后 100 万条数据 20 分钟就跑完了。
Day 5-6：数据准备、效果调优
数据准备比想象中麻烦很多：
文档里有大量 HTML 标签、特殊字符、停用词，需要先清洗
文档长度从 50 字到 50000 字不等，需要按长度分桶
Embedding 模型对短文档（< 20 字）效果差，需要做 chunking 切分
效果调优过程：第一版用默认的余弦相似度，Top10 准确率只有 60%。把 query 也做一遍 Embedding（而不是直接用关键词），准确率提到 75%。加上 query expansion（同义词扩展），准确率提到 82%。加上去停用词、文本归一化，准确率提到 87%。
Day 7：上线
最后一天做的是"能稳定跑起来"，包括：写了一个简单的 API 包装（FastAPI + gunicorn）、加上监控（向量检索 QPS、P99 延迟、Top10 准确率抽样）、写了一个 fallback 机制（向量检索失败时降级到 BM25）。
上线当天没出问题，线上的真实查询跑了一周，Top10 准确率稳定在 85%-90% 之间，已经达到业务要求了。
7 天下来最大的感受是：向量检索的"门槛"没有想象中那么高，主流框架（sentence-transformers + Qdrant）的文档都比较友好，按文档一步步来就能跑通。但工程上的"坑"比想象中多——文档清洗、chunking 策略、效果评估这些看似简单的环节，做不好就会拉低整体效果。
下一步准备尝试 BGE 的大模型版本（bge-large-zh-v1.5），看看准确率能不能再上一个台阶。