DBGPT对外API文件说明 以及 DBGPT对外API接口说明

爱吃土豆的马铃薯ㅤㅤㅤㅤㅤㅤㅤㅤㅤ2025-12-01 16:09

以下是各文件的主要区别，基于提供的代码片段和文档内容：

  1. knowledge.md

    • 核心功能：围绕「知识空间（Knowledge Space）」的交互，主要用于基于知识库的对话。
    • 关键内容：
      • 提供了通过 Curl、Python 客户端、OpenAI SDK 调用知识库对话的示例代码。
      • 包含知识空间相关的流式响应示例（如模型返回的片段内容）。
      • 涉及知识空间的更新操作（如修改名称、向量类型等）。

  2. chat.md

    • 核心功能：基础的「对话补全（Chat Completion）」功能，不依赖特定知识库、应用或流程。
    • 关键内容：
      • 提供普通对话（chat_normal 模式）的流式和非流式调用示例。
      • 展示了对话响应的格式（如分块返回的 data 字段和 [DONE] 结束标识）。
      • 支持通过 Curl、Python 客户端、OpenAI SDK 调用。

  3. app.md

    • 核心功能：围绕「应用（App）」的管理和交互，如查询、列表、获取应用详情等。
    • 关键内容：
      • 提供应用相关的 API 操作（获取单个应用、列出所有应用）。
      • 定义了应用模型（App Model）和应用详情模型（App Detail Model）的结构（如 app_code、app_name、prompt_template 等字段）。
      • 支持通过 Curl 和 Python 客户端调用。

  4. datasource.md

    • 核心功能：围绕「数据源（Datasource）」的管理和交互，如查询、删除、列出数据源等。
    • 关键内容：
      • 提供数据源相关的 API 操作（删除数据源、列出数据源）。
      • 定义了数据源对象（Datasource Object）的结构（如 id、db_name、db_type 等字段）。
      • 支持通过 Curl、Python 客户端、OpenAI SDK 调用数据源对话（chat_data 模式）。

  5. flow.md

    • 核心功能：围绕「流程（Flow）」的管理和交互，如查询、删除、列出流程等。
    • 关键内容：
      • 提供流程相关的 API 操作（获取单个流程、列出所有流程、删除流程）。
      • 定义了流程对象（Flow Object）的结构（如 uid、name、flow_data 等字段）。
      • 支持通过 Curl、Python 客户端、OpenAI SDK 调用流程对话（chat_flow 模式）。

  6. evaluation.md

    • 核心功能：模型评估相关功能，用于评估检索效果（如召回率、准确率等）。
    • 关键内容：
      • 提供评估请求的示例代码（如调用 run_evaluation 函数）。
      • 定义了评估指标（如 RetrieverHitRateMetric、RetrieverMRRMetric 等）。
      • 说明评估数据集的结构和要求。

  7. introduction.md

    • 核心功能：DB-GPT API 的入门介绍，包括认证方式和客户端安装。
    • 关键内容：
      • 说明 API 密钥的使用方式（Authorization 头）。
      • 提供 Python 客户端的安装命令（pip install "dbgpt-client>=0.7.1rc0"）。
      • 示例如何配置 API 密钥（如 .env 文件设置）。

总结：这些文件分别对应 DB-GPT 不同模块的功能，涵盖了基础对话、知识库、应用、数据源、流程管理及模型评估，每个文件聚焦于特定场景的 API 调用和数据结构定义。

datasource.md 文件内容及对外接口详细介绍

datasource.md 主要围绕「数据源（Datasource）」的管理和交互功能，提供了相关的 API 接口说明，包括数据源的对话交互、创建、更新、删除、查询、列表等操作。以下是具体内容及对外接口：

一、核心功能概述

该文件聚焦于与数据源相关的 API 调用，支持通过 Curl、Python 客户端、OpenAI SDK 等方式与数据源进行对话，并提供数据源的全生命周期管理（创建、更新、删除、查询等）。

二、对外接口详情

1. 数据源对话（Chat Datasource）

  • 功能：基于指定数据源进行对话交互，支持流式和非流式响应。

  • 接口地址 ：POST /api/v2/chat/completions

  • 请求参数 ：

    • messages：对话内容（用户输入）。
    • model：使用的模型（如 gpt-4o）。
    • chat_mode：对话模式，固定为 chat_data。
    • chat_param：数据源名称（DB_NAME）。

  • 调用示例 ：

    • Curl ：

      shell 复制代码 
      DBGPT_API_KEY=dbgpt
DB_NAME="{your_db_name}"
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\":\"show space datas limit 5\",\"model\":\"gpt-4o\", \"chat_mode\": \"chat_data\", \"chat_param\": \"$DB_NAME\"}"

    • Python 客户端 ：

      python 复制代码 
      from dbgpt_client import Client
DBGPT_API_KEY = "dbgpt"
DB_NAME="{your_db_name}"
client = Client(api_key=DBGPT_API_KEY)
res = client.chat(
    messages="show space datas limit 5", 
    model="gpt-4o", 
    chat_mode="chat_data", 
    chat_param=DB_NAME
)

    • OpenAI SDK ：

      python 复制代码 
      from openai import OpenAI
