NoSQL 与搜索 / 知识点
向量数据库操作速查手册
手册条目
组合向量相似度与关键词检索,提高专有名词和语义内容的召回效果。
执行混合检索
当查询既可能包含产品编号、缩写等精确词,也可能是自然语言描述时,同时召回稠密向量与稀疏向量结果,再用 RRF 融合。Qdrant Query API 通过 prefetch 执行多路子查询,并在主查询中统一排序。:contentReference[oaicite:0]{index=0}
命令定位
调用 POST /collections/{collection}/points/query。集合必须预先配置同一批 point 的命名向量 dense 与 sparse,写入时也必须同时保存两种表示。
下面示例假设 dense 为 4 维,仅用于展示请求结构;生产环境要替换成当前嵌入模型的真实维度和查询向量。稀疏向量的 indices 必须沿用建库时的词表编号。
基本语法
export QDRANT_URL='http://localhost:6333'
export COLLECTION='documents'
# 集合必须已存在 dense 与 sparse 两个命名向量字段。
# prefetch 扩大候选集,主查询只返回融合后的前 10 条。
curl -sS -w '\nHTTP %{http_code}\n' -X POST \
"${QDRANT_URL}/collections/${COLLECTION}/points/query" \
-H 'Content-Type: application/json' \
-d '{
"prefetch": [
{
"query": {"indices": [17, 204], "values": [1.0, 0.7]},
"using": "sparse",
"limit": 50
},
{
"query": [0.12, 0.34, 0.56, 0.78],
"using": "dense",
"limit": 50
}
],
"query": {"rrf": {}},
"limit": 10,
"with_payload": ["title", "doc_id"]
}'预期输出
{"status":"ok","time":<TIME>,"result":{"points":[{"id":<ID>,"version":<ID>,"score":<FUSION_SCORE>,"payload":{"title":"<TEXT>","doc_id":"<ID>"}}]}}
HTTP 200读取时先确认 HTTP 200 与 status=ok;最终顺序以 result.points 为准。score 是融合分数,不应与单独的余弦相似度或 BM25 分数直接比较;<TIME>、<ID> 和分数会随数据与版本变化。
常用参数
| 参数 | 用法 |
|---|---|
prefetch[].using |
指定本路使用的命名向量,例如 dense、sparse |
prefetch[].limit |
每路候选数,通常设为最终 limit 的 3~10 倍后压测 |
query.rrf |
按各路名次融合,适合原始分数量纲不同的通道 |
filter |
限定租户、权限、语言或时间范围,避免融合后再做越权过滤 |
with_payload |
只返回展示所需字段,减少网络传输与反序列化开销 |
分页使用 offset 时,每个 prefetch 的候选数至少覆盖 limit + offset,否则后续页可能为空。:contentReference[oaicite:1]{index=1}
高频用法
- 专有名词检索:稀疏通道命中型号、错误码、SKU,稠密通道补充同义表达和上下文。
- 知识库问答:稀疏通道保留术语精度,稠密通道召回语义相近段落,再交给重排或生成模型。
- 带权限检索:两路使用相同租户与 ACL 过滤条件,避免先召回无权限数据再在应用层删除。
风险与边界
- 触发条件:直接把稠密相似度与稀疏分数加权相加。可能后果:高量纲通道长期压制另一通道。安全替代:优先使用 RRF,或先离线校准、归一化后再加权。
- 触发条件:prefetch 候选数过小。可能后果:正确文档未进入融合池,最终调大
limit也无法恢复。安全替代:用离线评测逐步增加候选数,并同时观察召回率和 P95 延迟。 - 触发条件:查询向量维度、命名或稀疏词表与集合不一致。可能后果:请求报错或关键词召回失真。安全替代:把模型版本、维度和词表版本写入配置并在启动时校验。
排障清单
- 返回未知向量名:检查集合 schema 与
using是否逐字一致。 - 返回维度错误:确认查询编码器与入库编码器使用同一模型版本。
- 结果为空:分别执行 dense-only 与 sparse-only 查询,判断是过滤条件、词表还是向量生成问题。
- 延迟突增:缩小 prefetch、关闭不必要的 payload/vector 返回,并检查过滤字段是否建立索引。
速查:先保证两路单独检索正确,再启用融合;混合检索不能修复错误的向量、词表或权限过滤。
对多个向量字段、查询策略或召回通道的结果进行统一融合排序。
合并多路检索结果
当结果来自多个向量字段、不同嵌入模型、关键词引擎或规则召回通道时,先按稳定文档 ID 去重,再用 RRF 统一排序。RRF 只依赖各路名次,可避免直接相加余弦分数、BM25 分数等不同量纲的值。:contentReference[oaicite:2]{index=2}
命令定位
同一 Qdrant 集合内的多路查询优先使用服务端 prefetch + rrf,减少网络往返。结果跨数据库、跨搜索引擎,或需要自定义通道权重和业务规则时,在应用层融合更容易控制。
融合前为每路保留有序的 (doc_id, raw_score) 列表。doc_id 必须指向同一逻辑文档;如果各路使用 chunk ID,应先明确是按 chunk 竞争,还是先聚合到文档级。
基本语法
下面脚本只使用 Python 标准库,可直接运行。原始分数仅用于通道内部排序,融合阶段不参与相加。
from collections import defaultdict
channels = {
"title_dense": [("doc-1", 0.93), ("doc-2", 0.89), ("doc-3", 0.82)],
"body_dense": [("doc-2", 0.91), ("doc-4", 0.88), ("doc-1", 0.80)],
"keyword": [("doc-4", 12.7), ("doc-2", 11.4), ("doc-5", 9.8)],
}
weights = {"title_dense": 1.2, "body_dense": 1.0, "keyword": 1.5}
k = 60
fused = defaultdict(float)
sources = defaultdict(list)
for channel, rows in channels.items():
seen = set()
for rank, (doc_id, _raw_score) in enumerate(rows, start=1):
# 同一路出现重复 ID 时只保留最高名次,避免重复加分。
if doc_id in seen:
continue
seen.add(doc_id)
# 只使用名次,避免不同检索系统的原始分数量纲互相污染。
fused[doc_id] += weights[channel] / (k + rank)
sources[doc_id].append(channel)
ranking = sorted(fused, key=lambda doc_id: (-fused[doc_id], doc_id))
for rank, doc_id in enumerate(ranking, start=1):
joined = ",".join(sources[doc_id])
print(f"{rank}. {doc_id} score={fused[doc_id]:.6f} channels={joined}")预期输出
1. doc-2 score=0.059942 channels=title_dense,body_dense,keyword
2. doc-4 score=0.040719 channels=body_dense,keyword
3. doc-1 score=0.035545 channels=title_dense,body_dense
4. doc-5 score=0.023810 channels=keyword
5. doc-3 score=0.019048 channels=title_densescore 只在本次融合配置内用于排序;channels 用于解释文档从哪些通道进入候选池。分数相同时用 doc_id 做稳定排序,避免相同输入在不同进程中顺序抖动。
高频用法
- 多字段融合:标题向量负责高精度,正文向量负责上下文召回,关键词通道保留专有名词。
- 多模型融合:通用语义模型、领域模型和多语言模型分别召回,再统一去重排序。
- 多阶段召回:向量库、全文检索和业务规则先并行取候选,融合后再送入交叉编码器重排。
- 灰度迁移:旧模型与新模型同时召回,通过权重和离线指标逐步切换,不直接替换线上通道。
参数与策略
RRF 常用形式为 weight / (k + rank)。k 越大,头部名次差异越平缓;权重越高,该通道对最终排序影响越大。不要只凭主观设置权重,应在固定评测集上比较 Recall@K、MRR 或 NDCG,并记录延迟变化。
每路候选数应独立设置:高精度标题通道可以较小,长尾关键词或语义通道通常需要更大的召回池。最终 top K 之前必须先完成全局去重和融合,不能先截断每个文档的最佳 chunk 后再遗漏其他通道证据。
风险与边界
- 触发条件:不同通道使用不一致的文档 ID。可能后果:同一内容被当成多条结果,挤占 top K。安全替代:建立统一 canonical ID,并保留 chunk ID 作为定位字段。
- 触发条件:某一路候选数过小。可能后果:该通道几乎没有进入融合池,调高权重也无法补回缺失文档。安全替代:先调召回深度,再调权重。
- 触发条件:权重直接按线上点击率持续放大。可能后果:热门通道形成反馈回路,长尾结果消失。安全替代:设置权重上下限,使用留出评测集和探索流量验证。
- 触发条件:把融合分数当成相关性概率。可能后果:错误设置阈值并丢弃有效结果。安全替代:只把 RRF 分数用于排序;需要概率时单独训练校准模型。
排障清单
- 重复文档过多:打印 canonical ID、chunk ID 和来源通道,检查去重键。
- 单一路长期霸榜:核对权重、候选数和该路是否重复提交相同 ID。
- 新通道上线后无变化:确认其候选已进入融合输入,而不是在 top K 截断后才追加。
- 排序偶发抖动:增加确定性的次级排序键,并固定输入通道顺序。
- 延迟超标:并行执行召回,限制每路候选数,只传回融合需要的 ID、名次和少量展示字段。
速查:先统一 ID,再保证每路候选质量,最后调 RRF 的候选深度与权重;不要从原始分数直接推导跨通道优先级。
正确解释不同距离度量返回的分数方向、范围和阈值含义。
处理相似度分数
用于把向量检索返回的 score 或 distance 转成可判断的业务含义。先确认度量类型和分数方向,再设置阈值;不要只看字段名,因为部分客户端会把距离统一命名为 score。
判读规则
| 度量 | 更相似的方向 | 常见范围 | 阈值判断 |
|---|---|---|---|
余弦相似度 cosine_similarity |
越大越相似 | [-1, 1],非负嵌入常落在 [0, 1] |
score >= threshold |
余弦距离 cosine_distance |
越小越相似 | 常见为 [0, 2] |
distance <= threshold |
内积 dot_product / inner_product |
越大越相似 | 无固定上限 | score >= threshold |
欧氏距离 l2 / euclidean |
越小越相似 | [0, +∞) |
distance <= threshold |
同名度量也可能经过归一化或符号翻转。生产环境应以集合索引配置和 SDK 文档为准,并用已知向量做一次方向验证。
可运行校验
下面用两个二维向量同时计算四种常见分数,便于确认“越大越好”还是“越小越好”。
import math
query = [1.0, 0.0]
candidate = [0.8, 0.6]
dot = sum(a * b for a, b in zip(query, candidate))
query_norm = math.sqrt(sum(x * x for x in query))
candidate_norm = math.sqrt(sum(x * x for x in candidate))
cosine_similarity = dot / (query_norm * candidate_norm)
cosine_distance = 1.0 - cosine_similarity
l2_distance = math.sqrt(sum((a - b) ** 2 for a, b in zip(query, candidate)))
print(f"cosine_similarity={cosine_similarity:.6f}")
print(f"cosine_distance={cosine_distance:.6f}")
print(f"dot_product={dot:.6f}")
print(f"l2_distance={l2_distance:.6f}")预期输出
cosine_similarity=0.800000
cosine_distance=0.200000
dot_product=0.800000
l2_distance=0.632456读取时,余弦相似度和内积取较大值;余弦距离和欧氏距离取较小值。若查询结果排序方向与此相反,应检查服务端是否返回了负内积、归一化分数或统一相关度分数。
阈值设置
不要直接照搬“0.8 即相似”之类固定经验值。阈值至少受嵌入模型、向量是否归一化、文本长度、语言和数据分布影响。安全做法是准备已标注的正负样本,统计分数分布,再按召回率、准确率或误报成本选择阈值。
切换模型、调整分段策略或重建索引后,应重新标定阈值。不同度量之间不能直接换算阈值,除非服务端明确给出转换公式。
风险与边界
触发条件:把距离当相似度、混用不同模型的阈值,或只根据 TopK 排名判断是否命中。可能后果:低相关结果被误判为有效,或高相关结果被过滤。安全替代方案:记录原始度量、原始分数、模型版本和阈值版本,并在业务层显式使用 >= 或 <=。
速查:先看度量配置,再看排序方向,最后看阈值是否经过当前数据集标定。
使用游标、偏移量或主键范围分批遍历集合中的非向量数据。
分页读取数据
用于分批遍历集合中的主键和标量字段,执行导出、校验、迁移或补偿任务。优先使用游标或主键范围分页;只有数据量较小且集合基本不变时才使用偏移量分页。
方式选择
- 游标分页:服务端返回下一页令牌,适合支持快照或稳定扫描的数据库。
- 主键范围分页:按唯一且递增的主键执行
id > last_id,容易断点续跑,生产任务优先使用。 - 偏移量分页:使用
offset + limit,实现简单,但深分页越来越慢,数据变动时还可能重复或遗漏。
读取非向量数据时,只选择主键和必要标量字段。除非确实需要迁移向量,否则不要返回向量列,以减少网络流量和客户端内存占用。
主键范围遍历
下面用 SQLite 模拟向量集合的标量字段,按主键分批读取。代码可直接运行,并展示断点变量 last_id 的更新方式。
import sqlite3
conn = sqlite3.connect(":memory:")
conn.execute("CREATE TABLE items (id INTEGER PRIMARY KEY, category TEXT, status TEXT)")
conn.executemany(
"INSERT INTO items VALUES (?, ?, ?)",
[
(1, "doc", "ready"),
(2, "faq", "ready"),
(3, "doc", "pending"),
(4, "image", "ready"),
(5, "faq", "ready"),
],
)
page_size = 2
last_id = 0
while True:
rows = conn.execute(
"SELECT id, category, status FROM items "
"WHERE id > ? ORDER BY id ASC LIMIT ?",
(last_id, page_size),
).fetchall()
if not rows:
break
print(rows)
last_id = rows[-1][0]预期输出
[(1, 'doc', 'ready'), (2, 'faq', 'ready')]
[(3, 'doc', 'pending'), (4, 'image', 'ready')]
[(5, 'faq', 'ready')]读取方法:每页处理成功后保存最后一条主键;任务重启时从该主键继续。真实向量数据库中,把 SQL 条件替换为对应过滤表达式,并保持主键升序和固定页大小。
游标与偏移量
使用游标时,应原样保存服务端返回的 next_cursor,不要自行解析或修改。游标为空通常表示遍历结束;若游标有过期时间,长任务需要控制单页处理耗时或使用数据库提供的快照扫描能力。
偏移量分页只适合小集合或一次性后台查询。触发条件是页码很深或扫描期间持续插入、删除数据;可能后果是查询变慢、记录重复或遗漏。安全替代方案是游标、主键范围或固定快照。
风险与边界
触发条件:分页期间集合发生更新、主键不唯一、排序字段可修改,或处理成功前就保存新游标。可能后果:断点恢复后跳过数据、重复执行副作用,甚至无法证明扫描完整。安全替代方案是使用不可变唯一主键、稳定排序、幂等处理,并在当前页全部成功后再提交游标或 last_id。
速查:小数据可用偏移量;长时间全量扫描优先游标;需要可审计和断点续跑时优先主键范围。
统计集合总记录数或满足过滤条件的记录数量,核对导入完整性。
统计数据数量
用于核对集合总记录数、租户数据量或导入批次是否完整。以下命令基于 Qdrant HTTP API;统计对象是 point 数量,不等同于业务主键去重后的数量。
命令定位
调用 POST /collections/{collection_name}/points/count。不传 filter 时统计整个集合;传入过滤条件时只统计命中的 point。exact 默认为 true,设为 false 会更快但返回近似值,索引构建期间可能不可靠。 :contentReference[oaicite:0]{index=0}
高频用法
先确认 Qdrant 已启动且集合 documents 存在。下面依次统计总量,以及 tenant_id=tenant-a 的记录数。
QDRANT_URL="${QDRANT_URL:-http://localhost:6333}"
COLLECTION="${COLLECTION:-documents}"
# 1. 精确统计集合总量
curl -sS -X POST \
"$QDRANT_URL/collections/$COLLECTION/points/count" \
-H 'Content-Type: application/json' \
-d '{"exact":true}'
printf '\n'
# 2. 精确统计指定租户
curl -sS -X POST \
"$QDRANT_URL/collections/$COLLECTION/points/count" \
-H 'Content-Type: application/json' \
-d '{
"filter": {
"must": [
{"key": "tenant_id", "match": {"value": "tenant-a"}}
]
},
"exact": true
}'预期输出(关键字段)
{"result":{"count":<TOTAL_COUNT>},"status":"ok","time":<TIME>}
{"result":{"count":<MATCHED_COUNT>},"status":"ok","time":<TIME>}读取 result.count。<TOTAL_COUNT>、<MATCHED_COUNT> 和 <TIME> 会随数据量与机器负载变化;生产环境启用鉴权时追加 -H "api-key: <API_KEY>"。
输出字段说明
result.count:满足条件的 point 数量。status:正常响应为ok。time:服务端处理耗时,只用于观察趋势,不作为导入完整性的判断依据。usage:部分版本会返回硬件与 I/O 使用信息,不应参与数量比对。
风险与边界
导入仍在写入、异步删除尚未完成或副本读取一致性不同步时,连续两次统计可能变化。核对导入完整性时,应先停止该批次写入、等待写操作完成,再使用 exact:true 重复统计。
exact:false 只适合监控趋势或容量预估。将近似值用于审计、计费或数据迁移验收,可能造成漏报;安全替代是使用精确统计并固定过滤条件。
过滤字段未建 payload index 时结果仍可正确,但大集合可能扫描较多数据。高频按租户、状态或批次统计时,应为相应 payload 字段建立索引。 :contentReference[oaicite:1]{index=1}
排障清单
- 返回
404:检查集合名、URL 和端口是否正确。 - 返回
400:核对过滤字段类型;字符串、数字和布尔值不能混用。 - 数量比源端少:检查写入是否使用幂等主键覆盖、过滤条件是否遗漏、写操作是否仍在执行。
- 数量比源端多:检查重复业务记录是否使用了不同 point ID;需要按业务主键另做去重核验。
速查:完整性验收使用 exact:true,先冻结写入,再比较同一口径下的源端数量与 result.count。
按租户、时间或业务范围划分数据分区,降低检索和维护成本。
管理数据分区
用于按租户、日期或业务范围控制数据路由、查询范围和淘汰边界。以下以 Qdrant 自定义分片为例:分区键对应 shard key,写入和查询应显式携带同一键。
分区模型
创建集合时设置 sharding_method:"custom",point 才会按 shard key 路由。自定义分片下,shard_number 表示每个 shard key 对应的物理分片数,而不是整个集合的总分片数。 :contentReference[oaicite:2]{index=2}

