企业官网建设流程全解析

向量库这个词这两年出现得越来越频繁，做语义搜索、RAG 知识库、图片去重、推荐召回、日志聚类，绕来绕去都会撞到同一个问题：关键词匹配不够用了，得拿向量算相似度。而一旦数据量从几千条涨到几百万条，暴力遍历就彻底没法看了，这时候就需要一个专门干这件事的数据库。Milvus 就是这类工具里比较主流的一个，开源、支持 Python 客户端、单机能跑、集群也能扩。我拿它做过几个不同量级的检索场景，从小规模的本地原型到千万级向量的服务端部署都趟过一遍，中间因为 Schema 设计返工过两次，因为索引参数选错被慢查询折磨过一个多星期。这篇文章就把 Python 操作 Milvus 这条链路从头到尾捋一遍：为什么这么选、参数怎么算、代码怎么写、坑在哪里。适合刚接触向量检索、准备把原型跑起来的人，也适合已经把东西跑通了但在性能和稳定性上卡住的人。

1. 先把问题想清楚：向量检索到底在解决什么

在动手写第一行连接代码之前，我建议先花二十分钟把「我要解决什么问题」想明白。这一步想岔了，后面 Schema 设计和索引选型全是白费功夫。

1.1 从关键词匹配到语义相近

传统数据库检索靠的是精确匹配和模糊匹配，like '%python%'这种。它的前提是「用户输入的词和文档里的词长得一样」。但现实里用户说「怎么把表格数据导出成文件」，文档里写的是「DataFrame 写入 CSV 的方法」，两边一个共同关键词都没有，倒排索引直接抓瞎。

向量检索换了个思路：先把文本、图片、音频这些东西送进一个编码模型，压成一串固定长度的浮点数，也就是 embedding。语义相近的内容，在这个高维空间里的距离也相近。检索的时候把查询也编码一遍，然后在这堆向量里找距离最近的若干个，就完成了「按意思找」这件事。

这个转变带来的直接后果是：索引结构变了。B 树、倒排索引那套东西对「最近邻」这个问题完全无能为力，你需要的是近似最近邻搜索（ANN）。Milvus 干的就是这件事——它把向量存起来，建好 ANN 索引，然后在你查询的时候用尽量少的计算量给出尽量准的 Top-K。这个「尽量」两个字很关键，ANN 是近似的，用一点点召回率换巨大的速度提升，这是整个向量库领域的底层交易。

1.2 为什么不是 FAISS，也不是关系型数据库加个扩展

我一开始也用过 FAISS，纯内存的向量检索库，速度快、API 干净，做离线实验非常舒服。但它的问题在于「库」和「数据库」的区别：FAISS 没有持久化的服务进程，没有并发写入的协调，没有增删改的一致性保证，多进程同时写索引基本等于自找麻烦。你要拿它做线上服务，得自己在外面套一层数据管理、版本管理、故障恢复，工作量比想象中大得多。

关系型数据库加向量扩展（比如在 PostgreSQL 上装个向量插件）是另一条路。优点很明显：不用引入新组件，事务、权限、备份这些现成的东西都能复用。但它的向量索引在海量数据下的性能上限比专用系统低不少，尤其是需要多种索引类型混用、需要按标量字段做复杂过滤再走向量检索的时候，查询计划的优化空间很有限。

Milvus 的定位在两者之间偏右：它是一个独立的分布式数据库，有 Collection、Partition、Index 这些概念，有独立的写入和查询链路，支持标量过滤和向量检索的组合，也支持多种索引类型。代价是你得维护一个额外组件。所以我的判断标准很朴素：如果向量总量在百万级以下、QPS 要求不高、团队不想多维护一套服务，那么关系型库加扩展完全够用；如果向量量级往千万走、有明确的并发要求、需要频繁做批量导入和增量更新，那 Milvus 这类专用系统省下来的调优时间远超运维成本。

1.3 什么时候该用，什么时候别硬上

有一种情况我见得比较多：项目其实只有几万条数据，检索需求也就每天几百次，却非要上一套向量数据库集群。这种属于工具反噬需求。几万条向量，用 numpy 算一遍余弦相似度也就几十毫秒，连索引都不需要建。