DBGPT_API_KEY = "dbgpt"
DB_NAME="{your_db_name}"
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_data", "chat_param": DB_NAME},
    stream=True,
    max_tokens=2048,
)
for chunk in response:
    print(chunk.choices[0].delta.content, end="", flush=True)

  • 响应示例 （非流式）：

    json 复制代码 
    {
    "id": "2bb80fdd-e47e-4083-8bc9-7ca66ee0931b",
    "object": "chat.completion",
    "created": 1711509733,
    "model": "gpt-4o",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "The user wants to display information about knowledge spaces with a limit of 5..."
            },
            "finish_reason": null
        }
    ],
    "usage": {
        "prompt_tokens": 0,
        "total_tokens": 0,
        "completion_tokens": 0
    }
}

2. 创建数据源（Create Datasource）

  • 功能：创建新的数据源（如数据库连接配置）。
  • 接口地址 ：POST /api/v2/serve/datasources
  • 请求体 ：需包含数据源对象（Datasource Object），字段包括 db_name、db_type、db_host、db_port 等（详见下文「数据源对象结构」）。
  • 调用示例 ：
    • （具体 Curl/Python 示例未完全展示，需参考类似接口格式，传入数据源配置参数）

3. 更新数据源（Update Datasource）

  • 功能：更新已存在的数据源配置。
  • 接口地址 ：PUT /api/v2/serve/datasources
  • 请求体 ：需包含更新后的数据源对象（Datasource Object）。
  • 响应：返回更新后的数据源对象。

4. 删除数据源（Delete Datasource）

  • 功能：删除指定 ID 的数据源。

  • 接口地址 ：DELETE /api/v2/serve/datasources/{datasource_id}

  • 请求参数 ：datasource_id（数据源唯一 ID，必填）。

  • 调用示例 ：

    • Curl ：

      shell 复制代码 
      DBGPT_API_KEY=dbgpt
DATASOURCE_ID={YOUR_DATASOURCE_ID}
curl -X DELETE "http://localhost:5670/api/v2/serve/datasources/$DATASOURCE_ID" \
    -H "Authorization: Bearer $DBGPT_API_KEY"

    • Python 客户端 ：

      python 复制代码 
      from dbgpt_client import Client
from dbgpt_client.datasource import delete_datasource
DBGPT_API_KEY = "dbgpt"
datasource_id = "{your_datasource_id}"
client = Client(api_key=DBGPT_API_KEY)
res = await delete_datasource(client=client, datasource_id=datasource_id)

  • 响应：返回被删除的数据源对象。

5. 获取单个数据源（Get Datasource）

  • 功能：查询指定 ID 的数据源详情。

  • 接口地址 ：GET /api/v2/serve/datasources/{datasource_id}

  • 请求参数 ：datasource_id（数据源唯一 ID，必填）。

  • 调用示例 ：

    • Curl ：

      shell 复制代码 
      DBGPT_API_KEY=dbgpt
DATASOURCE_ID={YOUR_DATASOURCE_ID}
curl -X GET "http://localhost:5670/api/v2/serve/datasources/$DATASOURCE_ID" \
    -H "Authorization: Bearer $DBGPT_API_KEY"

    • Python 客户端 ：

      python 复制代码 
      from dbgpt_client import Client
from dbgpt_client.datasource import get_datasource
DBGPT_API_KEY = "dbgpt"
datasource_id = "{your_datasource_id}"
client = Client(api_key=DBGPT_API_KEY)
res = await get_datasource(client=client, datasource_id=datasource_id)

  • 响应：返回指定数据源的对象详情。

6. 列出所有数据源（List Datasource）

  • 功能：查询当前所有数据源的列表。

  • 接口地址 ：GET /api/v2/serve/datasources

  • 调用示例 ：

    • Curl ：

      shell 复制代码 
      DBGPT_API_KEY=dbgpt
curl -X GET "http://localhost:5670/api/v2/serve/datasources" \
    -H "Authorization: Bearer $DBGPT_API_KEY"

    • Python 客户端 ：

      python 复制代码 
      from dbgpt_client import Client
from dbgpt_client.datasource import list_datasource
DBGPT_API_KEY = "dbgpt"
client = Client(api_key=DBGPT_API_KEY)
res = await list_datasource(client=client)

  • 响应：返回数据源对象列表。

三、数据源对象结构（Datasource Object）

包含以下核心字段：

  • id：数据源唯一 ID（字符串）。
  • db_name：数据库名称（字符串）。
  • db_type：数据库类型（如 sqlite、mysql 等，字符串）。
  • db_path：文件型数据库的路径（字符串，可选）。
  • db_host：数据库主机地址（字符串，可选）。
  • db_port：数据库端口（整数，可选）。
  • db_user：数据库用户名（字符串，可选）。
  • db_pwd：数据库密码（字符串，可选）。
  • comment：数据源描述（字符串，可选）。

总结

datasource.md 提供的接口覆盖了数据源从创建到删除的全生命周期管理，以及基于数据源的对话交互能力，支持多种调用方式，适用于需要与数据库等数据源进行交互的场景。