创建集合与分区
下面创建一个 4 维向量集合,再建立 tenant-a 和 tenant-b 两个 shard key。集合必须从创建时就使用自定义分片。
QDRANT_URL="${QDRANT_URL:-http://localhost:6333}"
COLLECTION="${COLLECTION:-documents_partitioned}"
curl -sS -X PUT \
"$QDRANT_URL/collections/$COLLECTION" \
-H 'Content-Type: application/json' \
-d '{
"vectors": {"size": 4, "distance": "Cosine"},
"sharding_method": "custom",
"shard_number": 1,
"replication_factor": 1
}'
printf '\n'
for SHARD_KEY in tenant-a tenant-b; do
curl -sS -X PUT \
"$QDRANT_URL/collections/$COLLECTION/shards" \
-H 'Content-Type: application/json' \
-d "{\"shard_key\":\"$SHARD_KEY\"}"
printf '\n'
done预期输出(每个请求的关键字段)
{"result":true,"status":"ok","time":<TIME>}
{"result":true,"status":"ok","time":<TIME>}
{"result":true,"status":"ok","time":<TIME>}创建 shard key 的接口为 PUT /collections/{collection_name}/shards,可选参数还包括每个键的分片数、复制因子和节点放置策略。 :contentReference[oaicite:3]{index=3}
写入与验证
写入时在请求顶层指定 shard_key,随后对同一分区做精确计数。业务 payload 中仍建议保留 tenant_id,用于权限过滤和交叉核验。
QDRANT_URL="${QDRANT_URL:-http://localhost:6333}"
COLLECTION="${COLLECTION:-documents_partitioned}"
SHARD_KEY="${SHARD_KEY:-tenant-a}"
curl -sS -X PUT \
"$QDRANT_URL/collections/$COLLECTION/points?wait=true" \
-H 'Content-Type: application/json' \
-d "{
\"points\": [
{
\"id\": 1001,
\"vector\": [0.1, 0.2, 0.3, 0.4],
\"payload\": {\"tenant_id\": \"$SHARD_KEY\", \"text\": \"sample\"}
}
],
\"shard_key\": \"$SHARD_KEY\"
}"
printf '\n'
curl -sS -X POST \
"$QDRANT_URL/collections/$COLLECTION/points/count" \
-H 'Content-Type: application/json' \
-d "{\"shard_key\":\"$SHARD_KEY\",\"exact\":true}"预期输出(关键字段)
{"result":{"operation_id":<ID>,"status":"completed"},"status":"ok","time":<TIME>}
{"result":{"count":1},"status":"ok","time":<TIME>}<ID> 和 <TIME> 为动态值。Qdrant 的 count 接口可通过 shard_key 限定统计范围;不指定时会检查全部分片。 :contentReference[oaicite:4]{index=4}
高频分区策略
- 按租户:大型租户独占 shard key,便于隔离、迁移和限流;小租户过多时不要机械地一租户一分片。
- 按时间:使用
YYYY-MM-DD或YYYY-MM作为 shard key,查询最近窗口时只选择相关键,过期后按分区淘汰。Qdrant 官方时间分片方案也采用日期键。 :contentReference[oaicite:5]{index=5} - 按业务范围:地区、产品线或数据敏感级别可作为键,但应确保写入路由规则稳定,避免同一业务对象跨键漂移。
删除分区与风险
删除 shard key 会移除对应分片及其数据。触发条件通常是租户下线或时间分区过期;误删会造成不可逆的数据丢失。安全替代方案是先停止该键写入、执行快照或外部备份、精确统计并验证保留期,再删除。
QDRANT_URL="${QDRANT_URL:-http://localhost:6333}"
COLLECTION="${COLLECTION:-documents_partitioned}"
: "${SHARD_KEY:?必须显式设置要删除的 SHARD_KEY}"
curl -sS -X POST \
"$QDRANT_URL/collections/$COLLECTION/shards/delete" \
-H 'Content-Type: application/json' \
-d "{\"shard_key\":\"$SHARD_KEY\"}"预期输出
{"result":true,"status":"ok","time":<TIME>}删除接口为 POST /collections/{collection_name}/shards/delete。命令中的参数检查可防止变量为空时误操作默认分区,但不能替代备份与审批。 :contentReference[oaicite:6]{index=6}
排障清单
- 创建 shard key 失败:确认集合使用
sharding_method:"custom",并检查键是否已存在。 - 写入后分区计数为零:核对写入和统计请求中的
shard_key是否逐字一致。 - 查询延迟升高:检查是否未限定 shard key 导致跨分片扫描,或 shard key 数量过多造成资源开销。
- 分区负载不均:按真实数据量调整键粒度;不要仅按租户数量平均拆分。
- 删除超时:先停止写入并检查集群状态;不要在客户端重试逻辑中自动更换 shard key。
兼容性提示:本文命令适用于 Qdrant 自定义分片 API。Milvus 的 partition、Pinecone 的 namespace 和其他产品的分区语义不同,迁移时不要直接照搬删除与路由命令。
控制集合或分区进入和退出查询内存,平衡可用性与资源占用。
加载和释放集合
用于在 Milvus 中把集合或指定分区装入查询节点内存,或在低访问期释放内存。加载完成后才能执行向量检索;释放只移出查询内存,不删除持久化数据。:contentReference[oaicite:0]{index=0}
命令定位
整库上线或恢复查询时使用 load_collection();只保留热点租户、时间段或业务分区时使用 load_partitions()。对应释放接口是 release_collection() 与 release_partitions()。
集合只加载部分分区时,集合级状态仍可能显示未完全加载,应按分区调用 get_load_state() 判断。:contentReference[oaicite:1]{index=1}
基本语法
下面示例通过 PARTITION 是否为空选择集合级或分区级操作,先加载并验证,再释放并验证。目标集合必须已创建向量索引。
export MILVUS_URI="http://localhost:19530"
export MILVUS_TOKEN="root:Milvus"
export COLLECTION="docs"
export PARTITION="" # 留空操作整个集合;例如 partitionA 表示只操作该分区
python - <<'PY'
import os
from pymilvus import MilvusClient
uri = os.environ["MILVUS_URI"]
token = os.environ["MILVUS_TOKEN"]
collection = os.environ["COLLECTION"]
partition = os.environ.get("PARTITION", "").strip()
client = MilvusClient(uri=uri, token=token)
if partition:
# 分区级加载可减少冷数据占用,但查询必须限定到已加载分区。
client.load_partitions(
collection_name=collection,
partition_names=[partition],
)
print("after_load:", client.get_load_state(
collection_name=collection,
partition_name=partition,
))
client.release_partitions(
collection_name=collection,
partition_names=[partition],
)
print("after_release:", client.get_load_state(
collection_name=collection,
partition_name=partition,
))
else:
client.load_collection(collection_name=collection)
print("after_load:", client.get_load_state(
collection_name=collection,
))
client.release_collection(collection_name=collection)
print("after_release:", client.get_load_state(
collection_name=collection,
))
PY预期输出
after_load: {'state': <LoadState: Loaded>}
after_release: {'state': <LoadState: NotLoaded>}枚举的字符串格式可能随 PyMilvus 小版本略有不同,读取重点是状态从 Loaded 变为 NotLoaded。
高频用法
上线前先执行加载并等待 Loaded,再把流量切入;不要只依据接口无异常就认为已经可查询。
内存紧张时优先加载热点分区,而不是反复加载整个大集合。冷分区释放后仍可继续写入,但对该分区的查询需要重新加载。
批量发布时逐个集合操作并设置超时、重试和并发上限,避免多个大集合同时抢占 QueryNode 内存。
风险与边界
加载数据量超过可用查询内存时,可能出现加载失败、频繁换入换出或查询延迟陡增。安全做法是先评估索引与字段内存、分批加载分区,并监控 QueryNode 内存和加载进度。
释放正在承载流量的集合或分区会使后续查询不可用或报未加载错误。安全替代是先摘除流量、确认在途请求结束,再释放;恢复时必须验证 Loaded 后再回切。
释放不是删除操作,不会回收对象存储中的原始数据与索引文件。需要永久删除时应使用删除集合或分区流程,并单独做好备份与审批。
排障清单
NotLoaded长时间不变:确认向量字段已有索引、QueryNode 有足够内存,并查看服务端加载任务错误。- 只有部分请求失败:检查请求是否命中了未加载分区,或是否同时混用了分区名与分区键过滤。
- 释放后内存下降不明显:等待异步回收完成,排查其他集合、副本数和缓存占用。
- 重复加载超时:降低并发,避免在扩缩容、索引构建或大量导入期间同时加载。
在索引参数变化或数据规模显著增长后重新构建向量索引。
重建向量索引
用于在索引类型、距离度量或构建参数调整后,替换 Milvus 集合中现有向量索引。标准顺序是释放集合、删除旧索引、创建新索引、验证参数,再重新加载集合。Milvus 同一字段当前只能保留一个索引,因此原地重建存在查询中断窗口。:contentReference[oaicite:2]{index=2}
基本语法
示例把 docs.vector 的 vector_index 重建为 IVF_FLAT + COSINE。执行前应确认备份、维护窗口和回滚参数;集合及索引必须已存在。
export MILVUS_URI="http://localhost:19530"
export MILVUS_TOKEN="root:Milvus"
export COLLECTION="docs"
export FIELD="vector"
export INDEX_NAME="vector_index"
export NLIST="128"
python - <<'PY'
import os
from pymilvus import MilvusClient
client = MilvusClient(
uri=os.environ["MILVUS_URI"],
token=os.environ["MILVUS_TOKEN"],
)
collection = os.environ["COLLECTION"]
field = os.environ["FIELD"]
index_name = os.environ["INDEX_NAME"]
nlist = int(os.environ["NLIST"])
before = client.describe_index(
collection_name=collection,
index_name=index_name,
)
print("before:", before)
# 删除索引前必须先释放集合,否则 drop_index 会失败。
client.release_collection(collection_name=collection)
client.drop_index(
collection_name=collection,
index_name=index_name,
)
params = MilvusClient.prepare_index_params()
params.add_index(
field_name=field,
index_name=index_name,
index_type="IVF_FLAT",
metric_type="COSINE",
params={"nlist": nlist},
)
# sync=True 等待构建完成,避免尚未完成就重新承载查询。
client.create_index(
collection_name=collection,
index_params=params,
sync=True,
)
after = client.describe_index(
collection_name=collection,
index_name=index_name,
)
print("after:", after)
client.load_collection(collection_name=collection)
print("load_state:", client.get_load_state(
collection_name=collection,
))
PY预期输出
before: {'index_type': '<OLD_INDEX_TYPE>', 'metric_type': '<OLD_METRIC>', 'field_name': 'vector', 'index_name': 'vector_index'}
after: {'index_type': 'IVF_FLAT', 'metric_type': 'COSINE', 'field_name': 'vector', 'index_name': 'vector_index'}
load_state: {'state': <LoadState: Loaded>}<OLD_INDEX_TYPE> 与 <OLD_METRIC> 取决于原索引;服务端生成的任务 ID、耗时和字典字段顺序也可能不同。官方接口使用 prepare_index_params()、create_index()、describe_index() 与 drop_index() 完成创建、检查和删除。:contentReference[oaicite:3]{index=3}
常用参数
index_type:索引算法。没有明确调优依据时优先评估AUTOINDEX;使用 IVF、HNSW 或磁盘索引时必须同时校准构建参数和搜索参数。metric_type:必须与向量生成和在线查询保持一致,例如COSINE、L2或IP。改变度量会改变得分含义与排序结果。params:索引专属构建参数。IVF_FLAT的nlist增大通常会增加构建和内存成本,不能只按数据量机械放大。sync:设为True时客户端等待构建结束;设为False时必须轮询describe_index()或构建进度后再加载。:contentReference[oaicite:4]{index=4}
高频用法
索引参数变更时先在影子集合回放真实查询,比较召回率、P95/P99 延迟、内存和构建时长,再决定是否替换生产索引。
数据规模显著增长但参数未变时,不要默认必须重建。Milvus 会为后续满足条件的新段继续建立索引;只有监控与压测证明当前方案不再满足目标时才重建。:contentReference[oaicite:5]{index=5}
原地重建适合可接受维护窗口的集合。需要低中断时,复制数据到新集合、构建并加载新索引、完成一致性校验后通过别名或应用配置切流,旧集合保留到回滚窗口结束。
风险与边界
删除旧索引后若新索引构建失败,集合会处于无可用向量索引或不可加载状态,查询中断。安全替代是先在新集合构建验证,或至少记录旧索引完整参数并准备自动回滚脚本。
metric_type 与查询侧不一致会造成排序语义变化,表现为召回率下降而非明显报错。上线前必须用固定验证集比较 Top-K 结果,并同步更新搜索参数。
大规模重建会消耗 CPU、内存、磁盘与对象存储带宽,可能挤压在线写入和查询。应限制并发、安排低峰窗口,并持续观察索引进度和集群资源。
排障清单
drop_index失败:确认集合已释放,并核对index_name是否存在。- 构建长时间无进展:检查数据节点、索引节点资源和对象存储访问,降低并发后重试。
- 重建后无法加载:检查每个向量字段是否都有可用索引,以及索引构建是否真正完成。
- 延迟或召回恶化:核对度量、维度、搜索参数和归一化策略,使用同一验证集对比旧索引。
根据召回率、查询延迟、构建时间和内存占用调整索引配置。
调整索引参数
用于索引已经能工作,但召回率、构建耗时或内存占用不符合目标时。以下以 Milvus 的 HNSW 为例:M 和 efConstruction 属于构建参数,修改后必须重建索引;查询期参数 ef 应先单独调优,避免无必要重建。:contentReference[oaicite:0]{index=0}
参数取舍
| 参数 | 调大后的主要变化 | 调小后的主要变化 |
|---|---|---|
M |
图连接更密,通常提高召回上限;索引内存、构建时间和查询工作量可能增加 | 节省内存并加快构建,但高召回场景更容易丢失近邻 |
efConstruction |
构建时考察更多候选,图质量通常更高;构建耗时和临时资源占用增加 | 构建更快,但索引质量上限可能下降 |
metric_type |
不是性能旋钮,必须与向量生成方式和查询保持一致 | 不应只为降低延迟而更换,否则排序语义会改变 |
不要同时改多个参数。先固定数据集、查询集、limit 和查询参数,记录 Recall@K、P95/P99 延迟、索引大小及构建时长,再一次只调整一个变量。
安全重建示例
前置条件:已安装 pymilvus,集合 docs 已存在且当前已加载,向量字段名为 vector,索引名为 vector_index。脚本会释放集合、删除旧索引、同步重建并重新加载;生产环境优先在副本集合执行。
import os
from pymilvus import MilvusClient
uri = os.getenv("MILVUS_URI", "http://localhost:19530")
token = os.getenv("MILVUS_TOKEN", "root:Milvus")
collection = os.getenv("MILVUS_COLLECTION", "docs")
index_name = "vector_index"
client = MilvusClient(uri=uri, token=token)
# 删除索引前先释放集合,避免对正在加载的索引直接操作。
client.release_collection(collection_name=collection)
if index_name in client.list_indexes(collection_name=collection):
client.drop_index(collection_name=collection, index_name=index_name)
index_params = MilvusClient.prepare_index_params()
index_params.add_index(
field_name="vector",
index_name=index_name,
index_type="HNSW",
metric_type="COSINE",
params={"M": 32, "efConstruction": 200},
)
# sync=True 会等待构建完成再返回,便于随后立即验证和加载。
client.create_index(
collection_name=collection,
index_params=index_params,
sync=True,
)
client.load_collection(collection_name=collection)
info = client.describe_index(
collection_name=collection,
index_name=index_name,
)
print({
"index_name": info["index_name"],
"index_type": info["index_type"],
"metric_type": info["metric_type"],
})预期输出
{'index_name': 'vector_index', 'index_type': 'HNSW', 'metric_type': 'COSINE'}create_index(..., sync=True) 返回时索引已构建完成;describe_index 用于确认实际生效的索引类型和距离度量。Milvus 每个字段当前只能保留一个索引文件,因此原字段上的索引参数不能通过并存两个索引直接做在线对比。:contentReference[oaicite:1]{index=1}
调优顺序
- 先在不重建索引的情况下提高查询
ef,观察召回是否仍能明显上升。 - 若召回很快到达平台且仍不达标,再小步提高
efConstruction。 - 若高维数据在合理
ef下仍难达到目标,再评估提高M,同时核对常驻内存。 - 每次重建后预热同一批查询,再比较稳定阶段指标,避免把冷启动延迟当成索引退化。
风险与边界
直接在唯一生产集合上执行 release_collection 和 drop_index,会使查询在重建并重新加载前不可用;大索引重建还可能触发 CPU、内存和磁盘峰值。安全替代方案是复制集合或使用蓝绿集合重建,验证后切换流量,并保留旧集合用于快速回滚。
仅修改配置文件但未删除并重建索引时,旧索引仍按原参数运行。若新索引召回下降,先核对 metric_type、向量归一化方式、数据版本和测试查询集是否与基线一致。
修改搜索深度、候选数量等运行参数,在召回率和延迟之间取舍。
调整查询参数
用于不重建索引就调整单次搜索的召回率与延迟。以下以 Milvus HNSW 为例:limit 决定返回条数,search_params.params.ef 决定搜索宽度;ef 越大通常召回越高、延迟也越高,并且应不小于 limit。:contentReference[oaicite:2]{index=2}
基本语法
片段示例,依赖已初始化的 client 与维度正确的 query_vector。
results = client.search(
collection_name="docs",
anns_field="vector",
data=[query_vector],
limit=10,
search_params={"params": {"ef": 100}},
)预期结果
返回最多 10 个近邻;搜索阶段按 ef=100 的搜索宽度扩展候选。limit 不是 ef 的替代项。只增大 limit 而不调整 ef,会要求返回更多结果,却不一定给索引足够的搜索空间。
可运行示例
前置条件:集合 docs 至少有 10 条数据,向量字段为 vector,且当前已加载。脚本先读取一条现有向量作为查询向量,因此不需要手工填写维度。
import os
from pymilvus import MilvusClient
uri = os.getenv("MILVUS_URI", "http://localhost:19530")
token = os.getenv("MILVUS_TOKEN", "root:Milvus")
collection = os.getenv("MILVUS_COLLECTION", "docs")
client = MilvusClient(uri=uri, token=token)
rows = client.query(
collection_name=collection,
filter="",
output_fields=["vector"],
limit=1,
)
if not rows:
raise RuntimeError("集合中没有可用于测试的向量")
query_vector = rows[0]["vector"]
hits = client.search(
collection_name=collection,
anns_field="vector",
data=[query_vector],
limit=10,
search_params={"params": {"ef": 100}},
)
print(f"returned={len(hits[0])}")
print(f"top1_id={hits[0][0]['id']}")
print(f"top1_distance={hits[0][0]['distance']}")预期输出
returned=10
top1_id=<ID>
top1_distance=<DISTANCE><ID> 和 <DISTANCE> 由集合数据与距离度量决定,实际值会不同。用自身向量查询时,第一名通常是该记录本身;若业务需要排除自身,应按主键增加过滤条件或在应用层剔除。
高频调法
延迟优先时,从 ef=limit 开始,逐步增加并观察 Recall@K;召回优先时,每次将 ef 约翻倍,直到召回提升进入平台或 P99 延迟超过预算。不要直接把 ef 调到极大值,否则并发下 CPU 使用率和尾延迟可能突然升高。
候选返回数量由 limit 控制。增大 limit 会增加结果序列化、网络传输和后处理成本;若只需要前 10 条,不要为了“提高召回”把 limit 改成 100,应调整 ef 并用标准答案集测量 Recall@10。
带过滤条件的搜索先验证过滤表达式和命中数量。过滤过严时,增加 ef 也无法返回不存在的候选;过滤较复杂时,还要把标量过滤成本与向量搜索成本分开测量。
输出字段说明
id 是命中的主键,distance 的优劣方向取决于度量:L2 越小越近,COSINE 或 IP 越大越相似。比较两组调优结果时,必须保持索引的 metric_type、查询向量和过滤条件一致。:contentReference[oaicite:3]{index=3}
风险与排障
当 ef < limit 时,请求可能被拒绝或无法达到预期搜索宽度;安全做法是在应用入口校验 ef >= limit。当提高 ef 后召回不升,先检查索引构建质量、距离度量、向量归一化和测试集,而不是继续无上限增加 ef。
若延迟只在高并发下恶化,单请求压测结论不足。固定并发、数据热度和过滤条件,分别记录平均值、P95、P99 与超时率,再为不同流量等级设置查询参数上限。
通过批次大小、并发度、重试策略和异步提交提升数据导入效率。
优化批量写入
用于离线导入、数据回灌或持续摄取时,提高吞吐并控制超时与重复写入。调优顺序是先确定单批大小,再逐步增加并发,最后补充有上限的重试;不要同时把所有参数拉满。
基本语法
以下示例使用 PyMilvus 的异步客户端,将 1000 条 4 维向量按批次并发 upsert。运行前需安装 pymilvus,并确保 MILVUS_URI 可访问;示例会在集合不存在时创建 bulk_write_demo。
import asyncio
import os
import random
from pymilvus import AsyncMilvusClient, MilvusClient, MilvusException
URI = os.getenv("MILVUS_URI", "http://localhost:19530")
TOKEN = os.getenv("MILVUS_TOKEN", "root:Milvus")
COLLECTION = "bulk_write_demo"
TOTAL = 1000
BATCH_SIZE = 200
CONCURRENCY = 4
MAX_RETRIES = 3
def prepare_collection() -> None:
client = MilvusClient(uri=URI, token=TOKEN)
if not client.has_collection(collection_name=COLLECTION):
client.create_collection(
collection_name=COLLECTION,
dimension=4,
metric_type="COSINE",
)
client.close()
def make_rows() -> list[dict]:
return [
{
"id": i,
"vector": [
(i % 17) / 17,
(i % 19) / 19,
(i % 23) / 23,
(i % 29) / 29,
],
}
for i in range(TOTAL)
]
async def write_batch(
client: AsyncMilvusClient,
semaphore: asyncio.Semaphore,
batch: list[dict],
) -> int:
async with semaphore:
for attempt in range(MAX_RETRIES + 1):
try:
result = await client.upsert(
collection_name=COLLECTION,
data=batch,
timeout=20,
)
return int(
result.get(
"upsert_count",
result.get("insert_count", len(batch)),
)
)
except MilvusException:
if attempt == MAX_RETRIES:
raise
# 指数退避加抖动,避免多个失败批次同时重试。
delay = min(8.0, 0.5 * (2**attempt)) + random.random() * 0.2
await asyncio.sleep(delay)
return 0
async def main() -> None:
client = AsyncMilvusClient(uri=URI, token=TOKEN)
semaphore = asyncio.Semaphore(CONCURRENCY)
rows = make_rows()
batches = [
rows[start : start + BATCH_SIZE]
for start in range(0, len(rows), BATCH_SIZE)
]
counts = await asyncio.gather(
*(write_batch(client, semaphore, batch) for batch in batches)
)
await client.close()
print(
f"collection={COLLECTION} batches={len(batches)} "
f"rows={sum(counts)} concurrency={CONCURRENCY}"
)
if __name__ == "__main__":
prepare_collection()
asyncio.run(main())预期输出
collection=bulk_write_demo batches=5 rows=1000 concurrency=4常用参数
BATCH_SIZE 控制单请求数据量。先从 100~1000 条试跑,再根据向量维度、标量字段大小、网络带宽和服务端限制调整;高维向量或大文本字段应使用更小批次。
CONCURRENCY 控制同时在途的写请求。每次只增加一档并观察吞吐、P95 延迟、超时率和服务端 CPU;吞吐不再上升或错误率变高时,应回退到上一档。
MAX_RETRIES 只处理短暂网络或服务不可用。重试次数和总等待时间必须封顶,并记录最终失败批次,供后续补偿。
高频用法
离线全量导入优先使用较大批次、低到中等并发,并在导入完成后统一校验行数。持续摄取优先使用较小批次和固定并发,避免单批等待时间过长。
需要自动重试时使用稳定主键配合 upsert,使同一批次重复提交仍保持幂等。确认主键绝不冲突且不需要重试时,才使用 insert 获取更直接的写入路径。
批次应携带可追踪的范围,例如起止主键或源文件偏移;失败后只重放失败批次,不要重新提交整份数据。
风险与边界
批次过大会触发请求体过大、客户端内存突增或超时,结果是整批失败;安全替代方案是缩小批次并保持有限并发。并发过高会压满代理、消息队列或数据节点,使吞吐下降且尾延迟升高;应使用信号量限流并逐级压测。
对非幂等 insert 盲目重试可能造成主键冲突或重复数据。生产环境应使用确定性主键、upsert,或在重试前查询写入状态;维度不匹配、字段缺失和权限错误属于永久错误,不应持续重试。
排障清单
先确认失败是否集中在固定批次;固定失败通常是数据问题,随机失败通常与负载、网络或资源有关。再将并发降为 1:若恢复,优先检查服务端限流和资源饱和;若仍失败,检查字段类型、向量维度、主键和请求大小。
最后对比“每批耗时、成功条数、重试次数、最终失败批次”四项指标。只看总吞吐会掩盖尾部批次持续失败的问题。
兼容性
异步客户端和返回字段可能随 PyMilvus 版本变化。生产环境应固定客户端与服务端版本,在预发布环境验证 upsert 返回结构、并发连接数和关闭方式;若异步接口未通过验证,使用同步客户端配合有界任务队列作为替代。
从索引参数、过滤字段、返回字段和资源配置定位查询耗时来源。
优化查询延迟
用于搜索 P95/P99 升高、过滤查询变慢或返回结果体过大时,快速区分索引候选量、标量过滤、返回字段和资源负载的影响。每次只修改一个变量,并同时记录延迟与召回质量。
基本语法
下面的脚本对同一查询依次比较宽返回字段、精简字段、降低 HNSW ef 和去掉过滤条件。运行前需存在名为 latency_demo 的集合,字段至少包含 8 维 vector、整数 tenant_id 和字符串 title,向量索引为 HNSW 且度量方式为 COSINE。
import os
import statistics
import time
from pymilvus import MilvusClient
URI = os.getenv("MILVUS_URI", "http://localhost:19530")
TOKEN = os.getenv("MILVUS_TOKEN", "root:Milvus")
COLLECTION = os.getenv("MILVUS_COLLECTION", "latency_demo")
QUERY_VECTOR = [0.1, 0.2, 0.3, 0.4, 0.4, 0.3, 0.2, 0.1]
FILTER = "tenant_id == 3"
LIMIT = 10
ROUNDS = 30
WARMUPS = 5
client = MilvusClient(uri=URI, token=TOKEN)
def percentile(values: list[float], ratio: float) -> float:
ordered = sorted(values)
index = round((len(ordered) - 1) * ratio)
return ordered[index]
def benchmark(
name: str,
filter_expr: str,
output_fields: list[str] | None,
ef: int,
) -> None:
params = {"metric_type": "COSINE", "params": {"ef": ef}}
for _ in range(WARMUPS):
client.search(
collection_name=COLLECTION,
data=[QUERY_VECTOR],
anns_field="vector",
filter=filter_expr,
limit=LIMIT,
output_fields=output_fields,
search_params=params,
timeout=10,
)
samples = []
hits = 0
for _ in range(ROUNDS):
started = time.perf_counter()
result = client.search(
collection_name=COLLECTION,
data=[QUERY_VECTOR],
anns_field="vector",
filter=filter_expr,
limit=LIMIT,
output_fields=output_fields,
search_params=params,
timeout=10,
)
samples.append((time.perf_counter() - started) * 1000)
hits = len(result[0])
print(
f"case={name} p50_ms={statistics.median(samples):.2f} "
f"p95_ms={percentile(samples, 0.95):.2f} hits={hits}"
)
benchmark("wide-output", FILTER, ["tenant_id", "title"], 128)
benchmark("lean-output", FILTER, None, 128)
benchmark("lower-ef", FILTER, None, 64)
benchmark("no-filter", "", None, 64)
client.close()预期输出
case=wide-output p50_ms=<MS> p95_ms=<MS> hits=10
case=lean-output p50_ms=<MS> p95_ms=<MS> hits=10
case=lower-ef p50_ms=<MS> p95_ms=<MS> hits=10
case=no-filter p50_ms=<MS> p95_ms=<MS> hits=10<MS> 会随数据量、缓存、网络和节点负载变化。重点读取同一环境下各 case 的相对差异,而不是照搬某个绝对毫秒值。
常用参数
ef 决定 HNSW 搜索阶段检查的候选范围。值越大通常召回更稳,但 CPU 与延迟更高;调小后必须同时验证 Recall@K 或业务命中率。IVF 系列索引对应关注 nprobe,不要把 HNSW 参数直接套到其他索引。
filter 应尽量使用高选择性、类型稳定的标量字段。频繁过滤的字段应建立适配的标量索引,表达式中避免不必要的复杂计算和超长 in 列表。
output_fields 只返回业务真正需要的字段。返回大文本、JSON 或原始向量会增加服务端读取、序列化和网络传输时间;仅需要主键与距离时保持为空即可。
高频用法
先运行“宽字段”和“精简字段”对比。若差异明显,优先减少返回字段或拆成二次按主键查询,而不是先扩容。
再固定返回字段,逐步降低 ef 或 nprobe。每个档位都记录 P50、P95、P99、错误率和召回指标,选择满足质量下限的最小候选量。
过滤查询单独压测。若过滤后明显变慢,检查字段是否有标量索引、过滤选择性是否过低,以及是否能通过分区键或租户分区先缩小搜索范围。
最后检查集合是否已加载、内存是否足够、CPU 是否长期饱和、是否存在热点租户,以及副本数能否覆盖并发读流量。
输出字段说明
p50_ms 表示典型请求耗时,p95_ms 用于观察尾延迟,hits 用于确认不同 case 都返回预期数量。若 hits 变化,应先排查过滤条件、数据可见性或召回参数,再比较延迟。
搜索结果中的 id 是主键,distance 或 score 表示相似度结果,具体“越大越相似”还是“越小越相似”取决于度量类型;上线前必须按 COSINE、IP 或 L2 分别验证排序方向。
风险与边界
直接降低 ef、nprobe 或 limit 可能让延迟下降但漏掉正确结果,后果是召回率和排序质量退化;安全替代方案是用固定评测集做质量回归,并设置可接受的 Recall@K 下限。
删除过滤条件虽然可能更快,但会返回越权或无关数据;不能以性能为由绕过租户、权限或时间范围过滤。资源不足时盲目增加副本也可能放大内存压力,应先确认瓶颈位于 CPU、内存、磁盘、网络还是并发队列。
排障清单
先用同一查询向量、同一 limit 和同一数据版本重复测试,排除冷缓存和数据变更。然后按“返回字段 → 搜索参数 → 过滤条件 → 分区范围 → 资源负载”的顺序逐项替换,保留基线结果。
若只有 P99 异常,检查并发尖峰、后台导入、索引构建、压缩和节点重平衡;若所有分位数都变慢,优先检查集合加载状态、索引是否生效、网络 RTT 和资源利用率。
通过索引配置、候选数量、分块策略和嵌入模型改善相关结果召回。
提高检索召回率
用于“相关文档存在,但没有进入前 k 条结果”的场景。先用固定评测集量化 Recall@k,再依次调整嵌入模型、分块、候选数量和索引搜索参数;不要只凭单次查询主观判断。
命令定位
召回率必须基于已标注的相关文档集合计算。至少准备 20~50 条代表性查询,每条记录相关文档 ID,并固定过滤条件、索引版本和 top_k,否则前后结果不可比较。
调优顺序建议为:确认数据与模型正确 → 修正分块 → 扩大候选集 → 提高索引搜索强度 → 必要时增加重排。索引参数只能改善“近似搜索漏检”,不能修复错误嵌入或缺失数据。
可运行评估
下面用两组固定结果计算 Recall@5。真实环境中,将 relevant 替换为人工标注 ID,将 returned 替换为向量数据库返回的 ID。
from dataclasses import dataclass
@dataclass
class Case:
relevant: set[int]
returned: list[int]
def recall_at_k(case: Case, k: int) -> float:
hits = len(case.relevant.intersection(case.returned[:k]))
return hits / len(case.relevant) if case.relevant else 1.0
baseline = Case(relevant={7, 11, 19, 23}, returned=[7, 3, 11, 8, 5])
tuned = Case(relevant={7, 11, 19, 23}, returned=[7, 11, 19, 3, 23])
for name, case in [("baseline", baseline), ("tuned", tuned)]:
print(f"{name}: recall@5={recall_at_k(case, 5):.2f}")预期输出
baseline: recall@5=0.50
tuned: recall@5=1.00读取方法:0.50 表示 4 个相关文档中只有 2 个进入前 5;调优后 4 个全部命中。生产评估应汇总平均值,并同时记录 P95 延迟和返回重复率。
高频用法
| 现象 | 优先调整 | 验证方式 |
|---|---|---|
| 语义相近但长期搜不到 | 更换或微调嵌入模型,确认查询与文档使用同一模型和归一化方式 | 离线评测集 Recall@k 是否稳定提升 |
| 答案跨越分块边界 | 增大块大小或增加 10%~20% 重叠,并保留标题、路径等上下文 | 边界类查询是否命中,重复结果是否可控 |
| 精确检索能命中,ANN 检索漏检 | 提高候选数量及搜索强度,如 nprobe、ef 或同类参数 |
与精确检索结果对照,记录延迟增量 |
| 前 20 条包含答案,前 5 条没有 | 先取更大的候选集,再用关键词、交叉编码器或业务规则重排 | Recall@候选数不降,前 5 排名质量提升 |
候选数量通常应大于最终 top_k。例如最终返回 10 条时,可先检索 50~200 条再重排;具体上限由数据量、延迟预算和数据库实现决定。
风险与边界
提高搜索强度或候选数量会增加 CPU、内存、网络传输和 P95 延迟。触发条件是高并发或大集合查询;后果可能是超时和节点抖动。安全做法是在压测环境按阶梯增加参数,并设置查询超时、候选上限和回退值。
分块过小或重叠过高会制造大量近重复向量,导致结果被同一文档占满。应按文档 ID 去重,并监控“唯一文档数/返回条数”。
更换嵌入模型、维度、归一化规则或距离度量后,旧向量不可直接混用。应建立新集合重算向量,再通过双读对比和灰度切换迁移。
排障清单
- 确认待检索原文确实已写入,且未被租户、时间、权限等过滤条件排除。
- 确认查询向量与文档向量来自同一模型版本、相同预处理和相同归一化策略。
- 使用少量查询对比精确检索与近似检索;只有后者漏检时才优先调索引参数。
- 每次只改变一个变量,同时记录 Recall@k、P95 延迟、候选数和索引版本。
- 调优后回放失败查询,防止平均指标提升但关键业务查询退化。
排查嵌入模型、集合定义和历史数据之间的向量维度差异。
处理维度不匹配
用于写入或检索时报“向量维度与集合定义不一致”的场景。必须同时核对嵌入模型输出维度、集合字段维度和历史向量长度;三者不一致时,不要通过补零或截断强行绕过校验。
命令定位
先确认以下三个值:
- 当前嵌入模型实际输出的向量长度。
- 向量字段在集合或索引 Schema 中声明的维度。
- 已写入历史数据使用的模型版本和维度。
查询向量与库内向量还必须使用兼容的语义空间。即使两个模型都输出 768 维,也不能仅凭维度相同就认定可以混用。
可运行检查
下面的脚本在写库前验证模型维度、集合维度和批次内每条向量长度。示例故意设置为 1024 对 768,以复现配置错误。
def validate_dimensions(
model_dim: int,
collection_dim: int,
vectors: list[list[float]],
) -> None:
print(f"model_dim={model_dim}")
print(f"collection_dim={collection_dim}")
bad_rows = [
index
for index, vector in enumerate(vectors)
if len(vector) != collection_dim
]
if model_dim != collection_dim:
raise ValueError(
"embedding model dimension differs from collection schema"
)
if bad_rows:
raise ValueError(f"rows with invalid dimension: {bad_rows}")
print(f"validated_rows={len(vectors)}")
vectors = [[0.1] * 768, [0.2] * 768]
try:
validate_dimensions(
model_dim=1024,
collection_dim=768,
vectors=vectors,
)
except ValueError as exc:
print(f"ERROR: {exc}")预期输出
model_dim=1024
collection_dim=768
ERROR: embedding model dimension differs from collection schema读取方法:错误在调用数据库之前出现,说明应用配置已经不一致;应先修正模型或目标集合,避免把失败请求推到数据库层。
高频处理
新集合尚未写入数据
将集合维度改为模型真实输出维度,再重建索引。模型输出维度应通过一次实际编码读取,不要只依赖配置文件或模型名称。
更换了嵌入模型
创建一个使用新维度的新集合,从原始文本重新生成全部向量,并写入 embedding_model_version 等元数据。完成双读对比后再切换流量,旧集合保留到回滚窗口结束。
历史数据混用了多个版本
按模型版本抽样检查向量长度和元数据。只要同一向量字段中存在不同长度,就应从原文重建;无法追溯原文的数据应隔离,不要参与检索。
只有部分批次失败
在客户端记录失败行号、实体 ID、实际长度和期望长度。修复数据生成链路后只重放失败批次,避免重复写入已成功记录。
风险与边界
补零、截断或随机投影会改变向量空间。触发条件是为了迁就旧集合而修改新模型输出;后果是相似度失真、召回下降且问题难以察觉。安全替代方案是新建正确维度的集合并重新嵌入原始数据。
直接修改已有集合的维度通常不可行,即使数据库允许变更元数据,现有索引和历史向量也不会自动转换。应按“新集合 → 全量回填 → 校验 → 灰度切换 → 回滚窗口”迁移。
仅检查维度仍不足以保证兼容。距离度量、归一化方式、模型版本和文本预处理不同,也会使同维向量不可比较。
排障清单
- 打印一次真实查询向量的
len(vector),不要依据文档猜测。 - 读取线上集合 Schema,确认目标字段而不是同名测试集合。
- 检查应用环境变量、模型别名和部署版本,防止部分实例仍加载旧模型。
- 抽样历史记录,核对向量长度及
embedding_model_version。 - 重建后使用固定查询集比较新旧结果,并确认写入、查询和重排服务全部切到同一模型版本。
兼容性
主流向量数据库都会在写入或查询时校验稠密向量维度,但错误名称和发生阶段不同。稀疏向量、多向量字段或动态向量类型可能采用不同规则,应以目标数据库的 Schema 和客户端返回错误为准。
根据字段类型、主键冲突、请求限制和服务状态定位写入错误。
处理写入失败
写入报错时,先固定原始请求、集合 Schema 与服务状态,再判断是字段不匹配、主键策略、请求体过大还是服务不可用。不要先盲目重试,否则可能放大重复数据或写入压力。
命令定位
建议按“服务可达 → Schema 匹配 → 主键策略 → 单批大小 → 重试条件”的顺序检查。以下示例以 Milvus 2.6.x 的 MilvusClient 为例;先保持 APPLY=0 只检查,确认测试数据和目标集合无误后再设为 1。