反过来，也有该用却没用的情况：数据量到了一两千万条，还在用内存里的字典加暴力遍历，每次查询把整个进程卡死十几秒，然后靠加机器硬扛。这时候上 Milvus 就是正确选择，而且越早越好，因为 Schema 一旦定下来再改，数据迁移的成本会翻倍。

我把判断依据整理成下面这张表，实际选型的时候可以直接对着看：

注意：上面这个分档只是经验参考，实际还要看维度。768 维和 1536 维对内存的消耗差一倍，同样的「100 万条」，在不同维度下占用完全不是一个量级。

2. 环境准备：三种跑法和它们的边界

Milvus 的部署方式有好几种，我按「你什么时候会用到它」来排一下，别一上来就照着集群文档折腾。

2.1 Milvus Lite：本地调试最快的一条路

Milvus Lite 是个嵌入式的进程内版本，通过 Python 包直接装，不需要 Docker，不需要单独起服务。用法简单到有点不真实——把 uri 换成一个本地文件路径就行：

pip install -U pymilvus

from pymilvus import MilvusClient client = MilvusClient("./milvus_local.db")

第一次跑起来的时候我还特意确认了一下是不是真的写盘了，结果重启进程数据确实还在。它适合做什么？写单元测试、做原型验证、跑离线批处理、给同事演示。我一般用一个临时文件路径跑测试用例，跑完删掉，干净利落。

它的限制也要提前知道：单进程、单机、没有分区（Partition）功能、部分索引类型不支持、不支持多副本。所以别拿它做线上服务，它的定位就是开发阶段的替身。

2.2 Standalone：绝大多数项目的实际落点

单机版是我用得最多的形态。用 Docker Compose 起一套，包含 Milvus 本体和它依赖的元数据存储、消息队列、对象存储组件。官方仓库里有现成的 compose 文件，拉下来改改端口就能跑：

wget https://github.com/milvus-io/milvus/releases/download/v2.4.9/milvus-standalone-docker-compose.yml -O docker-compose.yml docker compose up -d

起来之后默认监听 19530 端口，还有个 9091 是监控指标端口。验证一下服务是否健康：

curl http://127.0.0.1:9091/healthz

返回OK就说明组件都起来了。这里有个我踩过的坑：docker compose up -d之后立刻连库大概率会失败，因为几个依赖组件启动有先后顺序，Milvus 本体要等它们就绪。等 20 到 30 秒再连，或者写个重试循环，别急着怀疑人生。

2.3 集群模式：什么时候才真的需要

集群模式要部署多个协调节点、多个查询节点、多个数据节点，还要配独立的对象存储和消息队列集群。配置复杂度比单机高一个数量级，硬件成本也是。我见过一些团队在数据量还不到五百万的时候就直接上集群，理由是「以后要扩」，结果日常负载连单机版的十分之一都用不满，白白多了一堆运维负担。

我的建议是：先把单机版跑稳，把 Schema、索引、查询模式全部验证清楚，等真的出现「单机内存扛不住」或者「查询节点 CPU 打满」的明确信号再考虑集群。Milvus 的架构本身支持从单机平滑过渡到集群，Schema 和客户端代码基本不用改，所以不用提前交这份学费。

2.4 Python 客户端版本对齐这件事

pymilvus的版本和服务端版本存在对应关系。客户端版本太旧，连新版服务端可能报一些看不懂的 RPC 错误；客户端版本太新，连旧服务端也可能出问题。我的习惯是让客户端小版本号不低于服务端，比如服务端 2.4.9，客户端就装 2.4.x 里最新的一版。

pip install pymilvus==2.4.9

装完确认一下：

import pymilvus print(pymilvus.__version__)

遇到奇怪的连接问题，第一件事永远是核对两边版本，而不是去翻源码。这个顺序能省掉大量时间。

3. 数据建模：Schema 设计里最容易返工的部分

