企业官网建设流程全解析

DB-GPT API 入门指南：认证方式、官方 Python Client 与 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 API 官方文档 为核心骨架，结合 dbgpt-client 源码与 服务端配置实现，系统讲解 DB-GPT HTTP API 的接入流程：如何配置 API Key 认证、如何用 curl 直连、如何安装并使用官方 Python Client，以及如何借助 OpenAI SDK 复用现有生态快速接入。读完本文，你将掌握从"零配置"到"跑通第一次对话请求"的完整链路，并能根据源码理解认证与请求参数的真实行为。

DB-GPT 的 API 层遵循 OpenAI 兼容设计，任何支持 HTTP 请求的语言都可以直接调用，官方同时提供了开箱即用的 Python Client 绑定。无论你是想在自己的应用中嵌入 DB-GPT 的 Agent 能力，还是仅仅想通过脚本快速验证模型服务，都可以从本文的认证与调用示例入手。

一、API 概览与接入方式

DB-GPT API 的入口是一个运行在本地的 HTTP 服务（默认地址为http://localhost:5670）。你可以通过三种方式与它交互：

1. 任意语言的 HTTP 请求：直接向/api/v2/...端点发送请求，不依赖特定语言 SDK；
2. 官方 Python Client（dbgpt-client）：官方封装的异步客户端，覆盖 Chat、App、Flow、知识库、数据源等核心能力；
3. OpenAI Python SDK：由于 DB-GPT API 与 OpenAI API 兼容，在部分聊天场景下可以直接复用 OpenAI SDK。

从服务端视角看，DB-GPT 的 API 由多个子模块组成：聊天补全（Chat）、应用（App）、工作流（Flow）、知识库（Knowledge）、数据源（Datasource）、评估（Evaluation）与基准测试（Benchmark）等。官方 Python Client 在 dbgpt-client 包 中提供了与这些模块一一对应的封装（如 app.py、flow.py、knowledge.py），并通过Client统一分发请求。

二、认证：API Key 的配置与使用

DB-GPT API 使用API Key进行认证。你需要先在服务端的 API Keys 页面（或配置文件）中获取用于请求的 Key。

2.1 服务端配置API_KEYS

服务端通过环境变量API_KEYS声明允许访问 API 的 Key 列表，多个 Key 之间用英文逗号分隔。对应实现位于 config.py：

self.API_KEYS = os.getenv("API_KEYS", None)

在项目的.env文件中设置如下（默认开发环境使用dbgpt作为示例 Key）：

API_KEYS=dbgpt

注意：API_KEYS是服务端侧的放行清单；DBGPT_API_KEY是客户端侧请求时携带的 Key。两者需要保持一致，请求才能通过认证。

2.2 生产环境的安全要求

官方文档明确要求：生产环境的请求必须经过你自己的后端服务器转发，API Key 应从环境变量或密钥管理服务中安全加载，绝不能硬编码在前端代码或客户端中，避免 Key 泄露。

2.3 请求头规范

所有 API 请求都应在 HTTP 请求头中携带 API Key，格式为：

Authorization: Bearer DBGPT_API_KEY

在客户端实现中，该 Header 由 client.py 自动构造：

headers = {"Authorization": f"Bearer {self._api_key}"} if self._api_key else {} self._http_client = httpx.AsyncClient( headers=headers, timeout=timeout if timeout else httpx.Timeout(None) )

即：只要构造Client时传入了api_key，后续所有请求都会自动带上Authorization: Bearer <api_key>，无需手动维护 Header。

三、快速开始：curl 直接调用

curl 是最直接的验证方式。先导出 Key，再调用聊天补全接口：

curl "http://localhost:5670/api/v2/chat/completions" \ -H "Authorization: Bearer $DBGPT_API_KEY"

完整的流式聊天请求示例如下（stream: true时服务端会以 SSE 形式逐 token 返回）：

DBGPT_API_KEY="dbgpt" curl -X POST "http://localhost:5670/api/v2/chat/completions" \ -H "Authorization: Bearer $DBGPT_API_KEY" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -d "{\"messages\":\"Hello\",\"model\":\"gpt-4o\", \"stream\": true}"

请求体中最核心的两个字段是messages（用户消息）与model（模型 ID，需为服务端已接入的模型名）。完整的请求字段说明见 Chat API 文档，包括：

四、安装并使用官方 Python Client

官方推荐 Python 用户直接安装dbgpt-client包：

pip install "dbgpt-client>=0.7.1rc0"

4.1 创建 Client 实例

最简用法只需传入api_key：

from dbgpt_client import Client DBGPT_API_KEY = "dbgpt" client = Client(api_key=DBGPT_API_KEY)

Client的完整构造参数定义在 client.py：

从源码可以看出两个关键行为：

• 环境变量优先：如果api_base/api_key未传，Client 会自动读取DBGPT_API_BASE与DBGPT_API_KEY环境变量（client.py）；
• URL 合法性校验：is_valid_url会检查 scheme 与 netloc 是否齐全，非法地址会抛出ValueError（client.py）。

