向量数据库入门：ChromaDB、Milvus、Qdrant、pgvector 对比实践

向量数据库这几年突然变成高频词核心原因是 RAG检索增强生成成了 AI 应用落地的主流方案。大模型再强也没法记住你的私有文档、聊天记录、商品库和日志要让模型基于自己的数据回答就得先把文本、图片、音视频拆成向量再存进一个能按“相似度”快速检索的引擎里。这个引擎就是向量数据库。这次我们来看向量数据库的入门玩法重点对比 ChromaDB、Milvus、Qdrant、pgvector 这四类代表性方案。文章会先给出规格速览再逐个演示本地部署、数据写入、相似度查询、元数据过滤、批量任务和 API 调用方式。最后整理一套常见问题和排查清单。读完你应该能判断自己的项目该选哪种库并且能照着步骤把第一个向量检索服务跑起来。先说结论如果你的需求是个人学习、小规模原型验证ChromaDB 最省事如果你要处理千万级向量、需要分布式和高可用Milvus 是主流选择如果你已经习惯 Docker 部署、要轻量高性能服务Qdrant 很顺手如果你的数据本来就在 PostgreSQL 里pgvector 不用引入新组件最适合“在现有库里顺便做向量检索”。下面的章节会围绕这四个方向展开。1. 核心能力速览下面这张表汇总了四个主流向量数据库的基本情况具体版本和参数以官方文档和实际部署环境为准。能力项ChromaDBMilvusQdrantpgvector项目定位轻量级内嵌向量库云原生分布式向量数据库Rust 编写的向量搜索引擎PostgreSQL 扩展部署方式pip 安装进程内运行Docker / K8s / 集群Docker / 单二进制PostgreSQL 扩展适合场景原型验证、本地测试、教学生产级大规模检索中大规模检索、推荐系统已有 PostgreSQL 的项目索引类型HNSWHNSW、IVF、DISKANNHNSW、Payload 索引HNSW、IVFFlat距离度量L2、内积、余弦多种向量距离余弦、欧氏、点积L2、内积、余弦元数据过滤支持支持支持支持API / SDKPython、JSPython、Java、Go、Node.js、RESTfulPython、JS、Go、RESTfulSQL 标准语法批量写入支持支持支持支持持久化方式SQLite 文件对象存储 消息队列RocksDBPostgreSQL 表是否需要 Docker不需要需要推荐需要或单文件运行需要 PostgreSQL显存需求无无无无补充一点这四个都是纯向量检索服务不依赖 GPU。如果你要做 embedding比如把“苹果手机”转成 384 维或 1024 维向量那部分可以由 OpenAI、SentenceTransformers、BGE 等模型完成可以把 embedding 模型部署成独立服务也可以离线批量生成后写入向量库。2. 适用场景与使用边界向量数据库适合解决三类问题第一类是语义搜索。传统搜索引擎依赖关键词匹配搜“怎么修漏水的水龙头”如果文档里写的是“管道渗漏处理”关键词完全对不上效果会很差。向量数据库把两边都映射到语义空间匹配的是“相似含义”而不是“相同字符串”。第二类是 RAG 知识库问答。把私有文档切片每片转成向量存入向量库用户提问时先做向量检索拿到最相关的几段内容再把内容拼进 prompt 交给大模型回答。这种方式能显著减少大模型“编造答案”的概率也能让模型回答基于你自己的资料。第三类是推荐与去重。通过物品向量计算相似度可以实现“看了 A 还推荐 B”对文本、商品名、图片做向量去重也能比哈希去重更鲁棒。不适合用向量数据库的场景也要说清楚精确等值查询、范围查询、复杂 SQL 关联用传统关系数据库更合适。向量数据库擅长“近似相似”不是为精确查询设计的。数据量只有几百条用向量库反而增加部署成本。直接在内存里算余弦相似度就够了。需要强事务和复杂 join 的业务系统向量数据库不是替代品。合规边界如果向量库存储的是用户隐私、人脸特征、声音特征、版权作品切片必须明确用途并获得合法授权。尤其在 RAG、人脸检索、音频匹配场景中不要在没有授权的情况下采集、持久化和对外提供个人生物特征或版权内容。部署接口服务时还要加访问控制避免向量库直接暴露在公网。3. 环境准备与前置条件先列一个通用环境检查清单再按不同数据库给出具体准备方法。3.1 通用检查清单操作系统Windows 10/11、Ubuntu 20.04/22.04、macOS 均可。Milvus 在 Windows 上通常借助 Docker Desktop 或 WSL2 运行。Python 版本ChromaDB、Qdrant、Milvus 的 Python 客户端需要 3.8 及以上推荐 3.10/3.11。DockerQdrant 和 Milvus 建议安装 Docker 与 Docker Compose。新手先把 Docker Desktop 装好。磁盘空间ChromaDB 几百 MB 足够Qdrant 镜像约 200MB 左右Milvus 部署较大预留 5GB 以上更稳妥。内存原型测试 4GB 内存起Qdrant 和 Milvus 生产环境建议 16GB 以上具体取决于索引大小和查询并发。端口ChromaDB 服务模式默认 8000Qdrant 默认 6333Milvus 默认 19530如果本地端口冲突按各自配置修改。3.2 安装 Python 依赖建议先建一个虚拟环境避免依赖冲突。# 创建并激活虚拟环境Windows 用户请将 source 改为 activate python -m venv venv source venv/bin/activate # 升级 pip pip install --upgrade pip后续按所选数据库安装对应依赖。3.3 安装 embedding 工具向量数据库只是存储和检索向量本身要由嵌入模型生成。入门推荐用 sentence-transformers轻量且离线可用。pip install sentence-transformers如果机器配置一般可以选用all-MiniLM-L6-v2这类小模型输出 384 维向量内存占用不高。生产环境可换 BGE、M3E 等中文效果更好的模型具体看数据语言和精度要求。4. 安装部署与启动方式下面分别演示 ChromaDB、Qdrant、Milvus、pgvector 的部署方法。4.1 ChromaDB最快跑起来的方式ChromaDB 内部基于 SQLite 和 HNSW 实现安装后可以进程内直接使用也可以启动成服务。pip install chromadb进程内模式不需要单独启动服务。import chromadb # 默认使用本地持久化目录 client chromadb.PersistentClient(path./chroma_data)需要服务模式时chroma run --host 127.0.0.1 --port 8000启动后可以通过http://127.0.0.1:8000访问。这种模式适合把向量库独立出来给多个客户端调用。4.2 QdrantDocker 一行启动Qdrant 官方提供镜像非常适合快速验证。# 拉取镜像 docker pull qdrant/qdrant # 启动容器映射 6333 端口 docker run -d --name qdrant-demo \ -p 6333:6333 \ -p 6334:6334 \ -v $(pwd)/qdrant_storage:/qdrant/storage \ qdrant/qdrant启动后 REST API 地址是http://127.0.0.1:6333Dashboard 访问http://127.0.0.1:6333/dashboard。可以用官方 Web UI 查看 collection 和向量检索结果对新手很友好。如果不想装 Docker也可以下载官方二进制文件直接运行。4.3 Milvus生产级分布式部署Milvus 组件较多最稳妥的方式是使用 Docker Compose 启动完整服务。先安装 Docker Compose然后执行官方提供的 compose 文件。注意 Milvus 依赖 Etcd 和 MinIO 存储启动时间较长。# 下载 Milvus standalone 部署配置 wget https://github.com/milvus-io/milvus/releases/download/v2.4.x/milvus-standalone-docker-compose.yml -O docker-compose.yml # 启动 docker compose up -d启动后检查容器状态docker compose ps如果看到etcd、minio、milvus三个容器都在运行说明部署成功。RESTful 端口默认是19530Dashboard 端口是9091。Milvus 的安装包和 compose 文件版本变化较快具体版本号以官方 releases 页面为准。4.4 pgvector在 PostgreSQL 里开启向量能力pgvector 不是独立进程而是 PostgreSQL 的一个扩展。对已经使用 PostgreSQL 的团队来说最友好。首先在 PostgreSQL 服务上安装扩展# Ubuntu 通常可以通过 apt 安装 sudo apt install postgresql-16-pgvector安装后进入数据库执行CREATE EXTENSION vector;接下来创建一张带向量字段的表CREATE TABLE items ( id bigserial PRIMARY KEY, content text, embedding vector(384) );这里vector(384)表示每行存储 384 维向量维度必须和你的 embedding 模型输出一致。5. 功能测试与效果验证部署只是起点真正要验证的是完整链路文本 - 向量 - 写入 - 检索 - 返回结果。5.1 准备测试数据用一个简单的英文小数据集做演示避免中文分词干扰。实际项目中按需求替换成中文数据即可。documents [ The cat sits on the mat., A dog is running in the park., We need to fix the leaking tap., How to repair a water pipe., The weather is sunny today. ]先用 sentence-transformers 把每段文本转成向量。from sentence_transformers import SentenceTransformer model SentenceTransformer(all-MiniLM-L6-v2) embeddings model.encode(documents).tolist() print(len(embeddings), len(embeddings[0]))预期输出类似5 384表示 5 条数据每条 384 维。5.2 ChromaDB 写入与检索import chromadb client chromadb.PersistentClient(path./chroma_data) collection client.get_or_create_collection(namedemo) collection.add( ids[str(i) for i in range(len(documents))], documentsdocuments, embeddingsembeddings ) # 查询 query how to stop water leak query_vec model.encode([query]).tolist() results collection.query(query_embeddingsquery_vec, n_results2) for doc, dist in zip(results[documents][0], results[distances][0]): print(fdistance{dist:.4f}, doc{doc})判断成功的标准查询 “how to stop water leak” 时最前面两条应该是How to repair a water pipe.和We need to fix the leaking tap.。说明向量库没有做关键词匹配而是理解了语义。失败时优先查两项一是向量维度是否一致二是 embedding 是否成功生成。5.3 Qdrant 批量写入与过滤查询Qdrant 先创建 collection再写入点每个点可以附带 payload。pip install qdrant-clientfrom qdrant_client import QdrantClient from qdrant_client.models import Distance, VectorParams, PointStruct client QdrantClient(host127.0.0.1, port6333) # 如果已存在同名 collection 会报错先删除 client.delete_collection(demo) client.create_collection( collection_namedemo, vectors_configVectorParams(size384, distanceDistance.COSINE) ) # 写入点这里为每条数据加一个 category 元数据字段 points [ PointStruct( idi, vectorembeddings[i], payload{text: documents[i], category: home} ) for i in range(len(documents)) ] client.upsert(collection_namedemo, pointspoints) # 检索同时验证元数据过滤 query_vec model.encode([how to stop water leak]).tolist() hits client.query_points( collection_namedemo, queryquery_vec, query_filtermodels.Filter( must[ models.FieldCondition( keycategory, matchmodels.MatchValue(valuehome) ) ] ), limit2 ) for hit in hits.points: print(fscore{hit.score:.4f}, text{hit.payload[text]})判断成功的标准检索能返回带payload的结果且过滤条件生效后只返回categoryhome的数据。Qdrant 的score越大代表相似度越高和 ChromaDB 的 distance 越小越好是相反逻辑注意区分。5.4 Milvus collection 与查询验证Milvus 客户端使用前先连接服务。pip install pymilvusfrom pymilvus import connections, CollectionSchema, FieldSchema, Collection, DataType connections.connect(host127.0.0.1, port19530) # 定义 schema fields [ FieldSchema(nameid, dtypeDataType.INT64, is_primaryTrue, auto_idFalse), FieldSchema(nametext, dtypeDataType.VARCHAR, max_length500), FieldSchema(nameembedding, dtypeDataType.FLOAT_VECTOR, dim384) ] schema CollectionSchema(fieldsfields, descriptiondemo collection) collection Collection(namedemo, schemaschema) # 写入数据 collection.insert( [[i for i in range(len(documents))], documents, embeddings] ) # 创建索引HNSW 是常见选择 index_params { index_type: HNSW, metric_type: COSINE, params: {M: 8, efConstruction: 64} } collection.create_index(field_nameembedding, index_paramsindex_params) # 加载到内存并搜索 collection.load() query_vec model.encode([how to stop water leak]).tolist() results collection.search( dataquery_vec, anns_fieldembedding, param{metric_type: COSINE, params: {ef: 64}}, limit2, output_fields[text] ) for res in results[0]: print(fdistance{res.distance:.4f}, text{res.entity.get(text)})判断成功的标准查询能返回最相似的两条文档。Milvus 的distance在 COSINE 度量下越接近 1 表示越相似。注意每次插入新数据后如果 collection 已创建索引需要调用flush()和load()才能查询到最新数据。5.5 pgvector SQL 查询pgvector 直接使用 SQL 操作适合已经有 PostgreSQL 基础设施的团队。-- 插入向量 INSERT INTO items (content, embedding) VALUES (The cat sits on the mat., [0.1, 0.2, ...]), (A dog is running in the park., [0.3, 0.2, ...]); -- 相似度查询按余弦距离排序 SELECT content, embedding [0.1, 0.2, ...] AS distance FROM items ORDER BY embedding [0.1, 0.2, ...] LIMIT 3;是余弦距离运算符-是 L2 距离#是内积。选择哪种运算符取决于 embedding 模型和数据场景和索引创建时指定的度量类型要一致。实际使用中先把文档批量转成向量再拼 SQL 写入避免逐条插入导致效率过低。6. 接口 API 与批量任务向量数据库的接口能力是生产集成时最关注的部分。下面分别说明服务化方案和批量设计思路。6.1 ChromaDB APIChromaDB 启动为服务后可以使用 REST API 或客户端连接。速度比嵌入式模式慢一些但适合跨进程调用。import chromadb client chromadb.HttpClient(host127.0.0.1, port8000) collection client.get_or_create_collection(demo)6.2 Qdrant REST APIQdrant 的 HTTP API 很适合直接调试特别是 curl 测试。# 创建 collection curl -X PUT http://127.0.0.1:6333/collections/demo \ -H Content-Type: application/json \ -d {vectors: {size: 384, distance: Cosine}}# 查询相似向量 curl -X POST http://127.0.0.1:6333/collections/demo/points/search \ -H Content-Type: application/json \ -d {vector: [0.1, 0.2, ...], limit: 3}Qdrant 的 Python 客户端底层也是调用这些 REST 接口掌握 curl 方式可以快速排查网络和接口问题。6.3 Milvus APIMilvus 生产环境通常用 SDK 操作也提供 RESTful API。重点说一下批量任务设计from pymilvus import connections, Collection connections.connect(host127.0.0.1, port19530) collection Collection(demo) # 分批写入 batch_size 1000 for start in range(0, len(all_embeddings), batch_size): batch_ids ids[start : start batch_size] batch_texts texts[start : start batch_size] batch_vectors all_embeddings[start : start batch_size] collection.insert([batch_ids, batch_texts, batch_vectors]) print(finserted {start len(batch_ids)} rows) collection.flush()批量任务的关键点先算好 embedding再写入向量库不要把 embedding 生成和向量写入放在同一个同步循环里。大批量写入时建议断点续传记录已写入批次索引。写入失败时先检查维度是否一致、主键是否冲突、服务是否负载过高。每个 batch 大小不要一次性拉满建议从 100-1000 条开始测试。6.4 pgvector 批量导入pgvector 批量导入一般通过COPY或循环执行INSERT。如果向量已经存在 Python 列表里可以用 psycopg2 执行批量插入。import psycopg2 from psycopg2.extras import execute_values conn psycopg2.connect(dbnametest userpostgres) cur conn.cursor() data [] for text, vec in zip(documents, embeddings): vec_str [ ,.join(map(str, vec)) ] data.append((text, vec_str)) execute_values( cur, INSERT INTO items (content, embedding) VALUES %s, data, template(%s, %s), page_size100 ) conn.commit()execute_values比单条 insert 快很多适合万级规模导入。更大的数据量建议先离线生成向量文件再用 COPY 导入。7. 资源占用与性能观察向量数据库本身不依赖 GPU资源占用主要看内存、磁盘和 CPU。下面给出观察方法和调优方向。7.1 内存占用向量索引常驻内存内存占用大约是“向量数量 x 向量维度 x 4 字节 x 索引膨胀系数”。比如 100 万条 384 维向量基础存储约 384 x 4 x 1000000 1.5GB加上 HNSW 索引复杂结构实际会更高。所以不要只看原始向量大小索引膨胀系数通常在 1.2 到 2 倍之间。7.2 CPU 占用Cosine 距离计算是 CPU 密集操作。查询并发越高CPU 占用越高。Milvus 和 Qdrant 都能做水平扩展但入门阶段先把索引参数调好更重要。7.3 索引参数影响HNSW 的两个核心参数是 M 和 efConstructionM 值越大检索精度越高内存占用越大。efConstruction 越大建索引越慢召回率越高。查询时的 ef 参数越大单次查询越慢但越准。合理做法是先用小数据集调优找到精度和延迟的平衡点再上线大数据量。7.4 观察命令Docker 部署的服务用下面命令查看资源占用docker stats本地服务直接看任务管理器或top。Qdrant 和 Milvus 的日志里通常也会输出查询耗时信息。7.5 降低资源占用的常用手段减少向量维度如果 embedding 模型是 1024 维先确认业务是否真的需要这么高精度不少场景 384 维已经够用。增加过滤条件先通过元数据过滤缩小范围再做向量检索。控制返回数量limit 越小计算和传输成本越低。定期清理无效数据向量库没有自动回收机制删除数据后要注意优化存储。8. 常见问题与排查方法8.1 问题排查表问题现象可能原因排查方式解决方案chroma 查询时报维度错误embedding 模型输出维度和 collection 不一致打印len(embedding)对比 collection 配置删除旧 collection重新用统一维度初始化Qdrant 创建 collection 报错同名 collection 已存在查看 Dashboard 或调用 list collection先删除旧 collection或换一个 collection 名称Milvus 查询结果为空collection 未 load 或未 flush检查是否调用flush()和load()插入后执行 flush查询前执行 loadDocker 启动 Qdrant 后 6333 端口无法访问容器未启动或端口映射错误docker ps查看容器状态检查端口映射必要时docker logs查看日志pgvector 查询顺序不对使用了错误的距离运算符打印查询语句和 distance 值确认、-、#分别对应哪种距离批量写入越来越慢索引自动更新或数据量过大查看服务日志和 CPU 占用分批写入考虑关闭实时索引改为定时构建API 调用超时查询 limit 过大或 ef 参数过高减小 limit 和 ef 参数优化索引参数对查询接口做超时控制中文检索效果差embedding 模型不适合中文用中文测试集评估模型效果换成 BGE、M3E 等中文优化模型8.2 部署阶段最容易踩的坑第一个坑是向量维度不一致。embedding 模型输出的维度是固定的所有数据、查询向量、collection 配置必须严格一致。第二个坑是忘记创建索引。ChromaDB 默认会建索引但 Milvus 和 Qdrant 需要显式创建否则查询性能会很差。第三个坑是服务端口暴露公网。向量库本身不设防直接暴露公网容易被扫到必须限制访问来源。9. 最佳实践与使用建议9.1 最小可运行配置先保证一条完整链路能跑通准备 10 条文本数据。用一个 embedding 模型批量转向量。写入向量库。用一条 query 做相似度检索。检查结果相关性。链路通了再考虑大数据量、高并发、集群部署。9.2 目录和命名规范建议按数据来源或业务场景建立 collection例如products_zh_v1、docs_legal_v2。不要把所有向量塞进一个 collection除非数据量和访问模式确实单一。collection 命名时带上模型版本和语言方便后续更换 embedding 模型时迁移。9.3 数据生命周期管理向量库数据更新时建议采用“新建 collection 切换别名”的方式而不是原地修改。备份向量库时同步备份 embedding 模型版本否则旧数据可能无法被新模型检索。记录每条数据的来源、生成时间、授权状态尤其是涉及人脸、声音、文本版权内容时。9.4 批量任务设计批量写入任务至少包含输入文件的读取和校验。embedding 生成的进度记录。写入向量库的批次控制。失败重试和日志。建议把任务分成两个阶段先批量生成向量文件再批量导入向量库。这样 embedding 模型异常时不会影响向量库状态向量库异常时也不用重新计算 embedding。9.5 安全边界向量检索服务只监听内网或 localhost不直接暴露公网。如果需要对外提供 API加认证和限流。涉及个人身份信息、人脸、声纹的数据先做脱敏和授权确认。不要用向量数据库绕过版权保护或批量收集未经授权的内容。10. 总结与下一步向量数据库不是神秘组件核心就是“把非结构化数据变成向量然后按距离检索”。入门阶段最容易获得成就感的路径是先用 ChromaDB 跑通一套本地 RAG确认语义检索能不能满足需求再根据数据规模决定是否迁移到 Qdrant 或 Milvus。最先应该验证的是相似度检索质量也就是“同一个问题用不同说法表达向量库能不能召回正确答案”。最容易踩的坑则是维度不一致和忘记创建索引。后续可以继续扩展的方向包括结合大模型做完整 RAG 问答系统、尝试不同 embedding 模型对比检索效果、用 Milvus 搭建分布式检索服务以及把向量库接入业务系统做实时推荐。这套入门流程建议收藏备用。部署时如果遇到问题优先看日志再对照排查表逐项检查。