企业官网建设流程全解析

DB-GPT 接入 Ollama 实战：本地模型部署、依赖安装与 proxy/ollama 配置全解析

【免费下载链接】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 官方文档中的 Ollama 接入方案为主体，覆盖从安装 Ollama、拉取 LLM 与 Embedding 模型，到使用uv安装proxy_ollama等依赖、修改 TOML 配置文件的完整流程，并结合 DB-GPT 源码（OllamaLLMClient、OllamaEmbeddings等实现）剖析proxy/ollama提供者的参数解析、流式推理与向量化的底层调用链，帮助你在本地机器上零成本跑通 DB-GPT 的“大模型 + 向量模型”全链路。

一、为什么选择 Ollama 作为 DB-GPT 的本地模型提供方

Ollama 是一个模型服务（serving）平台，可以在几秒内完成模型的部署与调用，为本地大模型和向量模型提供统一的 HTTP API（默认监听http://localhost:11434）。对 DB-GPT 来说，它的价值在于：

• LLM 侧：DB-GPT 的对话、SQL 生成、数据分析等能力默认依赖大模型推理，通过 Ollama 可以在无云端 API Key 的情况下完全本地化运行；
• Embedding 侧：DB-GPT 的 RAG 知识库、数据库 Schema 向量化等能力需要向量模型，Ollama 同样支持拉取和调用 embedding 模型；
• 配置解耦：DB-GPT 将 Ollama 封装为proxy/ollama提供者（provider），模型名、服务地址均通过 TOML 配置文件声明，无需改动任何代码。

从源码注册机制看，DB-GPT 通过@auto_register_resource将 Ollama 登记为 LLM 客户端资源（标签为 “Ollama Proxy LLM”，类别ResourceCategory.LLM_CLIENT），相关实现位于 Ollama LLM 客户端。

二、安装 Ollama

Linux 环境

在 Linux 系统上，一条命令即可完成安装（引自 官方 Ollama 文档）：

curl -fsSL https://ollama.com/install.sh | sh

其他操作系统（macOS、Windows）的安装方式请参考 Ollama 官网说明。安装完成后，Ollama 会以本地服务的形式运行，默认 API 地址为http://localhost:11434，这一点与 DB-GPT 源码中OllamaLLMClient的默认值完全一致（见 ollama.py 中api_base = "http://localhost:11434"的缺省逻辑）。

验证服务是否就绪

安装并启动后，可以用以下命令确认服务已在本机监听：

ollama list

能够正常返回模型列表（首次安装时列表为空属正常现象）即表示服务已就绪。

三、拉取 LLM 与 Embedding 模型

DB-GPT 完整运行一个“对话 + 知识库”场景需要两类模型：**LLM（对话/推理模型）**和Embedding 模型（文本向量化模型）。文档给出的推荐操作如下：

1. 拉取 LLM

ollama pull qwen:0.5b

qwen:0.5b是参数量最小的 Qwen 模型之一，适合在配置较低的机器上快速验证 DB-GPT 全链路。如果显存/内存充足，可以拉取更大的模型，例如仓库示例配置 dbgpt-proxy-ollama.toml 中使用的deepseek-r1:1.5b。

2. 拉取 Embedding 模型

ollama pull nomic-embed-text

需要说明的是，文档正文以nomic-embed-text为例演示 embedding 模型的拉取，而文档末尾的 TOML 配置示例以及仓库自带的 Ollama 示例配置 使用的都是bge-m3:latest。两者都是 Ollama 模型库中可用的 embedding 模型，任选其一即可，但配置文件中[[models.embeddings]]的name必须与本地实际拉取的模型名一致。从源码看，DB-GPT 为 Ollama embedding 适配器显式注册的受支持模型是BAAI/bge-m3，维度 1024、上下文长度 8192（见 embedding 适配器注册），因此bge-m3:latest是与 DB-GPT 内置 RAG 配置最贴合的选择。

四、安装 Ollama 相关的 Python 依赖

DB-GPT 采用uv作为多包工作区（workspace）依赖管理工具，仓库根目录的 pyproject.toml 将dbgpt-core、dbgpt-ext、dbgpt-serve等子包组织为统一工作区。要在本地接入 Ollama，需要按以下命令安装依赖（引自官方文档）：

# Use uv to install dependencies needed for Ollama proxy uv sync --all-packages \ --extra "base" \ --extra "proxy_ollama" \ --extra "rag" \ --extra "storage_chromadb" \ --extra "dbgpts"

各 extra 的作用可以结合仓库说明：

这里有一个容易踩坑的点：proxy_ollama安装的是Python 侧的ollama客户端库，它负责把 DB-GPT 的请求转发到 Ollama 的 HTTP API；而第二节安装的 Ollama 本体负责真正的模型推理。两者缺一不可。这一点从源码也能得到印证：OllamaLLMClient.sync_generate_stream在运行时执行import ollama，若未安装会抛出带pip install ollama提示的ValueError（见 ollama.py）。

五、修改 TOML 配置：启用 proxy/ollama 提供者

文档给出的最小配置

修改你的 TOML 配置文件，将 LLM 与 Embedding 的 provider 指向proxy/ollama：

# Model Configurations [models] [[models.llms]] name = "qwen:0.5b" provider = "proxy/ollama" api_base = "http://localhost:11434" api_key = "" [[models.embeddings]] name = "bge-m3:latest" provider = "proxy/ollama" api_url = "http://localhost:11434" api_key = ""

仓库中提供了一份可直接参考的完整示例 configs/dbgpt-proxy-ollama.toml，除了上面的模型配置外，还包含了 Web 服务、SQLite 数据库与 Chroma 向量存储等配套配置：

[system] language = "${env:DBGPT_LANG:-en}" api_keys = [] encrypt_key = "your_secret_key" [service.web] host = "0.0.0.0" port = 5670 [service.web.database] type = "sqlite" path = "pilot/meta_data/dbgpt.db" [rag.storage] [rag.storage.vector] type = "chroma" persist_path = "pilot/data"

参数逐项解析（结合源码实现）

1）name与provider

name是 Ollama 模型库中的模型名（如qwen:0.5b、deepseek-r1:1.5b、bge-m3:latest），provider固定为proxy/ollama。LLM 侧的参数类OllamaDeployModelParameters中provider的默认值正是"proxy/ollama"（见 OllamaDeployModelParameters）。

2）api_base（LLM）支持环境变量

从源码看，api_base的默认值为${env:OLLAMA_API_BASE:-http://localhost:11434}，即支持通过环境变量OLLAMA_API_BASE覆盖服务地址，未设置时回退到本机默认地址。如果 Ollama 部署在远程机器，直接在配置中写http://<host>:11434或导出该环境变量即可，无需改代码。

3）api_url（Embedding）与api_base（LLM）的命名差异

注意两类模型的地址字段名不同：LLM 用api_base，Embedding 用api_url。这与两侧参数类的定义一致——embedding 侧OllamaEmbeddingDeployModelParameters.api_url默认值同为http://localhost:11434（见 embedding 参数类）。此外 embedding 侧还有一个可选的backend字段：当backend为None时直接使用name作为传给 Ollama 的真实模型名（real_provider_model_name属性），一般场景下留空即可。

4）api_key留空

Ollama 是本地自托管服务，不需要 API Key，因此两处api_key = ""均为空字符串。

六、源码纵览：proxy/ollama 的调用链与能力边界

6.1 LLM 流式推理

OllamaLLMClient继承自ProxyLLMClient，核心推理逻辑在sync_generate_stream方法中（ollama.py）：

1. 通过parse_model_request构造统一请求，调用local_covert_message完成消息格式转换；
2. 创建ollama.Client(self._api_base)，以stream=True调用client.chat(model=..., messages=...)；
3. 逐块累加chunk["message"]["content"]，并通过parse_chat_message(..., extract_reasoning=is_reasoning_model)解析出正文与思考内容（thinking），最终封装为ModelOutput向上游流式返回；
4. 遇到ollama.ResponseError时，返回error_code=-1的ModelOutput，把错误信息以文本形式反馈到对话中，而不是直接中断流程。

可以推断，extract_reasoning分支是为了兼容 DeepSeek-R1 这类带思考过程（reasoning content）的模型——这也解释了为什么仓库示例配置选择了deepseek-r1:1.5b。

6.2 已注册的受支持模型元数据

register_proxy_model_adapter在注册时为 Ollama 客户端登记了受支持模型的元数据（ollama.py）：

源码注释中注明更多模型可参考 Ollama 模型库，即除上述元数据外，任意 Ollama 拉取成功的模型名都可以直接写入[[models.llms]]的name字段使用（supported_models主要用于 UI 展示与元数据，并不构成硬性白名单，这一点从new_client直接透传model_params.real_provider_model_name的实现可以印证）。

6.3 Embedding 同步/异步双通道

OllamaEmbeddings实现了embed_documents/embed_query（同步）与aembed_documents/aembed_query（异步）四组接口（ollama.py）。同步路径调用Client(self.api_url).embeddings(model=..., prompt=...)，异步路径则使用AsyncClient，二者都从返回结构中提取embedding字段并转为List[float]。批量向量化时embed_documents会对每个文本逐一调用embed_query，可以推断大批量文档入库场景下的耗时与文档数量线性相关，建议控制单次入库的切片规模。

七、常见问题与注意事项

1. 模型名不一致导致调用失败：[[models.llms]]/[[models.embeddings]]的name必须与ollama list中显示的模型名完全一致（包括 tag，如:0.5b、:latest）。Ollama 侧的错误会以**Ollama Response Error, Please CheckErrorInfo.**: ...的形式出现在输出或日志中（LLM 侧返回error_code=-1的 ModelOutput，Embedding 侧抛出ValueError，见 embedding 错误处理），可据此快速定位是模型未拉取还是地址配置错误。
2. 端口冲突：Ollama 默认占用11434端口；DB-GPT Web 服务默认占用5670端口（见 示例配置），两者互不冲突，但若 Ollama 被其他工具改过端口，需同步更新api_base与api_url两处。
3. 上下文长度：OllamaLLMClient的context_length默认为 4096，对于qwen:0.5b这类小模型足够验证流程；若接入 64K 上下文的 DeepSeek 系列，可结合模型元数据相应调整上下文配置。
4. 依赖检查：如果运行时报 “Could not import python package: ollama”，说明第四节的proxy_ollamaextra 未安装，重新执行uv sync --all-packages --extra "proxy_ollama" ...或在当前环境中执行pip install ollama即可。

八、小结

通过本文流程，你完成了 DB-GPT 接入 Ollama 的完整闭环：安装 Ollama 服务 → 拉取 LLM 与 Embedding 模型 →uv sync安装proxy_ollama等 extra 依赖 → 在 TOML 中配置provider = "proxy/ollama"。配置完成后，DB-GPT 的所有 LLM 调用会经由OllamaLLMClient走 Ollama 的流式 chat API，RAG 的向量化则经由OllamaEmbeddings走 Ollama 的 embeddings API，全部流量都停留在本地机器，为离线或内网环境中的 AI + Data 应用落地提供了可行的部署路径。

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