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

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

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：

    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 客户端：

    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：

    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)
    

• 响应示例（非流式）：

  {
      "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：

    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 客户端：

    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：

    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 客户端：

    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：

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

  • 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 调用

• 流式响应示例：

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）：

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 客户端调用

• 流式响应示例：

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)

• 非流式响应示例：

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 接口规范）

仅支持流式响应，示例：

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]，示例：

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 结构，示例：

{
    "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 调用

  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 客户端调用

  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 调用

  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)
  

• 响应示例（非流式）：

  {
      "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）：

  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 客户端）：

  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）

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 客户端调用

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 调用（兼容格式）

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）

{
  "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示例

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客户端示例

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）

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，并根据服务器/模型的资源情况控制并发数，避免性能瓶颈。