chat.md 文件内容及对外接口详细介绍

chat.md 聚焦 DB-GPT 的「基础对话补全（Chat Completion）」功能，核心是通过 POST /api/v2/chat/completions 接口实现通用对话交互，支持流式/非流式响应，兼容多种调用方式，不依赖特定知识库、应用或流程。以下是具体内容及对外接口详情：

一、核心功能概述

该文件主要定义基础对话能力，支持用户通过 HTTP 请求（Curl、Python 客户端、OpenAI SDK）与模型进行交互，返回符合对话上下文的响应。核心特点包括：

  • 支持 chat_normal（默认）、chat_app、chat_knowledge、chat_flow 等多种对话模式。
  • 提供流式（实时分块返回）和非流式（完整响应返回）两种响应方式。
  • 可配置模型、对话内容、生成参数（如最大 tokens、温度值）等核心参数。

二、对外核心接口：POST /api/v2/chat/completions

这是文件中唯一对外的核心接口，所有对话交互均通过该接口实现，不同调用方式和参数组合适配不同场景。

1. 接口基础信息

  • 功能：接收对话上下文，返回模型生成的补全响应。
  • 请求方法 ：POST
  • 接口地址 ：http://localhost:5670/api/v2/chat/completions
  • 认证方式 ：通过 HTTP 头 Authorization: Bearer $DBGPT_API_KEY 认证（DBGPT_API_KEY 为用户专属密钥）。
  • 请求头 ：
    • Authorization：必填，格式为 Bearer {DBGPT_API_KEY}。
    • accept：固定为 application/json。
    • Content-Type：固定为 application/json。

2. 核心请求参数

参数名 类型 是否必填 说明
messages string/array 是 对话上下文内容，可直接传字符串（如 "Hello"）或数组（含角色和内容，如 [{"role": "user", "content": "Hello"}]）。
model string 是 调用的模型 ID，示例中使用 gpt-4o（需结合模型兼容性选择）。
chat_mode string 否 对话模式，可选值：chat_normal（默认）、chat_app、chat_knowledge、chat_flow，对应不同交互场景。
chat_param string 否 对话模式关联参数，如 chat_app 对应 app_id、chat_knowledge 对应 space_name，默认 None。
max_new_tokens integer 否 生成响应的最大 tokens 数，受模型上下文长度限制。
stream boolean 否 是否开启流式响应，true 为流式（分块返回），false 为非流式（完整返回），默认 false。
temperature float 否 采样温度（0-2），值越高响应越随机，越低越 deterministic，默认无固定值。
conv_uid string 否 对话唯一 ID，用于关联多轮对话，默认 None。
span_id string 否 链路追踪 ID，用于日志排查，默认 None。
sys_code string 否 系统编码，默认 None。
user_name string 否 web 服务器用户名，默认 None。

3. 调用示例（3种方式）

（1）Curl 调用
  • 流式响应示例：
shell 复制代码 
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}"
  • 非流式响应示例（仅修改 stream: false）：
shell 复制代码 
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\": false}"
（2）Python 客户端调用
  • 流式响应示例：
python 复制代码 
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)
  • 非流式响应示例：
python 复制代码 
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()
（3）OpenAI SDK 调用（兼容 OpenAI 接口规范）

仅支持流式响应，示例：

python 复制代码 
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",  # 可选，默认即为 chat_normal
    },
    stream=True,
    max_tokens=2048,
)
for chunk in response:
    delta_content = chunk.choices[0].delta.content
    print(delta_content, end="", flush=True)

4. 响应格式

（1）流式响应（stream: true）

以 data: 开头分块返回，结束标识为 data: [DONE]，示例：

commandline 复制代码 
data: {"id": "chatcmpl-ba6fb52e-e5b2-11ee-b031-acde48001122", "model": "gpt-4o", "choices": [{"index": 0, "delta": {"role": "assistant", "content": "Hello"}}]}
data: {"id": "chatcmpl-ba6fb52e-e5b2-11ee-b031-acde48001122", "model": "gpt-4o", "choices": [{"index": 0, "delta": {"role": "assistant", "content": "!"}}]}
data: [DONE]
  • 流式响应字段说明：
    • id：对话唯一 ID（conv_uid）。
    • model：使用的模型 ID。
    • choices：响应列表（默认 1 个）。
      • index：响应索引（默认 0）。
      • delta：分块内容对象，包含 role（角色：assistant）和 content（分块文本）。
（2）非流式响应（stream: false）

返回完整 JSON 结构，示例：

json 复制代码 
{
    "id": "a8321543-52e9-47a5-a0b6-3d997463f6a3",
    "object": "chat.completion",
    "created": 1710826792,
    "model": "gpt-4o",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Hello! How can I assist you today?"
            },
            "finish_reason": null
        }
    ],
    "usage": {
        "prompt_tokens": 0,
        "total_tokens": 0,
        "completion_tokens": 0
    }
}
  • 非流式响应字段说明：
    • 新增 object：响应类型（固定为 chat.completion）。
    • 新增 usage：tokens 使用统计（prompt_tokens 提示词 tokens、completion_tokens 生成 tokens、total_tokens 总 tokens）。
    • choices[0].message：完整响应内容（而非分块 delta）。

