企业官网建设流程全解析

DB-GPT 使用 Milvus 作为 RAG 向量存储：从依赖安装、连接配置到源码实现解析

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT

本文介绍如何在 DB-GPT 中以 Milvus 作为 RAG 向量存储（Vector Store），覆盖storage_milvus依赖安装、Milvus 服务准备、configs/dbgpt-proxy-openai.toml中的[rag.storage]连接配置、webserver 启动，以及MilvusStore的底层实现细节（Collection Schema、默认 HNSW 索引、BM25 全文检索支持等）。读完本文，你将能够把 DB-GPT 的向量检索底座从默认的 Chroma 无缝切换到 Milvus，并理解检索链路中各参数的实际作用。

背景：向量存储与 Milvus 在 DB-GPT RAG 中的位置

DB-GPT 的 MS-RAG（Multi-Source Enhanced RAG）框架在索引阶段会对同一批 Chunk 构建多种索引，其中Vector 索引由EmbeddingAssembler负责 transform（chunk → embedding），并将结果持久化到向量数据库。根据 MS-RAG 模块参考 中的索引存储矩阵，Vector 索引的 Load 目标是 Chroma、Milvus、PGVector 等向量数据库，而 Milvus 正是官方支持并深度集成的后端之一（FAQ 中明确 Milvus > 2.1 可用，见 kbqa 常见问题）。

在 DB-GPT 中切换向量存储有两条并行的配置路径，本文以官方集成指南（milvus_rag_install.md）为准，逐项展开。

前置条件

• 已按 源码安装指南 准备基于uv的 Python 环境（当前仓库使用uv.lock与pyproject.toml管理依赖）；
• 拥有可访问的 Milvus 服务（Standalone 部署即可，参考 Milvus 官方 docker-compose 安装方式）；
• 一个 OpenAI 兼容的代理模型配置（本文使用仓库自带的configs/dbgpt-proxy-openai.toml作为演示配置）。

第一步：安装 Milvus 存储依赖

DB-GPT 将各向量数据库的客户端依赖以 optional extra 形式拆分。在 dbgpt-ext 的 pyproject.toml 中可以看到storage_milvus对应的依赖为pymilvus，与 Chroma、Qdrant、Weaviate 等并列：

storage_milvus = ["pymilvus"]

因此在项目根目录执行以下命令即可一次性安装基础运行、OpenAI 代理、RAG 与 Milvus 存储所需依赖：

uv sync --all-packages \ --extra "base" \ --extra "proxy_openai" \ --extra "rag" \ --extra "storage_milvus" \ --extra "dbgpts"

其中：

• --all-packages：同步仓库内全部 package（dbgpt-app / dbgpt-core / dbgpt-ext / dbgpt-serve / dbgpt-client 等）；
• --extra "base"/"proxy_openai"：基础运行与 OpenAI 代理模型支持；
• --extra "rag"：RAG 检索相关依赖；
• --extra "storage_milvus"：安装pymilvus，这是MilvusStore正常初始化的硬性前提；
• --extra "dbgpts"：DB-GPT 插件（DBGPTs）能力。

若使用 pip 安装方式，等价地需要pip install pymilvus；否则运行时 MilvusStore 源码 会抛出Could not import pymilvus python package的 ValueError。

第二步：准备 Milvus 服务

按照 Milvus 官方install_standalone_docker-compose方案部署一个可访问的 Milvus 实例，并确保 19530 端口可达。DB-GPT 侧默认以http://{uri}:{port}的形式建立连接（见下文源码解析），因此无需在服务端额外开启 TLS，除非你显式配置了secure。

第三步：配置 DB-GPT 连接 Milvus（TOML 方式）

编辑仓库根目录下的 configs/dbgpt-proxy-openai.toml，将默认的 Chroma 向量存储替换为 Milvus。原始文件中的默认片段为：

[rag.storage] [rag.storage.vector] type = "chroma" persist_path = "pilot/data"

将其改为（按集成指南整理并修正注释）：

[rag.storage] [rag.storage.vector] type = "Milvus" uri = "127.0.0.1" port = "19530" #username = "dbgpt" #password = "your_milvus_password"

字段说明：

• type = "Milvus"：指定向量存储后端为 Milvus（注意大小写，对应资源类型名）；
• uri：Milvus 服务主机地址，默认回退到MILVUS_URL环境变量或localhost；
• port：Milvus gRPC/HTTP 端口，默认19530；
• username/password：Milvus 认证信息，必须成对出现——源码中若只设置了其中一个会抛出Both username and password must be set to use authentication for Milvus；未启用认证时保持注释即可。

需要提醒的是：原指南中#password=19530属于笔误（19530 是端口号而非密码），实际应填写你为 Milvus 配置的密码字符串。

第四步：启动 DB-GPT webserver

配置完成后，在仓库根目录执行：

uv run python packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py --config configs/dbgpt-proxy-openai.toml

服务默认监听0.0.0.0:5670（对应 dbgpt-proxy-openai.toml 中的[service.web]配置）。启动后在 Web UI 中创建知识库并同步文档时，Chunk 的向量将写入 Milvus 对应 Collection，检索阶段即从 Milvus 进行similar_search。

备选方式：通过.env环境变量切换向量库