我在这个环节返工过两次，第一次是因为主键类型选错导致没法做增量更新，第二次是因为 VARCHAR 长度按字符数算的，中文数据一多直接越界报错。

3.1 主键、向量字段和标量字段怎么摆

一个 Collection 的结构类似关系库里的表，但字段类型是它自己的一套。常用的有INT64、VARCHAR、FLOAT、BOOL、JSON，加上专门的FLOAT_VECTOR、BINARY_VECTOR、SPARSE_FLOAT_VECTOR这些向量类型。

主键的选择有个小技巧。如果业务侧天然有稳定的整型 ID，直接用INT64做主键，最省空间也最快。如果只有字符串 ID（比如内容的哈希值），用VARCHAR做主键也行，但要意识到 Milvus 会为它维护一份倒排结构，长度越长开销越大。我后来的做法是统一把字符串 ID 做一次 64 位哈希转成INT64，冲突概率可以忽略，查询和存储都更划算。

标量字段的取舍标准很简单：你未来可能会用它做过滤的字段，现在就加上。因为 Milvus 支持在向量检索的同时带上标量过滤条件，让「在某个类别里找最相似的」这种查询一次完成。如果等数据全灌进去了才想起来要加字段，虽然可以用动态字段救急，但性能和表达力都会打折扣。

3.2 维度和度量方式：metric_type 决定一切

维度必须和你的 embedding 模型输出严格一致。常见的开源文本模型是 768 维或 1024 维，一些商业接口是 1536 维。这个数字一旦定错，写入的时候会直接报维度不匹配，改起来要重建整个集合。

度量方式有三个主要选项，选错了检索结果会明显变差：

文本语义检索场景我基本固定用COSINE。原因很实际：不同长度文本的 embedding 模长会波动，用IP的话长文本容易因为模长大而排在前面，语义相关性反而不是主导因素。用COSINE就排除了模长影响，只看方向。

如果你确实要用IP，那写入之前一定自己做一次 L2 归一化：

import numpy as np def normalize(vec: np.ndarray) -> np.ndarray: norm = np.linalg.norm(vec) if norm == 0: return vec return vec / norm

漏了这一步，检索结果会很奇怪，而且不会报错，属于最难排查的那类问题。

3.3 动态字段：好用但别滥用

enable_dynamic_field=True这个开关打开之后，插入数据时可以带 Schema 里没定义的字段，Milvus 会把它们塞进一个隐藏的 JSON 字段里。这在快速验证阶段特别好用，不用为了加个source字段就重建集合。

代价是两方面的：一是动态字段的过滤性能不如原生字段，因为要解析 JSON；二是它会让 Schema 慢慢失控，最后没人说得清线上到底有哪些字段。我的用法是：原型阶段打开，进入正式开发前把实际用到的字段全部提升为原生字段，然后关掉这个开关。这样既不耽误前期试错，也不会留下技术债。

3.4 完整 Schema 定义示例

下面是我在一个文档检索场景里用的结构，字段冗余度比较低，可以直接照抄改成自己的：

from pymilvus import MilvusClient, DataType client = MilvusClient(uri="http://127.0.0.1:19530") schema = client.create_schema(auto_id=False, enable_dynamic_field=False) schema.add_field(field_name="chunk_id", datatype=DataType.INT64, is_primary=True) schema.add_field(field_name="doc_id", datatype=DataType.INT64) schema.add_field(field_name="category", datatype=DataType.VARCHAR, max_length=64) schema.add_field(field_name="content", datatype=DataType.VARCHAR, max_length=8192) schema.add_field(field_name="create_ts", datatype=DataType.INT64) schema.add_field(field_name="embedding", datatype=DataType.FLOAT_VECTOR, dim=768)

这里有两个细节值得展开。category用VARCHAR而不是INT64，是因为它参与过滤表达式的时候可读性好很多，而且枚举值很少，存储开销可以接受。content的max_length=8192是按字节算的，中文 UTF-8 编码一个字符占 3 个字节，所以这个长度大约能放 2700 个汉字。如果你的切片长度超过这个数，会直接插入失败，报的错是长度超限。这个坑我在中文语料上踩过一次，一开始按字符数给了 4096，结果中文一进来就炸。