三、关键补充说明

  1. 对话模式适配：chat_mode 需与 chat_param 配套使用（如 chat_app 需传 app_id），默认 chat_normal 无需 chat_param。
  2. 模型兼容性：接口支持的模型需参考 DB-GPT 模型端点兼容表，示例中 gpt-4o 为常用选项。
  3. 流式响应优势：适合实时展示响应内容（如聊天界面），非流式适合需要完整响应的场景（如批量处理）。

datasource.md文件详细说明：

datasource.md 文件内容、对外接口及参数补充说明

datasource.md 聚焦 DB-GPT 的「数据源（Datasource）」交互与管理功能，核心是通过统一接口实现数据源对话、创建、更新、删除等操作。其对外接口基于 DB-GPT 通用对话接口扩展，支持补充 temperature（温度）和 max_new_tokens（最大生成 tokens）参数，以下是完整详情：

一、核心功能概述

该文件定义了数据源全生命周期管理能力，包括：

  1. 基于指定数据源的对话交互（支持流式/非流式响应）；
  2. 数据源配置的创建、更新、删除、查询及列表展示；
  3. 兼容 Curl、Python 客户端、OpenAI SDK 三种调用方式，且可复用通用对话参数。

二、对外接口详情（含参数补充）

所有接口均需通过 Authorization: Bearer $DBGPT_API_KEY 认证（DBGPT_API_KEY 为用户专属密钥），基础请求头统一为 accept: application/json 和 Content-Type: application/json。

1. 核心接口：数据源对话（Chat Datasource）

  • 功能：基于指定数据库（数据源）进行对话查询（如数据统计、信息检索），支持补充生成参数。

  • 接口地址 ：POST /api/v2/chat/completions（复用通用对话接口，通过 chat_mode 区分场景）

  • 请求参数：

    参数名 类型 是否必填 说明
    messages string/array 是 对话内容，可传字符串（如 "查询前5条数据"）或数组（含角色，如 [{"role": "user", "content": "查询前5条数据"}]）
    model string 是 调用的模型（如 gpt-4o、deepseek-reasoner）
    chat_mode string 是 固定为 chat_data（标识数据源对话场景）
    chat_param string 是 数据源名称（DB_NAME，即目标数据库名称）
    stream boolean 否 是否流式响应，true 分块返回，false 完整返回，默认 false
    temperature float 否 采样温度（0-2），值越高响应越随机，越低越确定，默认无固定值
    max_new_tokens integer 否 生成响应的最大 tokens 数，受模型上下文长度限制，默认无固定值
    conv_uid string 否 对话唯一 ID，用于多轮对话关联，默认 None
    span_id string 否 链路追踪 ID，用于日志排查，默认 None

  • 调用示例（补充温度和 Token 参数）：

    （1）Curl 调用
    shell 复制代码 
    DBGPT_API_KEY=dbgpt
DB_NAME="{your_db_name}"
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\":\"show space datas limit 5\",
        \"model\":\"gpt-4o\",
        \"chat_mode\": \"chat_data\",
        \"chat_param\": \"$DB_NAME\",
        \"stream\": false,
        \"temperature\": 0.3,  # 补充温度参数（低随机性）
        \"max_new_tokens\": 1024  # 补充最大生成 tokens
    }"
    （2）Python 客户端调用
    python 复制代码 
    from dbgpt_client import Client
DBGPT_API_KEY = "dbgpt"
DB_NAME="{your_db_name}"
client = Client(api_key=DBGPT_API_KEY)
res = client.chat(
    messages="show space datas limit 5",
    model="gpt-4o",
    chat_mode="chat_data",
    chat_param=DB_NAME,
    temperature=0.3,  # 补充温度参数
    max_new_tokens=1024  # 补充最大生成 tokens
)
print(res)
    （3）OpenAI SDK 调用
    python 复制代码 
    from openai import OpenAI
DBGPT_API_KEY = "dbgpt"
DB_NAME="{your_db_name}"
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": "show space datas limit 5"}],
    extra_body={
        "chat_mode": "chat_data",
        "chat_param": DB_NAME,
        "temperature": 0.3,  # 补充温度参数
        "max_new_tokens": 1024  # 补充最大生成 tokens
    },
    stream=True
)
for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

  • 响应示例（非流式）：

    json 复制代码 
    {
    "id": "2bb80fdd-e47e-4083-8bc9-7ca66ee0931b",
    "object": "chat.completion",
    "created": 1711509733,
    "model": "gpt-4o",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "以下是知识空间的前5条数据：<chart-view content=\"{\"type\": \"response_table\", \"sql\": \"SELECT * FROM knowledge_space LIMIT 5\", \"data\": [...]}\" />"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 15,
        "total_tokens": 120,
        "completion_tokens": 105
    }
}

2. 数据源管理接口（无生成参数，仅管理配置）