除了 TOML 配置，DB-GPT 还支持以环境变量方式切换向量存储，在 RAG 参数调整指南 中给出：

### Milvus vector db config VECTOR_STORE_TYPE=Milvus MILVUS_URL=127.0.0.1 MILVUS_PORT=19530 #MILVUS_USERNAME #MILVUS_PASSWORD #MILVUS_SECURE=

在 MilvusStore 源码 中，TOML 配置与这些环境变量是按优先级取值的（配置项优先，环境变量兜底）：

该实现位于dbgpt-ext包（storage/vector_store/milvus_store.py），与dbgpt-core中的VectorStoreBase抽象基类对接，因此两种方式底层走的是同一条存储链路。

MilvusVectorConfig 参数详解

MilvusStore 的连接与 Schema 参数在MilvusVectorConfig中统一定义（同样见 milvus_store.py），并在 配置参考文档 中同步维护：

其中uri、port、alias、primary_field、text_field、embedding_field、metadata_field也均作为 AWEL 资源参数暴露（@register_resource("milvus_vector_config", ...)），这意味着在 DB-GPT 的 AWEL 工作流编排中可以直接以资源节点的方式引用 Milvus 存储配置。

源码实现解析：MilvusStore 如何工作

连接与 Collection 初始化

MilvusStore.__init__中，DB-GPT 使用pymilvus.milvus_client.MilvusClient建立连接（url = f"http://{self.uri}:{self.port}"，默认db_name="default"），随后调用create_collection。创建 Collection 时：

1. 用当前 embedding 模型对 collection 名做一次embed_query以确定向量维度dim；
2. 构造 Schema：text_field（VARCHAR, 65535）、primary_field（INT64 主键自增）、embedding_field（FLOAT_VECTOR, dim）、metadata_field（VARCHAR, 65535）、props_field（JSON）；
3. 若 Milvus 版本支持全文检索（见下文），额外追加sparse_vector（SPARSE_FLOAT_VECTOR）字段，并注册 BM25 函数text_bm25_emb。

默认索引与检索参数

代码中默认索引参数为：

self.index_params = { "index_type": "HNSW", "metric_type": "COSINE", }

即默认使用HNSW 索引 + COSINE 距离度量。同时内置了多种索引的检索参数映射：IVF_FLAT/IVF_SQ8/IVF_PQ（nprobe=10）、HNSW（M=8, efConstruction=64）、RHNSW_FLAT/RHNSW_SQ/RHNSW_PQ（ef=10）、IVF_HNSW、ANNOY（search_k=10）等，满足不同规模与精度的检索需求。

检索入口similar_search/similar_search_with_scores会：

1. 将MetadataFilters转换为 Milvus 表达式（convert_metadata_filters，基于 JSON 字段props_field['key']构造 EQ / IN 表达式）；
2. 用 embedding 模型编码查询文本；
3. 以output_fields排除向量字段（包括稀疏向量）后执行col.search，返回内容、元数据、距离分数；
4. similar_search_with_scores额外支持score_threshold过滤，超出[0, 1]的相似度会打印告警日志。

Milvus 2.5+ 全文检索（BM25）支持

源码中is_support_full_text_search()通过解析get_server_version()判断 Milvus 版本是否 ≥ 2.5.0。若支持，则：

• Collection 会附带sparse_vector字段并创建AUTOINDEX+BM25度量的稀疏向量索引；
• full_text_search()直接以 BM25 稀疏向量做关键词检索，返回带retriever="full_text"标记的 Chunk，与向量检索形成混合召回能力。

这也是 v0.8.1 版本的重要改进之一（见 Release Notes 中 “Milvus 2.5+ compatibility” 条目）。

批量写入与数据维护

• load_document以500 chunks/批的方式分批写入（_load_documents→_add_documents），返回主键列表；
• vector_name_exists通过 MilvusClient 检查 Collection 是否存在且row_count > 0；
• delete_vector_name调用utility.drop_collection删除整个 Collection；
• delete_by_ids按主键批量删除，delete_by_file_id按metadata中的file_id做模糊匹配删除；
• truncate通过pk_id >= 0清空 Collection 数据并flush提交，用于安全清空而不删除 Collection 本身。

验证与常见排查

1. 依赖未安装：启动时报Could not import pymilvus python package→ 回到第一步补装storage_milvus；
2. 连接失败：确认uri/port与 Milvus 实际地址一致，且主机可路由；FAQ（kbqa.md）建议 Milvus 版本 > 2.1，全文检索特性则要求 ≥ 2.5；
3. 认证异常：username与password必须同时配置，缺失其一会被源码主动拒绝；
4. 检索无结果：检查知识库index_methods是否包含VectorStore，以及 embedding 模型是否可用——create_collection需要 embedding 模型先返回一个查询向量才能确定维度。

延伸阅读

• 知识库索引原理——一篇文档如何变成可检索的向量 / 关键词 / 知识图谱 / 结构索引；
• Agentic RAG 对话原理——问题如何通过 agentic 检索循环变成带引用的回答；
• MS-RAG 模块参考——向量索引在整体索引流水线（Extract → Transform → Load）中的位置；
• RAG 参数调整指南——topk、recall_score、chunk_size 等检索参数的调优方法；
• Milvus 配置参考——MilvusVectorConfig全量参数定义。

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT