Qdrant 集合与点模型
Qdrant 用 collection 管理一组向量配置：向量维度、距离度量与是否多向量都在建集合时定下来。记录单元叫 point，由三部分组成：id、vector、payload（任意结构的元数据）。距离度量建后不可修改，换度量只能新建集合并重灌数据，所以建库前先确认模型输出维度与度量口径。id 支持无符号整数或 UUID 字符串，同一个集合里混用两类 id 时注意客户端 SDK 的类型校验。
基本信息
| 管理单元 | collection（含向量维度与距离度量） |
|---|---|
| 记录单元 | point = id + vector + payload |
| 核心操作 | upsert 写入、retrieve 按 id 读取、delete 删除、query 检索 |
| id 类型 | 无符号整数或 UUID 字符串 |
| 接口 | REST（6333）与 gRPC（6334），Python 客户端两者都支持 |
典型使用场景
- 新建知识库集合：先按 embedding 维度与度量建库，再批量 upsert 切片
- 按 id 精确回查：拿到检索结果的 id 后取原文，用于引用与人工核查
- 删除过期内容：按 id 列表或过滤条件删除，配合增量更新链路
- 多集合隔离：不同模型或不同业务各建一个集合，避免维度冲突
- payload 精简：只放来源、页码、版本等检索与过滤真正需要的字段
建集合（REST）
建集合（REST）
curl -X PUT http://localhost:6333/collections/kb \
-H 'Content-Type: application/json' \
-d '{"vectors": {"size": 1024, "distance": "Cosine"}}'
# 距离度量建后不可改：换度量要重建集合upsert / retrieve / delete
upsert / retrieve / delete
from qdrant_client import QdrantClient
from qdrant_client.models import PointStruct
client = QdrantClient(url='http://localhost:6333')
client.upsert('kb', points=[PointStruct(id='c-1', vector=vec,
payload={'source': 'faq', 'page': 3})])
print(client.retrieve('kb', ids=['c-1']))
client.delete('kb', points_selector=['c-1']) # 容错：重复删除不报错距离度量选择
| 度量 | 含义 | 适用 |
|---|---|---|
| Cosine | 夹角余弦，忽略模长 | 文本向量检索的默认选择 |
| Dot | 内积，受模长影响 | 已归一化或需要按模长加权 |
| Euclid | 欧氏距离 | 图像、坐标类数据 |
| Manhattan | 曼哈顿距离 | 特定度量需求，较少使用 |
运维与排错要点
- 容量观察：向量与 payload 都写在数据目录，注意磁盘水位而非只看内存
- 索引补齐：过滤用到的 payload 字段要建索引，否则过滤在扫描阶段逐点执行
- 写入幂等：以稳定 id 为准覆盖写入，重跑任务不会产生重复点
- 回收测试：删除后立即按 id 回查，确认异步删除已经生效
payload 里不要塞整段原文：它随每次检索一起传输与反序列化，体积过大会拖慢查询；原文放对象存储或关系库，payload 只留定位用的字段。