主诊断示例
前置条件:已安装 pymilvus,并准备一条不会污染业务的测试记录。生产集合默认只执行只读检查。
export MILVUS_URI='http://127.0.0.1:19530'
export MILVUS_TOKEN='root:Milvus'
export COLLECTION='documents'
export PAYLOAD='[{"id":1001,"vector":[0.1,0.2,0.3,0.4],"title":"write-probe"}]'
export APPLY=0
python - <<'PY'
import json
import os
from pymilvus import MilvusClient
client = MilvusClient(
uri=os.environ["MILVUS_URI"],
token=os.environ["MILVUS_TOKEN"],
)
collection = os.environ["COLLECTION"]
rows = json.loads(os.environ["PAYLOAD"])
schema = client.describe_collection(collection_name=collection)
print("collection_visible=", collection in client.list_collections())
print("auto_id=", schema["auto_id"])
for field in schema["fields"]:
print(
"field=",
field["name"],
"type=",
field["type"],
"primary=",
field.get("is_primary", False),
"params=",
field.get("params", {}),
)
print("rows=", len(rows), "payload_bytes=", len(os.environ["PAYLOAD"].encode()))
if os.getenv("APPLY") != "1":
print("dry_run=true; set APPLY=1 only for an approved test write")
else:
try:
result = client.insert(collection_name=collection, data=rows)
print("insert_result=", result)
except Exception as exc:
print("insert_error=", type(exc).__name__, str(exc))
PY预期输出(字段和值随集合而变):
collection_visible= True
auto_id= False
field= id type= <TYPE> primary= True params= {}
field= vector type= <TYPE> primary= False params= {'dim': 4}
field= title type= <TYPE> primary= False params= {'max_length': <LENGTH>}
rows= 1 payload_bytes= <BYTES>
dry_run=true; set APPLY=1 only for an approved test write读取方法:向量字段的 dim 必须与请求向量长度一致;auto_id=True 时通常不要在普通插入中携带主键;字段名、数据类型、字符串长度和必填字段必须与 Schema 对齐。describe_collection() 会返回这些定义。:contentReference[oaicite:0]{index=0}
高频故障
- 字段或维度错误:触发条件是字段缺失、类型错误、字符串超长或向量维度不符;后果是整批拒绝。安全做法是先读取 Schema,在客户端逐条校验,再发送小批测试。
- 主键处理错误:触发条件是
auto_id集合仍携带主键,或业务把重复主键误当成更新;后果可能是请求失败或出现重复实体。需要更新或幂等写入时使用upsert,不要依赖普通insert自动去重。:contentReference[oaicite:1]{index=1} - 请求过大:触发条件是单批记录、向量或动态字段过多;后果是超时、gRPC 限制或代理拒绝。安全替代是按序列化后的字节数拆批,并为批次记录可重放标识。:contentReference[oaicite:2]{index=2}
- 服务状态异常:触发条件是鉴权失败、连接超时、节点资源不足或服务正在恢复;后果是连续失败和重试风暴。仅对超时、限流、临时不可用做指数退避;字段校验、权限和主键错误应立即停止重试。
排障清单
- 保存异常类型、错误码、消息、集合名、批次大小和请求 ID,敏感字段脱敏。
- 用只读接口确认连接、鉴权、集合存在及 Schema;不要用重复写入测试服务存活。
- 将失败批次缩到 1 条,核对字段、向量维度、主键和分区。
- 只有单条成功后再逐级放大批次;若失败点随大小变化,优先排查请求限制和资源压力。
- 重试前确认操作是否幂等;无法确认时先按主键查询或改用
upsert。
速查提示:先证明请求符合 Schema,再讨论扩容或重试;业务错误重试不会自行恢复。
检查集合加载状态、过滤条件、阈值、分区范围和数据可见性。
处理查询无结果
查询返回空数组时,先区分“集合里没有数据”和“数据存在但被加载、过滤、分区、阈值或一致性条件排除”。最有效的方法是从主键直查开始,逐项移除限制条件。
命令定位
按“加载状态 → 全集合计数 → 主键直查 → 移除分区 → 移除过滤 → 放宽阈值 → 检查写后可见性”的顺序缩小范围。不要同时修改多个条件,否则无法确认是哪一项导致无结果。