4. 索引选型与内存估算：参数不是拍脑袋定的

索引是这个系统里性能差异最大的一个变量。同一份数据，索引选错，查询延迟能差两个数量级。

4.1 FLAT、IVF_FLAT、HNSW 的选择逻辑

FLAT是暴力检索，不建任何索引结构，召回率百分之百，但延迟随数据量线性增长。它只适合小数据量做基准对照，或者你确实要求绝对精确且数据量很小。

IVF_FLAT是聚类倒排。建索引时把向量聚成nlist个簇，查询时只扫最近的nprobe个簇。它的优点是内存占用小、建索引快，缺点是召回率受nprobe影响大，而且数据分布不均的时候性能波动明显。

HNSW是分层可导航小世界图，查询时从稀疏的高层图逐层向下走。它是目前综合表现最好的一种：召回率高、延迟低、对数据分布不敏感。代价是内存占用大，建索引慢。我现在的默认选择基本都是它。

还有IVF_PQ这类带量化的索引，用压缩换内存，适合内存极度紧张的场景，但精度损失需要认真评估。DISKANN把索引放到磁盘上，适合内存装不下的超大规模数据，SSD 性能好的话延迟可以接受。

选择顺序我的经验是：默认HNSW，内存实在不够再考虑IVF_PQ或DISKANN，需要绝对精确且数据量小时才用FLAT。

4.2 nlist 和 ef 的计算方法

如果选了IVF_FLAT，nlist有个业界通用的经验公式：

nlist ≈ 4 × sqrt(N)

N 是向量总数。比如一百万条数据，nlist大约取 4000。取太小，每个簇太大，扫描成本高；取太大，建索引时间长，而且每个簇里的样本太少，聚类效果反而差。

查询参数nprobe是实际扫描的簇数，一般取nlist的 1% 到 10%。nprobe越大召回率越高、延迟越大。一百万条数据、nlist=4000的情况下，nprobe取 16 到 64 是比较常见的区间。

如果选了HNSW，要调的是两个参数：

• M：每个节点的最大连接数，控制图的稠密度。默认 16，常用范围 16 到 64。M越大，召回率越高，内存占用越大。对于千万级数据，我一般用 32。
• efConstruction：建索引时的搜索宽度。默认 200，常用范围 200 到 500。这个值越大，索引质量越好，但建索引越慢。

查询时还有一个ef参数，必须满足ef >= limit，实际取值一般是limit的 2 到 10 倍。比如你只取 Top 10，ef给 64 就够了；要取 Top 100，ef最好给到 300 以上。

index_params = client.prepare_index_params() index_params.add_index( field_name="embedding", index_type="HNSW", metric_type="COSINE", params={"M": 32, "efConstruction": 300}, )

4.3 内存占用的手算过程

这个必须会算，因为 Milvus 会把索引和数据加载到内存里才能提供服务，估算错了就是不断地被 OOM 打断。

向量本身的占用很好算：向量条数 × 维度 × 4 字节（float32）。一百万条 768 维向量：

1,000,000 × 768 × 4 = 3.07 GB

然后是 HNSW 索引的额外开销。图结构里每个节点要维护若干层的邻居列表，粗略按M × 2 × 4 字节估算每层每节点的出边开销，再乘上图的层数因子（通常 1.3 到 1.5 倍）。M=32 的情况下，额外开销大概是向量本身的 30% 到 50%，也就是 1 GB 到 1.5 GB。

再算上主键、标量字段、过滤用的倒排索引，一百万条数据总计大概在 5 GB 到 6 GB 之间。这个数字决定了你的机器配置下限，然后还要留出至少一倍余量给批量导入时的临时峰值和操作系统缓存。

我把常用量级粗算成一张表，方便快速对照（维度 768、float32、HNSW M=32）：

提示：这张表是粗算，实际还要看标量字段数量和过滤条件的复杂度。做容量规划的时候我习惯在这个基础上再乘 1.5，宁可多买内存也别在生产上被 OOM 叫醒。