以下接口用于数据源本身的配置管理（如创建数据库连接、修改配置），不涉及模型生成，因此无需也不支持 temperature 和 max_new_tokens 参数。

（1）创建数据源（Create Datasource）
  • 功能：新增数据源配置（如连接 MySQL、SQLite 数据库）。
  • 接口地址 ：POST /api/v2/serve/datasources
  • 请求体 ：需传入「数据源对象（Datasource Object）」，字段如下：
    • db_name：数据库名称（必填）；
    • db_type：数据库类型（如 mysql、sqlite，必填）；
    • db_host：数据库主机地址（可选，文件型数据库无需）；
    • db_port：数据库端口（可选）；
    • db_user：数据库用户名（可选）；
    • db_pwd：数据库密码（可选）；
    • db_path：文件型数据库路径（如 SQLite，可选）；
    • comment：数据源描述（可选）。
  • 响应 ：返回创建成功的数据源对象（含 id 等唯一标识）。
（2）更新数据源（Update Datasource）
  • 功能：修改已存在的数据源配置。
  • 接口地址 ：PUT /api/v2/serve/datasources
  • 请求体 ：同「创建数据源」，需包含数据源 id（必填，用于定位修改对象）。
  • 响应：返回更新后的数据源对象。
（3）删除数据源（Delete Datasource）

  • 功能：删除指定 ID 的数据源配置。

  • 接口地址 ：DELETE /api/v2/serve/datasources/{datasource_id}

  • 路径参数 ：datasource_id（数据源唯一 ID，必填）。

  • 调用示例（Curl） ：

    shell 复制代码 
    DBGPT_API_KEY=dbgpt
DATASOURCE_ID={YOUR_DATASOURCE_ID}
curl -X DELETE "http://localhost:5670/api/v2/serve/datasources/$DATASOURCE_ID" \
    -H "Authorization: Bearer $DBGPT_API_KEY"

  • 响应：返回被删除的数据源对象。

（4）获取单个数据源（Get Datasource）
  • 功能：查询指定 ID 的数据源配置详情。
  • 接口地址 ：GET /api/v2/serve/datasources/{datasource_id}
  • 路径参数 ：datasource_id（数据源唯一 ID，必填）。
  • 响应：返回对应的数据源对象。
（5）列出所有数据源（List Datasource）

  • 功能：查询当前所有已配置的数据源列表。

  • 接口地址 ：GET /api/v2/serve/datasources

  • 调用示例（Python 客户端） ：

    python 复制代码 
    from dbgpt_client import Client
from dbgpt_client.datasource import list_datasource
DBGPT_API_KEY = "dbgpt"
client = Client(api_key=DBGPT_API_KEY)
res = await list_datasource(client=client)  # 返回数据源对象列表

  • 响应：返回数据源对象数组。

三、关键补充说明

  1. 参数适用范围 ：temperature 和 max_new_tokens 仅适用于「数据源对话接口」（POST /api/v2/chat/completions），用于控制模型生成响应的随机性和长度；数据源管理接口（创建/更新/删除等）不涉及模型生成，不支持这两个参数。
  2. 参数兼容性 ：这两个参数是 DB-GPT 通用对话接口的标准可选参数，datasource.md 中的对话功能复用该接口，因此天然支持，无需额外配置。
  3. 模型限制 ：max_new_tokens 的取值不能超过所选模型的上下文长度限制（如 gpt-4o 通常支持 8192 或 32768 tokens），否则会返回参数错误。

四、数据源对象结构（Datasource Object）

所有数据源管理接口的请求/响应均基于该结构：

  • id：数据源唯一 ID（字符串，自动生成）；
  • db_name：数据库名称（字符串，必填）；
  • db_type：数据库类型（字符串，如 mysql、sqlite、milvus，必填）；
  • db_host：数据库主机地址（字符串，可选）；
  • db_port：数据库端口（整数，可选）；
  • db_user：数据库用户名（字符串，可选）；
  • db_pwd：数据库密码（字符串，可选）；
  • db_path：文件型数据库路径（字符串，可选，如 ./data/sqlite.db）；
  • comment：数据源描述（字符串，可选）。

datasource.md 接口参数完整版对照表

以下是 datasource.md 中所有对外接口的参数详情，包含参数类型、必填项、说明、示例值及补充参数适配情况，方便直接查询使用：

