Qdrant之一： 使用指南

Qdrant之一 使用指南1. Qdrant简介Qdrant是Rust开发的高性能向量搜索引擎专门处理非结构化数据文本、图片、音频等的向量检索。核心能力包括向量存储、元数据过滤、混合检索、向量量化、多租户隔离对外提供REST/gRPC接口支持多语言客户端对接常用于RAG知识库、相似内容召回、图片检索、推荐系统等场景。2. 部署启动自建服务端2.1 Docker部署开发/测试推荐# 拉取镜像dockerpull qdrant/qdrant# 启动实例映射端口持久化存储向量数据dockerrun-p6333:6333-p6334:6334\-v$(pwd)/qdrant_storage:/qdrant/storage\qdrant/qdrant6333REST API端口Web控制台地址http://localhost:6333/dashboard6334gRPC端口适合大批量操作性能更高qdrant_storage本地目录持久化全部向量、索引、元数据容器删除数据不会丢失。健康检查验证curlhttp://localhost:6333/healthz# 返回{status:ok}代表启动成功2.2 二进制部署生产环境从官方Release下载对应系统预编译二进制包解压后直接运行可执行文件qdrant可加载自定义yaml配置文件自定义存储路径、日志、认证等参数。⚠️注意默认启动无身份认证公网暴露必须配置API Key禁止裸跑在公网。2.3 Python客户端初始化fromqdrant_clientimportQdrantClient# 连接本地Qdrant服务clientQdrantClient(urlhttp://localhost:6333)3. 数据管理3.1 核心概念Collection集合等同于向量数据表定义向量维度、距离算法、索引、量化策略。Point单条向量记录包含id、vector向量数组、payload自定义元数据JSON格式。Payload业务元数据支持字符串、数字、布尔、数组可以建立索引用于过滤查询。3.2 创建集合创建集合时必须指定向量维度与距离度量方式支持Cosine(余弦相似度)、Dot(点积)、Euclid(欧氏距离)。fromqdrant_client.modelsimportDistance,VectorParams client.create_collection(collection_nameknowledge_base,vectors_configVectorParams(size384,# embedding模型输出向量维度distanceDistance.COSINE))高级配置标量量化压缩向量降低内存占用损失少量精度大规模数据集必选Payload索引对频繁过滤的元数据字段建立索引大幅提升带条件检索速度多向量配置一个Point存储多组向量稠密、稀疏向量支持混合检索多租户隔离通过命名空间区分不同业务数据实现数据隔离。示例创建带标量量化的集合fromqdrant_client.modelsimportQuantizationConfig,ScalarQuantization client.create_collection(collection_namekb_quant,vectors_configVectorParams(size384,distanceDistance.COSINE),quantization_configQuantizationConfig(scalarScalarQuantization(typeint8,always_ramTrue)))为payload元数据创建索引# 数字字段索引client.create_payload_index(collection_nameknowledge_base,field_namecategory,field_schemakeyword)# 全文检索索引client.create_payload_index(collection_nameknowledge_base,field_namecontent_text,field_schematext)3.3 写入向量数据Upsertupsert存在相同id则更新不存在则新增。points[{id:1,vector:[0.1,0.2,...],payload:{category:tech,title:Qdrant入门}},{id:2,vector:[0.3,0.4,...],payload:{category:ai,title:向量数据库介绍}}]client.upsert(collection_nameknowledge_base,pointspoints)3.4 基础数据操作# 获取集合信息client.get_collection(collection_nameknowledge_base)# 根据id获取pointsclient.retrieve(collection_nameknowledge_base,ids[1,2])# 删除pointclient.delete(collection_nameknowledge_base,points_selectormodels.PointIdsList(points[1]))# 删除集合client.delete_collection(collection_nameknowledge_base)4. 检索与查询Qdrant支持向量相似度搜索、Payload条件过滤、混合查询、高级召回策略。4.1 基础向量相似度搜索resclient.search(collection_nameknowledge_base,query_vector[0.11,0.22,...],# 查询的embedding向量limit5,# 返回top5结果score_threshold0.6,# 相似度阈值过滤低分结果with_payloadTrue,# 返回元数据payloadwith_vectorsFalse# 是否返回原始向量关闭节省带宽)# 遍历结果forhitinres:print(f分数:{hit.score}, payload:{hit.payload})4.2 带过滤条件检索结合元数据做过滤例如只检索categorytech的数据fromqdrant_client.modelsimportFilter,FieldCondition,MatchValue resclient.search(collection_nameknowledge_base,query_vector[0.11,0.22,...],limit5,query_filterFilter(must[FieldCondition(keycategory,matchMatchValue(valuetech))]))4.3 混合检索Hybrid Query同时使用稠密向量语义稀疏向量关键词进行检索融合语义匹配与关键词命中显著提升检索质量。集合需要同时配置dense与sparse两组向量查询时同时传入两组向量设置权重融合得分。4.4 Scroll分页遍历当需要遍历全部数据不能用search使用scroll接口做游标分页。client.scroll(collection_nameknowledge_base,limit10)5. 推理能力InferenceQdrant支持内置embedding推理可以直接向接口传入原始文本服务端内部完成向量化不需要业务代码单独调用embedding模型。支持稠密向量dense、稀疏sparse、多向量multi‑vector嵌入可对接本地部署的嵌入模型不需要依赖云模型服务。工作模式客户端传入原始文本字符串Qdrant内部调用嵌入模型生成向量完成写入或者查询简化业务链路。示例思路在集合配置中开启inference参数指定本地嵌入模型upsert写入时直接传文本由Qdrant自动生成向量search检索直接传入查询文本服务端内部完成向量化直接返回检索结果。6. 运维优化建议索引调优HNSW索引参数m、ef_construct控制索引构建速度和检索精度数据量大时调大参数提升召回率量化策略千万级向量建议开启int8标量量化内存可以降低数倍Payload索引对查询过滤条件的字段务必建立索引否则过滤查询会很慢批量写入使用upsert批量提交避免单条循环写入gRPC接口吞吐量高于REST备份使用快照snapshot功能做集合备份用于故障恢复。7. 典型业务流程示例原始非结构化文本 → 文本切片将文本送入Embedding模型生成向量创建Qdrant集合配置向量参数、量化、payload索引upsert把向量元数据写入集合用户查询文本生成查询向量调用search可选增加payload过滤条件返回top‑N相似结果将检索结果送入大模型完成RAG问答。8. Web控制台使用访问http://localhost:6333/dashboard可以可视化查看所有集合统计信息可视化执行search、upsert操作查看向量存储状态、索引状态调试查询过滤条件。更多高级功能参考官方文档https://qdrant.tech/documentation/