5. 跑通第一个集合：从建表到检索的完整代码

这一节把前面所有决策落地成可执行的代码，从建集合到检索出结果，一条链路走完。

5.1 建集合与索引

from pymilvus import MilvusClient, DataType client = MilvusClient(uri="http://127.0.0.1:19530") COLLECTION = "doc_chunks" if client.has_collection(COLLECTION): client.drop_collection(COLLECTION) schema = client.create_schema(auto_id=False, enable_dynamic_field=False) schema.add_field(field_name="chunk_id", datatype=DataType.INT64, is_primary=True) schema.add_field(field_name="doc_id", datatype=DataType.INT64) schema.add_field(field_name="category", datatype=DataType.VARCHAR, max_length=64) schema.add_field(field_name="content", datatype=DataType.VARCHAR, max_length=8192) schema.add_field(field_name="create_ts", datatype=DataType.INT64) schema.add_field(field_name="embedding", datatype=DataType.FLOAT_VECTOR, dim=768) index_params = client.prepare_index_params() index_params.add_index( field_name="embedding", index_type="HNSW", metric_type="COSINE", params={"M": 32, "efConstruction": 200}, ) client.create_collection( collection_name=COLLECTION, schema=schema, index_params=index_params, )

这里我把建索引和建集合合并成一步了。create_collection传了index_params之后会自动建索引并加载集合，省掉两步手动调用。如果你习惯分步走，也可以先建集合再client.create_index然后client.load_collection，效果一样。

5.2 批量插入与数据可见性