接口名称 参数分类 参数名 类型 是否必填 核心说明 示例值 支持补充参数（temperature/max_new_tokens）
数据源对话（Chat Datasource） 核心参数 messages string/array 是 对话内容，可传纯文本或含角色的数组（角色支持 user/assistant） "show space datas limit 5" 或 [{"role": "user", "content": "查询前5条数据"}] 是
model string 是 调用的模型 ID，需为 DB-GPT 兼容模型 "gpt-4o"、"deepseek-reasoner" 是
chat_mode string 是 对话场景标识，数据源对话固定为 chat_data "chat_data" 是
chat_param string 是 关联的数据源名称（目标数据库名称） "knowledge_db"、"enterprise_db" 是
生成控制参数 stream boolean 否 是否流式响应：true 分块返回，false 完整返回 true、false（默认） 是
temperature float 否 采样温度（0-2），值越高响应越随机，越低越确定 0.3（低随机）、1.0（默认）、1.8（高随机） 是（核心补充参数）
max_new_tokens integer 否 生成响应的最大 tokens 数，受模型上下文长度限制 512、1024、2048 是（核心补充参数）
可选辅助参数 conv_uid string 否 对话唯一 ID，用于关联多轮对话 "conv-123456" 是
span_id string 否 链路追踪 ID，用于日志排查和问题定位 "span-789012" 是
sys_code string 否 系统编码，用于多系统区分（默认无） "sys-enterprise-001" 是
user_name string 否 调用者用户名（默认无） "admin"、"developer" 是
创建数据源（Create Datasource） 数据源配置参数 db_name string 是 数据源（数据库）名称 "sales_db"、"inventory_db" 否（无模型生成环节）
db_type string 是 数据库类型，支持主流数据库 "mysql"、"sqlite"、"milvus"、"postgres" 否
db_host string 否 数据库主机地址（文件型数据库如 SQLite 无需） "127.0.0.1"、"localhost" 否
db_port integer 否 数据库端口（默认使用对应数据库默认端口） 3306（MySQL）、5432（PostgreSQL） 否
db_user string 否 数据库登录用户名 "root"、"db_user" 否
db_pwd string 否 数据库登录密码 "123456"、"db_password_xxx" 否
db_path string 否 文件型数据库路径（如 SQLite 数据库文件路径） "./data/sqlite_db.db" 否
comment string 否 数据源描述说明 "销售数据专用数据库"、"知识库向量数据库" 否
更新数据源（Update Datasource） 数据源配置参数 id string 是 数据源唯一 ID（用于定位待更新的数据源） "ds-12345678-xxxx-xxxx" 否
其余参数 - 同创建 与「创建数据源」参数一致，仅需传入需修改的字段 同创建数据源示例值 否
删除数据源（Delete Datasource） 路径参数 datasource_id string 是 待删除数据源的唯一 ID "ds-12345678-xxxx-xxxx" 否
获取单个数据源（Get Datasource） 路径参数 datasource_id string 是 待查询数据源的唯一 ID "ds-12345678-xxxx-xxxx" 否
列出所有数据源（List Datasource） 无 无 - - 无参数，直接调用接口即可返回所有数据源列表 - 否

补充说明

  1. 所有接口均需通过 Authorization: Bearer $DBGPT_API_KEY 认证，DBGPT_API_KEY 为用户专属密钥，需提前配置。
  2. 补充参数 temperature 和 max_new_tokens 仅适用于「数据源对话接口」，其他管理类接口（创建/更新/删除等）因不涉及模型生成响应，无需配置这两个参数。
  3. max_new_tokens 取值需小于所选模型的上下文长度限制（如 gpt-4o 通常支持 8192/32768 tokens），超出限制会返回参数错误。

要不要我帮你生成一份可直接复制使用的接口调用模板，包含对话接口（带补充参数）和所有管理接口的 Curl/Python 示例代码？

chat.md文件详细说明：

chat.md 文件内容、对外接口及参数补充说明

chat.md 聚焦 DB-GPT 的「基础对话补全（Chat Completion）」功能，核心是通过统一接口实现通用对话交互，支持多种调用方式和参数配置。其对外接口天然支持补充 temperature（温度）和 max_new_tokens（最大生成 tokens）参数，以下是详细内容：

一、核心功能概述

该文件定义了 DB-GPT 最基础的对话能力，不依赖特定知识库、数据源或应用，支持：

  1. 通用文本对话（如问答、创作、逻辑推理等）；
  2. 流式（分块实时返回）和非流式（完整响应返回）两种响应模式；
  3. 通过参数控制生成效果（如随机性、长度限制）；
  4. 兼容 Curl、Python 客户端、OpenAI SDK 三种调用方式。

二、对外核心接口：POST /api/v2/chat/completions

这是 chat.md 中唯一的对外接口，所有对话交互均通过该接口实现，支持补充温度和 token 等生成参数。

1. 接口基础信息

  • 功能：接收对话上下文，返回模型生成的补全响应，支持参数化控制生成效果。
  • 请求方法 ：POST
  • 接口地址 ：http://localhost:5670/api/v2/chat/completions
  • 认证方式 ：通过 HTTP 头 Authorization: Bearer $DBGPT_API_KEY 认证（DBGPT_API_KEY 为用户密钥）。
  • 请求头 ：
    • Authorization：必填，格式为 Bearer {DBGPT_API_KEY}；
    • Content-Type：必填，固定为 application/json；
    • accept：必填，固定为 application/json。

2. 完整请求参数（含补充参数）