主诊断示例
以下以 Milvus 2.6.x 为例。把 PK_FIELD 和 PK_VALUE 改为目标集合的主键字段和值;字符串主键需把过滤表达式改为带引号的形式。
export MILVUS_URI='http://127.0.0.1:19530'
export MILVUS_TOKEN='root:Milvus'
export COLLECTION='documents'
export PK_FIELD='id'
export PK_VALUE='1001'
python - <<'PY'
import os
from pymilvus import MilvusClient
client = MilvusClient(
uri=os.environ["MILVUS_URI"],
token=os.environ["MILVUS_TOKEN"],
)
collection = os.environ["COLLECTION"]
pk_field = os.environ["PK_FIELD"]
pk_value = int(os.environ["PK_VALUE"])
print("load_state=", client.get_load_state(collection_name=collection))
print(
"count=",
client.query(
collection_name=collection,
filter="",
output_fields=["count(*)"],
),
)
print(
"by_id=",
client.query(
collection_name=collection,
filter=f"{pk_field} == {pk_value}",
output_fields=["*"],
consistency_level="Strong",
),
)
PY预期输出(找到目标记录时):
load_state= {'state': <LoadState: Loaded>}
count= [{'count(*)': <COUNT>}]
by_id= [{'id': 1001, '<FIELD>': '<VALUE>'}]若 count 为正而 by_id=[],说明集合有数据但目标主键不在当前集合,或主键值、字段类型不正确。若主键直查有结果而原检索为空,问题集中在分区、过滤表达式、向量、阈值或搜索参数。query() 支持空过滤计数和布尔过滤,partition_names 会把查询限制在指定分区。:contentReference[oaicite:3]{index=3}
高频用法
逐步放宽条件
先保留相同查询向量,只移除业务过滤;随后移除 partition_names;最后暂时取消应用层分数阈值,仅观察前 topK 的原始距离或相似度。每次只改一项并记录结果。
检查阈值方向
COSINE、IP 通常是分数越大越相似,L2 通常是距离越小越相似。触发条件是把方向写反或阈值设得过严;后果是数据库已有近邻,但应用层全部丢弃。安全做法是先输出原始 score/distance 分布,再依据当前度量方式设置阈值,不要复用另一种度量的经验值。:contentReference[oaicite:4]{index=4}
检查写后可见性
刚写入即查询时,默认一致性设置可能允许短暂不可见。触发条件是写请求成功后立即由另一个会话读取;后果是偶发空结果。安全替代是关键读使用 Strong 或同会话语义,普通检索接受短暂延迟并设置有限重试。Milvus 支持 Strong、Bounded、Session 和 Eventually 等一致性级别。:contentReference[oaicite:5]{index=5}
风险与边界
不要把“加载成功”理解为“目标记录一定存在”;加载只说明查询节点可服务。集合统计也可能与刚写入的流式数据存在时间差,因此计数适合判断大方向,不能单独证明某个主键已可见。:contentReference[oaicite:6]{index=6}
不要在生产环境直接删除过滤条件并返回全部业务字段。触发条件是为了排障执行无界查询;后果是高负载或敏感数据暴露。安全做法是限定 limit、只返回主键和少数字段,并在测试账号或只读环境执行。
排障清单
- 确认查询连接的是正确集群、数据库、集合和别名。
- 检查集合加载状态;未加载时先加载并等待状态稳定。
- 用计数确认集合是否有数据,再用已知主键做强一致性直查。
- 主键可查时,依次移除分区、过滤和阈值,不要一次全改。
- 核对查询向量维度、归一化方式、索引度量与检索度量。
- 对刚写入数据检查一致性级别、写入结果和读取时序。
速查提示:先用主键证明数据存在,再恢复分区、过滤和阈值;空结果不是异常码,必须靠逐项减法定位。
从文本分块、嵌入模型、距离度量和查询表达定位检索质量问题。
处理结果相关性差
当检索结果主题偏离、正确文档排名靠后或相似内容互相干扰时,按“查询表达→文本分块→嵌入模型→距离度量与索引→过滤和重排”的顺序定位。目标是先量化问题,再一次只修改一个变量,避免凭主观反复调参。