import random import numpy as np def fake_embedding(dim=768): v = np.random.rand(dim).astype(np.float32) return (v / np.linalg.norm(v)).tolist() rows = [] for i in range(1000): rows.append({ "chunk_id": i, "doc_id": i // 10, "category": random.choice(["tech", "life", "news"]), "content": f"这是第 {i} 条测试内容", "create_ts": 1700000000 + i, "embedding": fake_embedding(), }) res = client.insert(collection_name=COLLECTION, data=rows) print(res)

insert返回里会带insert_count，可以用来校验条数对不对。

插入之后立刻查能不能查到，取决于一致性级别。Milvus 有好几档：Strong（强一致，最慢）、Bounded（有界延迟，默认）、Session（保证本会话能读到自己的写入）、Eventually（最终一致）。默认的Bounded意味着刚写进去的数据可能要等一小会儿才能查到。我一般这么处理：

client.flush(collection_name=COLLECTION)

flush会把内存里的数据落盘并让索引可见，代价是性能开销大，只适合测试和批量导入后的收尾。生产环境的查询如果对实时性敏感，可以在查询时指定更强的级别：

res = client.search( collection_name=COLLECTION, data=[query_vec], limit=5, search_params={"metric_type": "COSINE", "params": {"ef": 64}}, consistency_level="Strong", )

5.3 检索与过滤表达式

这段代码是整套东西最终对外提供能力的部分：

query_vec = fake_embedding() results = client.search( collection_name=COLLECTION, data=[query_vec], anns_field="embedding", limit=5, filter='category == "tech" and create_ts > 1700000500', output_fields=["content", "doc_id", "category"], search_params={"metric_type": "COSINE", "params": {"ef": 128}}, ) for hits in results: for hit in hits: print(hit["id"], round(hit["distance"], 4), hit["entity"]["content"])

search的返回值是一个列表的列表，外层对应每个查询向量，内层是对应的 Top-K 结果。distance的含义取决于度量方式，COSINE和IP是越大越相似，L2是越小越相似——这个方向千万别搞反，我见过把L2结果当相似度直接倒序排的代码。

过滤表达式支持的语法跟常见查询语言接近：比较运算、in、not in、and/or、范围、like "前缀%"。写的时候注意字符串要用双引号包裹，如果字符串本身含双引号，用单引号包外层。

5.4 更新与删除

Milvus 的更新其实是「删除旧记录 + 插入新记录」的语义，upsert是封装好的便捷方法：

updated = dict(rows[0]) updated["content"] = "更新后的内容" client.upsert(collection_name=COLLECTION, data=[updated])

删除支持按主键和按条件两种：

client.delete(collection_name=COLLECTION, ids=[1, 2, 3]) client.delete(collection_name=COLLECTION, filter='doc_id == 42')

这里有个容易误判的点：删除是软删除，数据不会立刻从磁盘消失，只是标记为不可见，真正的物理清理要靠后台的 compaction。所以你会看到删除之后磁盘占用没降，过一段时间才慢慢回收，这是正常现象。

6. 工程化细节：分区、批处理和混合检索

前面跑通的是最小闭环，真实项目里还有几个绕不开的工程问题。

6.1 批量插入的批次大小

一次性插几百万条会直接把你机器内存打满，因为客户端会把整个data列表序列化后发出去。我一般按 500 到 2000 条一批来切，具体看单条数据的大小。写入过程中要处理失败重试：

def batch_insert(client, collection, rows, batch_size=1000): total = 0 for i in range(0, len(rows), batch_size): batch = rows[i:i + batch_size] for attempt in range(3): try: res = client.insert(collection_name=collection, data=batch) total += res["insert_count"] break except Exception as e: if attempt == 2: raise import time time.sleep(1 + attempt) if i % (batch_size * 10) == 0: print(f"已写入 {total} 条") return total

批次太小的坏处是网络往返次数多、总耗时变长；批次太大的坏处是单次请求包体积过大，容易触发超时。我的经验是单批控制在 10 MB 到 50 MB 之间比较稳。

另外，大批量导入期间查询性能会明显下降，因为索引重建会抢资源。有条件的话把导入安排到低峰期，或者导入完成后统一建一次索引，而不是边写边建。

6.2 分区不是越多越好

Partition 是 Collection 内部的物理划分，用途是缩小检索范围。典型场景是按租户分、按日期分、按文档分。查询时指定partition_names，Milvus 就只在对应分区内检索，延迟能降一个数量级。

client.create_partition(collection_name=COLLECTION, partition_name="doc_001") client.insert( collection_name=COLLECTION, data=rows, partition_name="doc_001", ) results = client.search( collection_name=COLLECTION, data=[query_vec], limit=5, partition_names=["doc_001"], )

但分区数量不能无限加。每个分区都有独立的段文件和管理开销，分到几千个的时候，元数据管理和段合并的压力会变得很明显。我的经验是分区总数控制在几百以内。如果是按租户分，租户数量可能上万，那就别用分区，改用标量字段过滤——建一个tenant_id字段，查询时带上过滤条件，性能也不错，而且不用管分区治理。

6.3 标量过滤和向量检索的执行顺序

这是个值得搞清楚的问题。Milvus 在带过滤条件查询时，有「先过滤后检索」和「先检索后过滤」两种策略。前者精确但过滤后的候选集可能很小，图索引效果打折；后者快但可能过滤到结果不足 limit 条。

Milvus 内部会根据过滤条件的选择率自动决定。如果过滤后剩余数据很少，它会先做标量过滤，退化成小规模暴力检索，这时候反而更快也更准。如果过滤后剩余还很多，它就走正常的索引检索再过滤。

知道这个机制的好处是：当你的查询结果条数少于limit时，不要急着怀疑索引坏了，很可能是过滤条件太严，先看看过滤后的数据量到底有多少。

6.4 多向量字段与稀疏向量

一个 Collection 可以定义多个向量字段，比如同时存一个稠密向量和一个稀疏向量，然后做混合检索。这在「语义相似 + 关键词精确命中」兼顾的场景里很有用。

from pymilvus import AnnSearchRequest, RRFRanker req_dense = AnnSearchRequest( data=[dense_vec], anns_field="embedding", param={"metric_type": "COSINE", "params": {"ef": 64}}, limit=20, ) req_sparse = AnnSearchRequest( data=[sparse_vec], anns_field="sparse_embedding", param={"metric_type": "IP", "params": {}}, limit=20, ) results = client.hybrid_search( collection_name=COLLECTION, reqs=[req_dense, req_sparse], ranker=RRFRanker(k=60), limit=10, output_fields=["content"], )

RRFRanker是倒数排名融合，靠排名而不是分数来合并多路召回，好处是不用关心两路召回的分数量纲不一致。k一般取 60，这是原论文里的默认值，实际调整空间不大。

稀疏向量用来做关键词权重很合适，BM25 那套东西可以直接映射成稀疏向量。稠密负责语义泛化，稀疏负责精确命中，两路一融合，效果比单路稳定很多。这套组合我在中英文混合的语料上试过，比单用稠密向量的召回质量明显好。

7. 常见问题与排查实录

这部分是真正花时间的地方。功能跑通可能只要半天，把问题排干净要花几周。

7.1 报错与现象速查表

7.2 几个我踩得最深的坑

第一个坑：把 VARCHAR 的 max_length 按字符数理解。中文语料下，我一开始设了 4096，以为是四千个汉字，实际上是四千个字节，折合约一千三百个汉字。切片策略一变长就直接插入失败。后来统一按「预计最大汉字数 × 3 + 余量」来设，没再出过问题。

第二个坑：索引建好了但没加载。分步操作的时候，create_index只是建了索引元数据，集合还得load_collection才能查。这个状态用client.get_load_state(collection_name=...)可以查，返回Loaded才算就绪。我在这上面浪费过半天，一直以为是数据没写进去。

第三个坑：频繁小批量写入导致段文件爆炸。Milvus 每次写入会生成新的段，写入频率太高、每批数据太少的话，段数量会迅速膨胀，查询时要扫描大量小段，延迟很难看。解决办法就是前面说的合并批次，实在需要高频写入的话，定期检查段数量并依赖后台 compaction 做合并。

第四个坑：删除之后磁盘没降。前面提过，删除是软删，物理回收靠 compaction。如果磁盘告警，别指望删数据能立刻缓解，要么等，要么手动触发 compact。

第五个坑：用IP但忘了归一化。这个最隐蔽，因为完全不报错，只是检索结果排序莫名其妙。后来我干脆在数据入库的封装函数里强制做一次归一化，从流程上杜绝这个可能。

7.3 性能调优的几条实战经验

调优这件事，先定位瓶颈再动手，别一上来就改参数。我的一般顺序是：先看查询延迟的分布，是普遍慢还是只有长尾慢；再看是不是过滤条件导致的；最后才调索引参数。

ef是最直接的旋钮，从 64 开始往上加，加到召回率不再明显提升为止。别一上来就给 512，那是拿延迟换一点点召回，性价比很低。

批量导入完成后重建一次索引，往往比边写边建的质量好。因为 HNSW 的图结构在增量插入时会逐渐退化，全量重建能把质量拉回来。

另外，output_fields只填真正需要的字段。带上一个大文本字段会让返回包体积暴涨，在网络传输和反序列化上白白浪费时间。这个改动我在一个接口上做过，P99 延迟直接降了将近一半。

7.4 一个容易被忽略的检查清单

上线前我固定会过一遍这几项，每次都能发现点东西：

• Schema 里每个 VARCHAR 字段的max_length是否按字节算足了
• 索引状态是否为Loaded，get_load_state返回是否正常
• 度量方式与数据是否匹配，用IP的话归一化是否在入库链路里强制执行了
• 批量导入的批次大小是否在 10 MB 到 50 MB 区间
• 分区数量是否控制在合理范围，或者干脆改用标量过滤
• output_fields是否只包含必要字段
• 容量规划是否按 1.5 倍留了余量
• 客户端与服务端版本是否对齐

这套清单看起来琐碎，但每一条背后都对应着我真实踩过的一次故障。向量库这东西不像传统数据库那样成熟到「配好就能用」，很多参数的最优值和你的数据分布强相关，别人的经验只能给个起点，真正的答案要用自己的数据测出来。我现在的习惯是：任何一组索引参数上线前，都用一百条真实查询跑一次召回率对比，跟暴力检索的结果比一比，心里有数了再发。这一步花不了多少时间，但能挡住绝大多数「上线之后发现检索结果不对」的尴尬。