参数分类 参数名 类型 是否必填 说明 示例值
核心对话参数 messages string/array 是 对话内容： - 字符串（如 "你好"）； - 数组（含角色，如 [{"role": "user", "content": "你好"}]） "查询天气" 或 [{"role": "user", "content": "查询天气"}]
model string 是 调用的模型 ID（需为 DB-GPT 兼容模型） "gpt-4o"、"deepseek-reasoner"
chat_mode string 否 对话模式：默认 chat_normal（通用对话），其他模式需配合 chat_param 使用 "chat_normal"（默认）
chat_param string 否 对话模式关联参数（如 chat_app 模式需传 app_id），默认 None "app-123"（仅特定模式需填）
生成控制参数 stream boolean 否 是否流式响应：true 分块返回，false 完整返回（默认） true、false
temperature float 否 采样温度（0-2）：值越高响应越随机，越低越确定（默认无固定值） 0.3（低随机）、1.0（平衡）、1.8（高随机）
max_new_tokens integer 否 生成响应的最大 tokens 数（受模型上下文长度限制） 512、1024、2048
辅助参数 conv_uid string 否 对话唯一 ID（用于关联多轮对话） "conv-123456"
span_id string 否 链路追踪 ID（用于日志排查） "span-789012"

3. 调用示例（含补充参数）

（1）Curl 调用（带温度和最大 tokens）
shell 复制代码 
DBGPT_API_KEY="dbgpt"
curl -X POST "http://localhost:5670/api/v2/chat/completions" \
  -H "Authorization: Bearer $DBGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d '{
    "messages": "写一段关于环保的宣传语，50字以内",
    "model": "gpt-4o",
    "stream": false,
    "temperature": 0.8,  # 中等随机性
    "max_new_tokens": 100  # 限制最大长度
  }'
（2）Python 客户端调用
python 复制代码 
from dbgpt_client import Client

DBGPT_API_KEY = "dbgpt"
client = Client(api_key=DBGPT_API_KEY)

# 非流式调用（带补充参数）
response = client.chat(
    messages="写一段关于环保的宣传语，50字以内",
    model="gpt-4o",
    temperature=0.8,  # 补充温度
    max_new_tokens=100  # 补充最大 tokens
)
print(response)

# 流式调用（带补充参数）
async for chunk in client.chat_stream(
    messages="写一段关于环保的宣传语，50字以内",
    model="gpt-4o",
    temperature=0.8,
    max_new_tokens=100
):
    print(chunk["choices"][0]["delta"]["content"], end="", flush=True)
（3）OpenAI SDK 调用（兼容格式）
python 复制代码 
from openai import OpenAI

client = OpenAI(
    api_key="dbgpt",
    base_url="http://localhost:5670/api/v2"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一段关于环保的宣传语，50字以内"}],
    stream=True,
    temperature=0.8,  # 补充温度
    max_tokens=100,   # 等价于 max_new_tokens（OpenAI 兼容参数）
    extra_body={"chat_mode": "chat_normal"}  # 指定对话模式
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

4. 响应格式

（1）非流式响应（stream: false）
json 复制代码 
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1712345678,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "守护绿水青山，留住蓝天白云，环保无小事，行动在当下。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 25,
    "total_tokens": 40
  }
}
（2）流式响应（stream: true）

分块返回，以 data: [DONE] 结束：

复制代码 
data: {"id": "chatcmpl-xxx", "model": "gpt-4o", "choices": [{"index": 0, "delta": {"content": "守护"}}]}
data: {"id": "chatcmpl-xxx", "model": "gpt-4o", "choices": [{"index": 0, "delta": {"content": "绿水青山，"}}]}
data: [DONE]

三、关键说明

  1. 补充参数的作用：

    • temperature：控制响应随机性（0 接近精确答案，2 更具创造性）；
    • max_new_tokens：限制生成内容长度，避免超出模型上下文限制（如 gpt-4o 通常支持 8192/32768 tokens）。

  2. 参数兼容性：

    • 这两个参数是 DB-GPT 通用对话接口的标准参数，chat.md 中的所有对话场景均支持；
    • OpenAI SDK 调用时，max_tokens 等价于 max_new_tokens（兼容 OpenAI 规范）。

  3. 默认值与限制：

    • 若不指定 temperature，模型使用默认值（通常为 1.0）；
    • max_new_tokens 若超过模型支持的最大长度，会返回参数错误。

chat.md 对外接口：对话ID参数说明 & 并发调用支持

一、对话ID参数（conv_uid）说明

chat.md 中对外核心接口 POST /api/v2/chat/completions 明确支持对话ID参数 ，参数名是 conv_uid（conversation unique ID），具体细节如下：

1. 参数基础信息

参数名 类型 是否必填 核心作用 示例值
conv_uid string 否 唯一标识一组多轮对话，用于关联上下文、区分不同用户/会话的对话流程；接口会基于该ID维护对话上下文 "conv_123456"、"user001_20251127"

2. 调用示例（携带conv_uid）

Curl示例
shell 复制代码 
DBGPT_API_KEY="dbgpt"
curl -X POST "http://localhost:5670/api/v2/chat/completions" \
  -H "Authorization: Bearer $DBGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": "继续分析6MW风机的报价趋势",
    "model": "deepseek-reasoner",
    "chat_mode": "chat_normal",
    "conv_uid": "user001_wind_turbine_2025",  # 对话ID，关联前序对话
    "temperature": 0.3,
    "max_new_tokens": 1024
  }'
Python客户端示例
python 复制代码 
from dbgpt_client import Client