命令定位
先固定一组有明确正确答案的查询,导出每条查询的期望文档 ID 和实际 TopK 结果。不要先调大 topK;如果没有基准集,无法判断调整是真正提升了召回率,还是仅增加了噪声。
优先观察三类现象:正确文档完全未召回,多半是分块、嵌入或过滤问题;正确文档已召回但排名低,多半是度量、索引参数或重排问题;同类查询表现差异大,多半是查询表达、数据质量或租户过滤不一致。
可运行评估
下面脚本用少量人工标注样本计算 Recall@K 和 MRR。把 cases 替换为从业务系统导出的结果即可复用。
from statistics import mean
cases = [
{
"query": "重置用户密码",
"expected_ids": {"doc-17"},
"returned_ids": ["doc-03", "doc-17", "doc-22"],
},
{
"query": "查询订单退款状态",
"expected_ids": {"doc-09"},
"returned_ids": ["doc-09", "doc-31", "doc-18"],
},
{
"query": "修改发票抬头",
"expected_ids": {"doc-42"},
"returned_ids": ["doc-07", "doc-12", "doc-11"],
},
]
def recall_at_k(case: dict) -> float:
hits = case["expected_ids"].intersection(case["returned_ids"])
return len(hits) / len(case["expected_ids"])
def reciprocal_rank(case: dict) -> float:
for rank, doc_id in enumerate(case["returned_ids"], start=1):
if doc_id in case["expected_ids"]:
return 1.0 / rank
return 0.0
print(f"Recall@3={mean(recall_at_k(c) for c in cases):.3f}")
print(f"MRR={mean(reciprocal_rank(c) for c in cases):.3f}")预期输出
Recall@3=0.667
MRR=0.500Recall@3 表示三条查询中有两条在前三名找到了正确文档;MRR 为 0.500,说明正确结果即使被召回,整体排名仍不够靠前。调整后必须用同一批样本复测,才能比较前后效果。
排障清单
- 查询表达:确认检索文本包含真实业务意图,不要把无关对话历史、模板前缀或空字符串一起送入嵌入模型。
- 文本分块:检查块是否过短导致语义残缺,或过长导致多个主题混在一起;同时验证标题、路径等上下文是否随正文写入。
- 嵌入模型:入库与查询必须使用同一模型、同一版本和同一归一化方式;模型变更后应重算存量向量。
- 距离度量:余弦相似度通常要求方向一致;内积常与向量归一化配合;L2 的分数方向与相似度分数相反,排序读取不能混用。
- 过滤条件:确认租户、权限、时间和状态过滤没有误排除正确文档;先移除非必要过滤做对照,再逐项恢复。
- 索引与重排:近似索引参数过小会漏召回;正确结果已进入候选集但排序差时,再增加关键词融合或重排模型。
风险与边界
盲目增大 topK、nprobe、ef 等候选参数,会在数据量大或并发高时显著增加延迟和计算成本,而且可能把更多语义相近但业务无关的文档带入结果。安全做法是先建立离线基准集,在限定延迟预算下逐档测试参数,再通过过滤、混合检索或重排提升精度。
不要在同一次实验中同时更换分块策略、嵌入模型和索引参数,否则指标变化无法归因。生产调整前保留旧索引或旧集合,采用影子流量或小比例灰度验证,确认召回率、排名和超时率均未恶化后再扩大范围。
兼容性
这套方法适用于 Milvus、Elasticsearch/OpenSearch 向量检索、pgvector、Pinecone、Weaviate 等系统。具体分数字段、索引参数和过滤语法不同,但“固定基准集、逐层定位、单变量验证”的顺序不变。
检查索引状态、候选范围、并发压力和客户端超时设置。
处理查询超时
当查询在客户端报超时、HTTP 状态为空、延迟突然升高或高并发下大量失败时,先把总耗时拆成连接、排队、检索和返回四段。最终要判断超时发生在客户端预算、网络链路、服务排队还是索引搜索阶段,而不是直接把超时时间调大。

