how-to-guide

How to Use the DB‑GPT API to Integrate Chat Functionality into External Applications

February 23, 2026 eosphoros-ai/db-gpt ↗

DB‑GPT exposes an OpenAI‑compatible HTTP API at /api/v2/chat/completions that you can call using the official dbgpt_client Python SDK or raw HTTP requests, supporting both synchronous responses and streaming Server‑Sent Events.

The eosphoros-ai/DB‑GPT repository provides a production‑ready chat API that allows external applications to leverage its LLM capabilities, including RAG, SQL execution, and AWEL flows. By implementing an OpenAI‑compatible endpoint, DB‑GPT enables seamless integration with existing AI tooling and custom client implementations without requiring proprietary protocols.

Architecture of the DB‑GPT Chat API

Understanding the request flow helps debug integration issues and optimize performance. The architecture consists of five distinct layers:

Installing the DB‑GPT Python Client

To use the SDK, install the dbgpt-client package from the DB‑GPT repository:

pip install dbgpt-client

The client defaults to http://localhost:5670/api/v2 but can be configured via the DBGPT_API_BASE environment variable or constructor arguments.

Sending Chat Requests with the Python SDK

The Client class provides both synchronous‑style (async) and streaming interfaces for chat completions.

Non‑Streaming Chat Requests

For simple request‑response interactions, use the chat method which returns a complete ChatCompletionResponse:

from dbgpt_client import Client

client = Client(
    api_base="http://localhost:5670/api/v2",
    api_key="your-dbgpt-api-key"  # Optional: only if server requires auth

)

response = await client.chat(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello, DB‑GPT!"}],
    temperature=0.7,
    chat_mode="chat_normal"
)

print(response.choices[0].message.content)

The chat_mode parameter defaults to "chat_normal" but supports other modes for specialized functionality.

Streaming Responses for Real‑Time UIs

For applications that require incremental output (like chat UIs), use chat_stream which yields Server‑Sent Events:

async for chunk in client.chat_stream(
    model="gpt-4",
    messages="Explain quantum computing in one sentence.",
    stream=True
):
    # Each chunk is a ChatCompletionStreamResponse

    print(chunk.choices[0].delta.content, end="", flush=True)

This method handles the SSE parsing automatically, providing typed ChatCompletionStreamResponse objects for each token chunk.

Using Different Chat Modes (RAG, AWEL Flows, and Data Analysis)

DB‑GPT extends standard chat completion with chat modes that trigger specific pipelines:

  • chat_normal: Standard conversational AI without external data sources.
  • chat_knowledge: Enables RAG (Retrieval‑Augmented Generation) against configured knowledge bases.
  • chat_flow: Triggers an AWEL (Agentic Workflow Expression Language) flow.
  • chat_data: Executes SQL queries against connected databases.

Specify the mode in the request:

response = await client.chat(
    model="gpt-4",
    messages="What are the main challenges of LLM‑based RAG?",
    chat_mode="chat_knowledge",  # Enables vector store retrieval

    temperature=0.6
)

Integrating via Raw HTTP Requests

If you cannot use the Python SDK, send raw HTTP POST requests to the /chat/completions endpoint. The API accepts standard JSON payloads and returns OpenAI‑compatible responses.

curl -X POST http://localhost:5670/api/v2/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-dbgpt-api-key" \
  -d '{
        "model": "gpt-4",
        "messages": [{"role":"user","content":"What is the capital of France?"}],
        "temperature": 0.5,
        "chat_mode": "chat_normal",
        "stream": false
      }'

For streaming, set "stream": true and process the Server‑Sent Events returned by the server. Use tools like curl --no-buffer -N or HTTP libraries with SSE support to handle the incremental response chunks.

Authentication and API Security

When the DB‑GPT server is configured with api_keys (set via the DBGPT_API_KEYS environment variable), all requests must include an Authorization header:

  • Header format: Authorization: Bearer <your-api-key>
  • Client handling: The dbgpt_client.Client automatically injects this header when initialized with an api_key parameter.
  • Server validation: The check_api_key dependency in api_v2.py validates tokens against the server’s configured key store.

