NoSQL 与搜索 / 知识点
向量数据库操作速查手册
手册条目
配置服务地址、认证信息和连接参数,并验证客户端能够正常访问向量数据库。
连接向量数据库
用于确认服务地址、API Key、TLS 与超时参数是否正确。以下命令以 Qdrant REST API 为基准:REST 默认通过 6333 端口访问,启用鉴权后请求需携带 api-key;生产环境应使用 HTTPS,避免凭据明文传输。:contentReference[oaicite:0]{index=0}
前置配置
将地址和密钥放入环境变量,避免直接写进脚本、Shell 历史或代码仓库。QDRANT_URL 应包含协议和端口,但末尾斜杠可有可无。
export QDRANT_URL='https://<HOST>:<PORT>'
export QDRANT_API_KEY='<API_KEY>'
test -n "$QDRANT_URL" && test -n "$QDRANT_API_KEY"预期结果:命令无输出且退出码为 0;缺少任一变量时退出码非 0。
连接验证
根路径会返回服务标识和版本信息,可同时验证 DNS、TCP、TLS、认证与 REST 服务。--connect-timeout 限制建连时间,--max-time 限制整个请求时间。
curl --fail-with-body --silent --show-error \
--connect-timeout 3 \
--max-time 10 \
--header "api-key: ${QDRANT_API_KEY}" \
"${QDRANT_URL%/}"预期输出
{"title":"qdrant - vector search engine","version":"<VERSION>","commit":"<COMMIT>"}version 与 commit 会随实际部署变化。能收到该 JSON 说明网络、证书、密钥和服务入口均已通过;HTTP 401 或 403 表示认证或权限失败,连接超时通常表示地址、端口、防火墙或代理不可达。
常用连接参数
| 参数 | 建议值 | 作用 |
|---|---|---|
--connect-timeout |
3~5 秒 | 控制 DNS、TCP、TLS 建连等待时间 |
--max-time |
10~30 秒 | 防止请求无限挂起 |
--retry 2 |
仅幂等读取 | 缓解瞬时网络失败 |
--cacert <PATH> |
私有 CA 场景 | 指定可信 CA 证书 |
风险与边界
使用 HTTP 发送 API Key 时,链路监听者可能窃取凭据;安全替代方案是启用 HTTPS,或在受控内网通过反向代理终止 TLS。:contentReference[oaicite:1]{index=1}
不要用 -k 或 --insecure 解决证书错误。该选项会跳过服务端身份校验,可能把密钥发送给伪造节点;应改为修复证书域名、完整证书链或通过 --cacert <PATH> 指定可信 CA。
连接成功只证明当前入口可访问,不代表目标集合存在、向量维度匹配或写入权限可用。上线前还应以最小权限密钥读取一个已知集合,必要时再执行隔离的测试写入。
排障清单
Could not resolve host:检查主机名、DNS 搜索域和代理变量。Connection refused:检查端口映射、监听地址、安全组和容器状态。SSL certificate problem:核对证书域名、有效期、证书链和本机 CA。401/403:确认密钥未带多余空格,且权限覆盖目标集群或集合。404:检查是否把管理 API 地址误当成数据库 REST 地址。
速查:先验证根路径,再验证已知集合;不要用关闭 TLS 校验的方式“修好”连接。
通过健康检查接口确认数据库节点、依赖组件和核心服务是否可用。
检查向量数据库服务状态
用于区分“进程存活”和“已经可以接收业务流量”。以下示例以 Qdrant 为基准,依次检查 /healthz、/livez 和 /readyz;官方文档将它们用于实例健康、存活与就绪判断。:contentReference[oaicite:2]{index=2}
执行检查
脚本同时输出 HTTP 状态码和响应体。健康检查端点通常无需 API Key;若前置网关强制鉴权,可按网关规则补充请求头。
QDRANT_URL='http://<HOST>:<PORT>'
for endpoint in healthz livez readyz; do
output_file="$(mktemp)"
code="$(
curl --silent --show-error \
--connect-timeout 3 \
--max-time 5 \
--output "$output_file" \
--write-out '%{http_code}' \
"${QDRANT_URL%/}/${endpoint}"
)"
body="$(cat "$output_file")"
rm -f "$output_file"
printf '%-7s status=%s body=%s\n' "$endpoint" "$code" "$body"
done预期输出
healthz status=200 body="healthz check passed"
livez status=200 body="healthz check passed"
readyz status=200 body="healthz check passed"响应文本可能随版本变化,判断时以 HTTP 状态码为主。readyz=200 才适合作为接入业务流量的必要条件;livez=200 仅说明进程仍能响应。
结果读取
| 结果 | 含义 | 处理 |
|---|---|---|
| 三项均为 200 | 节点存活且已就绪 | 继续验证业务读写 |
livez=200、readyz!=200 |
进程存活但尚未就绪 | 暂停导流并查看启动、恢复或集群日志 |
| 全部超时 | 网络、代理、端口或节点阻塞 | 从同网络位置检查连通性 |
| 502/503 | 多半由网关或负载均衡返回 | 绕过网关直连节点复核 |
| 301/302 | 地址被重定向 | 检查 HTTP/HTTPS 和路径配置 |
生产探针建议
Kubernetes 的存活探针使用 /livez,就绪探针使用 /readyz。不要把短暂的就绪失败配置成立即重启,否则索引加载、数据恢复或滚动升级期间可能形成重启循环。
健康接口只说明被访问节点的基础状态,不等于集合可查询、分片完整、磁盘容量充足,也不验证外部嵌入服务或业务依赖。需要更强验证时,应追加一次对已知集合的只读请求,并分别监控代理、存储和嵌入服务。
风险与边界
探针超时设得过短会把正常的启动或恢复误判为故障,导致摘流或重启;应结合冷启动时间设置 initialDelaySeconds、timeoutSeconds 和失败阈值。
只检查负载均衡地址可能掩盖单节点故障;安全替代方案是同时保留节点级探针和集群级监控,并对连续失败而非单次抖动告警。
速查:livez 决定是否需要重启,readyz 决定是否可以接流量;业务可用性仍需集合级只读验证。
创建用于保存向量、标量字段和业务元数据的集合或索引空间。
创建集合
用于第一次建立向量存储空间,结果是一个包含主键、向量、正文和租户过滤字段的 Milvus 集合。示例使用 Milvus Lite 本地文件,替换 uri 后也可连接独立 Milvus 服务。
前置条件
已安装与目标 Milvus 版本匹配的 PyMilvus。生产环境应先确定向量模型维度、相似度度量和集合命名规则;集合创建后再修改核心字段通常比新建版本化集合风险更高。
主示例
以下脚本拒绝覆盖同名集合,创建 documents_v1,同时为向量字段建立余弦相似度索引。
from pymilvus import DataType, MilvusClient
DB_URI = "./vector_demo.db"
COLLECTION = "documents_v1"
client = MilvusClient(uri=DB_URI)
# 避免误删或覆盖已有业务数据。
if client.has_collection(collection_name=COLLECTION):
raise RuntimeError(f"collection already exists: {COLLECTION}")
schema = MilvusClient.create_schema(
auto_id=False,
enable_dynamic_field=False,
)
schema.add_field(
field_name="doc_id",
datatype=DataType.VARCHAR,
is_primary=True,
max_length=64,
)
schema.add_field(
field_name="embedding",
datatype=DataType.FLOAT_VECTOR,
dim=4,
)
schema.add_field(
field_name="content",
datatype=DataType.VARCHAR,
max_length=2048,
)
schema.add_field(
field_name="tenant_id",
datatype=DataType.VARCHAR,
max_length=64,
)
index_params = client.prepare_index_params()
index_params.add_index(
field_name="embedding",
index_type="AUTOINDEX",
metric_type="COSINE",
)
client.create_collection(
collection_name=COLLECTION,
schema=schema,
index_params=index_params,
)
description = client.describe_collection(collection_name=COLLECTION)
print(f"created={client.has_collection(collection_name=COLLECTION)}")
print("fields=" + str([field["name"] for field in description["fields"]]))
print("indexes=" + str(client.list_indexes(collection_name=COLLECTION)))
client.close()预期输出
created=True
fields=['doc_id', 'embedding', 'content', 'tenant_id']
indexes=['embedding']created=True 表示集合存在;fields 用于核对字段未遗漏;indexes 中出现 embedding 表示向量索引已创建。数据库文件实际路径可能随运行目录不同而变化,可用 <PATH> 表示。
关键参数
auto_id=False:由业务提供主键,便于幂等写入和跨系统追踪;设为True后插入数据时不要再传主键。enable_dynamic_field=False:拒绝未声明字段,能尽早发现拼写错误。只有确实需要接收不固定元数据时才开启。dim=4:仅为可运行演示。生产值必须与嵌入模型输出维度完全一致。metric_type="COSINE":适合按方向相似度比较的文本向量;索引度量应与后续搜索度量保持一致。index_params:随集合一起传入时会建立索引并加载集合;不传时应在写入或搜索流程中另行创建索引并加载。
风险与边界
同名集合已存在时重复创建会失败。不要用 drop_collection() 作为默认重试手段,否则可能永久删除向量和元数据;安全替代方案是先执行 has_collection(),再复用现有集合或创建 documents_v2。
向量维度配置错误时,后续插入会因长度不匹配失败。安全做法是在建表前用一条真实模型输出校验维度,并把模型名称、版本和维度写入部署配置。
Milvus Lite 适合本地验证,但分片、分区键等集群能力受限。需要多租户分区、横向扩展或高可用时,应在独立 Milvus 集群验证同一 schema。
排障清单
- 报“collection already exists”:确认是否应复用原集合;需要变更结构时创建新版本,不要直接删除。
- 报向量维度非法:检查
dim是否大于 1,并与模型输出数组长度一致。 - 创建成功但无法搜索:检查向量索引是否存在、集合是否已加载,以及搜索使用的度量是否与索引一致。
- 本地文件无法创建:确认当前目录可写,或把
DB_URI改为有权限的绝对<PATH>。 - 连接远程服务失败:检查
uri、认证令牌、网络和服务端与 PyMilvus 的版本兼容性。
速查提示:先固定模型维度和主键策略,再创建 schema、索引和集合;验证时至少检查集合存在、字段列表和索引列表。
定义主键、向量字段、文本字段和过滤字段的数据类型及约束。
设计字段结构
用于在创建集合前确定主键、向量、文本和过滤字段的类型与约束。目标是让写入可校验、查询可过滤,并避免把所有业务属性塞进无约束的动态字段。
字段设计规则
主键负责唯一定位实体,应稳定、不可复用。已有业务 ID 时优先使用 VARCHAR 或 INT64 并关闭自动生成;没有稳定 ID 时才考虑 auto_id=True。
向量字段必须选定向量类型和维度。FLOAT_VECTOR 的 dim 必须等于嵌入模型输出长度,度量方式则在索引或搜索参数中配置。
文本字段使用 VARCHAR 时必须设置 max_length。只保存检索结果展示所需的正文或摘要,超长原文可放对象存储,并在集合中保存 URI。
过滤字段应使用真实标量类型,例如租户和分类用 VARCHAR,时间用 INT64 时间戳,状态用 BOOL 或短字符串。经常出现在过滤表达式中的字段应保持值域稳定。
主示例
以下代码只构造并检查 schema,不连接服务端,适合在部署前做字段评审或单元测试。
from pymilvus import DataType, MilvusClient
EMBEDDING_DIM = 768
schema = MilvusClient.create_schema(
auto_id=False,
enable_dynamic_field=False,
)
schema.add_field(
field_name="doc_id",
datatype=DataType.VARCHAR,
is_primary=True,
max_length=64,
)
schema.add_field(
field_name="embedding",
datatype=DataType.FLOAT_VECTOR,
dim=EMBEDDING_DIM,
)
schema.add_field(
field_name="content",
datatype=DataType.VARCHAR,
max_length=4096,
)
schema.add_field(
field_name="tenant_id",
datatype=DataType.VARCHAR,
max_length=64,
)
schema.add_field(
field_name="category",
datatype=DataType.VARCHAR,
max_length=32,
)
schema.add_field(
field_name="created_at",
datatype=DataType.INT64,
)
spec = schema.to_dict()
fields = spec["fields"]
primary = next(field["name"] for field in fields if field.get("is_primary"))
vector = next(field for field in fields if field["name"] == "embedding")
print(f"primary={primary}")
print(f"vector_dim={vector['params']['dim']}")
print("fields=" + str([field["name"] for field in fields]))预期输出
primary=doc_id
vector_dim=768
fields=['doc_id', 'embedding', 'content', 'tenant_id', 'category', 'created_at']primary 用于确认只有预期字段承担主键;vector_dim 必须与模型配置一致;字段列表可用于发现漏字段或命名漂移。
常用约束
| 角色 | 推荐定义 | 必查约束 |
|---|---|---|
| 主键 | INT64 或 VARCHAR |
唯一、稳定;只能有一个主键 |
| 向量 | FLOAT_VECTOR |
dim 与模型输出一致 |
| 文本 | VARCHAR |
设置合理 max_length |
| 枚举或租户 | VARCHAR |
控制值域和大小写 |
| 时间 | INT64 |
统一秒或毫秒,不混用 |
| 可选元数据 | 显式字段或动态字段 | 明确是否允许缺失 |
可缺失字段才设置 nullable=True。非空字段在写入时缺失或传入空值会失败;对关键过滤字段保持非空,通常比依赖运行时兜底更安全。
风险与边界
开启动态字段后,未声明属性会进入保留的 $meta,拼写错误也可能被静默保存,导致过滤条件查不到数据。触发条件是写入包含 schema 外字段;安全替代方案是生产集合默认关闭动态字段,并在应用层做输入白名单校验。
VARCHAR.max_length 过小会导致超长数据写入失败,过大则放宽了无效数据边界。应基于真实样本的高分位长度留少量余量,超长正文改存外部 URI。
时间戳单位不统一会造成范围过滤结果错误。触发条件是部分服务写秒、部分服务写毫秒;安全替代方案是在字段名或接口契约中固定单位,例如统一使用 Unix 毫秒并在写入前校验数量级。
集合投入使用后再调整主键、向量类型或维度通常需要迁移数据。先创建版本化新集合、回填数据、双读验证,再切换别名或流量,比原地破坏性修改更安全。
排障清单
- schema 创建时报主键错误:确认只有一个字段设置
is_primary=True,且主键类型符合数据库支持范围。 - 写入报字段缺失:检查字段是否非空、是否关闭了动态字段,以及应用对象名称是否与 schema 完全一致。
- 写入报字符串过长:定位对应
VARCHAR,评估扩大max_length或改存摘要与外部 URI。 - 向量写入失败:打印单条向量长度,与 schema 的
dim和模型版本逐项核对。 - 过滤无结果:检查字段类型、大小写、时间单位和动态字段拼写,不要先假设向量检索异常。
速查提示:主键保证唯一,向量维度绑定模型,正文限制长度,过滤字段显式建模;核心约束在创建集合前一次定清。
根据嵌入模型输出确定向量字段维度,避免写入时发生维度不匹配。
设置向量维度
在创建集合、索引或向量字段前,先用实际嵌入结果确认维度;写入向量的元素数量必须与字段维度完全一致,否则通常会在写入或检索阶段被拒绝。
命令定位
维度由嵌入模型的输出决定,不应凭经验填写。先对一条固定文本生成向量并读取 len(vector),再把该值写入数据库的向量字段配置。查询向量也必须使用同一模型和同一维度。
高频用法
下面的脚本可在建库前验证单条向量、批量向量和预期维度。把 EXPECTED_DIM 替换为准备写入数据库的字段维度。
from collections.abc import Sequence
EXPECTED_DIM = 3
vectors = [
[0.12, -0.08, 0.91],
[0.44, 0.10, -0.27],
]
def validate_vectors(items: Sequence[Sequence[float]], expected_dim: int) -> None:
if expected_dim <= 0:
raise ValueError("expected_dim 必须大于 0")
for index, vector in enumerate(items):
actual_dim = len(vector)
if actual_dim != expected_dim:
raise ValueError(
f"第 {index} 条向量维度不匹配: expected={expected_dim}, actual={actual_dim}"
)
print(f"校验通过: count={len(items)}, dimension={expected_dim}")
validate_vectors(vectors, EXPECTED_DIM)预期输出
校验通过: count=2, dimension=3读取方法:dimension=3 表示每条向量都包含 3 个数,可据此设置向量字段;生产环境中的真实值通常远大于示例值。
风险与边界
模型升级或切换模型后,输出维度可能变化。继续写入旧字段会触发维度错误;即使维度相同,不同模型的向量空间也通常不可直接混用。安全做法是为新模型创建新字段、集合或索引,重新生成历史向量,再切换读流量。
不要通过截断或补零“适配”维度。这样虽然可能通过长度校验,却会破坏向量语义和召回质量。应回到嵌入模型配置,生成与字段定义一致的完整向量。
排障清单
- 打印实际向量长度,确认不是嵌套数组、空数组或序列化后的字符串。
- 核对写入端与查询端是否使用同一模型、模型版本和预处理流程。
- 检查批量数据中是否混入其他维度的向量。
- 修改维度后仍报错时,确认旧索引或旧集合是否需要重建。
速查:先测模型输出维度,再建字段;维度变化时迁移数据,不修改向量长度凑配置。
根据模型和检索目标选择余弦相似度、内积或欧氏距离。
选择距离度量
距离度量决定向量如何排序。语义检索通常优先使用余弦相似度;模型明确要求最大内积检索时使用内积;只有向量的绝对几何距离有意义且尺度一致时才使用欧氏距离。
基本语法
常见配置名为 COSINE、IP 或 DOT_PRODUCT、L2 或 EUCLIDEAN。名称因数据库而异,但排序方向必须分清:余弦和内积分数越大越相似,欧氏距离越小越相似。
高频用法
下面的可运行示例同时计算三种度量,便于核对数据库返回分数的含义。
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 = dot / (query_norm * candidate_norm)
l2 = math.sqrt(sum((a - b) ** 2 for a, b in zip(query, candidate)))
print(f"cosine={cosine:.3f}")
print(f"dot={dot:.3f}")
print(f"l2={l2:.3f}")预期输出
cosine=0.800
dot=0.800
l2=0.632读取方法:对同一批候选项,cosine 和 dot 应按降序取前几名,l2 应按升序取前几名。示例中两个向量已是单位向量,因此余弦与内积数值相同。
选择规则
| 度量 | 适用条件 | 排序方向 |
|---|---|---|
| 余弦相似度 | 只关心方向,向量长度不应影响语义相似度 | 越大越相似 |
| 内积 | 模型训练或文档明确要求最大内积,或向量模长携带有效信号 | 越大越相似 |
| 欧氏距离 | 绝对位置和尺度有意义,且写入与查询使用一致缩放 | 越小越相似 |
若所有向量都做了 L2 归一化,余弦与内积通常产生相同排序;未归一化时,两者可能明显不同。
风险与边界
索引创建后再更换度量,可能需要重建索引,旧阈值也不能直接复用。错误度量会导致排序异常、召回下降或阈值判断反向。安全做法是在固定验证集上比较 Recall@K、命中样例和分数分布,再确定度量。
归一化必须在写入端和查询端保持一致。只归一化一侧会改变分数分布;安全替代方案是统一封装嵌入后处理,并为归一化策略增加版本字段。
排障清单
- 确认模型文档是否指定距离度量或是否已输出归一化向量。
- 核对数据库返回的是“相似度”还是“距离”,以及排序方向。
- 用一组完全相同的向量验证:余弦应接近 1,欧氏距离应接近 0。
- 调整度量后重新评估过滤阈值,不沿用旧分数边界。
速查:模型无明确要求时先选余弦;最大内积模型选内积;几何距离和尺度明确时再选欧氏距离。
为向量字段创建适合数据规模和查询延迟要求的近似最近邻索引。
创建向量索引
用于给 Milvus 集合的向量字段建立 ANN 索引,并在上线前确认索引名称、距离度量和构建状态。没有明确调优依据时先用 AUTOINDEX;只有在压测证明需要时再切换 HNSW、IVF 或磁盘索引。
命令定位
核心调用链是 prepare_index_params() → add_index() → create_index() → describe_index()。索引完成后再加载集合并执行搜索;创建集合时已传入 index_params 的场景不需要重复创建。
基本语法
下面使用 Milvus Lite 创建一个独立测试集合,安装依赖后可直接运行:pip install -U "pymilvus[milvus-lite]"。
from pymilvus import DataType, MilvusClient
client = MilvusClient("./vector_ops.db")
collection_name = "docs_index_demo"
# 保证示例可重复运行;生产环境不要无条件删除现有集合。
if client.has_collection(collection_name):
client.drop_collection(collection_name)
schema = MilvusClient.create_schema(
auto_id=False,
enable_dynamic_field=False,
)
schema.add_field(
field_name="id",
datatype=DataType.INT64,
is_primary=True,
)
schema.add_field(
field_name="embedding",
datatype=DataType.FLOAT_VECTOR,
dim=4,
)
client.create_collection(
collection_name=collection_name,
schema=schema,
)
index_params = client.prepare_index_params()
index_params.add_index(
field_name="embedding",
index_name="embedding_auto_idx",
index_type="AUTOINDEX",
metric_type="COSINE",
)
# sync 默认为 True;返回时索引已构建完成。
client.create_index(
collection_name=collection_name,
index_params=index_params,
)
info = client.describe_index(
collection_name=collection_name,
index_name="embedding_auto_idx",
)
for key in ("index_name", "field_name", "metric_type", "state"):
print(f"{key}={info.get(key)}")预期输出
index_name=embedding_auto_idx
field_name=embedding
metric_type=COSINE
state=Finishedstate=Finished 表示构建完成;实际构建耗时取决于数据量、索引类型和集群资源。
索引选择速查
| 需求 | 优先选择 | 主要边界 |
|---|---|---|
| 无明确调优目标 | AUTOINDEX |
由 Milvus 选择实现,最省运维成本 |
| 数据可放入内存,追求低延迟和高召回 | HNSW |
M、efConstruction 越大,内存和构建时间通常越高 |
| 内存受限,可接受召回下降 | IVF_FLAT 或 IVF_PQ |
搜索端需联合调节 nprobe |
| 数据明显大于可用内存 | DiskANN |
依赖磁盘性能,先验证部署版本和资源要求 |
距离度量必须与嵌入模型和查询保持一致:文本语义检索常用 COSINE,原始欧氏空间使用 L2,已归一化且按内积训练的向量可用 IP。
风险与边界
- 在唯一生产集合上直接删除并重建索引,会造成搜索不可用或延迟抖动。需要变更类型或距离度量时,优先在新集合构建、压测并验证,再切换流量。
- 向量维度不影响索引参数声明,但插入和查询向量长度必须与字段
dim完全一致;不一致会直接报错,安全做法是在写入入口校验长度。 sync=False会让创建请求提前返回,此时不能把“请求成功”当作“索引可用”。必须轮询describe_index(),确认state=Finished后再加载和搜索。
排障清单
collection not found:确认数据库名、连接地址和集合名,避免连到默认数据库或测试实例。field not found:用describe_collection()核对向量字段名称、类型和维度。- 构建长期未完成:检查
pending_index_rows、数据量、磁盘和内存压力;先用AUTOINDEX验证链路,再逐步调大参数。 - 搜索结果异常:确认建索引与搜索使用相同的
metric_type,并检查向量是否按模型要求归一化。
兼容性
示例使用 MilvusClient。Milvus Lite 适合本地验证,小规模限制与集群版不同;生产环境只需把本地文件 URI 替换为服务地址和认证信息,并确保 PyMilvus 与服务端版本兼容。
检查集合字段、向量维度、索引配置、数据量和加载状态。
查看集合信息
用于一次性核对 Milvus 集合的字段、向量维度、索引、数据量和加载状态。生产排障时先读元数据,不要先执行删除、重建或强制加载等有副作用操作。
命令定位
常用接口分别是:describe_collection() 查看字段和维度,get_collection_stats() 查看行数,list_indexes() 与 describe_index() 查看索引,get_load_state() 查看是否已加载。
高频用法
下面的脚本先创建两条测试数据,再输出巡检时最常读的字段。生产使用时删除初始化部分,只保留从 describe_collection() 开始的查询逻辑。
from pymilvus import MilvusClient
client = MilvusClient("./vector_ops.db")
collection_name = "docs_inspect_demo"
# 仅为保证示例独立可运行;生产巡检禁止删除目标集合。
if client.has_collection(collection_name):
client.drop_collection(collection_name)
client.create_collection(
collection_name=collection_name,
dimension=4,
metric_type="COSINE",
)
client.insert(
collection_name=collection_name,
data=[
{"id": 1, "vector": [0.1, 0.2, 0.3, 0.4]},
{"id": 2, "vector": [0.4, 0.3, 0.2, 0.1]},
],
)
# 示例需要稳定行数;高写入生产集合不要为每次巡检都强制 flush。
client.flush(collection_name=collection_name)
schema = client.describe_collection(collection_name=collection_name)
stats = client.get_collection_stats(collection_name=collection_name)
index_names = client.list_indexes(collection_name=collection_name)
index_info = client.describe_index(
collection_name=collection_name,
index_name=index_names[0],
)
load_info = client.get_load_state(collection_name=collection_name)
vector_field = next(
field for field in schema["fields"] if field["name"] == "vector"
)
field_names = ",".join(field["name"] for field in schema["fields"])
state = load_info["state"]
state_name = getattr(state, "name", str(state))
print(f"collection={schema['collection_name']}")
print(f"fields={field_names}")
print(f"dimension={vector_field['params']['dim']}")
print(f"row_count={stats['row_count']}")
print(f"indexes={','.join(index_names)}")
print(f"metric_type={index_info.get('metric_type')}")
print(f"load_state={state_name}")预期输出
collection=docs_inspect_demo
fields=id,vector
dimension=4
row_count=2
indexes=vector
metric_type=COSINE
load_state=Loaded索引名称和部分内部 ID 可能因版本或建表方式不同;字段、维度、距离度量和加载状态应与预期配置一致。
输出字段说明
fields[].name:字段名;先确认主键和目标向量字段是否存在。fields[].params.dim:向量维度;必须与嵌入模型输出长度一致。row_count:已统计到的实体数量;持续写入时可能暂时落后于客户端累计写入数。index_name、index_type、metric_type:索引身份、算法和距离度量;多个向量字段时要逐个检查。state:索引构建状态;Finished才能视为索引就绪。load_state:集合或分区是否已加载;搜索前应为Loaded。
风险与边界
- 高频执行
flush()会增加持久化 I/O,并可能影响写入吞吐。日常巡检把row_count视为近似值;只有对账或发布验证需要稳定统计时,才在低峰期执行。 - 集合级
Loaded不代表目标分区一定满足预期。使用分区检索时,逐个调用get_load_state(collection_name=..., partition_name=...)。 - 不要只看行数判断数据完整性。行数正常但维度、索引度量或字段定义错误,仍会导致搜索报错或召回异常;应同时核对 schema 与 index。
排障清单
- 集合不存在:先用
list_collections()确认名称,并核对当前数据库和认证账号。 - 维度不符:检查
fields中真正的向量字段,避免误读其他向量字段或旧集合。 - 索引列表为空:集合可能按自定义 schema 创建但尚未建索引;先创建索引,再加载集合。
NotLoad:确认索引已完成,再执行load_collection();资源不足时检查查询节点内存。- 行数偏小:等待数据落盘或在低峰期
flush()后复查,同时检查插入返回的成功计数。
兼容性
Milvus Lite 的 describe_collection() 中部分集群属性没有实际意义,例如分片数、集合 ID 或一致性级别;排障时以字段定义、维度、索引和行数为主。连接 Standalone、Distributed 或云实例时,查询接口不变,但返回字段可能随服务端版本增加。
插入包含主键、向量、原始文本和业务元数据的单条记录。
写入单条数据
当需要把一段文本及其向量、主键和业务属性作为一个检索单元落库时,使用单条 upsert。以下示例采用 Qdrant REST API,假设本地服务位于 http://localhost:6333,集合 documents 已创建且向量维度为 4。
基本语法
接口为 PUT /collections/{collection}/points,请求体使用 points 数组;即使只写一条,也要放入数组。id 是稳定主键,vector 必须与集合维度一致,原始文本和业务元数据放在 payload 中。wait=true 表示等待变更实际应用后再返回。:contentReference[oaicite:0]{index=0}
主示例
curl -fsS -X PUT \
'http://localhost:6333/collections/documents/points?wait=true' \
-H 'Content-Type: application/json' \
--data-binary '{
"points": [
{
"id": 1001,
"vector": [0.12, -0.34, 0.56, 0.78],
"payload": {
"text": "退款申请将在两个工作日内审核。",
"tenant_id": "tenant-a",
"document_id": "faq-001",
"category": "after-sales",
"updated_at": "2026-08-06T12:00:00Z"
}
}
]
}' | jq '{status, result}'预期输出
{
"status": "ok",
"result": {
"operation_id": <ID>,
"status": "acknowledged"
}
}<ID> 是本次写操作编号,实际值会不同。根级 status 为 ok 且 result.status 为 acknowledged,表示服务已接受写入请求。官方接口返回还可能包含耗时和资源使用字段。:contentReference[oaicite:1]{index=1}
写后验证
按主键读取,并显式返回向量与 payload,避免只根据 HTTP 200 判断成功。
curl -fsS \
'http://localhost:6333/collections/documents/points/1001?with_payload=true&with_vector=true' \
| jq '.result | {id, vector, payload}'预期输出
{
"id": 1001,
"vector": [0.12, -0.34, 0.56, 0.78],
"payload": {
"text": "退款申请将在两个工作日内审核。",
"tenant_id": "tenant-a",
"document_id": "faq-001",
"category": "after-sales",
"updated_at": "2026-08-06T12:00:00Z"
}
}读取时重点核对 id、向量长度、文本和用于过滤的业务字段;向量数值出现轻微浮点显示差异通常不影响检索。
风险与边界
相同 id 再次 upsert 会覆盖该点现有内容。触发条件是主键复用,后果是旧向量或旧 payload 被替换;安全替代方案是写入前确认业务主键映射,更新场景携带版本号并避免并发写同一主键。Qdrant 官方也明确说明同 ID 会被覆盖。:contentReference[oaicite:2]{index=2}
向量维度与集合配置不一致会导致请求失败;应固定同一嵌入模型和版本,并在调用前校验数组长度。payload 中若包含敏感原文,可能被检索或日志暴露;生产环境应启用鉴权、传输加密,并只保存检索必需字段。
排障清单
- HTTP 404:集合名错误或集合尚未创建。
- HTTP 400:优先检查向量维度、数值类型和 JSON 结构。
- HTTP 401/403:云服务需增加
api-key请求头,并确认密钥权限。 - 返回成功但搜不到:确认查询使用同一集合、同一向量空间,并直接按主键读取验证。
按合理批次批量插入向量记录,提升吞吐并控制请求体大小。
批量写入数据
当待写记录较多时,将记录切成有限大小的批次逐次 upsert,可减少请求次数,同时避免单个请求体过大导致超时或内存峰值。以下示例使用稳定主键,使网络结果不确定时可以重试同一批。
批次策略
经验起点是每批 200~500 条,或压缩前请求体约 2 MiB,以先达到的限制为准;这不是固定上限。持续观察 P95 写入延迟、超时率、HTTP 429/5xx 和服务端内存,再逐步增减批次。
批次内每条记录都应包含唯一 id、等长 vector 和结构一致的 payload。同一请求可使用记录式 points 数组,Qdrant 官方也支持记录式和列式批量格式。:contentReference[oaicite:3]{index=3}
可运行示例
脚本仅使用 Python 标准库。运行前确保 Qdrant 位于 localhost:6333,集合 documents 已存在且向量维度为 4。
import json
from urllib.request import Request, urlopen
URL = "http://localhost:6333/collections/documents/points?wait=true"
BATCH_SIZE = 2
records = [
{"id": 2001, "vector": [0.11, 0.22, 0.33, 0.44], "payload": {"text": "安装指南", "tenant_id": "tenant-a", "document_id": "doc-001"}},
{"id": 2002, "vector": [0.21, 0.32, 0.43, 0.54], "payload": {"text": "升级指南", "tenant_id": "tenant-a", "document_id": "doc-002"}},
{"id": 2003, "vector": [0.31, 0.42, 0.53, 0.64], "payload": {"text": "备份指南", "tenant_id": "tenant-a", "document_id": "doc-003"}},
{"id": 2004, "vector": [0.41, 0.52, 0.63, 0.74], "payload": {"text": "恢复指南", "tenant_id": "tenant-a", "document_id": "doc-004"}},
{"id": 2005, "vector": [0.51, 0.62, 0.73, 0.84], "payload": {"text": "卸载指南", "tenant_id": "tenant-a", "document_id": "doc-005"}}
]
for start in range(0, len(records), BATCH_SIZE):
batch = records[start:start + BATCH_SIZE]
body = json.dumps({"points": batch}).encode("utf-8")
# 每次只保留一个批次在内存中,避免构造超大请求体。
request = Request(
URL,
data=body,
method="PUT",
headers={"Content-Type": "application/json"}
)
# 失败会抛出异常并停止,避免静默跳过未写入批次。
with urlopen(request, timeout=30) as response:
result = json.load(response)
print(
f"batch={start // BATCH_SIZE + 1} "
f"count={len(batch)} "
f"status={result['result']['status']} "
f"operation={result['result']['operation_id']}"
)预期输出
batch=1 count=2 status=acknowledged operation=<ID>
batch=2 count=2 status=acknowledged operation=<ID>
batch=3 count=1 status=acknowledged operation=<ID>每行代表一个请求;count 是该批记录数,operation 为动态操作编号。三行都出现且状态为 acknowledged,说明三个批次均被服务接受。官方 upsert 响应包含根级状态、操作状态与操作编号。:contentReference[oaicite:4]{index=4}
高频用法
增量导入时按源数据游标连续切批,并在每批成功后保存检查点。发生超时且无法确认服务端是否已处理时,用完全相同的主键和内容重试该批;稳定主键可避免重复生成新记录。
回灌大量历史数据时先用较小并发验证吞吐,再增加工作线程。不要只放大单批条数;请求体过大可能造成客户端内存上涨、反向代理拒绝或服务端处理时间过长。
风险与边界
同一主键会执行覆盖。触发条件是多个任务同时写入相同 id,后果是后到请求替换先前向量和 payload;安全替代方案是按业务主键分片串行、为导入任务设置唯一责任边界,并在 payload 中记录 source_version 便于审计。:contentReference[oaicite:5]{index=5}
无限重试会在持续性 400 错误或服务过载时放大流量。只对超时、连接中断、429 和可恢复 5xx 使用指数退避与抖动;对 400、401、403 应立即停止并修正数据或权限。失败批次应落入可重放队列,不要跳过后继续宣称全量成功。
排障清单
- 首批即 400:抽取一条记录单独写入,检查向量维度和字段类型。
- 小批成功、大批超时:降低每批条数或请求体字节数,并检查代理上传限制。
- 部分批次缺失:核对客户端日志中的批次序号、检查点和失败队列。
- 写入变慢:同时观察服务端 CPU、磁盘 I/O、索引构建和并发数,不要仅增加线程。
使用固定主键和更新插入操作避免重复导入产生多份相同数据。
执行幂等写入
当同一批文档可能被重试、重复消费或定时重跑时,使用稳定主键配合更新插入(upsert),保证同一业务片段始终只保留一条记录。
主键设计
主键应由稳定业务字段计算或拼接,例如 tenant_id + document_id + chunk_index。不要使用每次运行都会变化的随机 UUID,否则数据库无法识别重复数据。
固定主键只解决“写到同一条记录”;是否覆盖向量、文本和元数据,由冲突分支决定。
PostgreSQL + pgvector 示例
下面脚本可重复执行。第二次写入使用相同主键,但更新内容和向量,最终记录数仍为 1。
CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE IF NOT EXISTS knowledge_chunks (
id text PRIMARY KEY,
embedding vector(3) NOT NULL,
content text NOT NULL,
metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
updated_at timestamptz NOT NULL DEFAULT now()
);
INSERT INTO knowledge_chunks (id, embedding, content, metadata)
VALUES (
'tenant-a:doc-42:chunk-0001',
'[0.10,0.20,0.30]',
'旧版退款规则',
'{"source":"handbook.pdf","page":12}'::jsonb
)
ON CONFLICT (id) DO UPDATE SET
embedding = EXCLUDED.embedding,
content = EXCLUDED.content,
metadata = EXCLUDED.metadata,
updated_at = now();
INSERT INTO knowledge_chunks (id, embedding, content, metadata)
VALUES (
'tenant-a:doc-42:chunk-0001',
'[0.11,0.22,0.33]',
'新版退款规则',
'{"source":"handbook.pdf","page":13}'::jsonb
)
ON CONFLICT (id) DO UPDATE SET
embedding = EXCLUDED.embedding,
content = EXCLUDED.content,
metadata = EXCLUDED.metadata,
updated_at = now();
SELECT id, content, metadata, count(*) OVER () AS total_rows
FROM knowledge_chunks
WHERE id = 'tenant-a:doc-42:chunk-0001';预期输出
id | content | metadata | total_rows
tenant-a:doc-42:chunk-0001 | 新版退款规则 | {"page": 13, "source": "handbook.pdf"} | 1读取方法:total_rows = 1 表示重复执行没有新增副本;内容和元数据来自最后一次写入。updated_at 的实际值会随执行时间变化。
风险与边界
当主键只使用 document_id、未包含分片序号时,不同分片会互相覆盖,后果是召回内容缺失。安全做法是把租户、文档和分片位置全部纳入主键,并在导入前检查主键唯一性。
当两个生产者对同一主键写入不同版本时,后到写入会覆盖先到写入。需要防止旧数据回写时,应增加 source_version 或 content_hash,仅允许较新版本进入冲突更新分支。
向量维度必须与列定义一致;示例使用 vector(3) 仅便于验证,生产环境应改为嵌入模型的真实维度。
排障清单
- 记录数持续增长:检查是否仍在生成随机主键,或主键拼接中包含时间戳。
- 写入成功但内容未更新:检查冲突分支是否只执行了
DO NOTHING。 - 元数据字段丢失:当前示例是整对象替换;需要保留旧字段时,应改为 JSONB 合并策略。
- 重跑结果不稳定:确认所有写入方使用相同的主键规范和文本切分规则。
速查:稳定主键负责“命中同一条”,upsert 负责“重复时更新而不是新增”。
修改指定主键对应的向量、文本内容或业务元数据。
更新已有记录
当指定主键的文本、向量或业务元数据发生变化时,使用带明确 WHERE 条件的更新语句,并通过 RETURNING 或受影响行数确认目标记录确实存在。
更新原则
先明确哪些字段需要替换。文本变化通常要求重新生成向量;只修改标签、权限或状态时,可仅更新元数据,避免无意义地重新嵌入。
不要省略主键或租户条件。生产表通常应同时限制 tenant_id 和记录主键,防止跨租户误更新。
PostgreSQL + pgvector 示例
下面脚本先准备一条记录,再更新文本、向量和元数据。RETURNING 会直接返回更新后的结果。
CREATE EXTENSION IF NOT EXISTS vector;
CREATE TABLE IF NOT EXISTS knowledge_chunks (
id text PRIMARY KEY,
embedding vector(3) NOT NULL,
content text NOT NULL,
metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
updated_at timestamptz NOT NULL DEFAULT now()
);
INSERT INTO knowledge_chunks (id, embedding, content, metadata)
VALUES (
'tenant-a:doc-42:chunk-0002',
'[0.20,0.30,0.40]',
'旧版配送时效',
'{"status":"draft","page":20}'::jsonb
)
ON CONFLICT (id) DO NOTHING;
UPDATE knowledge_chunks
SET
embedding = '[0.25,0.35,0.45]',
content = '新版配送时效',
metadata = metadata || '{"status":"published","reviewed":true}'::jsonb,
updated_at = now()
WHERE id = 'tenant-a:doc-42:chunk-0002'
RETURNING id, content, metadata;预期输出
id | content | metadata
tenant-a:doc-42:chunk-0002 | 新版配送时效 | {"page": 20, "status": "published", "reviewed": true}
UPDATE 1读取方法:UPDATE 1 表示恰好更新一条;UPDATE 0 表示主键不存在或条件未命中。updated_at 的实际值会随执行时间变化。
字段更新选择
- 文本内容变化:同时更新
content和对应的embedding,避免向量仍表示旧文本。 - 仅标签变化:使用 JSONB 合并保留未修改字段;示例中的
metadata || 新对象会让右侧同名键覆盖旧值。 - 权限或租户变化:优先通过受控迁移处理,不要只改元数据而忽略过滤索引和访问控制数据。
风险与边界
只更新文本、不更新向量时,检索仍按旧语义召回,结果可能与展示内容不一致。安全做法是把“重新嵌入”和“数据库更新”放入同一任务状态机,失败时保持旧版本可用。
直接整对象替换元数据会删除未提供的旧字段。需要局部修改时使用 JSON 合并;需要删除特定键时,应显式执行删除操作并记录审计日志。
并发更新可能出现后写覆盖。关键数据应增加版本号,并在 WHERE 中同时校验主键和旧版本;受影响行数为 0 时重新读取后再决定是否重试。
排障清单
- 返回
UPDATE 0:核对主键、租户条件以及记录是否已被删除。 - 报向量维度错误:确认新向量长度与集合或列定义完全一致。
- 搜索仍命中旧内容:检查向量是否重新生成、索引是否已刷新,以及读取端是否有缓存。
- 更新后过滤失效:核对元数据字段名、类型和过滤表达式是否一致。
速查:更新后至少验证受影响行数、文本与向量的一致性,以及元数据过滤是否仍能命中目标记录。
按主键或过滤条件删除失效、错误或不再使用的向量数据。
删除指定记录(Qdrant REST)
用于清理已知错误、失效或过期的 point。已知主键时优先按 ID 删除;批量清理时可按 payload 过滤,但必须先用同一过滤条件预览命中范围。
命令定位
删除接口为 POST /collections/{collection_name}/points/delete。请求体使用 points 指定 ID 列表,或使用 filter 指定条件;两者不要同时传。生产校验建议加 wait=true,让接口在变更完成后再返回。
高频用法
下面的脚本会创建临时集合、写入 ID 为 13 的记录、按主键删除并确认查询结果数为 0。本机需已启动 Qdrant,且已安装 curl 与 jq。
set -euo pipefail
BASE_URL="${QDRANT_URL:-http://localhost:6333}"
COLLECTION="cheatsheet-delete-$RANDOM"
POINT_ID=13
trap 'curl -sS -X DELETE "$BASE_URL/collections/$COLLECTION" >/dev/null 2>&1 || true' EXIT
curl -sS -X PUT "$BASE_URL/collections/$COLLECTION" \
-H 'Content-Type: application/json' \
-d '{"vectors":{"size":3,"distance":"Cosine"}}' >/dev/null
curl -sS -X PUT "$BASE_URL/collections/$COLLECTION/points?wait=true" \
-H 'Content-Type: application/json' \
-d '{"points":[{"id":13,"vector":[0.1,0.2,0.3],"payload":{"status":"expired"}}]}' >/dev/null
curl -sS -X POST "$BASE_URL/collections/$COLLECTION/points/delete?wait=true" \
-H 'Content-Type: application/json' \
-d '{"points":[13]}' \
| jq '{status, delete_status: .result.status}'
curl -sS -X POST "$BASE_URL/collections/$COLLECTION/points" \
-H 'Content-Type: application/json' \
-d '{"ids":[13],"with_payload":true,"with_vector":true}' \
| jq '.result | length'预期输出
{
"status": "ok",
"delete_status": "completed"
}
0第一段表示删除操作已执行完成;最后的 0 表示按该 ID 已读取不到记录。实际集合名、耗时和操作 ID 可能不同。
按过滤条件删除时,将请求体改为 {"filter":{"must":[{"key":"status","match":{"value":"expired"}}]}}。执行前先调用 /points/scroll,使用完全相同的 filter 和较小的 limit 核对样本与命中数量。
输出字段说明
status 为请求处理状态;result.status 为更新状态,completed 表示已应用,acknowledged 只表示已接收;result.operation_id 是异步操作编号;time 是服务端耗时,属于动态值。
风险与边界
过滤条件过宽会批量删除仍在使用的数据,后果通常不可逆。安全替代方案是先滚动查询并统计命中数,再分批按 ID 删除;重要数据应先做快照或保留可重建来源。
未使用 wait=true 时,删除可能暂时尚未对读取或搜索可见。需要立即验证时使用 wait=true;高写入压力下若等待超时,应改用异步提交并重复读取确认。
删除 point 会同时移除其向量与 payload;只想清除某个 payload 字段或某个命名向量时,应调用对应的 payload 或 vector 删除接口,不要删除整条记录。
排障清单
- 返回
404:检查集合名、反向代理路径和租户环境是否正确。 - 返回
401或403:远程实例需添加api-key请求头,并确认密钥具有写权限。 - 删除后仍可读到:确认请求是否带
wait=true,以及读写是否落在同一集群、分片或一致性级别。 - 过滤删除数量异常:先用同一过滤器执行 scroll 或 count,核对字段类型、大小写和索引配置。
兼容性
示例适用于 Qdrant REST API 1.19.x。Milvus、Pinecone、Weaviate 等产品的删除路径、过滤表达式和一致性语义不同,迁移时应保留“预览命中范围、执行删除、再次读取验证”三个步骤。
按主键查询完整记录,用于校验写入结果和排查数据问题。
读取指定记录(Qdrant REST)
用于按 point ID 读取完整记录,核对写入后的主键、payload 和向量内容,或确认删除、更新是否真正生效。已知单个 ID 时使用单点读取,不要用相似度搜索代替精确校验。
命令定位
单点接口为 GET /collections/{collection_name}/points/{id}。ID 可为整数或字符串;成功响应的 result 中包含记录 ID、payload、vector,以及部署启用时可能出现的分片信息。
高频用法
下面的脚本会创建临时集合、写入一条记录,再按主键读取并提取核心字段。本机需已启动 Qdrant,且已安装 curl 与 jq。
set -euo pipefail
BASE_URL="${QDRANT_URL:-http://localhost:6333}"
COLLECTION="cheatsheet-read-$RANDOM"
POINT_ID=14
trap 'curl -sS -X DELETE "$BASE_URL/collections/$COLLECTION" >/dev/null 2>&1 || true' EXIT
curl -sS -X PUT "$BASE_URL/collections/$COLLECTION" \
-H 'Content-Type: application/json' \
-d '{"vectors":{"size":3,"distance":"Cosine"}}' >/dev/null
curl -sS -X PUT "$BASE_URL/collections/$COLLECTION/points?wait=true" \
-H 'Content-Type: application/json' \
-d '{"points":[{"id":14,"vector":[0.2,0.4,0.6],"payload":{"doc_id":"doc-14","status":"active"}}]}' >/dev/null
curl -sS "$BASE_URL/collections/$COLLECTION/points/$POINT_ID" \
| jq '{status, id: .result.id, payload: .result.payload, vector: .result.vector}'预期输出
{
"status": "ok",
"id": 14,
"payload": {
"doc_id": "doc-14",
"status": "active"
},
"vector": [
0.2,
0.4,
0.6
]
}id 应与请求路径一致,payload 用于核对业务字段,vector 用于确认维度和值是否写入正确。服务端耗时、分片字段和浮点显示精度可能不同。
一次读取多个已知 ID 时,使用 POST /collections/{collection_name}/points 并传入 ids。只核对元数据时设置 with_vector:false,可显著减少高维向量带来的响应体积。
输出字段说明
status 为请求状态;result.id 是 point 主键;result.payload 是业务元数据;result.vector 是向量,命名向量集合中可能表现为按名称组织的对象;result.shard_key 和 order_value 仅在相应配置下出现。
风险与边界
读取完整高维向量会增加网络流量、日志体积和序列化开销。只排查 payload 时,安全替代方案是使用批量读取接口并设置 with_vector:false;不要把完整向量写入普通应用日志。
刚完成异步写入或删除时,立即读取可能看到旧状态。需要读后即验时,写操作使用 wait=true;分布式部署还应确认读取一致性、分片路由和副本状态。
主键读取只能证明该 ID 的存储状态,不能证明向量可被正确召回。召回问题还需分别检查索引构建、过滤条件、距离度量和查询向量。
排障清单
- 返回
404:确认集合与 ID 是否存在,注意字符串 ID、数字 ID 不可混用。 - 返回
401或403:添加api-key请求头,并确认密钥具有读取权限。 payload缺字段:检查写入时是否覆盖 payload,或读取时是否使用了字段选择。vector为空或结构不符:检查集合使用匿名向量还是命名向量,以及记录是否只写入了部分向量。- 读到旧值:确认前序写入是否完成,并核对读写请求是否访问同一集群和一致性级别。
兼容性
示例适用于 Qdrant REST API 1.19.x。其他向量数据库可能将精确读取称为 get、fetch 或 query-by-id,但排障时都应核对主键、元数据、向量维度和值,并区分“精确读取”与“相似度搜索”。
提交查询向量并返回相似度最高的若干条记录及其分数。
执行相似度检索
用于把查询向量与已存向量计算距离,按相似度从高到低返回最相关记录。下面以 PostgreSQL 的 pgvector 为例,使用余弦距离完成一次可复制验证。
命令定位
适合验证向量是否写入正确、检查召回排序,或为语义搜索、推荐和 RAG 取回候选文档。查询向量必须与表中向量维度一致,并由同一嵌入模型生成。
基本语法
pgvector 的 <=> 表示余弦距离,距离越小越相似。需要直观分数时,可用 1 - 距离 转成余弦相似度。
CREATE EXTENSION IF NOT EXISTS vector;
CREATE TEMP TABLE demo_similarity_documents (
id bigint PRIMARY KEY,
content text NOT NULL,
embedding vector(3) NOT NULL
);
INSERT INTO demo_similarity_documents (id, content, embedding) VALUES
(1, '数据库连接排障', '[1,0,0]'),
(2, '连接池参数检查', '[0.8,0.2,0]'),
(3, '前端样式调整', '[0,1,0]');
WITH query AS (
SELECT '[1,0,0]'::vector AS embedding
)
SELECT
d.id,
d.content,
ROUND((1 - (d.embedding <=> q.embedding))::numeric, 4) AS score
FROM demo_similarity_documents AS d
CROSS JOIN query AS q
ORDER BY d.embedding <=> q.embedding
LIMIT 2;预期输出
id | content | score
----+--------------------+--------
1 | 数据库连接排障 | 1.0000
2 | 连接池参数检查 | 0.9701
(2 rows)先看 score,越接近 1 通常越相似;再确认返回顺序是否符合业务预期。建表和插入产生的状态行会因客户端不同而略有差异。
常用度量
- 余弦距离:
embedding <=> query_vector,适合大多数文本嵌入。 - 欧氏距离:
embedding <-> query_vector,适合向量绝对位置有意义的场景。 - 内积:
embedding <#> query_vector返回负内积,升序排列时最相关记录在前。
不要跨不同模型、不同维度或不同归一化策略直接比较分数;这会造成排序失真,甚至直接报维度不匹配。
风险与边界
未建立向量索引时,大表查询会触发全表距离计算,延迟和 CPU 占用随数据量增长。生产环境应建立与距离度量匹配的 HNSW 或 IVFFlat 索引,并用 EXPLAIN 验证执行计划。
相似度分数不是统一概率。更换模型或距离度量后,旧阈值通常失效;安全做法是使用真实标注样本重新评估阈值,而不是直接沿用历史值。
排障清单
- 报维度错误:检查列定义
vector(n)与查询向量长度是否一致。 - 排序明显异常:确认入库向量和查询向量来自同一模型、同一预处理流程。
- 查询过慢:检查索引类型、距离操作符和
ORDER BY是否匹配。 - 分数难以解释:同时输出原始距离和换算后的相似度,避免把距离当成相似度读取。
通过 Top K 参数控制相似度检索返回的候选记录数量。
设置返回数量
通过 Top K 控制每次相似度检索最多返回多少条候选记录。K 越大,返回内容越多,但排序计算、网络传输和后续重排成本也会增加。
基本语法
在 SQL 中使用 LIMIT K 表示 Top K。下面把 K 放进参数 CTE,修改一个值即可调整返回数量。
CREATE EXTENSION IF NOT EXISTS vector;
CREATE TEMP TABLE demo_topk_documents (
id bigint PRIMARY KEY,
content text NOT NULL,
embedding vector(3) NOT NULL
);
INSERT INTO demo_topk_documents (id, content, embedding) VALUES
(1, '数据库连接排障', '[1,0,0]'),
(2, '连接池参数检查', '[0.8,0.2,0]'),
(3, '前端样式调整', '[0,1,0]'),
(4, '图片压缩处理', '[-1,0,0]');
WITH params AS (
SELECT
'[1,0,0]'::vector AS query_embedding,
3::integer AS top_k
)
SELECT
d.id,
d.content,
ROUND((1 - (d.embedding <=> p.query_embedding))::numeric, 4) AS score
FROM demo_topk_documents AS d
CROSS JOIN params AS p
ORDER BY d.embedding <=> p.query_embedding
LIMIT (SELECT top_k FROM params);预期输出
id | content | score
----+--------------------+--------
1 | 数据库连接排障 | 1.0000
2 | 连接池参数检查 | 0.9701
3 | 前端样式调整 | 0.0000
(3 rows)把 3::integer 改为 1::integer,结果只保留最相似的一条;改为 10::integer 时,如果满足条件的记录不足 10 条,只返回实际存在的记录。
取值建议
- 在线问答或 RAG 初筛:先取较小 K,再由重排器筛选最终上下文。
- 去重或最近邻验证:通常取 1~5 条即可。
- 离线评估或人工审阅:可以提高 K,但应同时限制最大值和请求频率。
Top K 只控制返回条数,不等于相似度阈值。需要排除低质量候选时,应增加距离或分数条件,而不是只减小 K。
风险与边界
K 过大会增加数据库计算、应用内存、响应体大小和重排成本;高并发下可能放大尾延迟。安全做法是在接口层设置默认值和硬上限,例如默认 10、最大 100,并拒绝负数或异常大的输入。
使用近似索引时,K 与索引搜索参数不是同一个概念。只提高 K 不一定提升召回率;必要时还要调整 HNSW 搜索宽度或 IVFFlat 探测数量,并通过离线数据验证效果。
排障清单
- 返回少于 K 条:检查过滤条件、权限条件和表中实际数据量。
- K 已修改但数量不变:确认应用没有缓存旧请求,且最终 SQL 或 SDK 参数使用了新值。
- K 增大后延迟陡升:检查执行计划、索引命中情况和后续重排链路。
- 出现大量无关结果:增加最低相似度阈值,或先过滤业务范围再做向量排序。
指定查询结果需要携带的文本、来源、标签和其他业务字段。
返回业务字段
用于向量检索只返回页面或业务层真正需要的文本、来源、标签等字段,避免完整元数据和原始向量被一并传回。下面以 Qdrant 1.x 的 with_payload 为例;运行前需在本机 6333 端口启动 Qdrant,并安装 curl 与 jq。
基本语法
with_payload: true 返回全部 payload,false 不返回 payload,字符串数组只返回指定字段。业务列表通常同时设置 with_vector: false,避免返回体积较大的原始向量。
{
"query": [0.8, 0.2],
"limit": 10,
"with_payload": ["text", "source", "tags"],
"with_vector": false
}这是请求体片段。查询结果仍保留命中点的 id 和 score,但 payload 只携带 text、source、tags 三个业务字段。
高频用法
下面的命令创建临时集合、写入两条记录并查询,可直接验证字段投影效果。开头会删除同名测试集合,不要将测试名称替换为生产集合。
curl -s -X DELETE http://localhost:6333/collections/cheatsheet_fields >/dev/null
curl -s -X PUT http://localhost:6333/collections/cheatsheet_fields -H 'Content-Type: application/json' -d '{"vectors":{"size":2,"distance":"Cosine"}}' >/dev/null
curl -s -X PUT 'http://localhost:6333/collections/cheatsheet_fields/points?wait=true' -H 'Content-Type: application/json' -d '{"points":[{"id":1,"vector":[1,0],"payload":{"text":"退款流程","source":"kb/refund.md","tags":["售后"],"tenant_id":"tenant-a","internal_note":"仅客服可见"}},{"id":2,"vector":[0.9,0.1],"payload":{"text":"换货流程","source":"kb/exchange.md","tags":["售后"],"tenant_id":"tenant-a","internal_note":"内部备注"}}]}' >/dev/null
curl -s -X POST http://localhost:6333/collections/cheatsheet_fields/points/query -H 'Content-Type: application/json' -d '{"query":[1,0],"limit":2,"with_payload":["text","source","tags"],"with_vector":false}' | jq '.result.points'预期输出:
[
{
"id": 1,
"version": 0,
"score": 1,
"payload": {
"source": "kb/refund.md",
"tags": ["售后"],
"text": "退款流程"
},
"vector": null
},
{
"id": 2,
"version": 0,
"score": 0.9938837,
"payload": {
"source": "kb/exchange.md",
"tags": ["售后"],
"text": "换货流程"
},
"vector": null
}
]读取时确认 payload 中没有 tenant_id 和 internal_note,且 vector 为 null。浮点分数的小数位和对象字段顺序可能因版本不同而略有差异。
输出字段说明
id 是向量记录标识,score 是相似度得分,排序方向取决于集合使用的距离类型。payload 是允许返回的业务字段;某条记录缺少被选择字段时,该字段通常直接缺席,调用方不应假定每条结果拥有完全相同的键。
返回文本用于展示时,建议同时返回来源标识或文档 ID,便于生成引用链接和追查原始数据。仅需排序或去重时,可以关闭 payload,减少序列化和网络传输开销。
风险与边界
使用 with_payload: true 且 payload 含手机号、内部备注或权限标签时,会触发过量返回,可能造成隐私泄露和响应体膨胀。安全替代是使用字段白名单,并在接口层再次执行权限校验和敏感字段脱敏。
字段投影只控制“返回什么”,不会限制“哪些记录可以被检索”。不返回 tenant_id 并不等于完成租户隔离;租户、状态和时间范围仍必须通过标量过滤约束候选记录。
兼容性
Milvus、Weaviate、Pinecone 等产品也支持选择返回元数据,但参数名可能是 output_fields、return_properties 或 include_metadata。迁移时保持三个原则:显式使用字段白名单、默认不回传向量、服务端继续执行数据权限校验。
使用分类、时间、租户或状态字段缩小向量检索的数据范围。
添加标量过滤
用于在向量相似度排序前,先按租户、分类、状态或时间缩小候选范围,防止无效数据参与召回。下面以 Qdrant 1.x 的 filter 为例;运行前需在本机 6333 端口启动 Qdrant,并安装 curl 与 jq。
基本语法
must 中的条件必须全部满足,相当于 AND;should 表示至少满足一个,相当于 OR;must_not 用于排除。精确值使用 match.value,多值集合使用 match.any,数字或时间戳范围使用 range。
{
"filter": {
"must": [
{"key": "tenant_id", "match": {"value": "tenant-a"}},
{"key": "status", "match": {"value": "active"}},
{"key": "created_at", "range": {"gte": 1767225600}}
],
"must_not": [
{"key": "category", "match": {"value": "draft"}}
]
}
}这是请求体片段。时间字段应统一存为整数时间戳或数据库明确支持的日期类型,不要在同一字段中混用秒、毫秒和本地时间字符串。
高频用法
下面的命令创建四条测试记录,并只检索 tenant-a、状态为 active、创建时间不早于 2026-01-01 00:00:00 UTC 的数据。开头会删除同名测试集合,不得直接替换为生产集合名称。
curl -s -X DELETE http://localhost:6333/collections/cheatsheet_filter >/dev/null
curl -s -X PUT http://localhost:6333/collections/cheatsheet_filter -H 'Content-Type: application/json' -d '{"vectors":{"size":2,"distance":"Cosine"}}' >/dev/null
curl -s -X PUT 'http://localhost:6333/collections/cheatsheet_filter/points?wait=true' -H 'Content-Type: application/json' -d '{"points":[{"id":1,"vector":[1,0],"payload":{"tenant_id":"tenant-a","category":"guide","status":"active","created_at":1768000000,"text":"A 租户新指南"}},{"id":2,"vector":[0.99,0.01],"payload":{"tenant_id":"tenant-b","category":"guide","status":"active","created_at":1768000000,"text":"B 租户指南"}},{"id":3,"vector":[0.98,0.02],"payload":{"tenant_id":"tenant-a","category":"guide","status":"disabled","created_at":1768000000,"text":"已停用指南"}},{"id":4,"vector":[0.97,0.03],"payload":{"tenant_id":"tenant-a","category":"guide","status":"active","created_at":1735689600,"text":"旧指南"}}]}' >/dev/null
curl -s -X POST http://localhost:6333/collections/cheatsheet_filter/points/query -H 'Content-Type: application/json' -d '{"query":[1,0],"limit":10,"filter":{"must":[{"key":"tenant_id","match":{"value":"tenant-a"}},{"key":"status","match":{"value":"active"}},{"key":"created_at","range":{"gte":1767225600}}]},"with_payload":["tenant_id","status","created_at","text"],"with_vector":false}' | jq '.result.points'预期输出:
[
{
"id": 1,
"version": 0,
"score": 1,
"payload": {
"created_at": 1768000000,
"status": "active",
"tenant_id": "tenant-a",
"text": "A 租户新指南"
},
"vector": null
}
]只返回 ID 1,表示租户、状态和时间三个条件均已生效。若结果为空,先逐个移除条件,定位具体是字段缺失、类型不一致还是边界值错误。
常用条件
- 分类、租户和状态精确匹配使用
match.value。 - 多个分类任选其一使用
match.any,例如["guide","faq"]。 - 时间、价格和版本号范围使用
range的gt、gte、lt、lte。 - 删除态、草稿或黑名单数据放入
must_not,不要先取回再由应用端过滤。
组合条件时先确定业务逻辑再选择子句。把应当同时满足的租户与状态条件放入 should,会使任意一个条件成立即可返回,从而扩大数据范围。
风险与边界
漏掉租户条件时会触发跨租户召回,后果可能是数据越权。安全替代是由服务端根据认证上下文强制注入 tenant_id,禁止客户端覆盖,并将缺少租户上下文的请求直接拒绝,而不是降级为全库搜索。
大数据量下对未建 payload 索引的字段频繁过滤,可能产生高开销扫描和延迟抖动。生产环境应为稳定使用的过滤字段建立匹配类型的索引,并通过压测观察 P95、P99 延迟及资源消耗。
时间字段若秒和毫秒混用,会使数据全部过期或全部通过。写入前应统一时间单位,查询边界使用 UTC,并用边界前、边界时刻和边界后三条固定样本验证。
排障清单
- 确认过滤字段已经写入 payload,字段名和大小写完全一致。
- 检查数字是否被误存为字符串;数值
range不应依赖字符串比较。 - 区分字段缺失、空字符串、空数组和显式
null,它们可能具有不同匹配结果。 - 先使用一个
must条件验证,再逐项叠加,避免直接调试复杂嵌套表达式。 - 对比无过滤查询,确认目标记录本身能够被当前查询向量召回。
兼容性
Milvus 常用布尔表达式,Weaviate 使用 where,Pinecone 使用 metadata filter。迁移时重点核对 AND、OR、NOT、字段缺失、数组匹配和范围边界语义;语法相似并不代表空值与嵌套条件的行为完全一致。
使用逻辑运算组合多个过滤表达式,实现精确的候选集约束。
组合多个过滤条件
用于在向量检索前把候选集限制到同一租户、已发布、指定价格区间和允许区域,并排除软删除数据。Qdrant 的 must、should、must_not 分别表达 AND、OR、NOT,过滤器还可以递归嵌套。:contentReference[oaicite:0]{index=0}
基本语法
must 中的条件必须全部成立;should 至少命中一项;must_not 中的条件必须全部不成立。安全边界条件应放在 must,业务可选项再放进嵌套的 should。
高频用法
前置条件:本机 http://localhost:6333 已运行 Qdrant,并已安装 curl 与 jq。下面脚本会重建演示集合,只返回同时满足租户、状态、价格、区域和删除标记的点。
set -euo pipefail
QDRANT_URL="${QDRANT_URL:-http://localhost:6333}"
COLLECTION="filter_demo"
# 重建演示集合;不要对生产集合执行 DELETE。
curl -fsS -X DELETE "$QDRANT_URL/collections/$COLLECTION" >/dev/null || true
curl -fsS -X PUT "$QDRANT_URL/collections/$COLLECTION" \
-H 'Content-Type: application/json' \
-d '{"vectors":{"size":3,"distance":"Cosine"}}' >/dev/null
curl -fsS -X PUT "$QDRANT_URL/collections/$COLLECTION/points?wait=true" \
-H 'Content-Type: application/json' \
-d '{
"points":[
{"id":1,"vector":[1,0,0],"payload":{"tenant_id":"tenant-a","status":"published","price":120,"region":"us-east","deleted":false}},
{"id":2,"vector":[0.9,0.1,0],"payload":{"tenant_id":"tenant-a","status":"published","price":80,"region":"eu-west","deleted":false}},
{"id":3,"vector":[0.8,0.2,0],"payload":{"tenant_id":"tenant-a","status":"draft","price":100,"region":"us-west","deleted":false}},
{"id":4,"vector":[0.7,0.3,0],"payload":{"tenant_id":"tenant-b","status":"published","price":100,"region":"us-east","deleted":false}}
]
}' >/dev/null
curl -fsS -X POST "$QDRANT_URL/collections/$COLLECTION/points/query" \
-H 'Content-Type: application/json' \
-d '{
"query":[1,0,0],
"filter":{
"must":[
{"key":"tenant_id","match":{"value":"tenant-a"}},
{"key":"status","match":{"value":"published"}},
{"key":"price","range":{"gte":50,"lte":200}},
{"should":[
{"key":"region","match":{"value":"us-east"}},
{"key":"region","match":{"value":"us-west"}}
]}
],
"must_not":[
{"key":"deleted","match":{"value":true}}
]
},
"limit":10,
"with_payload":true
}' |
jq '.result.points[] | {
id,
score: (.score * 1000 | round / 1000),
tenant: .payload.tenant_id,
status: .payload.status,
price: .payload.price,
region: .payload.region
}'预期输出
{
"id": 1,
"score": 1,
"tenant": "tenant-a",
"status": "published",
"price": 120,
"region": "us-east"
}读取方法:只出现 id=1,说明所有 must 条件成立、区域命中嵌套 should,且未触发 must_not。
常用组合
精确值使用 match.value;多个候选值优先使用 match.any;数值和时间区间使用 range;复杂的 (A OR B) AND C 应把 should 作为一个嵌套过滤条件放进 must,避免改变整体逻辑。
风险与边界
触发条件:把 tenant_id、权限标记等隔离条件放进 should,或只在客户端过滤。可能后果:其他租户或无权限数据进入候选集。安全替代方案:服务端从认证上下文生成 tenant_id,固定放入 must,禁止直接信任客户端传值。
大数据量下若高频过滤字段没有 payload 索引,可能出现延迟上升和扫描开销。应为租户、状态、区域和范围字段建立匹配类型一致的索引;Qdrant 官方也建议为计划过滤的字段创建 payload 索引。:contentReference[oaicite:1]{index=1}
排障清单
- 结果为空:逐层移除条件,确认字符串大小写、字段路径和数值类型是否一致。
- 条件看似失效:检查
should是否放错层级,以及must_not是否错误包住整个组合。 - 返回 HTTP 400:核对查询向量维度是否与集合配置一致。
- 查询变慢:检查高频过滤字段是否已创建 payload 索引,并观察过滤后候选规模。
速查提示:先固定安全边界,再组合业务条件;复杂表达式用嵌套过滤器明确括号关系。
通过相似度阈值或距离范围仅返回满足最低相关性要求的结果。
执行范围检索
用于只保留达到最低相关性要求的向量结果,减少低质量召回进入重排或生成阶段。Qdrant 的 score_threshold 会排除比阈值更差的结果,但“更好”的方向由集合使用的距离度量决定。:contentReference[oaicite:2]{index=2}
基本语法
在 /points/query 请求中同时设置查询向量、score_threshold 和 limit。阈值负责质量门槛,limit 只限制最多返回多少条,二者不能互相替代。
高频用法
前置条件:本机 http://localhost:6333 已运行 Qdrant,并已安装 curl 与 jq。下面使用 Cosine 距离,只返回相似度不低于 0.75 的点。
set -euo pipefail
QDRANT_URL="${QDRANT_URL:-http://localhost:6333}"
COLLECTION="range_demo"
# 重建演示集合;生产环境请使用独立测试集合。
curl -fsS -X DELETE "$QDRANT_URL/collections/$COLLECTION" >/dev/null || true
curl -fsS -X PUT "$QDRANT_URL/collections/$COLLECTION" \
-H 'Content-Type: application/json' \
-d '{"vectors":{"size":3,"distance":"Cosine"}}' >/dev/null
curl -fsS -X PUT "$QDRANT_URL/collections/$COLLECTION/points?wait=true" \
-H 'Content-Type: application/json' \
-d '{
"points":[
{"id":1,"vector":[1,0,0],"payload":{"name":"exact"}},
{"id":2,"vector":[0.8,0.6,0],"payload":{"name":"related"}},
{"id":3,"vector":[0.5,0.8660254,0],"payload":{"name":"weak"}}
]
}' >/dev/null
curl -fsS -X POST "$QDRANT_URL/collections/$COLLECTION/points/query" \
-H 'Content-Type: application/json' \
-d '{
"query":[1,0,0],
"score_threshold":0.75,
"limit":10,
"with_payload":true
}' |
jq '[.result.points[] | {
id,
score: (.score * 1000 | round / 1000),
name: .payload.name
}]'预期输出
[
{
"id": 1,
"score": 1,
"name": "exact"
},
{
"id": 2,
"score": 0.8,
"name": "related"
}
]读取方法:id=3 的 Cosine 分数约为 0.5,低于 0.75,因此不会返回;实际耗时和浮点尾数可能不同。
参数与输出
score_threshold 是接受边界;Cosine 和 Dot 通常分数越高越相似。Euclid 等度量的分数方向不同,Qdrant 会按所用度量排除更差结果,不应直接复用 Cosine 阈值。score 是命中点与查询向量的度量结果,id 用于回查原记录,payload 是否返回由 with_payload 控制。
风险与边界
触发条件:更换嵌入模型、归一化方式或距离度量后继续沿用旧阈值。可能后果:阈值过高导致零召回,过低导致噪声进入后续流程。安全替代方案:用标注查询集统计正负样本分数分布,按召回率和准确率重新标定,并为不同模型分别保存阈值。
score_threshold 提供单侧质量边界,不等同于任意的最小值加最大值区间。若业务必须限制双侧区间,应使用数据库原生范围 API,或先保证足够大的候选集再做度量感知的服务端过滤,避免因 limit 太小漏掉有效结果。
排障清单
- 完全无结果:暂时移除阈值查看原始分数,并确认查询与入库使用同一嵌入模型。
- 结果过多:在 Cosine 或 Dot 下逐步提高阈值,不要只缩小
limit掩盖噪声。 - 分数方向异常:检查集合的距离度量,避免把 Euclid 距离当成“越大越相似”。
- 边界结果抖动:浮点计算存在细微误差,不要把业务逻辑建立在精确相等判断上。
速查提示:先确认距离度量,再用真实查询集校准阈值;阈值控制质量,limit 控制数量。