DB-GPT 接入 OpenAI 模型实战proxy_openai 扩展配置、模型选择与 Azure OpenAI 适配指南【免费下载链接】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 如何通过proxy/openai提供方接入 OpenAI 的 GPT 系列大模型与 text-embedding 系列向量模型。你将完整掌握从安装proxy_openai扩展、编写 TOML 配置含环境变量注入、选择合适模型到启动 Web 服务的全流程并结合仓库源码了解 LLM 客户端与 Embedding 客户端的底层实现细节最终能够把 OpenAI 作为 DB-GPT 的推理与向量化后端稳定运行起来。前置条件开始配置前需要确认以下两点一个可用的 OpenAI API key在 OpenAI 平台获取账号需已开通计费已安装带proxy_openai扩展的 DB-GPT即通过 uv 或 pip 安装时带上了该 extra。安装依赖使用 uv 同步依赖时指定proxy_openai扩展并顺带装入 RAG 与向量存储所需的扩展保证 LLM 与 Embedding 链路完整可用uv sync --all-packages \ --extra base \ --extra proxy_openai \ --extra rag \ --extra storage_chromadb \ --extra dbgptsproxy_openai扩展具体安装了哪些包可以从 dbgpt-core 的 pyproject.toml 中确认proxy_openai [ openai1.59.6, tiktoken0.8.0, httpx[socks], ]其中openai是 OpenAI 官方 SDK要求 1.59.6 及以上版本源码中亦有metadata.version(openai) 1.0.0的运行时校验tiktoken用于 token 计数httpx[socks]提供 HTTP 客户端能力并支持 SOCKS 代理这为后续故障排查中“配置代理”的方案提供了依赖基础。该扩展定义位于 packages/dbgpt-core/pyproject.toml。配置方式仓库提供了开箱即用的配置文件 configs/dbgpt-proxy-openai.toml。按文档的最小化写法核心是[models]段下的 LLM 与 Embedding 两块[models] [[models.llms]] name gpt-4o provider proxy/openai api_base https://api.openai.com/v1 api_key sk-your-openai-api-key [[models.embeddings]] name text-embedding-3-small provider proxy/openai api_url https://api.openai.com/v1/embeddings api_key sk-your-openai-api-key其中name是模型名provider固定为proxy/openaiLLM 侧用api_base指定接口基础地址Embedding 侧用api_url指定 embeddings 接口地址。推荐使用环境变量注入 API key不要把 API key 硬编码在配置文件里避免被误提交到版本库。DB-GPT 的配置支持${env:VAR}以及${env:VAR:-default}带默认值两种环境变量替换语法api_key ${env:OPENAI_API_KEY}export OPENAI_API_KEYsk-your-openai-api-key仓库自带的 configs/dbgpt-proxy-openai.toml 本身就是全环境变量化的示例其模型段完整写法为# Model Configurations [models] [[models.llms]] name ${env:LLM_MODEL_NAME:-gpt-4o} provider ${env:LLM_MODEL_PROVIDER:-proxy/openai} api_base ${env:OPENAI_API_BASE:-https://api.openai.com/v1} api_key ${env:OPENAI_API_KEY} [[models.embeddings]] name ${env:EMBEDDING_MODEL_NAME:-text-embedding-3-small} provider ${env:EMBEDDING_MODEL_PROVIDER:-proxy/openai} api_url ${env:EMBEDDING_MODEL_API_URL:-https://api.openai.com/v1/embeddings} api_key ${env:OPENAI_API_KEY}这意味着模型名、提供方、接口地址都可以通过环境变量覆盖而不必改文件例如LLM_MODEL_NAMEgpt-4o-mini即可切换更轻量的模型。该配置文件同时还定义了服务端与存储相关配置供你按需调整[system] language ${env:DBGPT_LANG:-en} api_keys [] encrypt_key your_secret_key # Server Configurations [service.web] host 0.0.0.0 port 5670 cors_allowed_origins ${env:DBGPT_CORS_ALLOWED_ORIGINS:-*} [service.web.database] type sqlite path pilot/meta_data/dbgpt.db [rag.storage] [rag.storage.vector] type chroma persist_path pilot/data即 Web 服务默认监听0.0.0.0:5670元数据落在 SQLitepilot/meta_data/dbgpt.dbRAG 向量数据落在 Chromapilot/data这也解释了为什么安装依赖时建议同时加上rag与storage_chromadb扩展。可用模型LLM模型配置名说明GPT-4ogpt-4o推荐效果最好GPT-4o minigpt-4o-mini更快、更便宜GPT-4 Turbogpt-4-turbo上一代方案GPT-3.5 Turbogpt-3.5-turbo预算敏感场景从源码结构看若未显式指定模型OpenAILLMClient的默认回退模型为gpt-4o-miniAzure 场景下为gpt-35-turbo见 packages/dbgpt-core/src/dbgpt/model/proxy/llms/chatgpt.py。因此即使配置中的name与后端实际部署的模型名不一致客户端也不会报错但请求会透传name中的模型名给 OpenAI选错名称会触发 “Model not found”这也是故障排查表中的一条。Embedding模型配置名维度text-embedding-3-smalltext-embedding-3-small1536text-embedding-3-largetext-embedding-3-large3072text-embedding-ada-002text-embedding-ada-0021536选择 Embedding 模型时要注意维度与向量库的匹配维度变更后已有向量索引不可复用建议首次入库前就确定模型。另外该 Embedding 客户端还支持一个可选参数backend当需要“配置名”与“实际请求模型名”解耦时例如网关侧统一注册名、后端真实模型不同可以设置backend为真实模型名从源码看real_provider_model_name的取值为backend or name即不设置backend时直接用name请求定义位于 packages/dbgpt-core/src/dbgpt/rag/embedding/embeddings.py。LLM 客户端源码解析配置项如何落到 HTTP 请求proxy/openai对应的 LLM 客户端是 chatgpt.py 中的OpenAILLMClient它继承自ProxyLLMClient通过 OpenAI 官方 SDK 的AsyncOpenAI异步客户端发起请求。理解几个关键点能帮助你预判配置行为1. 参数默认值与配置项对应关系。客户端的部署参数类OpenAICompatibleDeployModelParameters定义了各字段的默认值chatgpt.py#L42-L91参数默认值含义providerproxy/openai提供方标识api_base${env:OPENAI_API_BASE:-https://api.openai.com/v1}OpenAI API 基础地址api_key${env:OPENAI_API_KEY}API key标记为 privacyapi_typeNone使用 Azure 时设为azureapi_versionNoneAzure 的 API 版本context_lengthNone上下文长度为None时按模型元数据确定http_proxyNone访问 OpenAI 使用的 HTTP/HTTPS 代理concurrency100模型并发上限可以看到http_proxy参数是“Connection timeout / 网络不通”场景下配置代理的正式入口直接写进 TOML 的[[models.llms]]段即可生效。2. 环境变量兜底逻辑。客户端初始化时会经过 _build_openai_client实际构建逻辑在 chatgpt_utils.py#L53-L97 的_initialize_openai_v1中若 TOML 中未提供api_base/api_key会依次回退到环境变量OPENAI_API_BASE或 Azure 场景下的AZURE_OPENAI_ENDPOINT与OPENAI_API_KEY或AZURE_OPENAI_KEY。如果最终仍拿不到api_key会抛出api_key is required, please set OPENAI_API_KEY environment的ValueError。此外api_base末尾的/会被自动去除所以配置时写不写末尾斜杠都可以。3. 请求参数映射。_build_request会把 DB-GPT 内部的ModelRequest映射为 OpenAI 的 chat completions 请求体chatgpt.py#L243-L260temperature、max_new_tokens映射为max_tokens、stop、top_p在请求中非空时才会写入 payload模型名取request.model缺省回退到default_model。流式输出走generate_stream逐段产出ModelOutput这是 Web 界面能逐字渲染回答的底层链路。4. 超时设置。OpenAILLMClient.__init__中默认timeout240秒chatgpt.py#L134-L145。长提示词 大模型生成慢的场景下这个默认值通常够用如果仍频繁超时优先检查网络链路见故障排查。Embedding 客户端源码解析Embedding 侧由 embeddings.py 中的openapi_embeddings资源实现其部署参数OpenAPIEmbeddingDeployModelParametersembeddings.py#L651-L684与 TOML 中的字段对应如下参数默认值含义providerproxy/openai提供方标识api_urlhttp://localhost:8100/api/v1/embeddingsEmbedding 接口地址接 OpenAI 时需显式写https://api.openai.com/v1/embeddingsapi_keyNone接口鉴权 keybackendNone真实请求的模型名缺省用nametimeout60秒请求超时从源码结构看响应解析会检查 JSON 中是否存在data字段并按index排序后取embedding数组embeddings.py#L640-L648。注意api_url的默认值指向本地地址所以接 OpenAI 官方接口时必须在配置中显式写出api_url不能省略而 configs/dbgpt-proxy-openai.toml 已通过EMBEDDING_MODEL_API_URL环境变量为其提供了https://api.openai.com/v1/embeddings的默认值。另外在 model_config.py#L357 中proxy_openai也被登记为可用的 Embedding 提供方之一这说明 LLM 与 Embedding 两条链路共用同一套proxy_openai扩展依赖一次安装即可同时驱动。Azure OpenAI如果你要使用 Azure OpenAI可以把api_base改成 Azure endpoint[[models.llms]] name gpt-4o provider proxy/openai api_base https://your-resource.openai.azure.com/openai/deployments/your-deployment api_key your-azure-api-key结合源码看DB-GPT 对 Azure 有两条等效路径仅改api_base指向 deployment 端点即上面的写法请求按 OpenAI 兼容模式发出显式声明 Azure 模式在[[models.llms]]中增加api_type azure和api_versionOpenAI Azure API 的版本号此时 _build_openai_client 会改用 SDK 的AsyncAzureOpenAI客户端并通过azure_deployment环境变量API_AZURE_DEPLOYMENT可覆盖指定部署名。对应地api_base/api_key缺省时会回退到AZURE_OPENAI_ENDPOINT/AZURE_OPENAI_KEY环境变量。两条路径任选其一即可关键在于 deployment 名称、API 版本与资源实际开通情况一致否则会收到 Azure 侧的认证或 404 错误。启动服务配置完成后启动 Web 服务端uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml服务按配置文件默认监听0.0.0.0:5670浏览器访问该端口即可进入 DB-GPT 控制台选择已配置的gpt-4o/text-embedding-3-small开始对话与知识问答。故障排查问题解决方法AuthenticationError检查 API key 是否有效以及账号是否已开通计费RateLimitError降低请求频率或升级 OpenAI 套餐Connection timeout检查网络连接必要时配置代理LLM 侧可用http_proxy参数httpx[socks]依赖已包含在扩展中Model not found检查模型名称是否与 OpenAI 当前提供的模型一致结合源码可以补充两类常见根因其一OPENAI_API_KEY未设置且 TOML 中api_key为空时启动或首次调用会直接抛api_key is required的ValueError这不是网络问题而是配置缺失其二OpenAI SDK 版本低于 1.0 会触发Please upgrade openai package to version 1.0.0 or above的导入错误见 chatgpt_utils.py#L62-L63升级依赖即可解决。下一步快速开始 —— 完整首跑流程配置参考 —— 全部配置项说明更多 API 提供方仓库文档的 installation/advanced_usage 目录提供了More_proxyllms指南说明任何 OpenAI 兼容 API如 DeepSeek、SiliconFlow 等都可以复用同一套proxy_openai配置方式只需更换api_base与api_key【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考