# LangChain + Qdrant 向量数据库实战：从 Docker 安装到 RAG 问答全链路

LangChain Qdrant 向量数据库实战从 Docker 安装到 RAG 问答全链路适合人群LangChain 开发者、RAG 应用工程师、AI 工程落地、知识库开发人员摘要本文完整记录了在 Windows 环境下使用LangChain Qdrant搭建企业知识库问答系统的全流程。从 Docker 安装 Qdrant、Python 依赖配置、环境变量管理到 QdrantDB 封装、文档建库、向量检索、LCEL 链式 RAG 问答覆盖全链路实战。对比 Milvus 与 Qdrant 的选型差异附带完整可运行代码和高频踩坑排查方案。一、为什么选 QdrantMilvus vs Qdrant 选型对比在本地开发和中小规模知识库场景中向量数据库的选型直接影响开发体验。以下是 Milvus 与 Qdrant 的核心对比对比项Milvus (v2.6)Qdrant (v1.12)内存占用启动需 4-8 GB仅需 512 MB - 1 GB依赖复杂度需 etcd、MinIO、Pulsar 等 5 组件单容器零依赖部署难度多容器编排启动慢docker run一行启动Windows 兼容性偶发连接问题原生 HTTP/gRPC稳定适用场景大规模生产集群本地开发、中小项目、原型验证性能亿级向量分布式扩展百万级向量毫秒响应选型结论本地开发、学习项目、中小规模知识库Qdrant 是更轻、更快、更稳的选择。二、项目目录结构总览F:\LangChain\ ├── env\.env # 环境变量配置文件 ├── data\ │ ├── raw\XX销售有限公司员工守则.pdf # 原始知识库素材 │ └── readable\ # 预处理后的可读文本 ├── DB\ │ ├── __init__.py # 使 DB 成为 Python 包 │ ├── MilvusDB.py # Milvus 适配器保留原实现 │ └── QdrantDB.py # Qdrant 适配器新增 ├── providers\ │ └── models.py # 模型封装Embedding LLM └── Practice\07\0727_qdrant\ # Qdrant 版本练习脚本 ├── 01_基础完整版.py # 单 PDF 全内联保留 Milvus ├── 02_基础封装版.py # 调用封装保留 Milvus ├── 03_升级封装版.py # 多目录递归加载保留 Milvus ├── 04_Retriever 基础检索.py # 检索程序已适配 Qdrant ├── 05_手动 RAG.py # 手动组装 RAG已适配 Qdrant ├── 06_LCEL RAG.py # LCEL 链式 RAG已适配 Qdrant ├── 07_建库程序.py # 文档入库已适配 Qdrant ├── 08_rag_service.py # RAG 服务类已适配 Qdrant └── 09_问答入口.py # 交互式终端已适配 Qdrant三、Docker 安装 Qdrant3.1 前置条件Windows 10/11 专业版已启用 WSL2Docker Desktop 已安装并运行至少 2GB 可用内存3.2 创建数据持久化目录mkdirF:\LangChain\qdrant_data3.3 拉取镜像并启动容器dockerrun-d--nameqdrant\-p6333:6333-p6334:6334\-vF:/LangChain/qdrant_data:/qdrant/storage\qdrant/qdrant:v1.12.0参数详解参数说明-d后台运行--name qdrant容器名称-p 6333:6333HTTP REST API 端口-p 6334:6334gRPC 端口LangChain 使用此端口-v ...数据持久化到本地目录容器重启不丢数据3.4 验证容器运行状态dockerps--filternameqdrant应显示STATUS: UpPORTS: 0.0.0.0:6333-6334。3.5 Web UI 可视化管理可选浏览器访问 http://localhost:6333/dashboard可图形化管理集合、查看向量数据。四、Python 依赖安装在虚拟环境中安装 Qdrant 相关依赖F:\LangChain\.venv\Scripts\pip.exeinstallqdrant-client langchain-qdrant国内网络可加清华镜像加速pipinstallqdrant-client langchain-qdrant-ihttps://pypi.tuna.tsinghua.edu.cn/simple依赖说明包名作用qdrant-clientQdrant 原生客户端用于创建集合、统计信息langchain-qdrantLangChain 适配器提供QdrantVectorStore类五、.env 环境变量配置编辑F:\LangChain\env\.env添加 Qdrant 及模型配置# DashScope 向量模型 API Key DASHSCOPE_API_KEYsk-your-key-here # 本机 Docker Qdrant 服务地址 QDRANT_URLhttp://localhost:6333 # 中文文本向量模型 EMBEDDING_MODELtext-embedding-v4 # 大模型 APIOpenAI 兼容格式 DEEPSEEK_BASE_URLhttps://api.siliconflow.cn/v1 DEEPSEEK_API_KEYsk-your-key-here配置注意事项QDRANT_URL不要带端口号后面的路径纯http://localhost:6333即可如使用 LongCat-2.0 等第三方模型复用DEEPSEEK_BASE_URL和DEEPSEEK_API_KEY只需改model参数六、QdrantDB 适配器封装详解文件位置F:\LangChain\DB\QdrantDB.py这一层封装是整个项目的核心它屏蔽了 Qdrant 底层 API 的复杂性上层代码只需调用get_qdrant_client()即可获得 LangChain 适配的向量库实例。6.1 完整代码importosfromdotenvimportload_dotenvfromqdrant_clientimportQdrantClientfromqdrant_client.modelsimportDistance,VectorParamsfromlangchain_qdrantimportQdrantVectorStorefromproviders.modelsimportget_embedding_modeldefget_qdrant_client(collection_name,is_deleteFalse,urlhttp://localhost:6333): 获取 Qdrant 向量库实例可选择是否删除旧集合 参数 - collection_name: 集合名称必传 - is_delete: 是否删除旧集合 - url: Qdrant 服务地址 内部逻辑 1. 读取 Qdrant 服务地址 2. 创建 Qdrant 原生客户端跳过版本兼容性检查 3. 根据 is_delete 决定是否删除旧 collection 4. 如 collection 不存在自动创建指定 vector_size1024, Distance.COSINE 5. 构造并返回 QdrantVectorStore 实例 load_dotenv()urlos.getenv(QDRANT_URL,url)# 创建原生客户端跳过兼容性检查避免版本警告clientQdrantClient(urlurl,grpc_port6334,check_compatibilityFalse)# 检测集合是否存在collection_existsFalsetry:client.get_collection(collection_name)collection_existsTrueexceptException:pass# 删除旧集合ifis_deleteandcollection_exists:client.delete_collection(collection_name)print(f已删除旧 collection:{collection_name})collection_existsFalse# 自动创建新集合ifnotcollection_exists:vector_size1024# DashScope text-embedding-v4 维度client.create_collection(collection_namecollection_name,vectors_configVectorParams(sizevector_size,distanceDistance.COSINE,),timeout30,# 创建耗时较长需显式设置超时)print(f已创建新 collection:{collection_name}(dim{vector_size}))# 创建 LangChain 适配的向量库实例vector_storeQdrantVectorStore(clientclient,collection_namecollection_name,embeddingget_embedding_model(),# DashScope 嵌入模型单例)returnvector_store6.2 关键设计要点设计点说明check_compatibilityFalse跳过客户端与服务端的版本兼容性检查避免误报timeout30创建集合约需 10-15 秒默认 5 秒会超时vector_size1024DashScopetext-embedding-v4的固定维度勿改Distance.COSINE余弦距离适合语义相似度计算单例 embeddingget_embedding_model()内部缓存避免重复初始化七、建库程序文档入库全流程7.1 核心流程PDF 文件 | v PyPDFLoader按页加载 | v RecursiveCharacterTextSplitterchunk_size300, overlap50 | v get_qdrant_clientis_deleteTrue强制重建集合 | v vector_store.add_documents写入向量 | v 校验 points_count 与文档块数量一致7.2 关键代码Qdrant vs Milvus 差异# Qdrant 版本fromDB.QdrantDBimportget_qdrant_client# 建库vector_storeget_qdrant_client(COLLECTION_NAME,is_deleteTrue)idsvector_store.add_documents(chunks)# 统计方式不同Qdrant 用 points_countfromqdrant_clientimportQdrantClient clientQdrantClient(urlos.getenv(QDRANT_URL))collection_infoclient.get_collection(COLLECTION_NAME)row_countcollection_info.points_count7.3 运行验证cdF:\LangChain\Practice\07\0727_qdrantF:\LangChain\.venv\Scripts\python.exe07_建库程序.py预期输出PDF 加载完成共 3 页 文档切分完成共 10 个文档块 已删除旧 collection: employee_handbook 已创建新 collection: employee_handbook (dim1024) 写入返回 ID 数量10 Collection 实际行数10 建库成功employee_handbook八、检索程序向量相似度检索8.1 核心流程获取 Qdrant 向量库实例is_deleteFalse不删除已有数据构建 Retrieversearch_kwargs{k: 3}检索与问题最相关的 3 个文档块8.2 关键代码fromDB.QdrantDBimportget_qdrant_client vector_storeget_qdrant_client(COLLECTION_NAME,is_deleteFalse)retrievervector_store.as_retriever(search_kwargs{k:3})documentsretriever.invoke(QUESTION)8.3 运行验证F:\LangChain\.venv\Scripts\python.exe04_Retriever 基础检索.py预期输出问题今天生病了请了一天假扣多少钱 共检索到 3 个文档块 --- 查询结果 1 --- 来源XX销售有限公司员工守则.pdf第 1 页 业贿赂。 5. 维护公司利益... --- 查询结果 2 --- 来源XX销售有限公司员工守则.pdf第 2 页 件。 2. 合同审批... --- 查询结果 3 --- 来源XX销售有限公司员工守则.pdf第 2 页 体现 professionalism 和敬业精神。 第二章 员工权利与义务...九、RAG 完整服务架构9.1 架构概览用户提问 ↓ RetrieverQdrant 检索 top-3 文档块 ↓ format_documents格式化为 [资料1]\n来源...\n内容... ↓ PromptTemplateSystem Prompt 参考资料 用户问题 ↓ LLMLongCat-2.0 / DeepSeek ↓ StrOutputParser解析为纯文本 ↓ 返回 {answer, sources}9.2 关键配置COLLECTION_NAMEemployee_handbook# 检索器配置self.retrieverself.vector_store.as_retriever(search_kwargs{k:3})# 大模型温度temperature0 保证回答稳定、不发散modelget_longcat_model(temperature0)# Prompt 核心规则# 1. 不要编造参考资料中不存在的制度、时间、数字# 2. 资料不足时回答根据现有资料无法确定# 3. 简洁、清楚、分点9.3 运行验证fromrag_serviceimportRAGService serviceRAGService()resultservice.ask(病假扣多少钱)print(result[answer])# 输出根据现有资料无法确定。参考资料中仅提到...十、交互式问答入口F:\LangChain\.venv\Scripts\python.exe09_问答入口.py交互示例企业知识库助手已启动输入 exit 退出。 请输入问题病假扣多少钱 回答根据现有资料无法确定。参考资料中仅提到员工依法享有病假权利... 资料来源 1. XX销售有限公司员工守则.pdf,1页 2. XX销售有限公司员工守则.pdf,2页 请输入问题exit 程序已退出十一、常见问题排查11.1 创建集合超时 TimeoutError现象07_建库程序.py报TimeoutError: Operation timed out原因create_collection默认超时 5 秒实际需 10-15 秒解决显式设置timeout30client.create_collection(...,timeout30)11.2 集合不存在 404现象RuntimeError: Collection employee_handbook does not exist原因直接初始化QdrantVectorStore时集合不存在解决先用原生客户端create_collection创建再初始化QdrantVectorStore或使用封装好的get_qdrant_client内部已处理自动创建逻辑11.3 DeepSeek 503/429 限流现象模型调用报503 Service Unavailable或429 Too Many Requests原因DeepSeek 服务端高峰期过载解决方案等 5-10 分钟重试换非高峰时段晚上/凌晨测试切换备用模型如 LongCat-2.0复用同一 API 平台密钥11.4 维度不匹配错误现象Vector dimension mismatch: expected 1024, got 1536原因建库和查询使用了不同的 embedding 模型解决确保所有代码调用同一个get_embedding_model()单例模式模型固定为text-embedding-v4十二、快速命令速查表操作命令启动 Qdrantdocker run -d --name qdrant -p 6333:6333 -p 6334:6334 -v F:/LangChain/qdrant_data:/qdrant/storage qdrant/qdrant:v1.12.0查看容器docker ps --filter nameqdrant停止容器docker stop qdrant删除容器docker rm -f qdrant安装依赖pip install qdrant-client langchain-qdrant建库python 07_建库程序.py检索python 04_Retriever 基础检索.py完整 RAGpython 09_问答入口.py十三、核心知识点总结知识点说明Qdrant 定位轻量级向量数据库单容器启动适合本地开发和中小项目QdrantDB 封装层屏蔽底层 API 差异上层代码改 import 即可切换向量库集合自动创建get_qdrant_client()内部自动检测并创建集合无需手动管理vector_size1024DashScopetext-embedding-v4固定维度建库和查询必须一致Distance.COSINE余弦距离适合语义相似度计算timeout30创建集合耗时较长必须显式设置超时is_delete 参数建库时设 True 强制重建检索时设 False 保留数据完整数据流PDF 文件 - PyPDFLoader - RecursiveCharacterTextSplitter - Document 文档块 - Embedding 向量化 - Qdrant 向量数据库 - Retriever 检索 - LLM 生成回答Milvus 与 Qdrant 共存策略Milvus 版本保留在0727/目录Qdrant 版本在0727_qdrant/目录两者互不干扰通过DB/MilvusDB.py和DB/QdrantDB.py分别封装高频踩坑清单create_collection必须设置timeout30默认 5 秒会超时QDRANT_URL不要带尾部路径纯http://localhost:6333建库和查询必须使用同一个 embedding 模型否则维度不匹配is_deleteTrue会清空集合数据检索时务必设为FalseDocker Desktop 未运行时所有 Qdrant 操作会报连接拒绝DeepSeek 503/429 是模型服务端限流与向量库无关换模型或错峰即可check_compatibilityFalse可跳过版本警告不影响功能问题排查顺序容器状态 → 端口连通 → 集合存在 → embedding 维度 → 模型调用配套 CSDN 封面图提示词16:9CSDN技术博客封面极简科技蓝风格扁平化UILangChain Qdrant向量数据库RAG知识库问答系统架构图Docker容器向量检索代码元素干净渐变背景上方留白放标题高清科技风文末互动本文完整覆盖了 Qdrant 在 Windows 环境下的 Docker 安装、Python 依赖配置、环境变量管理、QdrantDB 适配器封装、文档建库、向量检索、LCEL 链式 RAG 问答全链路附带完整可运行代码和高频踩坑排查方案。大家在搭建 RAG 知识库时用的是 Milvus、Qdrant 还是其他向量数据库遇到过哪些部署或检索效果的问题欢迎评论区交流后续持续更新Embedding 模型对比选型、RAG 检索效果优化、多轮对话记忆持久化、Agent 智能体开发。点赞 收藏持续更新大模型工程化干货