命令定位
先用单请求测量各阶段耗时,再做并发测试。单请求也慢,优先查网络、索引状态和候选范围;单请求正常而并发时超时,优先查连接池、服务队列、CPU、内存和磁盘压力。
客户端超时必须大于连接超时,并覆盖网关和服务端的处理上限。任何一层更早终止,外层看到的都可能只是“timeout”,因此要同时保留客户端耗时、HTTP 状态和服务端请求日志中的同一请求 ID。
可运行测量
把 <PORT>、<PATH> 和请求字段替换为实际接口。命令会把响应体写入临时文件,并打印 DNS、连接、首字节和总耗时。
export VECTOR_API_URL="http://127.0.0.1:<PORT>/<PATH>"
cat > request.json <<'JSON'
{
"vector": [0.12, 0.34, 0.56],
"topK": 10,
"filter": "tenant_id == \"t-001\""
}
JSON
curl -sS \
-o /tmp/vector-response.json \
--connect-timeout 2 \
--max-time 10 \
-H "Content-Type: application/json" \
--data @request.json \
-w "http_code=%{http_code}\ntime_namelookup=%{time_namelookup}\ntime_connect=%{time_connect}\ntime_starttransfer=%{time_starttransfer}\ntime_total=%{time_total}\n" \
"$VECTOR_API_URL"预期输出
http_code=200
time_namelookup=<TIME>
time_connect=<TIME>
time_starttransfer=<TIME>
time_total=<TIME>实际时间会变化。time_connect 接近 2 秒时重点检查地址、DNS、防火墙和连接耗尽;time_starttransfer 明显高于 time_connect 时,等待主要发生在网关、服务队列或检索计算;time_total 接近 10 秒且 http_code=000 时,通常是客户端 --max-time 先触发。
高频用法
- 检查索引和集合状态:确认索引已构建、目标分区或集合已加载,且没有处于重建、迁移或恢复阶段。
- 缩小候选范围:先收紧租户、时间、状态或分区过滤,再降低
topK;近似索引的nprobe、ef等搜索参数只调到满足召回率的最小值。 - 区分并发问题:比较单请求、固定并发和峰值并发的 P50、P95、P99;只有尾延迟恶化时,重点查看连接池、线程池和服务队列。
- 对齐超时预算:连接超时应最短,服务端查询上限次之,网关和客户端总超时稍长;重试必须使用退避和抖动,避免超时后立即放大流量。
排障清单
- 查询计划:移除非必要输出字段、超大
topK、宽范围过滤和代价高的后处理,确认是否立即恢复。 - 索引参数:索引缺失、未加载或搜索参数过大时,系统可能退化为高成本扫描;检查索引命中与加载状态。
- 资源压力:同时查看 CPU、内存、磁盘 I/O、网络、线程池和排队长度;平均值正常不代表 P99 正常。
- 客户端配置:确认连接池上限、空闲连接、请求队列和读取超时,避免每次查询都新建连接。
- 日志关联:用请求 ID 对齐客户端、网关和服务端日志,定位最后一个成功阶段;只看客户端异常通常无法区分取消、断连和服务端超时。
风险与边界
直接把客户端超时从 10 秒提高到 60 秒,会让慢请求更久占用连接、线程和队列;高并发下可能引发级联阻塞,并掩盖索引未加载或查询范围过大的根因。安全替代方案是先限制查询成本、设置服务端硬上限,并对超时请求做限流、熔断或降级。
无条件重试会把一次慢查询变成多次并发查询,服务已过载时后果更严重。只有幂等查询才允许自动重试,并应限制次数、使用指数退避和随机抖动;客户端取消后,服务端也应尽可能传播取消信号,避免后台继续消耗资源。
兼容性
curl 的计时字段适用于 HTTP 或 REST 网关。使用 gRPC 或原生 SDK 时,应采集连接建立、客户端队列、服务端处理和总耗时等同类指标;具体索引状态、搜索参数和取消机制以所用向量数据库客户端为准。
持续观察查询延迟、写入吞吐、错误率、内存和磁盘使用情况。
监控运行指标
用于持续发现查询变慢、写入积压、错误突增和资源逼近上限。Milvus 分布式组件通常由 Prometheus 抓取指标,并通过 Grafana 展示;组件指标端点默认形态为 http://<component-host>:9091/metrics。
核心指标
| 目标 | 推荐指标 | 读取方法 |
|---|---|---|
| 查询延迟 | milvus_proxy_req_latency_bucket |
看 Search、Query 的 p95/p99,不只看平均值 |
| 写入吞吐 | milvus_proxy_insert_vectors_count |
对计数器使用 rate(),得到每秒写入向量数 |
| 请求错误 | milvus_proxy_req_count{status="fail"} |
按 function_name、pod 分组,定位失败接口和实例 |
| 内存 | container_memory_working_set_bytes |
与容器内存限制对比,观察持续增长而非瞬时尖峰 |
| 磁盘 | kubelet_volume_stats_used_bytes、kubelet_volume_stats_capacity_bytes |
计算 PVC 使用率,并同时关注增长速度 |
Milvus 官方看板使用 histogram_quantile() 计算请求尾延迟,并用 rate() 或 increase()读取计数器;Kubernetes 可提供容器内存和卷使用量指标。
快速查询
先把 PROM_URL 指向 Prometheus HTTP 地址。下面一次查询 p99 请求延迟、每秒写入向量数和每秒失败请求数。
PROM_URL="${PROM_URL:-http://localhost:9090}"
prom_query() {
curl -fsSG "${PROM_URL}/api/v1/query" --data-urlencode "query=$1"
printf '\n'
}
# 按接口查看最近 5 分钟的 p99 延迟
prom_query 'histogram_quantile(0.99, sum by (le, function_name) (rate(milvus_proxy_req_latency_bucket[5m])))'
# 按代理实例查看写入向量吞吐
prom_query 'sum by (pod) (rate(milvus_proxy_insert_vectors_count[5m]))'
# 按接口和代理实例查看失败请求速率
prom_query 'sum by (function_name, pod) (rate(milvus_proxy_req_count{status="fail"}[5m]))'预期输出
{"status":"success","data":{"resultType":"vector","result":[{"metric":{"function_name":"Search"},"value":["<TIME>","12.4"]}]}}
{"status":"success","data":{"resultType":"vector","result":[{"metric":{"pod":"<POD>"},"value":["<TIME>","850.2"]}]}}
{"status":"success","data":{"resultType":"vector","result":[]}}第一行数值是当前 p99 延迟,单位必须按所用 Milvus 版本的指标说明确认;第二行表示约每秒写入 850.2 个向量;第三行结果为空表示当前时间点没有匹配到失败请求。
资源查询
以下 PromQL 用于补齐 Kubernetes 层的内存与磁盘观察。将 <NAMESPACE> 替换为实际命名空间。
sum by (pod) (
container_memory_working_set_bytes{
namespace="<NAMESPACE>",
pod=~".*(proxy|querynode|datanode).*",
container!=""
}
)
100 *
sum by (persistentvolumeclaim) (
kubelet_volume_stats_used_bytes{namespace="<NAMESPACE>"}
)
/
sum by (persistentvolumeclaim) (
kubelet_volume_stats_capacity_bytes{namespace="<NAMESPACE>"}
)在 Prometheus 的 Table 页面验证是否返回目标 Pod 或 PVC;没有数据时先检查 kubelet、cAdvisor 或 kube-state-metrics 是否已被抓取,而不是直接判断 Milvus 没有资源压力。
告警边界
不要直接复制固定阈值到所有集群。数据规模、索引类型、TopK、NQ 和硬件差异会改变正常区间,应先用业务 SLO 和历史基线确定阈值。
只监控平均延迟会掩盖少量严重慢请求,后果是用户已超时但看板仍显示正常;安全替代方案是同时告警 p95/p99、错误率和请求量。直接读取累计计数器会把正常增长误判为异常,应使用 rate() 或 increase()。
Prometheus 抓取周期过短或标签包含 collection、ID 等高基数字段时,可能增加时序库负载;优先使用稳定标签聚合,并从 15~30 秒抓取周期开始评估。
排障清单
- 延迟升高但错误率不变:检查 QueryNode 读任务队列、CPU、内存和 segment load 延迟。
- 写入吞吐下降:同时检查失败请求、DataNode 资源、消息链路和磁盘增长。
- 单个 Pod 指标异常:先与同角色其他 Pod 对比,再查看该 Pod 日志和重启次数。
- 全部 Milvus 指标消失:检查 Prometheus target、网络策略、ServiceMonitor 和
9091/metrics是否可达。 - 指标名称不存在:确认 Milvus 版本及对应 Dashboard,不要跨大版本直接复用 PromQL。
Milvus 2.6.15 曾调整多类延迟指标的精度与单位表达,升级前后应核对看板单位并重建阈值,避免把数值变化误判成性能回退。
从客户端、代理、数据节点和查询节点日志中定位异常请求与资源问题。
查看服务日志
用于沿客户端请求路径定位超时、资源不足、节点重启和内部 RPC 异常。先用请求 ID、时间窗口和组件角色缩小范围,再依次检查客户端、Proxy、QueryNode 或 DataNode,避免从全量日志中盲目搜索。

命令定位
Milvus 默认把日志写到标准输出和标准错误,因此 Kubernetes 环境优先使用 kubectl logs;生产环境需要跨 Pod 生命周期保留日志时,应配置持久化或集中日志采集。
先设置命名空间和组件关键字。组件名通常可取 proxy、querynode 或 datanode,实际 Pod 名以部署结果为准。
NS="${NS:-milvus}"
COMPONENT="${COMPONENT:-proxy}"
POD="$(
kubectl -n "$NS" get pods -o name | grep -i "$COMPONENT" | head -n 1
)"
test -n "$POD" || {
echo "未找到组件: namespace=$NS component=$COMPONENT" >&2
exit 1
}
echo "target=$POD"
# 只取最近 30 分钟,并保留 Kubernetes 时间戳
kubectl -n "$NS" logs "$POD" --all-containers=true --since=30m --tail=500 --timestamps | grep -Ei 'error|warn|panic|fatal|oom|deadline|timeout|unavailable|resource exhausted' | tail -n 50 || true
kubectl -n "$NS" get "$POD" -o jsonpath='restartCount={.status.containerStatuses[*].restartCount}{"\n"}'预期输出
target=pod/<POD>
<TIME> <LOG_LINE_MATCHING_ERROR_OR_TIMEOUT>
restartCount=0没有异常匹配时只会显示目标 Pod 和重启次数。<TIME>、<POD> 与日志内容均为动态值;重启次数大于 0 时还要读取上一个容器实例的日志。
高频用法
查看崩溃或重启前的上一实例日志:
kubectl -n "$NS" logs "$POD" --all-containers=true --previous --timestamps --tail=500预期结果
<TIME> <LAST_CONTAINER_LOG_LINE>出现 previous terminated container ... not found 表示没有可读取的上一实例日志,或历史日志已被清理。
围绕请求 ID 搜索当前组件日志:
REQUEST_ID="<ID>"
kubectl -n "$NS" logs "$POD" --all-containers=true --since=2h --timestamps | grep -F "$REQUEST_ID"预期输出
<TIME> <LOG_LINE> request_id=<ID>若无结果,先确认客户端确实记录并透传了该 ID,再扩大时间窗口或切换到 Proxy、QueryNode、DataNode。客户端至少记录操作类型、collection、耗时、状态码和请求 ID,但不要记录认证令牌、完整向量或敏感业务字段。
读取顺序
客户端出现 deadline exceeded 时,先确认客户端超时值和实际耗时;Proxy 同时出现相同请求 ID,说明请求已到达服务端。Proxy 有记录但 QueryNode 或 DataNode 没有对应记录时,重点检查路由、队列、节点健康和内部 RPC。
查询类请求优先检查 Proxy 与 QueryNode;插入、删除和 flush 类请求优先检查 Proxy 与 DataNode。Milvus 新版本的分布式架构可能还包含 Streaming Node,因此升级后应按实际组件清单调整检索范围。
风险与边界
直接执行无时间范围的 kubectl logs 可能拉取大量日志,导致终端卡顿、API Server 压力增加或关键行被淹没;安全替代方案是先使用 --since、--tail 和请求 ID 缩小范围。
把日志级别长期调到 debug 或 trace 会显著增加日志量和存储消耗,并可能暴露更多请求上下文;只在限定组件和时间窗口内临时启用,完成采样后恢复原级别。
Pod 重建后,节点本地日志可能丢失。触发条件是未配置持久卷或集中采集且容器已退出;后果是无法还原故障现场。生产环境应将日志发送到集中系统,或按官方建议配置 log.file.rootPath 和 Helm 日志持久化。
排障清单
kubectl logs返回多个容器错误:先执行kubectl get pod "$POD" -n "$NS" -o jsonpath='{.spec.containers[*].name}',再用-c <CONTAINER>指定容器。- 日志为空但请求失败:核对命名空间、Pod、时间范围、时区和是否选中了 sidecar。
- 出现 OOM 或退出码 137:结合
kubectl describe pod、内存指标和 limits 判断,不要只靠日志结论。 - 同一错误在所有 Proxy 出现:检查公共依赖、配置和下游节点;只在单个 Pod 出现则优先隔离该实例。
- 只有客户端超时、服务端无请求记录:检查地址、DNS、负载均衡、TLS、网络策略和客户端连接池。
- 日志格式或组件名与示例不同:以当前 Milvus 版本、部署模式和 Helm/Operator 生成的 Pod 为准。