4.2 发起对话（非流式）

chat是异步方法，需在事件循环中调用：

from dbgpt_client import Client DBGPT_API_KEY = "dbgpt" client = Client(api_key=DBGPT_API_KEY) response = await client.chat(model="gpt-4o", messages="hello") print(response) await client.aclose()

chat方法内部会构造ChatCompletionRequestBody（stream=False），POST 到<api_base>/chat/completions，成功时解析为ChatCompletionResponse返回（client.py）。

4.3 流式对话

需要边生成边输出时使用chat_stream，它基于 SSE 解析逐块返回：

from dbgpt_client import Client DBGPT_API_KEY = "dbgpt" client = Client(api_key=DBGPT_API_KEY) async for data in client.chat_stream( model="gpt-4o", messages="hello", ): print(data)

底层实现会逐行读取data:前缀的 SSE 消息，解析为ChatCompletionStreamResponse，遇到data: [DONE]终止（client.py）。流式响应示例：

data: {"id": "chatcmpl-ba6fb52e-...", "model": "gpt-4o", "choices": [{"index": 0, "delta": {"role": "assistant", "content": "Hello"}}]} data: {"id": "chatcmpl-ba6fb52e-...", "model": "gpt-4o", "choices": [{"index": 0, "delta": {"role": "assistant", "content": "!"}}]} data: [DONE]

4.4 常用参数说明

chat/chat_stream均支持以下参数（定义见 schema.py）：

• temperature：采样温度，0～2；
• max_new_tokens：最大生成 token 数（字段已标记 deprecated，建议优先使用 OpenAI 规范的max_tokens，SDK 会在请求前自动将max_new_tokens映射到max_tokens）；
• chat_mode/chat_param：指定聊天模式及其参数（如知识库空间 ID、App ID、Flow ID）；
• conv_uid：会话 ID，用于多轮对话；
• span_id/user_name/sys_code：链路追踪与用户/系统标识；
• incremental：是否增量返回内容，默认True；
• enable_vis：响应内容是否输出可视化标签，默认True。

4.5 更丰富的客户端能力

Client实例还暴露了get/post/patch/put/delete等通用方法，统一路由到<api_base>/serve/...路径（client.py），应用列表、Flow 运行、知识库管理等能力均基于这些方法实现。例如list_app通过client.get("/apps")拉取应用列表（app.py）。此外包内还提供了dbgpt_client flow命令行工具，可本地或远程运行 AWEL Flow（CLI 实现）。

五、使用 OpenAI Python SDK 调用

由于 DB-GPT API 与 OpenAI API 兼容，在部分聊天场景可以直接复用 OpenAI SDK，将base_url指向 DB-GPT 即可：

pip install openai

from openai import OpenAI DBGPT_API_KEY = "dbgpt" client = OpenAI( api_key=DBGPT_API_KEY, base_url="http://localhost:5670/api/v2" ) response = client.chat.completions.create( model="gpt-4o", messages=[ { "role": "user", "content": "Hello", }, ], extra_body={ "chat_mode": "chat_normal", }, stream=True, max_tokens=2048, ) for chunk in response: delta_content = chunk.choices[0].delta.content print(delta_content, end="", flush=True)

要点说明：

• base_url必须指向 DB-GPT 的 API 根路径http://localhost:5670/api/v2；
• DB-GPT 扩展参数（如chat_mode）通过extra_body透传；
• 兼容性主要面向聊天补全（Chat Completions）场景，其他能力建议使用官方 Python Client。

六、验证与排错建议

接入完成后，可通过以下几点快速验证与排错：

1. 确认服务已启动：默认端口为5670，本地访问http://localhost:5670/api/v2/chat/completions应能收到响应；
2. 确认 Key 一致：服务端.env中的API_KEYS与请求携带的BearerToken 必须一致，否则会认证失败；
3. 确认模型 ID：请求中的model必须是服务端实际接入的模型名（如示例中的gpt-4o需已在服务端配置），否则返回 404 或模型不可用错误；
4. 异步调用环境：官方 Python Client 的方法均为async，需要在asyncio环境中使用；调用结束后可调用client.aclose()或依赖进程退出时自动关闭（源码通过atexit注册了自动清理，见 client.py）。

七、参考资源

• API 入口文档：docs/docs/api/introduction.md
• Chat 接口完整字段与响应结构：docs/docs/api/chat.md
• 官方 Python Client 实现：packages/dbgpt-client/src/dbgpt_client/client.py
• 客户端请求体 Schema：packages/dbgpt-client/src/dbgpt_client/schema.py
• 服务端API_KEYS配置解析：packages/dbgpt-core/src/dbgpt/_private/config.py
• 客户端调用示例：examples/client/client_openai_chat.py、examples/client/app_crud_example.py

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