client = Client(api_key="dbgpt")
response = client.chat(
    messages="继续分析6MW风机的报价趋势",
    model="deepseek-reasoner",
    conv_uid="user001_wind_turbine_2025",  # 指定对话ID
    temperature=0.3
)

3. 关键注意事项

  • conv_uid 为可选参数，若不传，接口会自动生成临时ID，但多轮对话时无法关联上下文；
  • 建议在并发场景/多用户场景下强制传入该参数，避免不同会话的上下文混淆；
  • 接口对 conv_uid 无格式限制，只需保证业务侧唯一（如：用户ID+会话时间戳）。

二、并发调用支持

chat.md 文档中未直接提及"并发调用"的显式限制，但结合接口设计逻辑和DB-GPT的底层架构，核心结论如下：

1. 接口层面：天然支持并发调用

  • chat.md 定义的 POST /api/v2/chat/completions 是标准RESTful接口，基于HTTP协议设计，无单例/排他性限制，可同时接收多个客户端的调用请求；
  • 对话ID（conv_uid）的设计本身就是为了适配并发场景------通过唯一ID区分不同并发会话，避免上下文串扰。

2. 实际并发的约束条件

并发调用的能力不取决于接口本身，而取决于以下因素：

约束项 说明
服务端部署配置 如API服务的进程数、线程池大小（如Gunicorn的workers/threads）、容器/虚拟机的资源配额；
模型侧限制 deepseek等模型的推理并发数（模型服务是否支持多请求并行推理，或是否有QPS限制）；
资源瓶颈 服务器CPU/GPU/内存资源不足时，并发调用会导致响应延迟升高，但接口本身不会拒绝请求；

3. 并发调用的最佳实践

  1. 强制传入conv_uid：每个并发会话使用唯一ID，避免不同请求的上下文混淆；
  2. 控制单模型并发数：若调用deepseek模型，需确认模型服务的最大并发推理数（如单GPU卡建议并发数≤8）；
  3. 添加请求超时/重试 ：并发场景下建议设置callTimeout（如300秒），并对超时请求做重试（避免因资源抢占导致的请求失败）；
  4. 流式响应优化 ：并发调用流式响应（stream=true）时，需确保客户端能独立处理每个会话的流式数据，避免数据接收串流。

4. 示例：多并发会话调用（不同conv_uid）

python 复制代码 
import threading
from dbgpt_client import Client

def chat_task(conv_uid, question):
    client = Client(api_key="dbgpt")
    response = client.chat(
        messages=question,
        model="deepseek-reasoner",
        conv_uid=conv_uid,
        stream=False
    )
    print(f"会话{conv_uid}响应：{response}")

# 启动3个并发会话，每个会话用唯一conv_uid
thread1 = threading.Thread(target=chat_task, args=("conv_001", "6MW风机平均报价？"))
thread2 = threading.Thread(target=chat_task, args=("conv_002", "风机轮毂高度趋势？"))
thread3 = threading.Thread(target=chat_task, args=("conv_003", "供应商报价标准差？"))

thread1.start()
thread2.start()
thread3.start()

thread1.join()
thread2.join()
thread3.join()

总结

  1. 对话ID参数：chat.md 接口支持 conv_uid 参数（非必填），用于标识多轮对话，是适配并发的核心参数；
  2. 并发调用：接口本身无并发限制，支持多请求同时调用，实际并发能力取决于服务端部署、模型侧资源和业务侧的ID管理；
  3. 核心建议：并发场景下务必传入唯一conv_uid，并根据服务器/模型的资源情况控制并发数，避免性能瓶颈。
相关推荐
Han.miracle2 小时前
JavaEE--网络编程 http请求 ：URL 方法get 和 post
数据库·sql·计算机网络
好好研究2 小时前
MyBatis框架 - 注解形式
java·数据库·mysql·maven·mybatis
爬山算法2 小时前
Redis（154）Redis的数据一致性如何保证？
数据库·redis·bootstrap
e***0962 小时前
postgresql链接详解
数据库·postgresql
踢球的打工仔2 小时前
mysql数据表的基本操作
数据库·mysql
踢球的打工仔2 小时前
mysql链接(2)
数据库·mysql
专注API从业者2 小时前
构建分布式京东商品数据采集器：基于微服务的架构设计与实现
数据结构·数据库·分布式·微服务·架构
h***01542 小时前
MySQL数据库的数据文件保存在哪？MySQL数据存在哪里
数据库·mysql
k***21602 小时前
MySQL 批量插入详解：快速提升大数据导入效率的实战方法
大数据·数据库·mysql
热门推荐
01GitHub 镜像站点02BongoCat - 跨平台键盘猫动画工具03UV安装并设置国内源04Linux下V2Ray安装配置指南05安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）06【保姆级教程】免费使用Gemini3的5种方法！免翻墙/国内直连0746个Nano-banana 精选提示词，持续更新中08本地部署阿里最新开源的Z-Image09Meta第三代“分割一切”模型——SAM 3本地部署教程：首支持文本提示分割，400万概念、30毫秒响应，检测分割追踪一网打尽10在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）