If the server runs without API key configuration, requests proceed without authentication headers.

Complete Integration Examples

Basic Q&A Implementation

This example demonstrates a minimal async script for simple question‑answering:

import asyncio
from dbgpt_client import Client

async def main():
    client = Client()  # Uses DBGPT_API_BASE from environment

    reply = await client.chat(
        model="gpt-4o-mini",
        messages="Summarize the plot of *The Matrix* in 2 sentences.",
        temperature=0.3
    )
    print(reply.choices[0].message.content)

asyncio.run(main())

Knowledge‑Augmented Retrieval (RAG)

To query documents stored in DB‑GPT’s vector stores:

import asyncio
from dbgpt_client import Client

async def rag_query():
    client = Client()
    resp = await client.chat(
        model="gpt-4o-mini",
        messages="What are the main challenges of LLM‑based RAG?",
        chat_mode="chat_knowledge",
        temperature=0.6
    )
    print(resp.choices[0].message.content)

asyncio.run(rag_query())

The chat_mode="chat_knowledge" setting activates the RAG pipeline defined in the BaseChat implementation within the dbgpt_app/scene module.

Building a Proxy API with FastAPI

You can wrap DB‑GPT’s client in your own FastAPI application to add business logic or rate limiting:

from fastapi import FastAPI
from dbgpt_client import Client

app = FastAPI()
client = Client()

@app.post("/proxy/chat")
async def proxy_chat(messages: str):
    async for chunk in client.chat_stream(
        model="gpt-4o-mini",
        messages=messages,
        stream=True
    ):
        # Forward SSE chunks to the caller

        yield f"data: {chunk.json()}\n\n"

This pattern allows you to expose DB‑GPT capabilities through your own API contract while leveraging the underlying streaming infrastructure.

Summary

  • DB‑GPT provides an OpenAI‑compatible API at /api/v2/chat/completions defined in packages/dbgpt-app/src/dbgpt_app/openapi/api_v2.py.
  • Use the dbgpt_client Python SDK for type‑safe, async interactions instead of raw HTTP.
  • Support for multiple chat modes (chat_normal, chat_knowledge, chat_flow, chat_data) enables RAG, SQL execution, and workflow automation through the same endpoint.
  • Streaming is implemented via Server‑Sent Events using the chat_stream method or by setting stream: true in HTTP requests.
  • Authentication uses standard Bearer tokens validated by the check_api_key dependency when DBGPT_API_KEYS is configured.
  • Key source files include client.py for the SDK, schema.py for request models, and api_v2.py for the FastAPI router implementation.

Frequently Asked Questions

Is the DB‑GPT API compatible with OpenAI's API format?

Yes, DB‑GPT implements an OpenAI‑compatible Chat Completions interface. The ChatCompletionRequestBody model in packages/dbgpt-client/src/dbgpt_client/schema.py mirrors OpenAI’s request schema, allowing you to use standard OpenAI client libraries by simply changing the base_url to your DB‑GPT instance (e.g., http://localhost:5670/api/v2).

What are the available chat modes in DB‑GPT?

DB‑GPT supports several chat modes controlled by the chat_mode parameter: chat_normal for standard conversation, chat_knowledge for RAG‑augmented responses using vector stores, chat_flow for executing AWEL agentic workflows, and chat_data for SQL generation and database querying. These modes are processed by corresponding BaseChat subclasses in the dbgpt_app/scene directory.

How do I handle streaming responses in my application?

For streaming, set stream=True in your request and use the chat_stream method in the Python SDK, which yields ChatCompletionStreamResponse objects. If using raw HTTP, consume the response as Server‑Sent Events (SSE) from the /chat/completions endpoint. The SDK handles SSE parsing automatically, while raw implementations must parse the event stream format.

Where is the chat completion endpoint defined in the source code?

The main chat completion endpoint is defined in packages/dbgpt-app/src/dbgpt_app/openapi/api_v2.py within the chat_completions function (lines 71‑100). This FastAPI route handles request validation via the check_api_key dependency, instantiates the appropriate BaseChat implementation based on chat_mode, and returns either JSON or a StreamingResponse for SSE streams.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →