# Technical Documentation: eosphoros-ai/DB-GPT
> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/eosphoros-ai/DB-GPT)
### Overview (README.md)
# 
DB-GPT: Open-Source Agentic AI Data Assistant
> **An open-source AI data assistant that connects to your data, writes SQL and code, runs skills in sandboxed environments, and turns analysis into reports, insights, and action.**
## What is DB-GPT?
DB-GPT is an open-source **agentic AI data assistant** for the next generation of **AI + Data** products.
It helps users and teams:
- connect to **databases, CSV / Excel files, warehouses, and knowledge bases**
- ask questions in natural language and let AI **write SQL autonomously**
- run **Python- and code-driven analysis** workflows
- load and execute reusable **skills** for domain-specific tasks
- generate **charts, dashboards, HTML reports, and analysis summaries**
- execute tasks safely in **sandboxed environments**
DB-GPT is also a platform for building **AI-native data agents, workflows, and applications** with agents, AWEL, RAG, and multi-model support.
## Why DB-GPT?
### 1. Agentic data analysis
Plan tasks, break work into steps, call tools, and complete analysis workflows end to end.
### 2. Autonomous SQL + code execution
Generate SQL and code to query data, clean datasets, compute metrics, and produce outputs.
### 3. Multi-source data access
Work across structured and unstructured sources, including databases, spreadsheets, documents, and knowledge bases.
### 4. Skills-driven extensibility
Package domain knowledge, analysis methods, and execution workflows into reusable skills.
### 5. Sandboxed execution
Run code and tools in isolated environments for safer, more reliable analysis.
## What you can do with DB-GPT
- **Analyze CSV / Excel files** and generate visual reports
- **Connect to databases** and produce profiling reports
- Ask business questions in natural language and let AI **write SQL automatically**
- Perform **financial report analysis** with code, charts, and narrative summaries
- Create and reuse **SQL analysis skills** and domain workflows
- Combine **code, SQL, retrieval, and tools** in a single agentic workflow
- Build next-generation **AI + Data assistants** for your team or product
## Product Workflow
### Explore data
Connect files, databases, and knowledge bases in one workspace.
### Plan and execute
Let AI reason through the task, write SQL and code, and execute step by step.
### Use skills
Load reusable skills for repeatable business analysis workflows.
### Generate reports
Produce charts, dashboards, HTML reports, and decision-ready outputs.
## Quick Start
Get DB-GPT running in minutes with the one-line installer (macOS & Linux):
```bash
curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh | bash
```
Or specify a profile and API key directly:
```bash
curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh \
| OPENAI_API_KEY=sk-xxx bash -s -- --profile openai
```
For Kimi 2.5 via Moonshot API:
```bash
curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh \
| MOONSHOT_API_KEY=sk-xxx bash -s -- --profile kimi
```
For MiniMax via the OpenAI-compatible API:
```bash
curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh \
| MINIMAX_API_KEY=sk-xxx bash -s -- --profile minimax
```
Already have a local DB-GPT checkout? Reuse it instead of cloning `~/.dbgpt/DB-GPT`:
```bash
OPENAI_API_KEY=sk-xxx \
bash scripts/install/install.sh --profile openai --repo-dir "$(pwd)" --yes
```
Or reuse your local repo with Kimi 2.5:
```bash
MOONSHOT_API_KEY=sk-xxx \
bash scripts/install/install.sh --profile kimi --repo-dir "$(pwd)" --yes
```
Or reuse your local repo with MiniMax:
```bash
MINIMAX_API_KEY=sk-xxx \
bash scripts/install/install.sh --profile minimax --repo-dir "$(pwd)" --yes
```
After installation, start the server with the generated profile config:
```bash
cd ~/.dbgpt/DB-GPT && uv run dbgpt start webserver --profile
```
Then open [http://localhost:5670](http://localhost:5670).
> **Prefer to review the script first?**
> ```bash
> curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh -o install.sh
> less install.sh
> bash install.sh --profile openai
> ```
### Install via PyPI
Install DB-GPT from PyPI and start it with a single command — no source checkout required.
> **Prerequisites:** Python **3.10+** and [uv](https://docs.astral.sh/uv/getting-started/installation/) (recommended) or pip.
**1. Install**
```bash
# Recommended: use uv
uv pip install dbgpt-app
# Or with pip
pip install dbgpt-app
```
The default installation includes the core framework (CLI, FastAPI, Agent), OpenAI-compatible LLM support, DashScope / Tongyi support, RAG document parsing, and ChromaDB vector store.
**2. Start**
```bash
dbgpt start
```
On first run, an interactive setup wizard will guide you through choosing an LLM provider and entering your API key. Once complete, the web server starts automatically.
**3. Open the Web UI**
Visit [http://localhost:5670](http://localhost:5670) — you're all set! 🎉
### Advanced Installation
For Docker, local GPU models (vLLM, llama.cpp), or manual source-code setup, see the full docs:
- [**Install**](http://docs.dbgpt.cn/docs/installation)
- [Docker](http://docs.dbgpt.cn/docs/installation/docker)
- [Source Code](http://docs.dbgpt.cn/docs/getting-started/deploy/source-code)
- [**Quickstart**](http://docs.dbgpt.cn/docs/overview)
- [**Application**](http://docs.dbgpt.cn/docs/use_cases)
- [Development Guide](http://docs.dbgpt.cn/docs/cookbook/app/data_analysis_app_develop)
- [AWEL Flow Usage](http://docs.dbgpt.cn/docs/application/awel_flow_usage)
- [**Debugging**](http://docs.dbgpt.cn/docs/operation_manual/advanced_tutorial/debugging)
- [**Advanced Usage**](http://docs.dbgpt.cn/docs/application/advanced_tutorial/cli)
- [SMMF](http://docs.dbgpt.cn/docs/application/advanced_tutorial/smmf)
- [Finetune](http://docs.dbgpt.cn/docs/application/fine_tuning_manual/dbgpt_hub)
- [AWEL](http://docs.dbgpt.cn/docs/awel/tutorial)
## Core Capabilities
### Agentic Analysis
- task planning
- step-by-step execution
- tool use
- iterative reasoning
### SQL + Code Execution
- natural language to SQL
- Python-based analysis and transformation
- metric calculation
- chart generation
### Multi-Source Data Access
- relational databases
- CSV / Excel
- documents
- knowledge bases
- mixed-source workflows
### Skills and Agents
- reusable skills
- domain workflows
- agent orchestration
- customizable execution flows
### Reporting and Decision Support
- database profiling reports
- financial analysis reports
- visual reports and dashboards
- summaries and business insights
### Safe Execution
- sandboxed code execution
- controlled tool use
- reproducible outputs and artifacts
#### Text2SQL Finetune
| LLM | Supported |
|:-----------:|:-----------:|
| LLaMA | ✅ |
| LLaMA-2 | ✅ |
| BLOOM | ✅ |
| BLOOMZ | ✅ |
| Falcon | ✅ |
| Baichuan | ✅ |
| Baichuan2 | ✅ |
| InternLM | ✅ |
| Qwen | ✅ |
| XVERSE | ✅ |
| ChatGLM2 | ✅ |
[More Information about Text2SQL finetune](https://github.com/eosphoros-ai/DB-GPT-Hub)
### Supported Models
- [More Supported LLMs](http://docs.dbgpt.cn/docs/modules/smmf)
### Privacy and Security
We protect data privacy and execution safety through private model deployment, proxy desensitization, and sandboxed execution mechanisms.
### Data Sources
- [Datasources](http://docs.dbgpt.cn/docs/modules/connections)
## Vision
We believe the future of data products goes beyond dashboards.
The next generation of **AI + Data** products will be:
- **agentic**
- **multi-source**
- **skill-driven**
- **sandboxed**
- capable of writing **SQL and code**
- able to turn analysis into **reports, decisions, and action**
DB-GPT aims to help developers and enterprises build that future.
## Contribution
- To check detailed guidelines for new contributions, please refer [how to contribute](https://github.com/eosphoros-ai/DB-GPT/blob/main/CONTRIBUTING.md)
### Contributors Wall
## Licence
The MIT License (MIT)
## DISCKAIMER
- [disckaimer](./DISCKAIMER.md)
## Citation
If you want to understand the overall architecture of DB-GPT, please cite Paper and Paper
If you want to learn about using DB-GPT for Agent development, please cite the Paper
```
/* Detailed source-code truncated for AI context efficiency. */
```
## Contact Information
Thanks to everyone who has contributed to DB-GPT! Your ideas, code, comments, and even sharing them at events and on social platforms can make DB-GPT better.
We are working on building a community, if you have any ideas for building the community, feel free to contact us.
- [Github Issues](https://github.com/eosphoros-ai/DB-GPT/issues) ⭐️：For questions about using GB-DPT, see the CONTRIBUTING.
- [Github Discussions](https://github.com/orgs/eosphoros-ai/discussions) ⭐️：Share your experience or unique apps.
- [Twitter](https://x.com/DBGPT_AI) ⭐️：Please feel free to talk to us.
[](https://star-history.com/#csunny/DB-GPT)
---
### README (`docs/README.md`)
# DB-GPT documentation
## Quick Start
### Install dependencies
- Clone current project firstly!
- Install docusaurus dependencies, generate node_modules folder.
```
yarn install
```
### launch
```
yarn start
```
The default service starts on port `3000`, visit `localhost:3000`
## Deploy Multi-Version Documentation
We can deploy multiple versions of the documentation by docker.
### Build Docker Image
Firstly, build the docker image in `DB-GPT` project root directory.
```bash
# Use the default NPM_REGISTRY=https://registry.npmjs.org
# Use https://www.npmmirror.com/
NPM_REGISTRY=https://registry.npmmirror.com
docker build -f docs/Dockerfile-deploy \
-t eosphorosai/dbgpt-docs \
--build-arg NPM_REGISTRY=$NPM_REGISTRY \
--build-arg CI=false \
--build-arg NUM_VERSION=2 .
```
### Run Docker Container
Run the docker container with the following command:
```bash
docker run -it --rm -p 8089:8089 \
--name my-dbgpt-docs \
-v $(pwd)/docs/nginx/nginx-docs.conf:/etc/nginx/nginx.conf \
eosphorosai/dbgpt-docs
```
Open the browser and visit `localhost:8089` to see the documentation.
---
### Docs Overview (`docs/docs/overview.mdx`)
---
sidebar_position: 0
title: DB-GPT
---
import CommandCopyCard from "@site/src/components/mdx/CommandCopyCard";
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
# DB-GPT
An open-source AI data assistant that connects to your data, writes SQL and code, runs skills in sandboxed environments, and turns analysis into reports, insights, and action.
DB-GPT is also a platform for building AI-native data agents, workflows, and applications with agents, AWEL, RAG, and multi-model support.
## Quick start
One-line installer for macOS & Linux — downloads, configures, and sets up DB-GPT automatically.
Install with pip and start in seconds — the fastest way to try DB-GPT on any platform.
1
Install the package
🌏
Users in China region can use a mirror for faster downloads:
## What is DB-GPT?
DB-GPT is an open-source **agentic AI data assistant** for the next generation of **AI + Data** products.
It helps users and teams:
- connect to **databases, CSV / Excel files, warehouses, and knowledge bases**
- ask questions in natural language and let AI **write SQL autonomously**
- run **Python- and code-driven analysis** workflows
- load and execute reusable **skills** for domain-specific tasks
- generate **charts, dashboards, HTML reports, and analysis summaries**
- execute tasks safely in **sandboxed environments**
## Why DB-GPT?
🧠
Agentic data analysis
Plan tasks, break work into steps, call tools, and complete analysis workflows end to end.
💻
Autonomous SQL + code execution
Generate SQL and code to query data, clean datasets, compute metrics, and produce outputs.
🗂️
Multi-source data access
Work across structured and unstructured sources, including databases, spreadsheets, documents, and knowledge bases.
🧩
Skills-driven extensibility
Package domain knowledge, analysis methods, and execution workflows into reusable skills.
📈
Reporting and decision support
Produce charts, dashboards, HTML reports, and decision-ready business outputs.
🛡️
Sandboxed execution
Run code and tools in isolated environments for safer, more reliable analysis.
## Product workflow
🔍
Explore data
Connect files, databases, and knowledge bases in one workspace.
🪄
Plan and execute
Let AI reason through the task, write SQL and code, and execute step by step.
🧰
Use skills
Load reusable skills for repeatable business analysis workflows.
📄
Generate reports
Produce charts, dashboards, HTML reports, and decision-ready outputs.
## Core capabilities
🤖
Agentic Analysis
Task planning, step-by-step execution, tool use, and iterative reasoning.
🧮
SQL + Code Execution
Natural language to SQL, Python-based analysis, metric calculation, and chart generation.
🗃️
Multi-Source Data Access
Relational databases, CSV / Excel, documents, knowledge bases, and mixed-source workflows.
🧠
Skills and Agents
Reusable skills, domain workflows, agent orchestration, and customizable execution flows.
📊
Reporting
Database profiling reports, financial analysis reports, dashboards, summaries, and insights.
🔐
Safe Execution
Sandboxed code execution, controlled tool use, and reproducible outputs and artifacts.
## Platform & ecosystem
## Terminology
| Term | Description |
|------|-------------|
| **DB-GPT** | DataBase Generative Pre-trained Transformer — open-source framework around databases and LLMs |
| **Data App** | An intelligent data application built on DB-GPT |
| **Text2SQL** | Generate SQL from natural language using LLM capabilities |
| **KBQA** | Knowledge-Based Q&A system |
| **GBI** | Generative Business Intelligence — analysis and decisions through dialogue |
| **LLMOps** | End-to-end workflow for training, tuning, deploying, and monitoring LLMs |
| **Embedding** | Methods to convert text, audio, video into vectors |
| **RAG** | Retrieval Augmented Generation |
| **AWEL** | Agentic Workflow Expression Language |
| **AWEL Flow** | Workflow orchestration using AWEL |
| **SMMF** | Service-oriented Multi-model Management Framework |
## Community
If you encounter problems, submit an [issue](https://github.com/eosphoros-ai/DB-GPT/issues), join [discussions](https://github.com/orgs/eosphoros-ai/discussions), or check the [releases](https://github.com/eosphoros-ai/DB-GPT/releases).
---
### Docs Quickstart (`docs/docs/quickstart.md`)
---
sidebar_position: 0
---
# Quickstart
DB-GPT supports the installation and use of various open-source and closed-source models. Different models have different requirements for environment and resources. If local model deployment is required, GPU resources are necessary. The API proxy model requires relatively few resources and can be deployed and started on a CPU machine.
:::info note
- Detailed installation and deployment tutorials can be found in [Installation](./installation).
- This page only introduces deployment based on ChatGPT proxy and local GLM model.
:::
## Environment Preparation
### Download Source Code
:::tip
Download DB-GPT
:::
```bash
git clone https://github.com/eosphoros-ai/DB-GPT.git
```
### Environment Setup
- The default database uses SQLite, so there is no need to install a database in the
default startup mode. If you need to use other databases, please refer to the [advanced tutorials](./application/advanced_tutorial/rag.md) below.
Starting from version 0.7.0, DB-GPT uses uv for environment and package management, providing faster and more stable dependency management.
:::info note
There are some ways to install uv:
:::
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Install uv using pipx.
```bash
python -m pip install --upgrade pip
python -m pip install --upgrade pipx
python -m pipx ensurepath
pipx install uv --global
```
You can see more installation methods on the [uv installation](https://docs.astral.sh/uv/getting-started/installation/)
Then, you can run `uv --version` to check if uv is installed successfully.
```bash
uv --version
```
## Deploy DB-GPT
:::tip
If you are in the China region, you can add --index-url=https://pypi.tuna.tsinghua.edu.cn/simple at the end of the command.Like this:
```bash
uv sync --all-packages \
--extra "base" \
--extra "proxy_openai" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "dbgpts" \
--index-url=https://pypi.tuna.tsinghua.edu.cn/simple
```
And we recommend you to configure you pypi index to environment variable `UV_INDEX_URL`
example:
```bash
echo "export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple" >> ~/.bashrc
```
This tutorial assumes that you can establish network communication with the dependency download sources.
:::
### Install Dependencies
```bash
# Use uv to install dependencies needed for OpenAI proxy
uv sync --all-packages \
--extra "base" \
--extra "proxy_openai" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "dbgpts"
```
### Run Webserver
To run DB-GPT with OpenAI proxy, you must provide the OpenAI API key in the `configs/dbgpt-proxy-openai.toml` configuration file or provide it in the environment variable with key `OPENAI_API_KEY`.
```toml
# Model Configurations
[models]
[[models.llms]]
...
api_key = "your-openai-api-key"
[[models.embeddings]]
...
api_key = "your-openai-api-key"
```
Then run the following command to start the webserver:
```bash
uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml
```
In the above command, `--config` specifies the configuration file, and `configs/dbgpt-proxy-openai.toml` is the configuration file for the OpenAI proxy model, you can also use other configuration files or create your own configuration file according to your needs.
Optionally, you can also use the following command to start the webserver:
```bash
uv run python packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py --config configs/dbgpt-proxy-openai.toml
```
```bash
# Use uv to install dependencies needed for OpenAI proxy
uv sync --all-packages \
--extra "base" \
--extra "proxy_openai" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "dbgpts"
```
### Run Webserver
To run DB-GPT with DeepSeek proxy, you must provide the DeepSeek API key in the `configs/dbgpt-proxy-deepseek.toml`.
And you can specify your embedding model in the `configs/dbgpt-proxy-deepseek.toml` configuration file, the default embedding model is `BAAI/bge-large-zh-v1.5`. If you want to use other embedding models, you can modify the `configs/dbgpt-proxy-deepseek.toml` configuration file and specify the `name` and `provider` of the embedding model in the `[[models.embeddings]]` section. The provider can be `hf`.Finally, you need to append `--extra "hf"` at the end of the dependency installation command. Here's the updated command:
```bash
uv sync --all-packages \
--extra "base" \
--extra "proxy_openai" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "dbgpts" \
--extra "hf" \
--extra "cpu"
```
**Model Configurations**:
```toml
# Model Configurations
[models]
[[models.llms]]
# name = "deepseek-chat"
name = "deepseek-reasoner"
provider = "proxy/deepseek"
api_key = "your-deepseek-api-key"
[[models.embeddings]]
name = "BAAI/bge-large-zh-v1.5"
provider = "hf"
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# path = "the-model-path-in-the-local-file-system"
path = "/data/models/bge-large-zh-v1.5"
```
Then run the following command to start the webserver:
```bash
uv run dbgpt start webserver --config configs/dbgpt-proxy-deepseek.toml
```
In the above command, `--config` specifies the configuration file, and `configs/dbgpt-proxy-deepseek.toml` is the configuration file for the DeepSeek proxy model, you can also use other configuration files or create your own configuration file according to your needs.
Optionally, you can also use the following command to start the webserver:
```bash
uv run python packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py --config configs/dbgpt-proxy-deepseek.toml
```
```bash
# Use uv to install dependencies needed for GLM4
# Install core dependencies and select desired extensions
uv sync --all-packages \
--extra "base" \
--extra "cuda121" \
--extra "hf" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "quant_bnb" \
--extra "dbgpts"
```
### Run Webserver
To run DB-GPT with the local model. You can modify the `configs/dbgpt-local-glm.toml` configuration file to specify the model path and other parameters.
```toml
# Model Configurations
[models]
[[models.llms]]
name = "THUDM/glm-4-9b-chat-hf"
provider = "hf"
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# path = "the-model-path-in-the-local-file-system"
[[models.embeddings]]
name = "BAAI/bge-large-zh-v1.5"
provider = "hf"
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# path = "the-model-path-in-the-local-file-system"
```
In the above configuration file, `[[models.llms]]` specifies the LLM model, and `[[models.embeddings]]` specifies the embedding model. If you not provide the `path` parameter, the model will be downloaded from the Hugging Face model hub according to the `name` parameter.
Then run the following command to start the webserver:
```bash
uv run dbgpt start webserver --config configs/dbgpt-local-glm.toml
```
```bash
# Use uv to install dependencies needed for vllm
# Install core dependencies and select desired extensions
uv sync --all-packages \
--extra "base" \
--extra "hf" \
--extra "cuda121" \
--extra "vllm" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "quant_bnb" \
--extra "dbgpts"
```
### Run Webserver
To run DB-GPT with the local model. You can modify the `configs/dbgpt-local-vllm.toml` configuration file to specify the model path and other parameters.
```toml
# Model Configurations
[models]
[[models.llms]]
name = "THUDM/glm-4-9b-chat-hf"
provider = "vllm"
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# path = "the-model-path-in-the-local-file-system"
[[models.embeddings]]
name = "BAAI/bge-large-zh-v1.5"
provider = "hf"
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# path = "the-model-path-in-the-local-file-system"
```
In the above configuration file, `[[models.llms]]` specifies the LLM model, and `[[models.embeddings]]` specifies the embedding model. If you not provide the `path` parameter, the model will be downloaded from the Hugging Face model hub according to the `name` parameter.
Then run the following command to start the webserver:
```bash
uv run dbgpt start webserver --config configs/dbgpt-local-vllm.toml
```
If you has a Nvidia GPU, you can enable the CUDA support by setting the environment variable `CMAKE_ARGS="-DGGML_CUDA=ON"`.
```bash
# Use uv to install dependencies needed for llama-cpp
# Install core dependencies and select desired extensions
CMAKE_ARGS="-DGGML_CUDA=ON" uv sync --all-packages \
--extra "base" \
--extra "hf" \
--extra "cuda121" \
--extra "llama_cpp" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "quant_bnb" \
--extra "dbgpts"
```
Otherwise, run the following command to install dependencies without CUDA support.
```bash
# Use uv to install dependencies needed for llama-cpp
# Install core dependencies and select desired extensions
uv sync --all-packages \
--extra "base" \
--extra "hf" \
--extra "llama_cpp" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "quant_bnb" \
--extra "dbgpts"
```
### Run Webserver
To run DB-GPT with the local model. You can modify the `configs/dbgpt-local-llama-cpp.toml` configuration file to specify the model path and other parameters.
```toml
# Model Configurations
[models]
[[models.llms]]
name = "DeepSeek-R1-Distill-Qwen-1.5B"
provider = "llama.cpp"
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# path = "the-model-path-in-the-local-file-system"
[[models.embeddings]]
name = "BAAI/bge-large-zh-v1.5"
provider = "hf"
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# path = "the-model-path-in-the-local-file-system"
```
In the above configuration file, `[[models.llms]]` specifies the LLM model, and `[[models.embeddings]]` specifies the embedding model. If you not provide the `path` parameter, the model will be downloaded from the Hugging Face model hub according to the `name` parameter.
Then run the following command to start the webserver:
```bash
uv run dbgpt start webserver --config configs/dbgpt-local-llama-cpp.toml
```
```bash
# Use uv to install dependencies needed for Ollama proxy
uv sync --all-packages \
--extra "base" \
--extra "proxy_ollama" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "dbgpts"
```
### Run Webserver
To run DB-GPT with Ollama proxy, you must provide the Ollama API base in the `configs/dbgpt-proxy-ollama.toml` configuration file.
```toml
# Model Configurations
[models]
[[models.llms]]
...
api_base = "your-ollama-api-base"
[[models.embeddings]]
...
api_base = "your-ollama-api-base"
```
Then run the following command to start the webserver:
```bash
uv run dbgpt start webserver --config configs/dbgpt-proxy-ollama.toml
```
In the above command, `--config` specifies the configuration file, and `configs/dbgpt-proxy-ollama.toml` is the configuration file for the Ollama proxy model, you can also use other configuration files or create your own configuration file according to your needs.
Optionally, you can also use the following command to start the webserver:
```bash
uv run python packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py --config configs/dbgpt-proxy-ollama.toml
```
## (Optional) More Configuration
You can view the configuration in [Configuration](./config/config-reference) to learn more about
the configuration options.
For example, if you want to configure the LLM model, you can see all available options in the [LLM Configuration](./config-reference/llm/).
And another example, if you want to how to configure the vllm model, you can see all available options in the [VLLM Configuration](./config-reference/llm/vllm_adapter_vllmdeploymodelparameters_1d4a24.mdx).
## DB-GPT Install Help Tool
If you need help with the installation, you can use the `uv` script to get help.
```bash
uv run install_help.py --help
```
## Generate Install Command
You can use the `uv` script to generate the install command in the interactive mode.
```bash
uv run install_help.py install-cmd --interactive
```
And you can generate an install command with all the dependencies needed for the OpenAI proxy model.
```bash
uv run install_help.py install-cmd --all
```
You can found all the dependencies and extras.
```bash
uv run install_help.py list
```
## Visit Website
Open your browser and visit [`http://localhost:5670`](http://localhost:5670)
### (Optional) Run Web Front-end Separately
You can also run the web front-end separately:
```bash
cd web && npm install
cp .env.template .env
// Set API_BASE_URL to your DB-GPT server address, usually http://localhost:5670
npm run dev
```
Open your browser and visit [`http://localhost:3000`](http://localhost:3000)
---
### Docs Config Reference Overview (`docs/docs/config-reference/overview.mdx`)
---
title: "Configuration Overview"
---
# Configuration Overview
This document provides an overview of all configuration classes organized by type.
## Configuration Types
- [app](#type-app) (6 classes)
- [datasource](#type-datasource) (18 classes)
- [embedding](#type-embedding) (8 classes)
- [graph_store](#type-graph_store) (3 classes)
- [llm](#type-llm) (28 classes)
- [memory](#type-memory) (2 classes)
- [other](#type-other) (1 classes)
- [reranker](#type-reranker) (6 classes)
- [serve](#type-serve) (13 classes)
- [service](#type-service) (1 classes)
- [utils](#type-utils) (2 classes)
- [vector_store](#type-vector_store) (7 classes)
## Type Details
### app {#type-app}
This type contains 6 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [ChatDashboardConfig](app/config_chatdashboardconfig_2480d0) | |
| [ChatExcelConfig](app/config_chatexcelconfig_8dcf86) | |
| [ChatKnowledgeConfig](app/config_chatknowledgeconfig_d51d9e) | |
| [ChatNormalConfig](app/config_chatnormalconfig_83c865) | |
| [ChatWithDBExecuteConfig](app/config_chatwithdbexecuteconfig_64fe0f) | |
| [ChatWithDBQAConfig](app/config_chatwithdbqaconfig_62cbe4) | |
---
### datasource {#type-datasource}
This type contains 18 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [ClickhouseParameters](datasource/conn_clickhouse_clickhouseparameters_4a1237) | |
| [DorisParameters](datasource/conn_doris_dorisparameters_e33c53) | |
| [DuckDbConnectorParameters](datasource/conn_duckdb_duckdbconnectorparameters_c672c7) | |
| [GaussDBParameters](datasource/conn_gaussdb_gaussdbparameters_9c9811) | |
| [HiveParameters](datasource/conn_hive_hiveparameters_ec3601) | |
| [MSSQLParameters](datasource/conn_mssql_mssqlparameters_d79d1c) | |
| [MySQLParameters](datasource/conn_mysql_mysqlparameters_4393c4) | |
| [Neo4jParameters](datasource/conn_neo4j_neo4jparameters_041b12) | |
| [OceanBaseParameters](datasource/conn_oceanbase_oceanbaseparameters_260d2d) | |
| [OracleParameters](datasource/conn_oracle_oracleparameters_c011ed) | |
| [PostgreSQLParameters](datasource/conn_postgresql_postgresqlparameters_22efa5) | |
| [RDBMSDatasourceParameters](datasource/base_rdbmsdatasourceparameters_4f774f) | |
| [SQLiteConnectorParameters](datasource/conn_sqlite_sqliteconnectorparameters_82c8b5) | |
| [SparkParameters](datasource/conn_spark_sparkparameters_174bbc) | |
| [StarRocksParameters](datasource/conn_starrocks_starrocksparameters_e511f7) | |
| [TuGraphParameters](datasource/conn_tugraph_tugraphparameters_0c844e) | |
| [VerticaParameters](datasource/conn_vertica_verticaparameters_c712b8) | |
| [openGaussParameters](datasource/conn_opengauss_opengaussparameters_85409c) | |
---
### embedding {#type-embedding}
This type contains 8 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [AimlapiEmbeddingDeployModelParameters](embedding/aimlapi_aimlapiembeddingdeploymodelparameters_97d1c4) | |
| [HFEmbeddingDeployModelParameters](embedding/embeddings_hfembeddingdeploymodelparameters_f588e1) | |
| [JinaEmbeddingsDeployModelParameters](embedding/jina_jinaembeddingsdeploymodelparameters_40b0f2) | |
| [OllamaEmbeddingDeployModelParameters](embedding/ollama_ollamaembeddingdeploymodelparameters_b511e0) | |
| [OpenAPIEmbeddingDeployModelParameters](embedding/embeddings_openapiembeddingdeploymodelparameters_f9ba47) | |
| [QianfanEmbeddingDeployModelParameters](embedding/qianfan_qianfanembeddingdeploymodelparameters_257d2a) | |
| [SiliconFlowEmbeddingDeployModelParameters](embedding/siliconflow_siliconflowembeddingdeploymodelparameters_113c43) | |
| [TongyiEmbeddingDeployModelParameters](embedding/tongyi_tongyiembeddingdeploymodelparameters_a7cbb4) | |
---
### graph_store {#type-graph_store}
This type contains 3 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [Neo4jStoreConfig](graph_store/neo4j_store_neo4jstoreconfig_a4db5d) | |
| [OpenSPGConfig](graph_store/open_spg_openspgconfig_a744fd) | |
| [TuGraphStoreConfig](graph_store/tugraph_store_tugraphstoreconfig_7ca8a8) | |
---
### llm {#type-llm}
This type contains 28 configuration classes.
#### Relationships
```mermaid
graph TD
HFLLMDeployModelParameters -->|quantization| BitsandbytesQuantization
HFLLMDeployModelParameters -->|quantization| BitsandbytesQuantization8bits
HFLLMDeployModelParameters -->|quantization| BitsandbytesQuantization4bits
```
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [AimlapiDeployModelParameters](llm/aimlapi_aimlapideploymodelparameters_7c1b54) | |
| [BaichuanDeployModelParameters](llm/baichuan_baichuandeploymodelparameters_0bf9cc) | |
| [BitsandbytesQuantization](llm/parameter_bitsandbytesquantization_d40e3b) | |
| [BitsandbytesQuantization4bits](llm/parameter_bitsandbytesquantization4bits_52b778) | |
| [BitsandbytesQuantization8bits](llm/parameter_bitsandbytesquantization8bits_909aed) | |
| [BurnCloudDeployModelParameters](llm/burncloud_burnclouddeploymodelparameters_e59cbb) | |
| [ClaudeDeployModelParameters](llm/claude_claudedeploymodelparameters_1f0c45) | |
| [DeepSeekDeployModelParameters](llm/deepseek_deepseekdeploymodelparameters_194cbd) | |
| [GeminiDeployModelParameters](llm/gemini_geminideploymodelparameters_5113b9) | |
| [GiteeDeployModelParameters](llm/gitee_giteedeploymodelparameters_d1bdb3) | |
| [HFLLMDeployModelParameters](llm/hf_adapter_hfllmdeploymodelparameters_103e81) | |
| [InfiniAIDeployModelParameters](llm/infiniai_infiniaideploymodelparameters_682301) | |
| [LiteLLMDeployModelParameters](llm/litellm_litellmdeploymodelparameters_d053f9) | |
| [LlamaCppModelParameters](llm/llama_cpp_py_adapter_llamacppmodelparameters_e88874) | |
| [LlamaServerParameters](llm/llama_cpp_adapter_llamaserverparameters_421f40) | |
| [MLXDeployModelParameters](llm/mlx_adapter_mlxdeploymodelparameters_f26f45) | |
| [MiniMaxDeployModelParameters](llm/minimax_minimaxdeploymodelparameters_97ce61) | |
| [MoonshotDeployModelParameters](llm/moonshot_moonshotdeploymodelparameters_aa2f6b) | |
| [OllamaDeployModelParameters](llm/ollama_ollamadeploymodelparameters_d55be6) | |
| [OpenAICompatibleDeployModelParameters](llm/chatgpt_openaicompatibledeploymodelparameters_c3d426) | |
| [SiliconFlowDeployModelParameters](llm/siliconflow_siliconflowdeploymodelparameters_abe22f) | |
| [SparkDeployModelParameters](llm/spark_sparkdeploymodelparameters_afba3c) | |
| [TongyiDeployModelParameters](llm/tongyi_tongyideploymodelparameters_02a91b) | |
| [VLLMDeployModelParameters](llm/vllm_adapter_vllmdeploymodelparameters_1d4a24) | |
| [VolcengineDeployModelParameters](llm/volcengine_volcenginedeploymodelparameters_938015) | |
| [WenxinDeployModelParameters](llm/wenxin_wenxindeploymodelparameters_63c66b) | |
| [YiDeployModelParameters](llm/yi_yideploymodelparameters_92dbaa) | |
| [ZhipuDeployModelParameters](llm/zhipu_zhipudeploymodelparameters_c51e31) | |
---
### memory {#type-memory}
This type contains 2 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [BufferWindowGPTsAppMemoryConfig](memory/config_bufferwindowgptsappmemoryconfig_c31071) | |
| [TokenBufferGPTsAppMemoryConfig](memory/config_tokenbuffergptsappmemoryconfig_6a2000) | |
---
### other {#type-other}
This type contains 1 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [ApplicationConfig](config_applicationconfig_72fd1c) | |
---
### reranker {#type-reranker}
This type contains 6 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [CrossEncoderRerankEmbeddingsParameters](reranker/rerank_crossencoderrerankembeddingsparameters_63ec13) | |
| [InfiniAIRerankEmbeddingsParameters](reranker/rerank_infiniairerankembeddingsparameters_879440) | |
| [OpenAPIRerankerDeployModelParameters](reranker/rerank_openapirerankerdeploymodelparameters_778108) | |
| [QwenRerankEmbeddingsParameters](reranker/rerank_qwenrerankembeddingsparameters_18e7d2) | |
| [SiliconFlowRerankEmbeddingsParameters](reranker/rerank_siliconflowrerankembeddingsparameters_af0257) | |
| [TeiEmbeddingsParameters](reranker/rerank_teiembeddingsparameters_e38e28) | |
---
### serve {#type-serve}
This type contains 13 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [ServeConfig](serve/config_serveconfig_63f1e9) | |
| [ServeConfig](serve/config_serveconfig_adbd6f) | |
| [ServeConfig](serve/config_serveconfig_313252) | |
| [ServeConfig](serve/config_serveconfig_ec2d70) | |
| [ServeConfig](serve/config_serveconfig_1a9284) | |
| [ServeConfig](serve/config_serveconfig_8839e0) | |
| [ServeConfig](serve/config_serveconfig_fa1f35) | |
| [ServeConfig](serve/config_serveconfig_cb64c6) | |
| [ServeConfig](serve/config_serveconfig_c0b589) | |
| [ServeConfig](serve/config_serveconfig_b1c2b9) | |
| [ServeConfig](serve/config_serveconfig_7a0577) | |
| [ServeConfig](serve/config_serveconfig_854dad) | |
| [ServeConfig](serve/config_serveconfig_7889f9) | |
---
### service {#type-service}
This type contains 1 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [DBModelRegistryParameters](service/parameter_dbmodelregistryparameters_87d036) | |
---
### utils {#type-utils}
This type contains 2 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [OSSStorageConfig](utils/config_ossstorageconfig_1ad505) | |
| [S3StorageConfig](utils/config_s3storageconfig_f0cdc9) | |
---
### vector_store {#type-vector_store}
This type contains 7 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [ChromaVectorConfig](vector_store/chroma_store_chromavectorconfig_16224f) | |
| [ElasticsearchStoreConfig](vector_store/elastic_store_elasticsearchstoreconfig_15bdb6) | |
| [OceanBaseConfig](vector_store/oceanbase_store_oceanbaseconfig_220e36) | |
| [PGVectorConfig](vector_store/pgvector_store_pgvectorconfig_3ef448) | |
| [QdrantVectorConfig](vector_store/qdrant_store_qdrantvectorconfig_3d0339) | |
| [ValkeyVectorConfig](vector_store/valkey_store_valkeyvectorconfig_a0fffb) | |
| [WeaviateVectorConfig](vector_store/weaviate_store_weaviatevectorconfig_093ce3) | |
---
## Cross-Type Relationships
The following diagram shows relationships between different configuration types:
```mermaid
graph TD
other[other - 1 classes]
datasource[datasource - 18 classes]
llm[llm - 28 classes]
embedding[embedding - 8 classes]
reranker[reranker - 6 classes]
service[service - 1 classes]
graph_store[graph_store - 3 classes]
vector_store[vector_store - 7 classes]
serve[serve - 13 classes]
memory[memory - 2 classes]
app[app - 6 classes]
utils[utils - 2 classes]
service -->|18 connections| datasource
other -->|13 connections| serve
serve -->|2 connections| utils
app -->|14 connections| memory
```
## Looking for a specific configuration?
1. Use the search function in the documentation site
2. Browse the configuration types above
3. Check the specific class documentation for detailed parameter information
---
### Docs Getting Started Cli Quickstart (`docs/docs/getting-started/cli-quickstart.md`)
---
sidebar_position: 1
---
# CLI Quick Start
Install DB-GPT from PyPI and start it with a single command — no source checkout required.
:::tip Prerequisites
- Python **3.10** or later
- [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager (recommended) or pip
:::
## 1. Install
```bash
# Recommended: use uv
uv pip install dbgpt-app
# Or with pip
pip install dbgpt-app
```
:::tip Using a PyPI Mirror
For faster downloads, specify a mirror when installing:
```bash
uv pip install dbgpt-app --index-url https://pypi.tuna.tsinghua.edu.cn/simple # uv
pip install dbgpt-app -i https://pypi.tuna.tsinghua.edu.cn/simple # pip
```
Alternatively, set an environment variable to apply the mirror to **all** installs in the current shell session:
```bash
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple # uv
export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple # pip
```
:::
:::info What's included
The default installation includes the **core framework** (CLI, FastAPI, SQLAlchemy, Agent),
**OpenAI-compatible LLM support** (also works with Kimi, Qwen, MiniMax, Z.AI),
**DashScope / Tongyi** support, **RAG document parsing**, and **ChromaDB** vector store.
Need additional providers or data sources? See [Optional Modules](#8-optional-modules).
:::
After installation the `dbgpt` command is available in your terminal.
## 2. Start DB-GPT
```bash
dbgpt start
```
That's it! On first run DB-GPT will launch an **interactive setup wizard** that helps you:
1. Choose an LLM provider (OpenAI, Kimi, Qwen, MiniMax, Z.AI, or a custom endpoint)
2. Enter your API key (or use an environment variable)
3. Confirm the model names and API base URL
Once complete, a TOML configuration file is written to `~/.dbgpt/configs/.toml` and the web server starts automatically.
### What the startup looks like
```
____ ____ ____ ____ _____
| _ \| __ ) / ___| _ \_ _|
| | | | _ \ ____| | _| |_) || |
| |_| | |_) |____| |_| | __/ | |
|____/|____/ \____|_| |_|
🚀 DB-GPT Quick Start
+- - - - - - - - - - - - - - - - - - - - - - - -+
: Profile: openai :
: Config: /Users/you/.dbgpt/configs/openai.toml:
: Workspace: /Users/you/.dbgpt/workspace :
+- - - - - - - - - - - - - - - - - - - - - - - -+
```
## 3. Open the Web UI
Then open [http://localhost:5670](http://localhost:5670).
---
## 4. Command Reference
### Overview
```
dbgpt [OPTIONS] COMMAND [ARGS]...
Options:
--log-level TEXT Log level (default: warn)
--version Show version and exit
--help Show help message
Commands:
start Start the DB-GPT server
stop Stop a running server
setup Configure LLM provider (interactive wizard or CI mode)
profile Manage configuration profiles
knowledge Knowledge base operations
model Manage model serving
db Database management and migration
...
```
---
### `dbgpt start`
Start the DB-GPT web server. Running `dbgpt start` without a subcommand is equivalent to `dbgpt start web`.
#### Subcommands
| Subcommand | Description |
|---|---|
| `web` (or `webserver`) | Start the web server (default) |
| `none` | API-only mode — *planned for a future release* |
| `controller` | Start the model controller |
| `worker` | Start a model worker |
| `apiserver` | Start the API server |
#### `dbgpt start web` Options
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
| `--config` | `-c` | PATH | *auto* | Path to a TOML config file. If omitted, uses the active profile or launches the setup wizard. |
| `--profile` | `-p` | TEXT | *active* | Provider profile name (`openai`, `kimi`, `qwen`, `minimax`, `glm`, `custom`). Overrides the active profile. |
| `--yes` | `-y` | FLAG | false | Non-interactive mode: skip the wizard and use defaults / environment variables. Ideal for CI/CD. |
| `--api-key` | | TEXT | *env* | API key for the chosen provider. Can also be set via the provider's own environment variable. |
| `--daemon` | `-d` | FLAG | false | Run as a background daemon. Stop with `dbgpt stop webserver`. |
#### Examples
```bash
# Interactive (first run) — wizard will guide you
dbgpt start
# Use an existing profile
dbgpt start web --profile openai
# Non-interactive with explicit API key
dbgpt start web --profile kimi --api-key sk-xxx --yes
# Use a specific config file
dbgpt start web --config /path/to/my-config.toml
# Run as a daemon
dbgpt start web --daemon
```
#### Config Resolution Priority
When the web server starts, the configuration file is resolved in this order:
1. **`--config` flag** — if specified, use this file directly
2. **`--profile` flag** — look up `~/.dbgpt/configs/.toml`
3. **Active profile** — read from `~/.dbgpt/config.toml`
4. **Setup wizard** — if nothing is configured yet, launch the interactive wizard
---
### `dbgpt stop`
Stop running DB-GPT server processes.
```bash
# Stop the web server
dbgpt stop webserver
# Stop the web server on a specific port
dbgpt stop webserver --port 5670
# Stop all servers
dbgpt stop all
```
---
### `dbgpt setup`
Configure the LLM provider interactively, or in non-interactive / CI mode. This command writes a TOML config to `~/.dbgpt/configs/.toml` and marks it as the active profile.
#### Options
| Option | Short | Type | Default | Description |
|---|---|---|---|---|
| `--profile` | `-p` | TEXT | *interactive* | Provider profile to configure. If omitted, an interactive menu is shown. |
| `--yes` | `-y` | FLAG | false | Non-interactive mode: skip the wizard and use defaults. |
| `--api-key` | | TEXT | *env* | API key. Also reads `DBGPT_API_KEY` env var. |
| `--show` | | FLAG | false | Show the current active profile and config path, then exit. |
#### Examples
```bash
# Interactive wizard
dbgpt setup
# Non-interactive: use OpenAI with env key
export OPENAI_API_KEY=sk-xxx
dbgpt setup --profile openai --yes
# Non-interactive with explicit key
dbgpt setup --profile kimi --api-key sk-xxx
# Show current configuration
dbgpt setup --show
```
---
### `dbgpt profile`
Manage multiple configuration profiles. Each profile is a TOML file under `~/.dbgpt/configs/`.
#### Subcommands
| Subcommand | Description |
|---|---|
| `list` | List all profiles. The active one is marked with `*`. |
| `show ` | Display the TOML content of a profile. |
| `create ` | Create (or reconfigure) a profile using the setup wizard. |
| `switch ` | Set a profile as the active default. |
| `delete ` | Delete a profile configuration file. |
#### Examples
```bash
# List all profiles
dbgpt profile list
# openai ← no asterisk
# * kimi ← active
# Show profile content
dbgpt profile show openai
# Create a new profile
dbgpt profile create qwen
# Switch active profile
dbgpt profile switch openai
# Delete a profile
dbgpt profile delete minimax
dbgpt profile delete minimax --yes # skip confirmation
```
---
## 5. Supported Providers
The setup wizard and `--profile` flag support the following providers:
| Profile Name | Display Name | LLM Model | Embedding Model | API Key Env Var |
|---|---|---|---|---|
| `openai` | OpenAI | gpt-4o | text-embedding-3-small | `OPENAI_API_KEY` |
| `kimi` | Kimi | kimi-k2 | text-embedding-v3 | `MOONSHOT_API_KEY` (+ `DASHSCOPE_API_KEY` for embeddings) |
| `qwen` | Qwen | qwen-plus | text-embedding-v3 | `DASHSCOPE_API_KEY` |
| `minimax` | MiniMax | abab6.5s-chat | embo-01 | `MINIMAX_API_KEY` |
| `glm` | Z.AI | glm-4-plus | embedding-3 | `ZHIPUAI_API_KEY` |
| `custom` | Custom | gpt-4o | text-embedding-3-small | `OPENAI_API_KEY` |
:::info
The **Custom** profile lets you connect to any OpenAI-compatible API endpoint. During the wizard you'll be asked for the API base URL.
:::
---
## 6. Directory Structure
After first run, DB-GPT creates the following structure under your home directory:
```
~/.dbgpt/
├── config.toml # Records the active profile name
├── configs/
│ ├── openai.toml # Profile: OpenAI
│ ├── kimi.toml # Profile: Kimi
│ └── ... # One file per profile
└── workspace/
└── pilot/ # Runtime workspace (databases, data files, etc.)
├── meta_data/
│ └── dbgpt.db # SQLite metadata database
└── data/ # Vector store data
```
### Environment Variables
| Variable | Default | Description |
|---|---|---|
| `DBGPT_HOME` | `~/.dbgpt` | Override the DB-GPT home directory |
| `OPENAI_API_KEY` | — | OpenAI API key (used by `openai` and `custom` profiles) |
| `MOONSHOT_API_KEY` | — | Kimi / Moonshot API key |
| `DASHSCOPE_API_KEY` | — | Qwen / DashScope API key (also used for Kimi embeddings) |
| `MINIMAX_API_KEY` | — | MiniMax API key |
| `ZHIPUAI_API_KEY` | — | Z.AI / Zhipu API key |
| `DBGPT_API_KEY` | — | Generic API key (fallback for `--api-key` flag) |
| `DBGPT_LANG` | `en` | UI language (`en` or `zh`) |
---
## 7. Common Workflows
### First-time setup
```bash
pip install dbgpt-app
dbgpt start
# Follow the wizard → choose provider → enter API key → server starts
```
### Switch between providers
```bash
# Create a Kimi profile
dbgpt profile create kimi
# Switch to it
dbgpt profile switch kimi
# Start with the new profile
dbgpt start
```
### CI/CD deployment
```bash
export OPENAI_API_KEY=sk-xxx
dbgpt setup --profile openai --yes
dbgpt start web --daemon
```
### Custom endpoint (e.g. Azure OpenAI, local vLLM)
```bash
dbgpt setup --profile custom
# Wizard will ask for:
# - API base URL (e.g. http://localhost:8000/v1)
# - API key
# - Model names
```
---
## 8. Optional Modules
The core framework is included by default when you `pip install dbgpt-app`. Use extras to add LLM providers, vector stores, data sources, and more.
### LLM Providers
| Extra | Provider | Key packages |
|-------|----------|-------------|
| `proxy_openai` | OpenAI, Kimi, Qwen, MiniMax, Z.AI, any OpenAI-compatible API | `openai`, `tiktoken` |
| `proxy_ollama` | Ollama (local models) | `ollama` |
| `proxy_zhipuai` | Zhipu AI (GLM) | `openai` |
| `proxy_tongyi` | Tongyi Qianwen | `openai`, `dashscope` |
| `proxy_qianfan` | Baidu Qianfan | `qianfan` |
| `proxy_anthropic` | Anthropic Claude | `anthropic` |
### Vector Stores
| Extra | Storage | Key packages |
|-------|---------|-------------|
| `storage_chromadb` | ChromaDB | `chromadb`, `onnxruntime` |
| `storage_milvus` | Milvus | `pymilvus` |
| `storage_valkey` | Valkey | `valkey-glide` |
| `storage_weaviate` | Weaviate | `weaviate-client` |
| `storage_elasticsearch` | Elasticsearch | `elasticsearch` |
| `storage_obvector` | OBVector | `pyobvector` |
### Knowledge & RAG
| Extra | What it adds | Key packages |
|-------|-------------|-------------|
| `rag` | Document parsing (PDF, DOCX, PPTX, Markdown, HTML) | `spacy`, `pypdf`, `python-docx`, `python-pptx` |
| `graph_rag` | Graph-based RAG with TuGraph/Neo4j | `networkx`, `neo4j` |
### Data Sources
| Extra | Database | Key packages |
|-------|----------|-------------|
| `datasource_mysql` | MySQL | `mysqlclient` |
| `datasource_postgres` | PostgreSQL | `psycopg2-binary` |
| `datasource_clickhouse` | ClickHouse | `clickhouse-connect` |
| `datasource_oracle` | Oracle | `oracledb` |
| `datasource_mssql` | SQL Server | `pymssql` |
| `datasource_spark` | Apache Spark | `pyspark` |
| `datasource_hive` | Hive | `pyhive` |
| `datasource_vertica` | Vertica | `vertica-python` |
### Example: combine multiple extras
```bash
# OpenAI + ChromaDB + RAG + MySQL
pip install "dbgpt-app[proxy_openai,storage_chromadb,rag,datasource_mysql]"
```
:::tip Minimal install
If you only need the core framework without any LLM or storage:
```bash
pip install dbgpt-app
```
This gives you the CLI, FastAPI server, and agent framework — but you'll need to add at least one LLM provider extra to actually use it.
:::
---
## 9. Troubleshooting
### Port already in use
```bash
# Stop the existing server
dbgpt stop webserver --port 5670
# Or choose a different port by editing the config file
# [service.web]
# port = 5671
```
### "No config file found" error
This means no profile has been set up yet. Run:
```bash
dbgpt setup
```
### Changing your API key
Re-run the setup wizard for the same profile — it will overwrite the existing config:
```bash
dbgpt setup --profile openai
# Or simply edit ~/.dbgpt/configs/openai.toml directly
```
### View current configuration
```bash
dbgpt setup --show
dbgpt profile show openai
```
---
### Docs Getting Started Index (`docs/docs/getting-started/index.md`)
---
sidebar_position: 0
---
# Getting Started
Welcome to DB-GPT! This section will help you get up and running quickly.
- **[CLI Quick Start](./cli-quickstart)** — Install DB-GPT via pip and start it with a single command. Includes interactive setup wizard, profile management, and all CLI options.
---
### Docs Installation Index (`docs/docs/installation/index.md`)
---
sidebar_position: 0
title: Install Overview
summary: "Choose the fastest way to install DB-GPT: quick install, CLI install, or source install"
read_when:
- You want to decide which installation path fits your environment
- You want the shortest route to a working DB-GPT setup
---
# Install Overview
DB-GPT offers three recommended installation paths. Pick the one that matches how you want to run and manage the project.
## Choose an installation path
| Method | Best for | Scenario | What you get |
|:-------|:---------|:---------|:-------------|
| [Quick Install](/docs/installation/quick-install) | Fastest first run on macOS / Linux | Quick launch the latest DB-GPT from source with automated environment setup and dependency installation | Quick install and start the latest source project with optional advanced config |
| [CLI Install](/docs/getting-started/cli-quickstart) | Users who prefer installing from PyPI | One-click start and try a stable DB-GPT release without worrying about project structure or config details | One-line installer, interactive setup wizard, profile management |
| [Source Install](/docs/getting-started/deploy/source-code) | Developers and custom deployments | You need to modify source code, debug internals, or integrate DB-GPT into a custom deployment pipeline | Full repo checkout, editable configs, maximum flexibility |
## When to choose each method
### Quick Install
For MacOS / Linux users — choose this if you want the fewest steps to install, quickly launch the latest DB-GPT from source with automated environment setup and dependency installation.
### CLI Install (Recommended)
Choose this if you want to install DB-GPT directly from PyPI and use the `dbgpt` command to set up profiles interactively.
### Source Install
Choose this if you want full access to the repository for development, debugging, or custom integrations.
## Next steps
- [Quick Install](/docs/installation/quick-install)
- [CLI Install](/docs/getting-started/cli-quickstart)
- [Source Install](/docs/getting-started/deploy/source-code)
---
### Docs Sandbox Index (`docs/docs/sandbox/index.md`)
---
sidebar_position: 0
title: Sandbox Overview
---
# Sandbox Overview
DB-GPT uses a sandbox to let agents execute code and tools in an isolated runtime
instead of running directly in the host environment.
This matters for agent workflows because an agent often needs to do more than
reason in text. It may need to run code, execute shell commands, install
dependencies, generate files, and keep execution state across multiple steps.
The sandbox is the execution boundary that makes those actions safer and more
manageable.
## What is a sandbox?
In DB-GPT, a sandbox is an isolated execution environment used by an agent when it
needs to execute code, run commands, or manipulate files as part of a task.
Instead of letting the agent operate directly on the host system, the sandbox
provides:
- process isolation
- resource limits
- controlled working directories
- optional dependency installation
- session lifecycle management
- a clear boundary between reasoning and execution
## How the sandbox works with agents
The agent decides **what** to do next. The sandbox executes **how** that action is
run.
```mermaid
flowchart TB
User["User / UI"] --> API["dbgpt-app API"]
API --> Agent["ReAct Agent / Agent Logic"]
Agent --> Decide["Select tool or code action"]
Decide --> Sandbox["Sandbox Runtime"]
subgraph SandboxLayer["Sandbox execution"]
Session["Session lifecycle"]
Exec["Code / shell execution"]
Files["File & report generation"]
Limits["Memory / CPU / timeout / isolation"]
end
Sandbox --> Session
Sandbox --> Exec
Sandbox --> Files
Sandbox --> Limits
Exec --> Observation["Execution result / observation"]
Observation --> Agent
Agent --> Result["Final answer / report / UI output"]
```
## Why agents need a sandbox
An agent that can execute code without isolation is difficult to operate safely in
real environments. The sandbox gives DB-GPT a dedicated runtime for actions such
as:
- code execution
- shell command execution
- dependency installation
- file creation and retrieval
- multi-step stateful analysis
This is especially important for data analysis, report generation, and tool-driven
workflows where the agent must combine reasoning with real execution.
## DB-GPT's current sandbox solution
DB-GPT's sandbox implementation lives in:
- `packages/dbgpt-sandbox/`
The current design is a layered, extensible sandbox runtime with multiple backend
options.
### Runtime backends
The current application-side Agent integration uses LocalRuntime by default.
Container execution is opt-in through SANDBOX_RUNTIME=docker (or an explicit
Podman/Nerdctl selection). If a configured container backend cannot be initialized,
or its session cannot be created, the Agent executor returns an error without
running user code locally. LocalRuntime is a default, not a failure fallback,
and does not provide container isolation.
See [Sandbox Runtime Configuration](./runtime) for setup, image requirements,
execution lifecycle, and verification commands.
Implementation anchor:
- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/execution_layer/runtime_factory.py`
Docker is not selected merely because Docker is installed. This keeps the default
installation usable without a pre-built Agent image while allowing deployments to
opt into container execution explicitly.
## Layered architecture in `dbgpt-sandbox`
DB-GPT's sandbox is implemented as a small runtime system with several layers.
### 1. Execution layer
The execution layer provides the runtime implementations and the core abstractions.
- `base.py` defines shared runtime/session/result/config interfaces
- `docker_runtime.py`, `podman_runtime.py`, `nerdctl_runtime.py`, `local_runtime.py`
implement concrete runtimes
- `runtime_factory.py` selects the runtime backend
### 2. Control layer
The control layer manages task lifecycle and execution orchestration.
Implementation anchor:
- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/control_layer/control_layer.py`
This layer handles operations such as:
- connect
- configure
- execute
- status
- disconnect
- get file
It also manages session creation and session-scoped execution.
### 3. User layer
The user layer exposes the sandbox service interface used by callers.
Implementation anchors:
- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/user_layer/service.py`
- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/user_layer/schemas.py`
### 4. Display layer
The display layer packages outputs for runtime-specific display or file-oriented
results.
Implementation anchor:
- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/display_layer/display_layer.py`
## Session model and stateful execution
One important part of the DB-GPT sandbox design is that it supports **session-based
stateful execution**.
That means:
- a sandbox session can be created once
- multiple execution steps can run in the same session
- installed dependencies can remain available in later steps
- files produced in one step can be reused in the next step
This is important for agent workflows where a task is solved through multiple
reasoning and execution rounds rather than a single tool call.
## Current integration in DB-GPT app
Today, DB-GPT already uses sandbox execution in application-side agent tooling.
For example, the `shell_interpreter` tool in:
- `packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/agentic_data_api.py`
uses `dbgpt-sandbox` `LocalRuntime` to execute shell commands with:
- process isolation
- memory limits
- timeout limits
- security validation
The current implementation there is **stateless per call** for shell execution: each
tool call creates a temporary sandbox session and destroys it after completion.
So the repo currently contains both:
- a more complete `dbgpt-sandbox` design for reusable sandbox sessions
- a practical app-side integration already using sandboxed execution for tools
## What DB-GPT supports today
Based on the current `dbgpt-sandbox` implementation, DB-GPT is moving toward a
general-purpose agent runtime that supports:
- multi-runtime sandbox execution
- safe code and shell execution
- stateful sandbox sessions
- dependency installation inside the sandbox
- task lifecycle control
- file retrieval from sandbox sessions
This makes the sandbox suitable for agent scenarios such as:
- code agents
- data analysis agents
- report generation agents
- browser/computer style execution runtimes in future extensions
## High-level view of the current DB-GPT sandbox direction
```mermaid
flowchart TB
Apps["Agent applications"] --> Access["Access layer"]
Access --> Runtime["Agent sandbox runtime"]
subgraph AccessLayer["Access layer"]
SDK["SDK / API / CLI"]
end
subgraph RuntimeLayer["Sandbox runtime"]
Code["Code execution"]
Browser["Browser / GUI style execution"]
SessionMgmt["Lifecycle / snapshot / state / files"]
Isolation["Isolation / limits / runtime selection"]
end
Runtime --> Code
Runtime --> Browser
Runtime --> SessionMgmt
Runtime --> Isolation
```
This diagram is conceptual. It shows the direction of the sandbox as a dedicated
runtime layer under agent applications, while the current repo implementation
already provides the execution, control, session, and runtime selection foundations
in `dbgpt-sandbox`.
## Key implementation anchors
- `packages/dbgpt-sandbox/README.md`
- `packages/dbgpt-sandbox/src/docs/architecture.md`
- `packages/dbgpt-sandbox/src/docs/usage.md`
- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/execution_layer/runtime_factory.py`
- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/control_layer/control_layer.py`
- `packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/agentic_data_api.py`
---
### Docs Tutorials Index (`docs/docs/tutorials/index.md`)
# Tutorial for DB-GPT
Some video tutorials for the DB-GPT project, through these tutorials, you can understand the DB-GPT project better.
## DB-GPT introduction
On this page, we will give you some introduction about DB-GPT that can help you learn about it.
---
### Docs Config Reference App Index (`docs/docs/config-reference/app/index.mdx`)
---
title: "app"
description: "app Configuration"
---
# app Configuration
This document provides an overview of all configuration classes in app type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
---
### Docs Config Reference Datasource Index (`docs/docs/config-reference/datasource/index.mdx`)
---
title: "datasource"
description: "datasource Configuration"
---
# datasource Configuration
This document provides an overview of all configuration classes in datasource type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
---
### Docs Config Reference Embedding Index (`docs/docs/config-reference/embedding/index.mdx`)
---
title: "embedding"
description: "embedding Configuration"
---
# embedding Configuration
This document provides an overview of all configuration classes in embedding type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
, encode_kwargs: Dict[str, Any] = , embed_instruction: Optional[str] = None, query_instruction: Optional[str] = None)",
"link": "./embeddings_hfembeddingdeploymodelparameters_f588e1"
},
{
"name": "JinaEmbeddingsDeployModelParameters",
"description": "Jina AI Embeddings deploy model parameters.",
"link": "./jina_jinaembeddingsdeploymodelparameters_40b0f2"
},
{
"name": "OllamaEmbeddingDeployModelParameters",
"description": "Ollama Embeddings deploy model parameters.",
"link": "./ollama_ollamaembeddingdeploymodelparameters_b511e0"
},
{
"name": "OpenAPIEmbeddingDeployModelParameters",
"description": "OpenAPI embedding deploy model parameters.",
"link": "./embeddings_openapiembeddingdeploymodelparameters_f9ba47"
},
{
"name": "QianfanEmbeddingDeployModelParameters",
"description": "Qianfan Embeddings deploy model parameters.",
"link": "./qianfan_qianfanembeddingdeploymodelparameters_257d2a"
},
{
"name": "TongyiEmbeddingDeployModelParameters",
"description": "Qianfan Embeddings deploy model parameters.",
"link": "./tongyi_tongyiembeddingdeploymodelparameters_a7cbb4"
},
]} />
---
### Docs Config Reference Graph Store Index (`docs/docs/config-reference/graph_store/index.mdx`)
---
title: "graph_store"
description: "graph_store Configuration"
---
# graph_store Configuration
This document provides an overview of all configuration classes in graph_store type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
---
### Docs Config Reference Llm Index (`docs/docs/config-reference/llm/index.mdx`)
---
title: "llm"
description: "llm Configuration"
---
# llm Configuration
This document provides an overview of all configuration classes in llm type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
, no_context_shift: bool = False, no_webui: Optional[bool] = None, startup_timeout: Optional[int] = None)",
"link": "./llama_cpp_adapter_llamaserverparameters_421f40"
},
{
"name": "MiniMaxDeployModelParameters",
"description": "MiniMax proxy LLM configuration.",
"link": "./minimax_minimaxdeploymodelparameters_a1b2c4"
},
{
"name": "MoonshotDeployModelParameters",
"description": "Moonshot proxy LLM configuration.",
"link": "./moonshot_moonshotdeploymodelparameters_aa2f6b"
},
{
"name": "OllamaDeployModelParameters",
"description": "Ollama proxy LLM configuration.",
"link": "./ollama_ollamadeploymodelparameters_d55be6"
},
{
"name": "OpenAICompatibleDeployModelParameters",
"description": "OpenAI Compatible Proxy LLM",
"link": "./chatgpt_openaicompatibledeploymodelparameters_c3d426"
},
{
"name": "AimlapiDeployModelParameters",
"description": "AI/ML API proxy LLM configuration.",
"link": "./aimlapi_aimlapideploymodelparameters_a1b2c3"
},
{
"name": "SiliconFlowDeployModelParameters",
"description": "SiliconFlow proxy LLM configuration.",
"link": "./siliconflow_siliconflowdeploymodelparameters_abe22f"
},
{
"name": "SparkDeployModelParameters",
"description": "Xunfei Spark proxy LLM configuration.",
"link": "./spark_sparkdeploymodelparameters_afba3c"
},
{
"name": "TongyiDeployModelParameters",
"description": "Tongyi proxy LLM configuration.",
"link": "./tongyi_tongyideploymodelparameters_02a91b"
},
{
"name": "VLLMDeployModelParameters",
"description": "Local deploy model parameters.",
"link": "./vllm_adapter_vllmdeploymodelparameters_1d4a24"
},
{
"name": "VolcengineDeployModelParameters",
"description": "Volcengine proxy LLM configuration.",
"link": "./volcengine_volcenginedeploymodelparameters_938015"
},
{
"name": "WenxinDeployModelParameters",
"description": "Baidu Wenxin proxy LLM configuration.",
"link": "./wenxin_wenxindeploymodelparameters_63c66b"
},
{
"name": "YiDeployModelParameters",
"description": "Yi proxy LLM configuration.",
"link": "./yi_yideploymodelparameters_92dbaa"
},
{
"name": "ZhipuDeployModelParameters",
"description": "Zhipu proxy LLM configuration.",
"link": "./zhipu_zhipudeploymodelparameters_c51e31"
},
]} />
---
### Docs Config Reference Memory Index (`docs/docs/config-reference/memory/index.mdx`)
---
title: "memory"
description: "memory Configuration"
---
# memory Configuration
This document provides an overview of all configuration classes in memory type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
---
### Docs Config Reference Reranker Index (`docs/docs/config-reference/reranker/index.mdx`)
---
title: "reranker"
description: "reranker Configuration"
---
# reranker Configuration
This document provides an overview of all configuration classes in reranker type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
---
### Docs Config Reference Serve Index (`docs/docs/config-reference/serve/index.mdx`)
---
title: "serve"
description: "serve Configuration"
---
# serve Configuration
This document provides an overview of all configuration classes in serve type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
---
### Docs Config Reference Service Index (`docs/docs/config-reference/service/index.mdx`)
---
title: "service"
description: "service Configuration"
---
# service Configuration
This document provides an overview of all configuration classes in service type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
---
### Docs Config Reference Utils Index (`docs/docs/config-reference/utils/index.mdx`)
---
title: "utils"
description: "utils Configuration"
---
# utils Configuration
This document provides an overview of all configuration classes in utils type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
)",
"link": "./config_s3storageconfig_f0cdc9"
},
]} />
---
### Docs Config Reference Vector Store Index (`docs/docs/config-reference/vector_store/index.mdx`)
---
title: "vector_store"
description: "vector_store Configuration"
---
# vector_store Configuration
This document provides an overview of all configuration classes in vector_store type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
---
### Docs Dbgpts Built In Skills Overview (`docs/docs/dbgpts/built-in-skills/overview.md`)
# Built-in Skills Overview
DB-GPT ships with built-in skills under the project-level `skills/` directory.
This subsection mirrors the repository structure and gives each built-in skill its own page.
## Repo mapping
```text
skills/
├── agent-browser/
├── csv-data-analysis/
├── financial-report-analyzer/
├── skill-creator/
└── walmart-sales-analyzer/
```
## What built-in skills provide
Built-in skills package repeatable workflows into reusable units.
- `SKILL.md` defines when the skill should be used and how it should work
- `scripts/` contains executable helpers when deterministic processing is needed
- `references/` stores deeper domain guidance that can be loaded on demand
- `templates/` or `assets/` provide output resources such as HTML report templates
## Current built-in skills
| Skill | Primary use | Key bundled resources |
|------|--------------|-----------------------|
| `agent-browser` | Browser automation for agents | command-driven workflow in `SKILL.md` |
| `csv-data-analysis` | CSV / Excel / TSV analysis | `scripts/csv_analyzer.py`, `templates/report_template.html`, `references/reference.md` |
| `financial-report-analyzer` | Financial report extraction and reporting | extraction, ratio, and chart scripts plus financial references and templates |
| `skill-creator` | Creating and packaging new skills | `init_skill.py`, `package_skill.py`, design references |
| `walmart-sales-analyzer` | Walmart sales trend analysis and reporting | report-generation scripts and `templates/report_template.html` |
## How to read this section
Each built-in skill page includes:
- the skill's purpose
- when to use it
- its core workflow
- the important scripts, references, and templates bundled with it
- practical output expectations
## Next step
Open the individual pages in this Built-in Skills section to see how each shipped skill maps to the repository's `skills/` folder.
---
### Docs Getting Started Providers Index (`docs/docs/getting-started/providers/index.md`)
---
sidebar_position: 0
title: Model Providers
summary: "Which DB-GPT model provider to choose and where each provider guide lives"
read_when:
- You need to pick a provider for your first setup
- You want to know whether to use API models, Ollama, or vLLM
---
# Model Providers
DB-GPT supports API providers and local runtimes. For a first run, use an API provider unless you specifically want local inference.
:::info Quick pick
Not sure which provider to choose? Start with **OpenAI** or **DeepSeek** for the fastest setup (API proxy, no GPU needed). Use **Ollama** if you want to run models locally without complex setup.
:::
## Provider comparison
| Provider | Type | GPU Required | Best for |
|---|---|---|---|
| [**OpenAI**](./openai) | API proxy | No | Production quality, fastest setup |
| [**DeepSeek**](./deepseek) | API proxy | No | Cost-effective, strong reasoning |
| [**Qwen (Tongyi)**](./qwen) | API proxy | No | Chinese language, Alibaba Cloud users |
| [**SiliconFlow**](./siliconflow) | API proxy | No | China-hosted, multiple model choices |
| [**Ollama**](./ollama) | Local proxy | Optional | Easy local models, privacy-first |
| [**vLLM**](./vllm) | Local | Yes (NVIDIA) | High-throughput production inference |
## How model configuration works
All models are configured in TOML files under `configs/`. Each config file defines:
- **LLM(s)** — The language model(s) for chat and reasoning
- **Embedding(s)** — The embedding model(s) for RAG and knowledge search
- **Reranker(s)** — Optional re-ranking models for better retrieval
```toml
[models]
# Language model
[[models.llms]]
name = "model-name"
provider = "provider-type"
api_key = "your-api-key"
# Embedding model
[[models.embeddings]]
name = "embedding-model-name"
provider = "provider-type"
api_key = "your-api-key"
```
:::tip Environment variables
You can use environment variable syntax in TOML configs: `"${env:VARIABLE_NAME:-default_value}"`. This keeps secrets out of config files.
:::
## Provider guides
- [OpenAI](/docs/getting-started/providers/openai) — fastest default for a first setup
- [DeepSeek](/docs/getting-started/providers/deepseek) — strong reasoning, OpenAI-compatible proxy pattern
- [Qwen (Tongyi)](/docs/getting-started/providers/qwen) — Alibaba Cloud / DashScope
- [SiliconFlow](/docs/getting-started/providers/siliconflow) — China-hosted API options
- [Ollama](/docs/getting-started/providers/ollama) — simple local model runtime
- [vLLM](/docs/getting-started/providers/vllm) — GPU-backed local inference for heavier workloads
## More providers
DB-GPT also supports additional providers through its proxy system. See [Advanced LLM Configuration](/docs/installation/advanced_usage/More_proxyllms) for:
- Azure OpenAI
- Google Gemini
- Anthropic Claude
- Baichuan
- Spark (iFlyTek)
- And more
---
### Docs Getting Started Tools Index (`docs/docs/getting-started/tools/index.md`)
---
sidebar_position: 0
title: Tools & Plugins
summary: "How DB-GPT extends agents with MCP, dbgpts, and AWEL Flow"
read_when:
- You want to add tools or external integrations to DB-GPT
- You want to understand the difference between MCP, dbgpts, and AWEL Flow
---
# Tools & Plugins
Extend DB-GPT with external tools, community packages, and visual workflow building.
- [MCP Protocol](/docs/getting-started/tools/mcp) — connect external tools and services to agents
- [dbgpts Ecosystem](/docs/getting-started/tools/dbgpts) — install community apps, operators, workflows, and agents
- [AWEL Flow](/docs/getting-started/tools/awel-flow) — build workflows visually in the Web UI
## Overview
DB-GPT supports three main extension mechanisms:
| Mechanism | What it does | When to use |
|---|---|---|
| **MCP Protocol** | Connects external tools (APIs, services) to agents | Need agents to call external services |
| **dbgpts** | Install pre-built apps, operators, and workflows | Want ready-made components |
| **AWEL Flow** | Visually compose AI pipelines | Need custom workflows without writing code |
## How tools work with agents
```mermaid
graph LR
User[User] --> Agent[Agent]
Agent --> LLM[LLM]
Agent --> Tools[Tools]
Tools --> MCP[MCP Server]
Tools --> DB[(Database)]
Tools --> KB[Knowledge Base]
Tools --> API[External APIs]
```
Agents in DB-GPT can use tools to:
1. **Access data** — Query databases, search knowledge bases
2. **Call APIs** — Interact with external services via MCP
3. **Execute code** — Run Python code in sandboxed environments
4. **Manage files** — Read, write, and process files
## Quick links
| Topic | Link |
|---|---|
| AWEL concepts | [AWEL](/docs/getting-started/concepts/awel) |
| Agent framework | [Agents](/docs/getting-started/concepts/agents) |
| Agent development | [Development Guide](/docs/agents/introduction/tools) |
---
### Docs Getting Started Troubleshooting Index (`docs/docs/getting-started/troubleshooting/index.md`)
---
sidebar_position: 0
title: Troubleshooting
summary: "First checks and common fixes for install, model, and environment issues"
read_when:
- Something broke and you want the fastest fix path
- DB-GPT starts inconsistently, the UI is blank, or models fail to load
---
# Troubleshooting
Common issues and solutions when working with DB-GPT.
## First 60 seconds
Run these first:
```bash
curl http://localhost:5670/api/health
dbgpt model list
docker logs dbgpt -f
```
If you are not using Docker, check the same terminal where you started the webserver.
## Common quick fixes
- **Server will not start**
- Re-run `uv sync` with the right extras
- See [Installation Issues](/docs/getting-started/troubleshooting/installation)
- **Web UI is blank**
- Wait for startup to finish
- Confirm the server is reachable on `http://localhost:5670`
- **Model not found / auth error**
- Re-check the TOML config and provider name
- See [Model Issues](/docs/getting-started/troubleshooting/llm)
- **Port 5670 is already in use**
- Find the conflicting process with `lsof -i :5670`
- **Out of memory**
- Use a smaller local model or switch to an API proxy model
## More specific guides
- [Installation Issues](/docs/getting-started/troubleshooting/installation)
- [Model Issues](/docs/getting-started/troubleshooting/llm)
- [Environment Variables](/docs/getting-started/troubleshooting/environment)
## Logs
```bash
# Source code deployment
# Logs are printed to stdout by default
# Docker deployment
docker logs dbgpt -f
# Docker Compose deployment
docker logs db-gpt-webserver-1 -f
```
## Getting help
If the troubleshooting guides don't resolve your issue:
1. **Search existing issues**: [GitHub Issues](https://github.com/eosphoros-ai/DB-GPT/issues)
2. **Ask the community**: [GitHub Discussions](https://github.com/orgs/eosphoros-ai/discussions)
3. **Join Slack**: [DB-GPT Slack](https://join.slack.com/t/slack-inu2564/shared_invite/zt-29rcnyw2b-N~ubOD9kFc7b7MDOAM1otA)
4. **Check FAQ**: [Installation FAQ](/docs/faq/install) · [LLM FAQ](/docs/faq/llm) · [KBQA FAQ](/docs/faq/kbqa)
---
### Docs Getting Started Web Ui Index (`docs/docs/getting-started/web-ui/index.md`)
---
sidebar_position: 0
title: Web UI Overview
summary: "What is available in the DB-GPT Web UI and where each main feature lives"
read_when:
- You already started DB-GPT and want to know what to click first
- You want a quick map of chat, knowledge, dashboard, and app screens
---
# Web UI Overview
DB-GPT ships with a web interface at **[http://localhost:5670](http://localhost:5670)**.
## Main areas
- [Chat](/docs/getting-started/web-ui/chat) — normal chat, data chat, Excel chat, knowledge chat
- [Knowledge Base](/docs/getting-started/web-ui/knowledge-base) — upload files and build RAG datasets
- [Dashboard](/docs/getting-started/web-ui/dashboard) — generate charts and reports from natural language
- [App Management](/docs/getting-started/web-ui/app-management) — create and manage DB-GPT applications
## Feature map
| Feature | Description | Section |
|---|---|---|
| **Chat** | Multi-turn conversation with LLMs | [Chat](/docs/getting-started/web-ui/chat) |
| **Chat Data** | Natural language queries on connected databases (Text2SQL) | [Chat](/docs/getting-started/web-ui/chat) |
| **Chat Excel** | Upload and query Excel files with natural language | [Chat](/docs/getting-started/web-ui/chat) |
| **Chat Knowledge** | RAG conversations over your uploaded documents | [Knowledge Base](/docs/getting-started/web-ui/knowledge-base) |
| **Dashboard** | Auto-generated charts and reports from data | [Dashboard](/docs/getting-started/web-ui/dashboard) |
| **App Store** | Browse and install community applications | [App Management](/docs/getting-started/web-ui/app-management) |
| **AWEL Flow** | Visual workflow editor for building AI pipelines | [AWEL Flow](/docs/getting-started/tools/awel-flow) |
| **Agent Workspace** | Configure and run multi-agent tasks | [App Management](/docs/getting-started/web-ui/app-management) |
## Accessing the Web UI
After starting the DB-GPT server, the Web UI is available at:
```
http://localhost:5670
```
:::tip Running the front-end separately
For front-end development, you can run the Next.js app independently:
```bash
cd web && npm install
cp .env.template .env
# Set API_BASE_URL=http://localhost:5670
npm run dev
```
Then visit [http://localhost:3000](http://localhost:3000).
:::
## What to try first
1. Open **Chat** and confirm the configured model responds
2. Open **Knowledge Base** if you want RAG over documents
3. Open **Dashboard** if you want Text2SQL and charts
4. Open **Apps** if you want reusable app configurations
## Next steps
| Topic | Link |
|---|---|
| Start chatting | [Chat](/docs/getting-started/web-ui/chat) |
| Set up knowledge base | [Knowledge Base](/docs/getting-started/web-ui/knowledge-base) |
| Build workflows | [AWEL Flow](/docs/getting-started/tools/awel-flow) |
---
### Static Img Dashboard README (`docs/static/img/dashboard/README.md`)
# Dashboard illustrations / 数据看板插图
The maintained architecture and publication diagrams are Mermaid diagrams in the [English design](../../../docs/design/dashboard.md) and [Chinese design](../../../i18n/zh-CN/docusaurus-plugin-content-docs/current/design/dashboard.md).
当前架构与发布流程图以 Mermaid 形式维护在[英文设计](../../../docs/design/dashboard.md)和[中文设计](../../../i18n/zh-CN/docusaurus-plugin-content-docs/current/design/dashboard.md)中。
This directory contains one original screenshot for each business example:
本目录保留两个业务示例的原始截图：
- `walmart-core-desktop-20260929.png`: synthetic retail example / 合成零售示例。
- `apple-core-desktop-20260929.png`: historical Apple financial example / Apple 历史财务示例。
The English and Chinese walkthroughs share these original screenshots through `/img/dashboard/`; the captured UI remains Chinese. These historical illustrations do not establish that a newer commit passed a browser test. Fresh test screenshots and traces belong in test output. Template-gallery preview assets are maintained under [`web/public/dashboard-templates`](../../../../web/public/dashboard-templates/).
中英文案例通过 `/img/dashboard/` 共用原始截图，截图中的界面保留中文。历史插图不代表新提交已通过浏览器测试。新测试的截图和 trace 放在测试输出目录；模板库封面位于 [`web/public/dashboard-templates`](../../../../web/public/dashboard-templates/)。
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Overview (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/overview.mdx`)
---
sidebar_position: 0
title: DB-GPT
---
import CommandCopyCard from "@site/src/components/mdx/CommandCopyCard";
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
# DB-GPT
一个开源的 AI 数据助手，能够连接你的数据、编写 SQL 和代码、在沙箱环境中运行技能，并将分析过程转化为报告、洞察与行动。
DB-GPT 也是一个用于构建 AI Native 数据 Agent、工作流与应用的平台，支持 Agents、AWEL、RAG 和多模型能力。
## 快速开始
适用于 macOS 和 Linux 的一键安装脚本——自动下载、配置并完成 DB-GPT 环境搭建。
通过 pip 安装，几秒内即可启动——全平台最快的 DB-GPT 体验方式。
## 什么是 DB-GPT？
DB-GPT 是一个面向下一代 **AI + Data** 产品的开源 **Agentic AI 数据助手**。
它帮助个人与团队：
- 连接 **数据库、CSV / Excel 文件、数据仓库与知识库**
- 使用自然语言提问，并让 AI **自动生成 SQL**
- 运行 **Python / 代码驱动** 的分析流程
- 加载并执行可复用的 **skills** 以完成领域任务
- 生成 **图表、仪表盘、HTML 报告与分析摘要**
- 在 **沙箱环境** 中安全执行任务
## 为什么选择 DB-GPT？
🧠
Agentic 数据分析
能够规划任务、拆解步骤、调用工具，并端到端完成分析流程。
💻
自主 SQL + 代码执行
自动生成 SQL 与代码，用于查询数据、清洗数据集、计算指标并生成结果。
🗂️
多源数据接入
同时处理结构化与非结构化数据，包括数据库、表格、文档和知识库。
🧩
Skills 驱动的可扩展性
将领域知识、分析方法和执行流程封装成可复用的 skills。
📈
报告与决策支持
生成图表、仪表盘、HTML 报告以及可直接用于决策的业务输出。
🛡️
沙箱执行
在隔离环境中运行代码和工具，让分析过程更加安全、可靠。
## 产品工作流
🔍
探索数据
在同一个工作空间中连接文件、数据库与知识库。
🪄
规划并执行
让 AI 理解任务、编写 SQL 与代码，并逐步执行。
🧰
使用技能
加载可复用的 skills，用于重复性的业务分析流程。
📄
生成报告
输出图表、仪表盘、HTML 报告以及可直接用于决策的结果。
## 核心能力
🤖
Agentic Analysis
任务规划、逐步执行、工具调用与迭代式推理。
🧮
SQL + Code Execution
从自然语言到 SQL、基于 Python 的分析、指标计算和图表生成。
🗃️
Multi-Source Data Access
关系型数据库、CSV / Excel、文档、知识库以及混合数据源工作流。
🧠
Skills and Agents
可复用 skills、领域工作流、agent 编排与可定制执行流程。
📊
Reporting
数据库分析报告、财报分析、仪表盘、摘要与业务洞察。
🔐
Safe Execution
沙箱代码执行、受控工具调用，以及可复现的输出与产物。
## 平台与生态
## 术语说明
| 术语 | 说明 |
|------|-------------|
| **DB-GPT** | DataBase Generative Pre-trained Transformer，一个围绕数据库与大模型构建的开源框架 |
| **Data App** | 基于 DB-GPT 构建的智能数据应用 |
| **Text2SQL** | 利用大模型能力将自然语言转换为 SQL |
| **KBQA** | 基于知识库的问答系统 |
| **GBI** | Generative Business Intelligence，通过对话完成分析与决策 |
| **LLMOps** | 大模型训练、调优、部署与监控的端到端流程 |
| **Embedding** | 将文本、音频、视频等内容转换为向量的方法 |
| **RAG** | Retrieval Augmented Generation，检索增强生成 |
| **AWEL** | Agentic Workflow Expression Language |
| **AWEL Flow** | 基于 AWEL 的工作流编排 |
| **SMMF** | Service-oriented Multi-model Management Framework |
## 社区
如果你在使用过程中遇到问题，可以提交 [issue](https://github.com/eosphoros-ai/DB-GPT/issues)、参与 [discussions](https://github.com/orgs/eosphoros-ai/discussions)，或查看 [releases](https://github.com/eosphoros-ai/DB-GPT/releases)。
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Quickstart (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/quickstart.md`)
---
sidebar_position: 0
---
# Quickstart
DB-GPT supports the installation and use of various open-source and closed-source models. Different models have different requirements for environment and resources. If local model deployment is required, GPU resources are necessary. The API proxy model requires relatively few resources and can be deployed and started on a CPU machine.
:::info note
- Detailed installation and deployment tutorials can be found in [Installation](./installation).
- This page only introduces deployment based on ChatGPT proxy and local GLM model.
:::
## Environment Preparation
### Download Source Code
:::tip
Download DB-GPT
:::
```bash
git clone https://github.com/eosphoros-ai/DB-GPT.git
```
### Environment Setup
- The default database uses SQLite, so there is no need to install a database in the
default startup mode. If you need to use other databases, please refer to the [advanced tutorials](./application/advanced_tutorial/rag.md) below.
Starting from version 0.7.0, DB-GPT uses uv for environment and package management, providing faster and more stable dependency management.
:::info note
There are some ways to install uv:
:::
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Install uv using pipx.
```bash
python -m pip install --upgrade pip
python -m pip install --upgrade pipx
python -m pipx ensurepath
pipx install uv --global
```
You can see more installation methods on the [uv installation](https://docs.astral.sh/uv/getting-started/installation/)
Then, you can run `uv --version` to check if uv is installed successfully.
```bash
uv --version
```
## Deploy DB-GPT
:::tip
If you are in the China region, you can add --index-url=https://pypi.tuna.tsinghua.edu.cn/simple at the end of the command.Like this:
```bash
uv sync --all-packages \
--extra "base" \
--extra "proxy_openai" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "dbgpts" \
--index-url=https://pypi.tuna.tsinghua.edu.cn/simple
```
And we recommend you to configure you pypi index to environment variable `UV_INDEX_URL`
example:
```bash
echo "export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple" >> ~/.bashrc
```
This tutorial assumes that you can establish network communication with the dependency download sources.
:::
### Install Dependencies
```bash
# Use uv to install dependencies needed for OpenAI proxy
uv sync --all-packages \
--extra "base" \
--extra "proxy_openai" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "dbgpts"
```
### Run Webserver
To run DB-GPT with OpenAI proxy, you must provide the OpenAI API key in the `configs/dbgpt-proxy-openai.toml` configuration file or privide it in the environment variable with key `OPENAI_API_KEY`.
```toml
# Model Configurations
[models]
[[models.llms]]
...
api_key = "your-openai-api-key"
[[models.embeddings]]
...
api_key = "your-openai-api-key"
```
Then run the following command to start the webserver:
```bash
uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml
```
In the above command, `--config` specifies the configuration file, and `configs/dbgpt-proxy-openai.toml` is the configuration file for the OpenAI proxy model, you can also use other configuration files or create your own configuration file according to your needs.
Optionally, you can also use the following command to start the webserver:
```bash
uv run python packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py --config configs/dbgpt-proxy-openai.toml
```
```bash
# Use uv to install dependencies needed for OpenAI proxy
uv sync --all-packages \
--extra "base" \
--extra "proxy_openai" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "dbgpts"
```
### Run Webserver
To run DB-GPT with DeepSeek proxy, you must provide the DeepSeek API key in the `configs/dbgpt-proxy-deepseek.toml`.
And you can specify your embedding model in the `configs/dbgpt-proxy-deepseek.toml` configuration file, the default embedding model is `BAAI/bge-large-zh-v1.5`. If you want to use other embedding models, you can modify the `configs/dbgpt-proxy-deepseek.toml` configuration file and specify the `name` and `provider` of the embedding model in the `[[models.embeddings]]` section. The provider can be `hf`.Finally, you need to append `--extra "hf"` at the end of the dependency installation command. Here's the updated command:
```bash
uv sync --all-packages \
--extra "base" \
--extra "proxy_openai" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "dbgpts" \
--extra "hf" \
--extra "cpu"
```
**Model Configurations**:
```toml
# Model Configurations
[models]
[[models.llms]]
# name = "deepseek-chat"
name = "deepseek-reasoner"
provider = "proxy/deepseek"
api_key = "your-deepseek-api-key"
[[models.embeddings]]
name = "BAAI/bge-large-zh-v1.5"
provider = "hf"
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# path = "the-model-path-in-the-local-file-system"
path = "/data/models/bge-large-zh-v1.5"
```
Then run the following command to start the webserver:
```bash
uv run dbgpt start webserver --config configs/dbgpt-proxy-deepseek.toml
```
In the above command, `--config` specifies the configuration file, and `configs/dbgpt-proxy-deepseek.toml` is the configuration file for the DeepSeek proxy model, you can also use other configuration files or create your own configuration file according to your needs.
Optionally, you can also use the following command to start the webserver:
```bash
uv run python packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py --config configs/dbgpt-proxy-deepseek.toml
```
```bash
# Use uv to install dependencies needed for GLM4
# Install core dependencies and select desired extensions
uv sync --all-packages \
--extra "base" \
--extra "cuda121" \
--extra "hf" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "quant_bnb" \
--extra "dbgpts"
```
### Run Webserver
To run DB-GPT with the local model. You can modify the `configs/dbgpt-local-glm.toml` configuration file to specify the model path and other parameters.
```toml
# Model Configurations
[models]
[[models.llms]]
name = "THUDM/glm-4-9b-chat-hf"
provider = "hf"
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# path = "the-model-path-in-the-local-file-system"
[[models.embeddings]]
name = "BAAI/bge-large-zh-v1.5"
provider = "hf"
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# path = "the-model-path-in-the-local-file-system"
```
In the above configuration file, `[[models.llms]]` specifies the LLM model, and `[[models.embeddings]]` specifies the embedding model. If you not provide the `path` parameter, the model will be downloaded from the Hugging Face model hub according to the `name` parameter.
Then run the following command to start the webserver:
```bash
uv run dbgpt start webserver --config configs/dbgpt-local-glm.toml
```
```bash
# Use uv to install dependencies needed for vllm
# Install core dependencies and select desired extensions
uv sync --all-packages \
--extra "base" \
--extra "hf" \
--extra "cuda121" \
--extra "vllm" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "quant_bnb" \
--extra "dbgpts"
```
### Run Webserver
To run DB-GPT with the local model. You can modify the `configs/dbgpt-local-vllm.toml` configuration file to specify the model path and other parameters.
```toml
# Model Configurations
[models]
[[models.llms]]
name = "THUDM/glm-4-9b-chat-hf"
provider = "vllm"
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# path = "the-model-path-in-the-local-file-system"
[[models.embeddings]]
name = "BAAI/bge-large-zh-v1.5"
provider = "hf"
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# path = "the-model-path-in-the-local-file-system"
```
In the above configuration file, `[[models.llms]]` specifies the LLM model, and `[[models.embeddings]]` specifies the embedding model. If you not provide the `path` parameter, the model will be downloaded from the Hugging Face model hub according to the `name` parameter.
Then run the following command to start the webserver:
```bash
uv run dbgpt start webserver --config configs/dbgpt-local-vllm.toml
```
If you has a Nvidia GPU, you can enable the CUDA support by setting the environment variable `CMAKE_ARGS="-DGGML_CUDA=ON"`.
```bash
# Use uv to install dependencies needed for llama-cpp
# Install core dependencies and select desired extensions
CMAKE_ARGS="-DGGML_CUDA=ON" uv sync --all-packages \
--extra "base" \
--extra "hf" \
--extra "cuda121" \
--extra "llama_cpp" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "quant_bnb" \
--extra "dbgpts"
```
Otherwise, run the following command to install dependencies without CUDA support.
```bash
# Use uv to install dependencies needed for llama-cpp
# Install core dependencies and select desired extensions
uv sync --all-packages \
--extra "base" \
--extra "hf" \
--extra "llama_cpp" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "quant_bnb" \
--extra "dbgpts"
```
### Run Webserver
To run DB-GPT with the local model. You can modify the `configs/dbgpt-local-llama-cpp.toml` configuration file to specify the model path and other parameters.
```toml
# Model Configurations
[models]
[[models.llms]]
name = "DeepSeek-R1-Distill-Qwen-1.5B"
provider = "llama.cpp"
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# path = "the-model-path-in-the-local-file-system"
[[models.embeddings]]
name = "BAAI/bge-large-zh-v1.5"
provider = "hf"
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# path = "the-model-path-in-the-local-file-system"
```
In the above configuration file, `[[models.llms]]` specifies the LLM model, and `[[models.embeddings]]` specifies the embedding model. If you not provide the `path` parameter, the model will be downloaded from the Hugging Face model hub according to the `name` parameter.
Then run the following command to start the webserver:
```bash
uv run dbgpt start webserver --config configs/dbgpt-local-llama-cpp.toml
```
```bash
# Use uv to install dependencies needed for Ollama proxy
uv sync --all-packages \
--extra "base" \
--extra "proxy_ollama" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "dbgpts"
```
### Run Webserver
To run DB-GPT with Ollama proxy, you must provide the Ollama API base in the `configs/dbgpt-proxy-ollama.toml` configuration file.
```toml
# Model Configurations
[models]
[[models.llms]]
...
api_base = "your-ollama-api-base"
[[models.embeddings]]
...
api_base = "your-ollama-api-base"
```
Then run the following command to start the webserver:
```bash
uv run dbgpt start webserver --config configs/dbgpt-proxy-ollama.toml
```
In the above command, `--config` specifies the configuration file, and `configs/dbgpt-proxy-ollama.toml` is the configuration file for the Ollama proxy model, you can also use other configuration files or create your own configuration file according to your needs.
Optionally, you can also use the following command to start the webserver:
```bash
uv run python packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py --config configs/dbgpt-proxy-ollama.toml
```
## (Optional) More Configuration
You can view the configuration in [Configuration](./config/config-reference) to learn more about
the configuration options.
For example, if you want to configure the LLM model, you can see all available options in the [LLM Configuration](./config-reference/llm/).
And another example, if you want to how to configure the vllm model, you can see all available options in the [VLLM Configuration](./config-reference/llm/vllm_adapter_vllmdeploymodelparameters_1d4a24.mdx).
## DB-GPT Install Help Tool
If you need help with the installation, you can use the `uv` script to get help.
```bash
uv run install_help.py --help
```
## Generate Install Command
You can use the `uv` script to generate the install command in the interactive mode.
```bash
uv run install_help.py install-cmd --interactive
```
And you can generate an install command with all the dependencies needed for the OpenAI proxy model.
```bash
uv run install_help.py install-cmd --all
```
You can found all the dependencies and extras.
```bash
uv run install_help.py list
```
## Visit Website
Open your browser and visit [`http://localhost:5670`](http://localhost:5670)
### (Optional) Run Web Front-end Separately
You can also run the web front-end separately:
```bash
cd web && npm install
cp .env.template .env
// Set API_BASE_URL to your DB-GPT server address, usually http://localhost:5670
npm run dev
```
Open your browser and visit [`http://localhost:3000`](http://localhost:3000)
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Config Reference Overview (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/config-reference/overview.mdx`)
---
title: "Configuration Overview"
---
# Configuration Overview
This document provides an overview of all configuration classes organized by type.
## Configuration Types
- [app](#type-app) (6 classes)
- [datasource](#type-datasource) (14 classes)
- [embedding](#type-embedding) (6 classes)
- [graph_store](#type-graph_store) (4 classes)
- [llm](#type-llm) (22 classes)
- [memory](#type-memory) (2 classes)
- [other](#type-other) (1 classes)
- [reranker](#type-reranker) (3 classes)
- [serve](#type-serve) (13 classes)
- [service](#type-service) (1 classes)
- [utils](#type-utils) (2 classes)
- [vector_store](#type-vector_store) (6 classes)
## Type Details
### app {#type-app}
This type contains 6 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [ChatDashboardConfig](app/config_chatdashboardconfig_2480d0) | |
| [ChatExcelConfig](app/config_chatexcelconfig_8dcf86) | |
| [ChatKnowledgeConfig](app/config_chatknowledgeconfig_d51d9e) | |
| [ChatNormalConfig](app/config_chatnormalconfig_83c865) | |
| [ChatWithDBExecuteConfig](app/config_chatwithdbexecuteconfig_64fe0f) | |
| [ChatWithDBQAConfig](app/config_chatwithdbqaconfig_62cbe4) | |
---
### datasource {#type-datasource}
This type contains 14 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [ClickhouseParameters](datasource/conn_clickhouse_clickhouseparameters_4a1237) | |
| [DorisParameters](datasource/conn_doris_dorisparameters_e33c53) | |
| [DuckDbConnectorParameters](datasource/conn_duckdb_duckdbconnectorparameters_c672c7) | |
| [HiveParameters](datasource/conn_hive_hiveparameters_ec3601) | |
| [MSSQLParameters](datasource/conn_mssql_mssqlparameters_d79d1c) | |
| [MySQLParameters](datasource/conn_mysql_mysqlparameters_4393c4) | |
| [OceanBaseParameters](datasource/conn_oceanbase_oceanbaseparameters_260d2d) | |
| [PostgreSQLParameters](datasource/conn_postgresql_postgresqlparameters_22efa5) | |
| [RDBMSDatasourceParameters](datasource/base_rdbmsdatasourceparameters_4f774f) | |
| [SQLiteConnectorParameters](datasource/conn_sqlite_sqliteconnectorparameters_82c8b5) | |
| [SparkParameters](datasource/conn_spark_sparkparameters_174bbc) | |
| [StarRocksParameters](datasource/conn_starrocks_starrocksparameters_e511f7) | |
| [TuGraphParameters](datasource/conn_tugraph_tugraphparameters_0c844e) | |
| [VerticaParameters](datasource/conn_vertica_verticaparameters_c712b8) | |
---
### embedding {#type-embedding}
This type contains 6 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [HFEmbeddingDeployModelParameters](embedding/embeddings_hfembeddingdeploymodelparameters_f588e1) | |
| [JinaEmbeddingsDeployModelParameters](embedding/jina_jinaembeddingsdeploymodelparameters_40b0f2) | |
| [OllamaEmbeddingDeployModelParameters](embedding/ollama_ollamaembeddingdeploymodelparameters_b511e0) | |
| [OpenAPIEmbeddingDeployModelParameters](embedding/embeddings_openapiembeddingdeploymodelparameters_f9ba47) | |
| [QianfanEmbeddingDeployModelParameters](embedding/qianfan_qianfanembeddingdeploymodelparameters_257d2a) | |
| [TongyiEmbeddingDeployModelParameters](embedding/tongyi_tongyiembeddingdeploymodelparameters_a7cbb4) | |
---
### graph_store {#type-graph_store}
This type contains 4 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [BuiltinKnowledgeGraphConfig](graph_store/knowledge_graph_builtinknowledgegraphconfig_f26e05) | |
| [Neo4jStoreConfig](graph_store/neo4j_store_neo4jstoreconfig_a4db5d) | |
| [OpenSPGConfig](graph_store/open_spg_openspgconfig_a744fd) | |
| [TuGraphStoreConfig](graph_store/tugraph_store_tugraphstoreconfig_7ca8a8) | |
---
### llm {#type-llm}
This type contains 22 configuration classes.
#### Relationships
```mermaid
graph TD
HFLLMDeployModelParameters -->|quantization| BitsandbytesQuantization
HFLLMDeployModelParameters -->|quantization| BitsandbytesQuantization8bits
HFLLMDeployModelParameters -->|quantization| BitsandbytesQuantization4bits
```
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [BaichuanDeployModelParameters](llm/baichuan_baichuandeploymodelparameters_0bf9cc) | |
| [BitsandbytesQuantization](llm/parameter_bitsandbytesquantization_d40e3b) | |
| [BitsandbytesQuantization4bits](llm/parameter_bitsandbytesquantization4bits_52b778) | |
| [BitsandbytesQuantization8bits](llm/parameter_bitsandbytesquantization8bits_909aed) | |
| [ClaudeDeployModelParameters](llm/claude_claudedeploymodelparameters_1f0c45) | |
| [DeepSeekDeployModelParameters](llm/deepseek_deepseekdeploymodelparameters_194cbd) | |
| [GeminiDeployModelParameters](llm/gemini_geminideploymodelparameters_5113b9) | |
| [GiteeDeployModelParameters](llm/gitee_giteedeploymodelparameters_d1bdb3) | |
| [HFLLMDeployModelParameters](llm/hf_adapter_hfllmdeploymodelparameters_103e81) | |
| [LlamaCppModelParameters](llm/llama_cpp_py_adapter_llamacppmodelparameters_e88874) | |
| [LlamaServerParameters](llm/llama_cpp_adapter_llamaserverparameters_421f40) | |
| [MoonshotDeployModelParameters](llm/moonshot_moonshotdeploymodelparameters_aa2f6b) | |
| [OllamaDeployModelParameters](llm/ollama_ollamadeploymodelparameters_d55be6) | |
| [OpenAICompatibleDeployModelParameters](llm/chatgpt_openaicompatibledeploymodelparameters_c3d426) | |
| [SiliconFlowDeployModelParameters](llm/siliconflow_siliconflowdeploymodelparameters_abe22f) | |
| [SparkDeployModelParameters](llm/spark_sparkdeploymodelparameters_afba3c) | |
| [TongyiDeployModelParameters](llm/tongyi_tongyideploymodelparameters_02a91b) | |
| [VLLMDeployModelParameters](llm/vllm_adapter_vllmdeploymodelparameters_1d4a24) | |
| [VolcengineDeployModelParameters](llm/volcengine_volcenginedeploymodelparameters_938015) | |
| [WenxinDeployModelParameters](llm/wenxin_wenxindeploymodelparameters_63c66b) | |
| [YiDeployModelParameters](llm/yi_yideploymodelparameters_92dbaa) | |
| [ZhipuDeployModelParameters](llm/zhipu_zhipudeploymodelparameters_c51e31) | |
---
### memory {#type-memory}
This type contains 2 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [BufferWindowGPTsAppMemoryConfig](memory/config_bufferwindowgptsappmemoryconfig_c31071) | |
| [TokenBufferGPTsAppMemoryConfig](memory/config_tokenbuffergptsappmemoryconfig_6a2000) | |
---
### other {#type-other}
This type contains 1 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [ApplicationConfig](config_applicationconfig_72fd1c) | |
---
### reranker {#type-reranker}
This type contains 3 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [CrossEncoderRerankEmbeddingsParameters](reranker/rerank_crossencoderrerankembeddingsparameters_63ec13) | |
| [OpenAPIRerankerDeployModelParameters](reranker/rerank_openapirerankerdeploymodelparameters_778108) | |
| [SiliconFlowRerankEmbeddingsParameters](reranker/rerank_siliconflowrerankembeddingsparameters_af0257) | |
---
### serve {#type-serve}
This type contains 13 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [ServeConfig](serve/config_serveconfig_63f1e9) | |
| [ServeConfig](serve/config_serveconfig_adbd6f) | |
| [ServeConfig](serve/config_serveconfig_313252) | |
| [ServeConfig](serve/config_serveconfig_ec2d70) | |
| [ServeConfig](serve/config_serveconfig_1a9284) | |
| [ServeConfig](serve/config_serveconfig_8839e0) | |
| [ServeConfig](serve/config_serveconfig_fa1f35) | |
| [ServeConfig](serve/config_serveconfig_cb64c6) | |
| [ServeConfig](serve/config_serveconfig_c0b589) | |
| [ServeConfig](serve/config_serveconfig_b1c2b9) | |
| [ServeConfig](serve/config_serveconfig_7a0577) | |
| [ServeConfig](serve/config_serveconfig_854dad) | |
| [ServeConfig](serve/config_serveconfig_7889f9) | |
---
### service {#type-service}
This type contains 1 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [DBModelRegistryParameters](service/parameter_dbmodelregistryparameters_87d036) | |
---
### utils {#type-utils}
This type contains 2 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [OSSStorageConfig](utils/config_ossstorageconfig_1ad505) | |
| [S3StorageConfig](utils/config_s3storageconfig_f0cdc9) | |
---
### vector_store {#type-vector_store}
This type contains 6 configuration classes.
#### Configuration Classes
| Class | Description |
|-------|-------------|
| [ChromaVectorConfig](vector_store/chroma_store_chromavectorconfig_16224f) | |
| [ElasticsearchStoreConfig](vector_store/elastic_store_elasticsearchstoreconfig_15bdb6) | |
| [MilvusVectorConfig](vector_store/milvus_store_milvusvectorconfig_20af52) | |
| [OceanBaseConfig](vector_store/oceanbase_store_oceanbaseconfig_220e36) | |
| [PGVectorConfig](vector_store/pgvector_store_pgvectorconfig_3ef448) | |
| [WeaviateVectorConfig](vector_store/weaviate_store_weaviatevectorconfig_093ce3) | |
---
## Cross-Type Relationships
The following diagram shows relationships between different configuration types:
```mermaid
graph TD
other[other - 1 classes]
datasource[datasource - 14 classes]
llm[llm - 22 classes]
embedding[embedding - 6 classes]
reranker[reranker - 3 classes]
service[service - 1 classes]
graph_store[graph_store - 4 classes]
vector_store[vector_store - 6 classes]
serve[serve - 13 classes]
memory[memory - 2 classes]
app[app - 6 classes]
utils[utils - 2 classes]
service -->|14 connections| datasource
other -->|13 connections| serve
serve -->|2 connections| utils
app -->|14 connections| memory
```
## Looking for a specific configuration?
1. Use the search function in the documentation site
2. Browse the configuration types above
3. Check the specific class documentation for detailed parameter information
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Getting Started Cli Quickstart (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/cli-quickstart.md`)
---
sidebar_position: 1
title: CLI 安装
summary: "通过 PyPI 安装 DB-GPT，并用单条命令启动它，无需源码 checkout"
read_when:
- 你想直接从 PyPI 安装 DB-GPT
- 你希望通过 `dbgpt` CLI 完成交互式配置
---
# CLI 安装
通过 PyPI 安装 DB-GPT，并使用单条命令启动它 —— 无需检出源码仓库。
:::tip 前置条件
- Python **3.10** 或更高版本
- 推荐使用 [uv](https://docs.astral.sh/uv/getting-started/installation/) 包管理器，也支持 pip
:::
## 1. 安装
```bash
# 推荐：使用 uv
uv pip install dbgpt-app
# 或者使用 pip
pip install dbgpt-app
```
:::tip 配置 PyPI 镜像源
如果下载速度较慢，可在安装时指定镜像源加速：
```bash
uv pip install dbgpt-app --index-url https://pypi.tuna.tsinghua.edu.cn/simple # uv
pip install dbgpt-app -i https://pypi.tuna.tsinghua.edu.cn/simple # pip
```
也可以通过环境变量，让当前终端会话中的**所有**安装命令自动使用镜像源：
```bash
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple # uv
export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple # pip
```
:::
:::info 默认包含内容
默认安装会包含 **核心框架**（CLI、FastAPI、SQLAlchemy、Agent）、**OpenAI 兼容 LLM 支持**（也适用于 Kimi、Qwen、MiniMax、Z.AI）、**DashScope / Tongyi** 支持、**RAG 文档解析** 和 **ChromaDB** 向量存储。
如果你需要更多 provider 或数据源，可参考 [可选模块](#8-可选模块)。
:::
安装完成后，终端中就可以直接使用 `dbgpt` 命令。
## 2. 启动 DB-GPT
```bash
dbgpt start
```
首次运行时，DB-GPT 会自动启动一个 **交互式配置向导**，帮助你：
1. 选择 LLM provider（OpenAI、Kimi、Qwen、MiniMax、Z.AI 或自定义 endpoint）
2. 输入 API Key（或改用环境变量）
3. 确认模型名称和 API Base URL
完成后，系统会把 TOML 配置写入 `~/.dbgpt/configs/.toml`，并自动启动 webserver。
### 启动后的样子
```
____ ____ ____ ____ _____
| _ \| __ ) / ___| _ \_ _|
| | | | _ \ ____| | _| |_) || |
| |_| | |_) |____| |_| | __/ | |
|____/|____/ \____|_| |_|
🚀 DB-GPT Quick Start
+- - - - - - - - - - - - - - - - - - - - - - - -+
: Profile: openai :
: Config: /Users/you/.dbgpt/configs/openai.toml:
: Workspace: /Users/you/.dbgpt/workspace :
+- - - - - - - - - - - - - - - - - - - - - - - -+
```
## 3. 打开 Web UI
然后打开 [http://localhost:5670](http://localhost:5670)。
---
## 4. 命令参考
### 总览
```
dbgpt [OPTIONS] COMMAND [ARGS]...
Options:
--log-level TEXT Log level (default: warn)
--version Show version and exit
--help Show help message
Commands:
start Start the DB-GPT server
stop Stop a running server
setup Configure LLM provider (interactive wizard or CI mode)
profile Manage configuration profiles
knowledge Knowledge base operations
model Manage model serving
db Database management and migration
...
```
---
### `dbgpt start`
启动 DB-GPT web server。直接运行 `dbgpt start` 等价于 `dbgpt start web`。
#### 子命令
| 子命令 | 说明 |
|---|---|
| `web`（或 `webserver`） | 启动 web server（默认） |
| `none` | 仅 API 模式 —— *未来版本计划支持* |
| `controller` | 启动模型 controller |
| `worker` | 启动模型 worker |
| `apiserver` | 启动 API server |
#### `dbgpt start web` 参数
| 参数 | Short | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `--config` | `-c` | PATH | *auto* | TOML 配置文件路径。若未提供，则使用当前 active profile，或自动启动配置向导。 |
| `--profile` | `-p` | TEXT | *active* | Provider profile 名称（`openai`、`kimi`、`qwen`、`minimax`、`glm`、`custom`）。会覆盖当前 active profile。 |
| `--yes` | `-y` | FLAG | false | 非交互模式：跳过向导，直接使用默认值 / 环境变量，适合 CI/CD。 |
| `--api-key` | | TEXT | *env* | 指定 provider 的 API key，也可通过对应环境变量提供。 |
| `--daemon` | `-d` | FLAG | false | 后台守护进程方式运行。可通过 `dbgpt stop webserver` 停止。 |
#### 示例
```bash
# 首次运行，使用交互式向导
dbgpt start
# 使用现有 profile
dbgpt start web --profile openai
# 非交互方式并显式传入 API key
dbgpt start web --profile kimi --api-key sk-xxx --yes
# 使用指定配置文件
dbgpt start web --config /path/to/my-config.toml
# 以 daemon 方式运行
dbgpt start web --daemon
```
#### 配置解析优先级
启动 web server 时，配置文件的解析顺序如下：
1. **`--config` 参数** —— 如果提供，直接使用这个文件
2. **`--profile` 参数** —— 查找 `~/.dbgpt/configs/.toml`
3. **Active profile** —— 从 `~/.dbgpt/config.toml` 中读取
4. **配置向导** —— 如果还没有配置，则自动启动交互式向导
---
### `dbgpt stop`
停止正在运行的 DB-GPT 服务进程。
```bash
# 停止 web server
dbgpt stop webserver
# 停止指定端口上的 web server
dbgpt stop webserver --port 5670
# 停止所有服务
dbgpt stop all
```
---
### `dbgpt setup`
交互式配置 LLM provider，或用于非交互 / CI 模式配置。这个命令会把 TOML 配置写入 `~/.dbgpt/configs/.toml`，并将它标记为 active profile。
#### 参数
| 参数 | Short | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `--profile` | `-p` | TEXT | *interactive* | 要配置的 provider profile。若省略，则显示交互菜单。 |
| `--yes` | `-y` | FLAG | false | 非交互模式：跳过向导并使用默认值。 |
| `--api-key` | | TEXT | *env* | API key，也会读取 `DBGPT_API_KEY` 环境变量。 |
| `--show` | | FLAG | false | 显示当前 active profile 和配置路径后退出。 |
#### 示例
```bash
# 交互式向导
dbgpt setup
# 非交互：使用 OpenAI + 环境变量
export OPENAI_API_KEY=sk-xxx
dbgpt setup --profile openai --yes
# 非交互：显式传入 key
dbgpt setup --profile kimi --api-key sk-xxx
# 查看当前配置
dbgpt setup --show
```
---
### `dbgpt profile`
管理多个配置 profile。每个 profile 都是 `~/.dbgpt/configs/` 下的一个 TOML 文件。
#### 子命令
| 子命令 | 说明 |
|---|---|
| `list` | 列出所有 profile，active 的会用 `*` 标记 |
| `show ` | 显示某个 profile 的 TOML 内容 |
| `create ` | 使用配置向导创建（或重新配置）一个 profile |
| `switch ` | 将某个 profile 设为当前默认 |
| `delete ` | 删除某个 profile 配置文件 |
#### 示例
```bash
# 列出所有 profile
dbgpt profile list
# openai ← no asterisk
# * kimi ← active
# 查看 profile 内容
dbgpt profile show openai
# 创建新 profile
dbgpt profile create qwen
# 切换 active profile
dbgpt profile switch openai
# 删除 profile
dbgpt profile delete minimax
dbgpt profile delete minimax --yes # 跳过确认
```
---
## 5. 支持的 Providers
配置向导和 `--profile` 参数支持以下 provider：
| Profile 名称 | 显示名称 | LLM 模型 | Embedding 模型 | API Key 环境变量 |
|---|---|---|---|---|
| `openai` | OpenAI | gpt-4o | text-embedding-3-small | `OPENAI_API_KEY` |
| `kimi` | Kimi | kimi-k2 | text-embedding-v3 | `MOONSHOT_API_KEY`（embedding 同时需要 `DASHSCOPE_API_KEY`） |
| `qwen` | Qwen | qwen-plus | text-embedding-v3 | `DASHSCOPE_API_KEY` |
| `minimax` | MiniMax | abab6.5s-chat | embo-01 | `MINIMAX_API_KEY` |
| `glm` | Z.AI | glm-4-plus | embedding-3 | `ZHIPUAI_API_KEY` |
| `custom` | Custom | gpt-4o | text-embedding-3-small | `OPENAI_API_KEY` |
:::info
**Custom** profile 可以连接任意 OpenAI 兼容 API endpoint。在向导中你会被要求输入 API Base URL。
:::
---
## 6. 目录结构
首次运行后，DB-GPT 会在用户目录下创建如下结构：
```
~/.dbgpt/
├── config.toml # 记录当前 active profile 名称
├── configs/
│ ├── openai.toml # OpenAI profile
│ ├── kimi.toml # Kimi profile
│ └── ... # 每个 profile 对应一个文件
└── workspace/
└── pilot/ # 运行时工作区（数据库、数据文件等）
├── meta_data/
│ └── dbgpt.db # SQLite 元数据库
└── data/ # 向量数据存储
```
### 环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
| `DBGPT_HOME` | `~/.dbgpt` | 覆盖 DB-GPT home 目录 |
| `OPENAI_API_KEY` | — | OpenAI API key（也用于 `openai` 和 `custom` profile） |
| `MOONSHOT_API_KEY` | — | Kimi / Moonshot API key |
| `DASHSCOPE_API_KEY` | — | Qwen / DashScope API key（也用于 Kimi embedding） |
| `MINIMAX_API_KEY` | — | MiniMax API key |
| `ZHIPUAI_API_KEY` | — | Z.AI / Zhipu API key |
| `DBGPT_API_KEY` | — | 通用 API key（`--api-key` 的 fallback） |
| `DBGPT_LANG` | `en` | UI 语言（`en` 或 `zh`） |
---
## 7. 常见工作流
### 首次安装
```bash
pip install dbgpt-app
dbgpt start
# Follow the wizard → choose provider → enter API key → server starts
```
### 在不同 provider 间切换
```bash
# 创建一个 Kimi profile
dbgpt profile create kimi
# 切换到它
dbgpt profile switch kimi
# 使用新 profile 启动
dbgpt start
```
### CI/CD 部署
```bash
export OPENAI_API_KEY=sk-xxx
dbgpt setup --profile openai --yes
dbgpt start web --daemon
```
### 自定义 endpoint（例如 Azure OpenAI、local vLLM）
```bash
dbgpt setup --profile custom
# Wizard will ask for:
# - API base URL (e.g. http://localhost:8000/v1)
# - API key
# - Model names
```
---
## 8. 可选模块
默认 `pip install dbgpt-app` 会包含核心框架。你也可以通过 extras 为 LLM provider、vector store、data source 等增加能力。
### LLM Providers
| Extra | Provider | 关键包 |
|-------|----------|-------------|
| `proxy_openai` | OpenAI、Kimi、Qwen、MiniMax、Z.AI 以及任意 OpenAI-compatible API | `openai`, `tiktoken` |
| `proxy_ollama` | Ollama（本地模型） | `ollama` |
| `proxy_zhipuai` | Zhipu AI（GLM） | `openai` |
| `proxy_tongyi` | Tongyi Qianwen | `openai`, `dashscope` |
| `proxy_qianfan` | 百度千帆 | `qianfan` |
| `proxy_anthropic` | Anthropic Claude | `anthropic` |
### Vector Stores
| Extra | 存储 | 关键包 |
|-------|---------|-------------|
| `storage_chromadb` | ChromaDB | `chromadb`, `onnxruntime` |
| `storage_milvus` | Milvus | `pymilvus` |
| `storage_weaviate` | Weaviate | `weaviate-client` |
| `storage_elasticsearch` | Elasticsearch | `elasticsearch` |
| `storage_obvector` | OBVector | `pyobvector` |
### Knowledge & RAG
| Extra | 增加能力 | 关键包 |
|-------|-------------|-------------|
| `rag` | 文档解析（PDF、DOCX、PPTX、Markdown、HTML） | `spacy`, `pypdf`, `python-docx`, `python-pptx` |
| `graph_rag` | 基于 TuGraph / Neo4j 的 Graph RAG | `networkx`, `neo4j` |
### Data Sources
| Extra | 数据库 | 关键包 |
|-------|----------|-------------|
| `datasource_mysql` | MySQL | `mysqlclient` |
| `datasource_postgres` | PostgreSQL | `psycopg2-binary` |
| `datasource_clickhouse` | ClickHouse | `clickhouse-connect` |
| `datasource_oracle` | Oracle | `oracledb` |
| `datasource_mssql` | SQL Server | `pymssql` |
| `datasource_spark` | Apache Spark | `pyspark` |
| `datasource_hive` | Hive | `pyhive` |
| `datasource_vertica` | Vertica | `vertica-python` |
### 组合多个 extras 的示例
```bash
# OpenAI + ChromaDB + RAG + MySQL
pip install "dbgpt-app[proxy_openai,storage_chromadb,rag,datasource_mysql]"
```
:::tip 最小安装
如果你只需要核心框架而不需要任何 LLM 或存储支持：
```bash
pip install dbgpt-app
```
这会提供 CLI、FastAPI server 和 agent framework，但要真正使用它，至少还需要安装一个 LLM provider extra。
:::
---
## 9. 故障排查
### 端口已被占用
```bash
# 停止已有 web server
dbgpt stop webserver --port 5670
# 或改配置文件换端口
# [service.web]
# port = 5671
```
### 提示 “No config file found”
这说明当前还没有配置任何 profile，请运行：
```bash
dbgpt setup
```
### 更换 API Key
重新对同一个 profile 运行 setup 向导即可覆盖原配置：
```bash
dbgpt setup --profile openai
# 或者直接编辑 ~/.dbgpt/configs/openai.toml
```
### 查看当前配置
```bash
dbgpt setup --show
dbgpt profile show openai
```
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Getting Started Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/index.md`)
---
sidebar_position: 0
title: DB-GPT
summary: "快速开始总览：了解 DB-GPT、最短上手路径，以及下一步阅读建议"
read_when:
- 你希望从 clone 仓库到跑通 DB-GPT 对话，走最短路径
- 你希望在深入之前先了解核心文档地图
---
# DB-GPT
DB-GPT 是一个开源框架，用于构建结合 **LLM、RAG、智能体、AWEL 工作流与数据库集成** 的 AI Native 数据应用。
如果你想最快跑通：选择一个 API 模型提供方，启动 webserver，然后打开 Web UI。
## 最快路径
1. 检查环境要求：[前置条件](/docs/getting-started/prerequisites)
2. 按 5 分钟上手流程操作：[快速开始](/docs/getting-started/quick-start)
3. 选择模型提供方：[模型提供方](/docs/getting-started/providers/)
4. 确认 UI 能在 `http://localhost:5670` 打开
## 快速开始
```bash
# 1. 克隆仓库
git clone https://github.com/eosphoros-ai/DB-GPT.git
cd DB-GPT
# 2. 安装依赖（以 OpenAI 代理模式为例）
uv sync --all-packages \
--extra "base" \
--extra "proxy_openai" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "dbgpts"
# 3. 配置 API Key
# 编辑 configs/dbgpt-proxy-openai.toml 并设置 api_key
# 4. 启动服务
uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml
```
打开浏览器访问 [http://localhost:5670](http://localhost:5670)。
如果 UI 能正常打开，并且你可以发起对话，说明基础环境已经可用。
## DB-GPT 包含什么
- **SMMF**：模型管理与提供方切换
- **RAG**：文档与知识检索
- **Agents**：工具调用、任务规划与多智能体协作
- **AWEL**：基于 DAG 的工作流编排
- **Data sources**：SQL、分析与 Text2SQL 场景的数据源能力
## 接下来读什么
- **核心概念**
- [架构](/docs/getting-started/concepts/architecture)
- [AWEL](/docs/getting-started/concepts/awel)
- [智能体](/docs/getting-started/concepts/agents)
- [RAG](/docs/getting-started/concepts/rag)
- **安装与部署**
- [模型提供方](/docs/getting-started/providers/)
- [源码部署](/docs/getting-started/deploy/source-code)
- [Docker 部署](/docs/getting-started/deploy/docker)
- **产品使用**
- [Web UI 概览](/docs/getting-started/web-ui/)
- [工具与插件](/docs/getting-started/tools/)
- [故障排查](/docs/getting-started/troubleshooting/)
- **参考资料**
- [开发指南](/docs/agents/introduction/)
- [API 参考](/docs/api/introduction)
- [配置参考](/docs/config/config-reference)
- [FAQ](/docs/faq/install)
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Installation Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/installation/index.md`)
---
sidebar_position: 0
title: 安装概览
summary: "选择最适合你的 DB-GPT 安装方式：快速安装、CLI 安装或源码安装"
read_when:
- 你想判断哪种安装路径最适合当前环境
- 你希望以最短路径完成可用的 DB-GPT 安装
---
# 安装概览
DB-GPT 提供三种推荐安装方式。你可以根据自己的使用方式和环境选择最合适的路径。
## 选择安装方式
| 方式 | 适合人群 | 场景 | 你会得到什么 |
|:-----|:---------|:-----|:---------------------------------------------|
| [快速安装](/docs/installation/quick-install) | 希望在 macOS / Linux 上最快完成首次启动的用户 | 从源码快速启动最新版 DB-GPT，自动完成环境配置和依赖安装 | 通过脚本快速安装并启动最新的源项目，还可选择进行高级配置（基于源码快速体验） |
| [CLI 安装](/docs/getting-started/cli-quickstart) | 希望通过 PyPI 安装并使用命令行的用户 | 一键启动并体验稳定版 DB-GPT，无需关心项目结构或配置细节 | 通过`dbgpt` CLI一键启动、交互式安装向导、配置文件管理（基于稳定版本快速体验） |
| [源码安装](/docs/getting-started/deploy/source-code) | 开发者或需要自定义部署的用户 | 需要修改源码、调试内部逻辑，或将 DB-GPT 集成到自定义部署流程中 | 完整源码仓库、自定义高级配置、给予开发者最大灵活性（自定义配置和二次开发） |
## 什么时候选择哪种方式
### 快速安装
MacOS / Linux 用户，如果你想以最少步骤完成安装，从源码快速启动最新版 DB-GPT，自动完成环境配置和依赖安装，选择这种方式。
### CLI 安装（推荐）
如果你想直接通过 PyPI 安装 DB-GPT，并用 `dbgpt` 命令交互式配置 provider profile，选择这种方式。
### 源码安装
如果你需要完整仓库用于开发、调试或自定义集成，选择这种方式。
## 下一步
- [快速安装](/docs/installation/quick-install)
- [CLI 安装](/docs/getting-started/cli-quickstart)
- [源码安装](/docs/getting-started/deploy/source-code)
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Sandbox Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/sandbox/index.md`)
---
sidebar_position: 0
title: Sandbox Overview
---
# Sandbox 总览
DB-GPT 使用 sandbox（沙箱）让智能体在隔离的运行环境中执行代码和工具，而不是直接在宿主机环境中运行。
这对 agent 工作流非常重要，因为智能体往往不仅仅需要文本推理，还需要：
- 执行代码
- 运行 shell 命令
- 安装依赖
- 生成文件
- 在多轮执行之间保持状态
Sandbox 就是把这些执行能力放在一个更安全、可控、可管理的边界内。
## 什么是 sandbox？
在 DB-GPT 中，sandbox 是一个隔离执行环境，供智能体在任务过程中执行代码、运行命令、处理文件或调用执行型工具。
它避免智能体直接操作宿主机，并提供：
- 进程隔离
- 资源限制
- 可控工作目录
- 可选依赖安装能力
- 会话生命周期管理
- 清晰的“推理”和“执行”边界
## Sandbox 如何作用于 agent
智能体负责决定**下一步做什么**，sandbox 负责安全地执行**这个动作怎么运行**。
```mermaid
flowchart TB
User["用户 / UI"] --> API["dbgpt-app API"]
API --> Agent["ReAct Agent / Agent Logic"]
Agent --> Decide["选择工具或代码动作"]
Decide --> Sandbox["Sandbox Runtime"]
subgraph SandboxLayer["Sandbox 执行层"]
Session["Session 生命周期"]
Exec["代码 / shell 执行"]
Files["文件与报告生成"]
Limits["内存 / CPU / 超时 / 隔离"]
end
Sandbox --> Session
Sandbox --> Exec
Sandbox --> Files
Sandbox --> Limits
Exec --> Observation["执行结果 / observation"]
Observation --> Agent
Agent --> Result["最终答案 / 报告 / UI 输出"]
```
## 为什么 agent 需要 sandbox
如果智能体可以不受限制地直接执行代码，那么在真实环境中很难安全落地。Sandbox 为 DB-GPT 提供了一个专门的执行层，用于支持：
- 代码执行
- shell 命令执行
- 依赖安装
- 文件创建与读取
- 多步骤、有状态的数据分析
这对数据分析、报表生成和工具驱动型工作流尤其重要，因为这些场景需要把推理和真实执行结合起来。
## DB-GPT 当前的 sandbox 方案
DB-GPT 当前的 sandbox 实现位于：
- `packages/dbgpt-sandbox/`
它是一个分层的、可扩展的沙箱运行时系统，支持多种 backend。
### Runtime backends
当前应用侧 Agent 集成默认使用 LocalRuntime。容器执行需要通过
SANDBOX_RUNTIME=docker（或显式选择 Podman/Nerdctl）开启。如果配置的容器运行时
无法初始化或会话创建失败，Agent 执行器会返回错误，不会在本地执行用户代码。
LocalRuntime 是默认值，而不是故障兜底，且不提供容器隔离。
关于配置、镜像要求、执行生命周期和验证命令，请参阅
[Sandbox 运行时配置](./runtime)。
实现锚点：
- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/execution_layer/runtime_factory.py`
Docker 不会因为已经安装在机器上就自动启用。这样默认安装无需预先构建 Agent 镜像，
同时允许部署方显式选择容器执行。
## `dbgpt-sandbox` 的分层架构
### 1. Execution layer
执行层提供具体 runtime 实现与核心抽象：
- `base.py`：定义 runtime / session / result / config 等公共接口
- `docker_runtime.py`、`podman_runtime.py`、`nerdctl_runtime.py`、`local_runtime.py`：具体运行时实现
- `runtime_factory.py`：负责自动选择 backend
### 2. Control layer
控制层负责任务生命周期与执行编排。
实现锚点：
- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/control_layer/control_layer.py`
它处理的操作包括：
- connect
- configure
- execute
- status
- disconnect
- get file
同时也负责 session 创建与基于 session 的执行调度。
### 3. User layer
用户层对外暴露 sandbox 服务接口。
实现锚点：
- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/user_layer/service.py`
- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/user_layer/schemas.py`
### 4. Display layer
显示层用于封装运行时相关的展示结果或文件型结果。
实现锚点：
- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/display_layer/display_layer.py`
## Session 模型与有状态执行
DB-GPT 当前 sandbox 设计的一个重要点，是支持**基于 session 的有状态执行**。
这意味着：
- sandbox session 可以先创建一次
- 多个执行步骤可以复用同一个 session
- 上一步安装的依赖在后续步骤中仍然可用
- 前一步生成的文件也可以在后一步继续使用
这非常适合 agent 场景，因为很多任务不是一次工具调用就完成，而是需要多轮“推理 -> 执行 -> 观察”。
## DB-GPT app 中当前的接入方式
目前 DB-GPT 已经在应用侧 agent 工具里实际使用了 sandbox。
例如：
- `packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/agentic_data_api.py`
中的 `shell_interpreter` 工具，就使用了 `dbgpt-sandbox` 的 `LocalRuntime` 执行 shell 命令，并具备：
- 进程隔离
- 内存限制
- 超时限制
- 安全校验
当前这里的实现是**单次调用无状态**的：每次工具调用都会创建一个临时 sandbox session，执行结束后销毁。
因此仓库里实际上同时存在两层能力：
- `dbgpt-sandbox` 中更完整的、可复用 session 的 sandbox 设计
- `dbgpt-app` 中已经在实际工具执行里接入的 sandbox 用法
## DB-GPT 当前支持的方向
基于当前 `dbgpt-sandbox` 实现，DB-GPT 正在走向一个更通用的 agent 执行运行时，支持：
- 多 runtime 的 sandbox 执行
- 安全代码与 shell 执行
- 有状态 session
- sandbox 内依赖安装
- 任务生命周期控制
- 文件读取与产物管理
这使得 sandbox 很适合支撑：
- 代码 agent
- 数据分析 agent
- 报告生成 agent
- 未来扩展到 browser / computer 风格运行时
## 当前 DB-GPT sandbox 方向图
```mermaid
flowchart TB
Apps["Agent applications"] --> Access["接入层"]
Access --> Runtime["Agent sandbox runtime"]
subgraph AccessLayer["接入层"]
SDK["SDK / API / CLI"]
end
subgraph RuntimeLayer["Sandbox runtime"]
Code["代码执行"]
Browser["Browser / GUI 风格执行"]
SessionMgmt["生命周期 / 快照 / 状态 / 文件"]
Isolation["隔离 / 限制 / runtime 选择"]
end
Runtime --> Code
Runtime --> Browser
Runtime --> SessionMgmt
Runtime --> Isolation
```
这张图是概念性的，表示 sandbox 作为 agent 应用之下的专门运行时层。当前仓库已经在 `dbgpt-sandbox` 中具备 execution、control、session 和 runtime selection 的基础能力。
## 关键实现锚点
- `packages/dbgpt-sandbox/README.md`
- `packages/dbgpt-sandbox/src/docs/architecture.md`
- `packages/dbgpt-sandbox/src/docs/usage.md`
- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/execution_layer/runtime_factory.py`
- `packages/dbgpt-sandbox/src/dbgpt_sandbox/sandbox/control_layer/control_layer.py`
- `packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/agentic_data_api.py`
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Tutorials Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/tutorials/index.md`)
# Tutorial for DB-GPT
Some video tutorials for the DB-GPT project, through these tutorials, you can understand the DB-GPT project better.
## DB-GPT introduction
On this page, we will give you some introduction about DB-GPT that can help you learn about it.
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Config Reference App Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/config-reference/app/index.mdx`)
---
title: "app"
description: "app Configuration"
---
# app Configuration
This document provides an overview of all configuration classes in app type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Config Reference Datasource Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/config-reference/datasource/index.mdx`)
---
title: "datasource"
description: "datasource Configuration"
---
# datasource Configuration
This document provides an overview of all configuration classes in datasource type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Config Reference Embedding Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/config-reference/embedding/index.mdx`)
---
title: "embedding"
description: "embedding Configuration"
---
# embedding Configuration
This document provides an overview of all configuration classes in embedding type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
, encode_kwargs: Dict[str, Any] = , embed_instruction: Optional[str] = None, query_instruction: Optional[str] = None)",
"link": "./embeddings_hfembeddingdeploymodelparameters_f588e1"
},
{
"name": "JinaEmbeddingsDeployModelParameters",
"description": "Jina AI Embeddings deploy model parameters.",
"link": "./jina_jinaembeddingsdeploymodelparameters_40b0f2"
},
{
"name": "OllamaEmbeddingDeployModelParameters",
"description": "Ollama Embeddings deploy model parameters.",
"link": "./ollama_ollamaembeddingdeploymodelparameters_b511e0"
},
{
"name": "OpenAPIEmbeddingDeployModelParameters",
"description": "OpenAPI embedding deploy model parameters.",
"link": "./embeddings_openapiembeddingdeploymodelparameters_f9ba47"
},
{
"name": "QianfanEmbeddingDeployModelParameters",
"description": "Qianfan Embeddings deploy model parameters.",
"link": "./qianfan_qianfanembeddingdeploymodelparameters_257d2a"
},
{
"name": "TongyiEmbeddingDeployModelParameters",
"description": "Qianfan Embeddings deploy model parameters.",
"link": "./tongyi_tongyiembeddingdeploymodelparameters_a7cbb4"
},
]} />
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Config Reference Graph Store Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/config-reference/graph_store/index.mdx`)
---
title: "graph_store"
description: "graph_store Configuration"
---
# graph_store Configuration
This document provides an overview of all configuration classes in graph_store type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Config Reference Llm Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/config-reference/llm/index.mdx`)
---
title: "llm"
description: "llm Configuration"
---
# llm Configuration
This document provides an overview of all configuration classes in llm type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
, no_context_shift: bool = False, no_webui: Optional[bool] = None, startup_timeout: Optional[int] = None)",
"link": "./llama_cpp_adapter_llamaserverparameters_421f40"
},
{
"name": "MoonshotDeployModelParameters",
"description": "Moonshot proxy LLM configuration.",
"link": "./moonshot_moonshotdeploymodelparameters_aa2f6b"
},
{
"name": "OllamaDeployModelParameters",
"description": "Ollama proxy LLM configuration.",
"link": "./ollama_ollamadeploymodelparameters_d55be6"
},
{
"name": "OpenAICompatibleDeployModelParameters",
"description": "OpenAI Compatible Proxy LLM",
"link": "./chatgpt_openaicompatibledeploymodelparameters_c3d426"
},
{
"name": "AimlapiDeployModelParameters",
"description": "AI/ML API proxy LLM configuration.",
"link": "./aimlapi_aimlapideploymodelparameters_a1b2c3"
},
{
"name": "SiliconFlowDeployModelParameters",
"description": "SiliconFlow proxy LLM configuration.",
"link": "./siliconflow_siliconflowdeploymodelparameters_abe22f"
},
{
"name": "SparkDeployModelParameters",
"description": "Xunfei Spark proxy LLM configuration.",
"link": "./spark_sparkdeploymodelparameters_afba3c"
},
{
"name": "TongyiDeployModelParameters",
"description": "Tongyi proxy LLM configuration.",
"link": "./tongyi_tongyideploymodelparameters_02a91b"
},
{
"name": "VLLMDeployModelParameters",
"description": "Local deploy model parameters.",
"link": "./vllm_adapter_vllmdeploymodelparameters_1d4a24"
},
{
"name": "VolcengineDeployModelParameters",
"description": "Volcengine proxy LLM configuration.",
"link": "./volcengine_volcenginedeploymodelparameters_938015"
},
{
"name": "WenxinDeployModelParameters",
"description": "Baidu Wenxin proxy LLM configuration.",
"link": "./wenxin_wenxindeploymodelparameters_63c66b"
},
{
"name": "YiDeployModelParameters",
"description": "Yi proxy LLM configuration.",
"link": "./yi_yideploymodelparameters_92dbaa"
},
{
"name": "ZhipuDeployModelParameters",
"description": "Zhipu proxy LLM configuration.",
"link": "./zhipu_zhipudeploymodelparameters_c51e31"
},
]} />
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Config Reference Memory Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/config-reference/memory/index.mdx`)
---
title: "memory"
description: "memory Configuration"
---
# memory Configuration
This document provides an overview of all configuration classes in memory type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Config Reference Reranker Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/config-reference/reranker/index.mdx`)
---
title: "reranker"
description: "reranker Configuration"
---
# reranker Configuration
This document provides an overview of all configuration classes in reranker type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Config Reference Serve Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/config-reference/serve/index.mdx`)
---
title: "serve"
description: "serve Configuration"
---
# serve Configuration
This document provides an overview of all configuration classes in serve type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Config Reference Service Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/config-reference/service/index.mdx`)
---
title: "service"
description: "service Configuration"
---
# service Configuration
This document provides an overview of all configuration classes in service type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Config Reference Utils Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/config-reference/utils/index.mdx`)
---
title: "utils"
description: "utils Configuration"
---
# utils Configuration
This document provides an overview of all configuration classes in utils type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
)",
"link": "./config_s3storageconfig_f0cdc9"
},
]} />
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Config Reference Vector Store Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/config-reference/vector_store/index.mdx`)
---
title: "vector_store"
description: "vector_store Configuration"
---
# vector_store Configuration
This document provides an overview of all configuration classes in vector_store type.
import { ConfigClassTable } from '@site/src/components/mdx/ConfigClassTable';
## Configuration Classes
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Dbgpts Built In Skills Overview (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/dbgpts/built-in-skills/overview.md`)
# Built-in Skills 总览
DB-GPT 在项目级 `skills/` 目录下内置了一批可直接使用的 skills。
这个小节按照仓库结构组织，为每一个 built-in skill 提供单独页面说明。
## 仓库映射
```text
skills/
├── agent-browser/
├── csv-data-analysis/
├── financial-report-analyzer/
├── skill-creator/
└── walmart-sales-analyzer/
```
## Built-in skills 提供什么能力
Built-in skill 会把可重复工作流打包成可复用单元。
- `SKILL.md` 定义 skill 应该何时使用、如何执行
- `scripts/` 存放在需要确定性处理时用到的可执行脚本
- `references/` 存放按需加载的领域参考资料
- `templates/` 或 `assets/` 存放 HTML 报告模板等输出资源
## 当前内置 skills
| Skill | 主要用途 | 关键资源 |
|------|----------|----------|
| `agent-browser` | 面向 agent 的浏览器自动化 | `SKILL.md` 中的命令式工作流 |
| `csv-data-analysis` | CSV / Excel / TSV 数据分析 | `scripts/csv_analyzer.py`、`templates/report_template.html`、`references/reference.md` |
| `financial-report-analyzer` | 财报提取、分析与报告生成 | 提取、比率分析、图表脚本，以及财务参考资料与模板 |
| `skill-creator` | 创建并打包新的 skill | `init_skill.py`、`package_skill.py`、设计参考资料 |
| `walmart-sales-analyzer` | Walmart 销售趋势分析与报告 | 报告生成脚本与 `templates/report_template.html` |
## 如何阅读这一节
每个 built-in skill 页面通常会包含：
- skill 的用途
- 适用场景
- 核心工作流
- 附带的重要脚本、参考资料与模板
- 预期输出形式
## 下一步
继续打开本小节下的具体页面，查看每个已内置 skill 如何映射到仓库中的 `skills/` 目录。
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Getting Started Providers Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/providers/index.md`)
---
sidebar_position: 0
title: 模型提供方
summary: "了解 DB-GPT 支持哪些模型提供方，以及首次部署应该如何选择"
read_when:
- 你第一次部署时需要选择模型提供方
- 你想判断应该使用 API 模型、Ollama 还是 vLLM
---
# 模型提供方
DB-GPT 同时支持 API 模型提供方和本地运行时。对于第一次部署，除非你明确需要本地推理，否则建议优先选择 API 提供方。
:::info 快速建议
如果你不确定该选哪个，建议先从 **OpenAI** 或 **DeepSeek** 开始：它们配置快、无需 GPU。若你希望在本地运行模型且尽量简化配置，可以选择 **Ollama**。
:::
## 提供方对比
| 提供方 | 类型 | 是否需要 GPU | 适合场景 |
|---|---|---|---|
| [**OpenAI**](./openai) | API 代理 | 否 | 生产质量、最快完成首跑 |
| [**DeepSeek**](./deepseek) | API 代理 | 否 | 性价比高、推理能力强 |
| [**Qwen (Tongyi)**](./qwen) | API 代理 | 否 | 中文场景、阿里云用户 |
| [**SiliconFlow**](./siliconflow) | API 代理 | 否 | 国内可用、模型选择多 |
| [**Ollama**](./ollama) | 本地代理 | 可选 | 本地模型、注重隐私、部署简单 |
| [**vLLM**](./vllm) | 本地运行时 | 是（NVIDIA） | 更高吞吐的生产级本地推理 |
## 模型配置是如何组织的
所有模型都通过 `configs/` 目录下的 TOML 文件配置。一个配置文件通常定义：
- **LLM(s)**：聊天与推理使用的大模型
- **Embedding(s)**：RAG 和知识检索使用的向量模型
- **Reranker(s)**：可选的重排序模型，用于提高检索质量
```toml
[models]
# 语言模型
[[models.llms]]
name = "model-name"
provider = "provider-type"
api_key = "your-api-key"
# 向量模型
[[models.embeddings]]
name = "embedding-model-name"
provider = "provider-type"
api_key = "your-api-key"
```
:::tip 环境变量
你可以在 TOML 中使用环境变量语法：`"${env:VARIABLE_NAME:-default_value}"`，避免把密钥直接写死在配置文件中。
:::
## 提供方指南
- [OpenAI](/docs/getting-started/providers/openai) —— 首次部署最常见、最省心的默认方案
- [DeepSeek](/docs/getting-started/providers/deepseek) —— 强推理能力，兼容 OpenAI 代理模式
- [Qwen (Tongyi)](/docs/getting-started/providers/qwen) —— 阿里云 / DashScope 方案
- [SiliconFlow](/docs/getting-started/providers/siliconflow) —— 适合国内环境的 API 方案
- [Ollama](/docs/getting-started/providers/ollama) —— 简单本地模型运行方式
- [vLLM](/docs/getting-started/providers/vllm) —— GPU 驱动的高性能本地推理方案
## 更多提供方
DB-GPT 还可以通过代理体系接入更多模型提供方。详见 [Advanced LLM Configuration](/docs/installation/advanced_usage/More_proxyllms)，包括：
- Azure OpenAI
- Google Gemini
- Anthropic Claude
- Baichuan
- Spark（讯飞星火）
- 以及更多兼容提供方
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Getting Started Tools Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/tools/index.md`)
---
sidebar_position: 0
title: Tools & Plugins
summary: "理解 DB-GPT 如何通过 MCP、dbgpts 和 AWEL Flow 扩展 agent 能力"
read_when:
- 你想为 DB-GPT 增加工具或外部集成
- 你想理解 MCP、dbgpts 和 AWEL Flow 之间的区别
---
# Tools & Plugins
通过外部工具、社区包和可视化工作流扩展 DB-GPT。
- [MCP Protocol](/docs/getting-started/tools/mcp) —— 把外部工具和服务接入 agent
- [dbgpts Ecosystem](/docs/getting-started/tools/dbgpts) —— 安装社区应用、operator、workflow 和 agent
- [AWEL Flow](/docs/getting-started/tools/awel-flow) —— 在 Web UI 中可视化构建工作流
## Overview
DB-GPT 目前主要支持三种扩展机制：
| 机制 | 作用 | 适用场景 |
|---|---|---|
| **MCP Protocol** | 把外部工具（API、服务）连接到 agent | 需要让 agent 调用外部服务 |
| **dbgpts** | 安装预构建应用、operator 和 workflow | 想直接复用现成组件 |
| **AWEL Flow** | 可视化编排 AI 流程 | 想构建自定义工作流且尽量少写代码 |
## 工具如何与 agent 协同
```mermaid
graph LR
User[User] --> Agent[Agent]
Agent --> LLM[LLM]
Agent --> Tools[Tools]
Tools --> MCP[MCP Server]
Tools --> DB[(Database)]
Tools --> KB[Knowledge Base]
Tools --> API[External APIs]
```
DB-GPT 中的 agent 可以通过工具完成：
1. **访问数据** —— 查询数据库、搜索知识库
2. **调用 API** —— 通过 MCP 与外部服务交互
3. **执行代码** —— 在沙箱环境中运行 Python 代码
4. **管理文件** —— 读写和处理文件
## 快速链接
| 主题 | 链接 |
|---|---|
| AWEL 概念 | [AWEL](/docs/getting-started/concepts/awel) |
| Agent 框架 | [Agents](/docs/getting-started/concepts/agents) |
| Agent 开发 | [Development Guide](/docs/agents/introduction/tools) |
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Getting Started Troubleshooting Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/troubleshooting/index.md`)
---
sidebar_position: 0
title: Troubleshooting
summary: "安装、模型和环境问题的首要检查项与常见修复方式"
read_when:
- 遇到问题，想先走最快的排查路径
- DB-GPT 启动不稳定、UI 白屏或模型加载失败
---
# Troubleshooting
这里整理了使用 DB-GPT 时的常见问题和解决方法。
## 前 60 秒先做什么
先执行下面这些检查：
```bash
curl http://localhost:5670/api/health
dbgpt model list
docker logs dbgpt -f
```
如果你不是用 Docker 部署的，请直接查看你启动 webserver 的那个终端输出。
## 常见快速修复方式
- **服务无法启动**
- 重新执行带正确 extras 的 `uv sync`
- 参考 [Installation Issues](/docs/getting-started/troubleshooting/installation)
- **Web UI 白屏**
- 先等待启动完全结束
- 确认服务在 `http://localhost:5670` 可访问
- **模型不存在 / 鉴权错误**
- 重新检查 TOML 配置和 provider 名称
- 参考 [Model Issues](/docs/getting-started/troubleshooting/llm)
- **5670 端口被占用**
- 使用 `lsof -i :5670` 找到冲突进程
- **内存不足**
- 换更小的本地模型，或改用 API 代理模型
## 更具体的排查指南
- [Installation Issues](/docs/getting-started/troubleshooting/installation)
- [Model Issues](/docs/getting-started/troubleshooting/llm)
- [Environment Variables](/docs/getting-started/troubleshooting/environment)
## Logs
```bash
# 源码部署
# 默认日志直接输出到 stdout
# Docker 部署
docker logs dbgpt -f
# Docker Compose 部署
docker logs db-gpt-webserver-1 -f
```
## 获取帮助
如果这些排查文档仍然无法解决问题：
1. **搜索已有 issue**：[GitHub Issues](https://github.com/eosphoros-ai/DB-GPT/issues)
2. **向社区提问**：[GitHub Discussions](https://github.com/orgs/eosphoros-ai/discussions)
3. **加入 Slack**：[DB-GPT Slack](https://join.slack.com/t/slack-inu2564/shared_invite/zt-29rcnyw2b-N~ubOD9kFc7b7MDOAM1otA)
4. **查看 FAQ**：[Installation FAQ](/docs/faq/install) · [LLM FAQ](/docs/faq/llm) · [KBQA FAQ](/docs/faq/kbqa)
---
### I18n Zh CN Docusaurus Plugin Content Docs Current Getting Started Web Ui Index (`docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/web-ui/index.md`)
---
sidebar_position: 0
title: Web UI 总览
summary: "了解 DB-GPT Web UI 中有哪些主要能力，以及它们分别在哪里"
read_when:
- 你已经启动了 DB-GPT，想知道先点哪里
- 你想快速了解 chat、knowledge、dashboard 和 app 界面的分布
---
# Web UI 总览
DB-GPT 默认自带 Web 界面，地址为 **[http://localhost:5670](http://localhost:5670)**。
## 主要区域
- [Chat](/docs/getting-started/web-ui/chat) —— 普通对话、数据对话、Excel 对话、知识库对话
- [Knowledge Base](/docs/getting-started/web-ui/knowledge-base) —— 上传文件并构建 RAG 数据集
- [Dashboard](/docs/getting-started/web-ui/dashboard) —— 从自然语言生成图表和报告
- [App Management](/docs/getting-started/web-ui/app-management) —— 创建和管理 DB-GPT 应用
## 功能地图
| 功能 | 描述 | 所在区域 |
|---|---|---|
| **Chat** | 与 LLM 进行多轮对话 | [Chat](/docs/getting-started/web-ui/chat) |
| **Chat Data** | 基于已连接数据库进行自然语言问数（Text2SQL） | [Chat](/docs/getting-started/web-ui/chat) |
| **Chat Excel** | 上传并用自然语言分析 Excel 文件 | [Chat](/docs/getting-started/web-ui/chat) |
| **Chat Knowledge** | 基于上传文档做 RAG 对话 | [Knowledge Base](/docs/getting-started/web-ui/knowledge-base) |
| **Dashboard** | 自动生成图表和数据报告 | [Dashboard](/docs/getting-started/web-ui/dashboard) |
| **App Store** | 浏览并安装社区应用 | [App Management](/docs/getting-started/web-ui/app-management) |
| **AWEL Flow** | 可视化工作流编辑器 | [AWEL Flow](/docs/getting-started/tools/awel-flow) |
| **Agent Workspace** | 配置并运行多智能体任务 | [App Management](/docs/getting-started/web-ui/app-management) |
## 访问 Web UI
启动 DB-GPT 服务后，可以通过以下地址访问 Web UI：
```
http://localhost:5670
```
:::tip 单独运行前端
如果你要做前端开发，也可以单独运行 Next.js 应用：
```bash
cd web && npm install
cp .env.template .env
# 设置 API_BASE_URL=http://localhost:5670
npm run dev
```
然后访问 [http://localhost:3000](http://localhost:3000)。
:::
## 建议先尝试什么
1. 打开 **Chat**，确认配置的模型能正常回复
2. 如果你想做文档问答，打开 **Knowledge Base**
3. 如果你想做 Text2SQL 和图表分析，打开 **Dashboard**
4. 如果你想复用应用配置，打开 **Apps**
## 下一步
| 主题 | 链接 |
|---|---|
| 开始聊天 | [Chat](/docs/getting-started/web-ui/chat) |
| 搭建知识库 | [Knowledge Base](/docs/getting-started/web-ui/knowledge-base) |
| 构建工作流 | [AWEL Flow](/docs/getting-started/tools/awel-flow) |
---
### Data Analysis Planning Agent (`docs/data_analysis_planning_agent.md`)
# Data Analysis Planning Agent
基于`react_agent.py`开发的具有自主规划能力的数据分析智能体，能够理解数据分析需求、制定分析计划并系统性地执行。
## 核心特性
### 🎯 自主规划能力
- **需求理解**: 深度理解业务问题和分析目标
- **计划制定**: 创建系统性的数据分析步骤计划
- **动态调整**: 根据分析结果动态调整后续步骤
### 📊 全流程分析
- **数据源检查**: 自动识别和检查可用数据源
- **数据加载**: 智能加载和预处理数据
- **探索性分析**: 进行全面的数据探索
- **统计分析**: 执行统计检验和深度分析
- **可视化**: 生成图表和可视化结果
- **洞察提取**: 提供业务洞察和建议
### 🤖 智能决策
- **步骤优化**: 根据数据特点优化分析步骤
- **工具选择**: 智能选择最适合的分析工具
- **结果验证**: 验证分析结果的可靠性
## 架构设计
### 继承结构
```
DataAnalysisPlanningAgent
├── 继承自 ConversableAgent
├── 扩展 ReActAgent 的规划能力
└── 集成数据分析专用工具
```
### 核心组件
#### 1. 规划状态管理
```python
class DataAnalysisPlanningAgent(ConversableAgent):
analysis_plan: Optional[List[Dict[str, Any]]] # 分析计划
current_step: int = Field(default=0) # 当前步骤
planning_complete: bool = Field(default=False) # 规划完成状态
```
#### 2. 专用工具集
- `create_analysis_plan`: 创建分析计划
- `examine_data_sources`: 检查数据源
- `load_data`: 加载数据
- `explore_data`: 探索性分析
- `statistical_analysis`: 统计分析
- `create_visualization`: 创建可视化
- `generate_insights`: 生成洞察
#### 3. 智能提示模板
```python
_DATA_AGENT_SYSTEM_TEMPLATE = """
You are an expert data analyst with strong planning and execution capabilities.
1. Planning Phase: 理解目标、识别数据、创建计划
2. Execution Phase: 加载数据、执行分析、生成结果
3. Communication Phase: 展示发现、提供洞察、建议后续
"""
```
## 使用方法
### 基础使用
```python
from dbgpt.agent.expand.data_agent import DataAnalysisPlanningAgent
from dbgpt.agent.resource import ToolPack, ResourcePack
# 1. 创建工具
tools = [DataSourceTool(), LoadDataTool(), ExploreDataTool()]
tool_pack = ToolPack(tools=tools)
# 2. 创建资源包
resource_pack = ResourcePack()
resource_pack._resources["tools"] = tool_pack
# 3. 创建Agent
agent = DataAnalysisPlanningAgent(resource=resource_pack)
# 4. 发送分析请求
message = AgentMessage(content="分析销售数据趋势，提供业务洞察")
response = await agent.act(message, sender=None)
```
### 高级配置
```python
# 自定义规划参数
agent = DataAnalysisPlanningAgent(
max_retry_count=25, # 增加重试次数
resource=resource_pack,
llm_client=your_llm_client
)
# 设置分析目标
agent.profile.goal = "专注于电商数据分析，提供精准的业务洞察"
```
## 工作流程
### 1. 需求理解阶段
```
用户输入 → 理解业务问题 → 识别分析目标 → 确定数据需求
```
### 2. 规划制定阶段
```
数据需求 → 检查数据源 → 制定分析计划 → 估算时间和资源
```
### 3. 执行分析阶段
```
执行计划 → 数据加载 → 探索分析 → 深度分析 → 结果验证
```
### 4. 结果呈现阶段
```
分析结果 → 生成洞察 → 创建可视化 → 提供建议 → 完成任务
```
## 示例场景
### 场景1: 销售趋势分析
```python
question = "分析我们的销售数据，识别趋势并提供业务规划洞察"
# Agent会自动执行：
# 1. 创建销售趋势分析计划
# 2. 检查可用的销售数据源
# 3. 加载销售数据
# 4. 进行趋势分析
# 5. 生成可视化图表
# 6. 提供业务洞察和建议
```
### 场景2: 客户细分分析
```python
question = "进行客户细分分析，识别不同客户群体特征"
# Agent会自动执行：
# 1. 制定客户细分分析计划
# 2. 检查客户数据
# 3. 执行细分算法
# 4. 分析各群体特征
# 5. 提供营销建议
```
## 扩展开发
### 添加自定义工具
```python
class CustomAnalysisTool(BaseTool):
@property
def name(self) -> str:
return "custom_analysis"
@property
def description(self) -> str:
return "执行自定义分析逻辑"
async def async_execute(self, **kwargs):
# 实现自定义分析逻辑
return {"result": "自定义分析结果"}
# 添加到Agent
agent.resource._resources["custom_analysis"] = CustomAnalysisTool()
```
### 自定义规划逻辑
```python
class CustomDataAnalysisAgent(DataAnalysisPlanningAgent):
async def create_custom_plan(self, objective: str):
# 实现自定义规划逻辑
custom_plan = [
{"step": 1, "action": "custom_preprocessing"},
{"step": 2, "action": "custom_analysis"},
]
self.analysis_plan = custom_plan
return custom_plan
```
## 最佳实践
### 1. 数据准备
- 确保数据源可访问
- 提供数据文档和元数据
- 预处理常见数据质量问题
### 2. 目标设定
- 明确分析目标和业务问题
- 提供背景信息和约束条件
- 设定期望的输出格式
### 3. 工具配置
- 根据分析需求配置合适工具
- 确保工具参数正确设置
- 提供工具使用文档
### 4. 结果验证
- 验证分析结果的合理性
- 检查数据质量影响
- 确认业务洞察的准确性
## 故障排除
### 常见问题
#### 1. 规划失败
```
问题: Agent无法创建有效的分析计划
解决: 检查数据源可用性，明确分析目标
```
#### 2. 工具执行错误
```
问题: 数据分析工具执行失败
解决: 检查工具参数，验证数据格式
```
#### 3. 结果质量差
```
问题: 分析结果不够深入或准确
解决: 提供更多背景信息，调整分析策略
```
### 调试方法
```python
# 启用详细日志
import logging
logging.basicConfig(level=logging.DEBUG)
# 检查Agent状态
print(f"Planning complete: {agent.planning_complete}")
print(f"Current step: {agent.current_step}")
print(f"Analysis plan: {agent.analysis_plan}")
```
## 性能优化
### 1. 缓存策略
- 缓存数据加载结果
- 缓存分析计算结果
- 缓存常用查询结果
### 2. 并行处理
- 并行执行独立分析任务
- 异步处理数据加载
- 批量处理相似请求
### 3. 资源管理
- 合理管理内存使用
- 优化计算资源分配
- 控制并发任务数量
## 未来规划
### 短期目标
- [ ] 添加更多预定义分析模板
- [ ] 优化规划算法
- [ ] 增强错误处理能力
### 中期目标
- [ ] 支持多数据源联合分析
- [ ] 集成机器学习模型
- [ ] 添加实时分析能力
### 长期目标
- [ ] 支持自然语言交互
- [ ] 自动化报告生成
- [ ] 智能推荐系统
## 贡献指南
欢迎提交Issue和Pull Request来改进这个项目！
### 开发环境设置
```bash
# 安装依赖
pip install -r requirements.txt
# 运行测试
pytest tests/
# 代码格式化
black src/
```
### 提交规范
- 使用清晰的提交信息
- 添加适当的测试用例
- 更新相关文档
## 许可证
MIT License - 详见LICENSE文件
---
### Blog 2024 07 24 Db Gpt Llama 3.1 Support (`docs/blog/2024-07-24-db-gpt-llama-3.1-support.md`)
---
slug: db-gpt-llama-3.1-support
title: DB-GPT Now Supports Meta Llama 3.1 Series Models
authors: fangyinc
tags: [llama, LLM]
---
We are thrilled to announce that DB-GPT now supports inference with the Meta Llama 3.1 series models!
## Introducing Meta Llama 3.1
Meta Llama 3.1 is a state-of-the-art series of language models developed by Meta AI. Designed with cutting-edge techniques, the Llama 3.1 models offer unparalleled performance and versatility. Here are some of the key highlights:
- **Variety of Models**: Meta Llama 3.1 is available in 8B, 70B, and 405B versions, each with both instruction-tuned and base models, supporting contexts up to 128k tokens.
- **Multilingual Support**: Supports 8 languages, including English, German, and French.
- **Extensive Training**: Trained on over 1.5 trillion tokens, utilizing 250 million human and synthetic samples for fine-tuning.
- **Flexible Licensing**: Permissive model output usage allows for adaptation into other large language models (LLMs).
- **Quantization Support**: Available in FP8, AWQ, and GPTQ quantized versions for efficient inference.
- **Performance**: The Llama 3 405B version has outperformed GPT-4 in several benchmarks.
- **Enhanced Efficiency**: The 8B and 70B models have seen a 12% improvement in coding and instruction-following capabilities.
- **Tool and Function Call Support**: Supports tool usage and function calling.
## How to Access Meta Llama 3.1
Your can access the Meta Llama 3.1 models according to [Access to Hugging Face](https://github.com/meta-llama/llama-models?tab=readme-ov-file#access-to-hugging-face).
For comprehensive documentation and additional details, please refer to the [model card](https://github.com/meta-llama/llama-models/blob/main/models/llama3_1/MODEL_CARD.md).
## Using Meta Llama 3.1 in DB-GPT
Please read the [Source Code Deployment](../docs/installation/sourcecode) to learn how to install DB-GPT from source code.
Llama 3.1 needs upgrade your transformers >= 4.43.0, please upgrade your transformers:
```bash
pip install --upgrade "transformers>=4.43.0"
```
Please cd to the DB-GPT root directory:
```bash
cd DB-GPT
```
We assume that your models are stored in the `models` directory, e.g., `models/Meta-Llama-3.1-8B-Instruct`.
Then modify your `.env` file:
```env
LLM_MODEL=meta-llama-3.1-8b-instruct
# LLM_MODEL=meta-llama-3.1-70b-instruct
# LLM_MODEL=meta-llama-3.1-405b-instruct
## you can also specify the model path
# LLM_MODEL_PATH=models/Meta-Llama-3.1-8B-Instruct
## Quantization settings
# QUANTIZE_8bit=False
# QUANTIZE_4bit=True
## You can configure the maximum memory used by each GPU.
# MAX_GPU_MEMORY=16Gib
```
Then you can run the following command to start the server:
```bash
dbgpt start webserver
```
Open your browser and visit `http://localhost:5670` to use the Meta Llama 3.1 models in DB-GPT.
Enjoy the power of Meta Llama 3.1 in DB-GPT!
---
### Blog 2024 09 04 Dbgpt V0.6.0 Defining New Standards For AI Native Data Applications (`docs/blog/2024-09-04-dbgpt-v0.6.0-Defining new standards for AI-native data applications.md`)
# DB-GPT V0.6.0, Defining new standards for AI-native data applications.
## Introduction
DB-GPT is an open source AI native data application development framework with AWEL and agents. In the V0.6.0 version, we further provide flexible and scalable AI native data application management and development capabilities around large models, which can help enterprises quickly build and deploy intelligent AI data applications, and achieve enterprise digital transformation and business growth through intelligent data analysis, insights and decisions
### The V0.6.0 version mainly adds and enhances the following core features
- AWEL protocol upgrade 2.0, supporting more complex orchestration
- Supports the creation and lifecycle management of data applications, and supports multiple application construction modes, such as: multi-agent automatic planning mode, task flow orchestration mode, single agent mode, and native application mode
- GraphRAG supports graph community summary and hybrid retrieval, and the graph index cost is reduced by 50% compared to Microsoft GraphRAG.
- Supports multiple Agent Memories, such as perceptual memory, short-term memory, long-term memory, hybrid memory, etc.
- Supports intent recognition and prompt management, and newly added support for Text2NLU and Text2GQL fine-tuning
- GPT-Vis front-end visualization upgrade to support richer visualization charts
## Features
**AWEL protocol upgrade 2.0 supports more complex orchestration and optimizes front-end visualization and interaction capabilities.**
AWEL (Agentic Workflow Expression Language) is an agent-based workflow expression language designed specifically for large model application development, providing powerful functions and flexibility. Through the AWEL API, developers can focus on large model application logic development without having to pay attention to cumbersome model, environment and other details. In AWEL2.0, we support more complex orchestration and visualization
**Supports the creation and life cycle management of data applications, and supports multiple modes to build applications, such as: multi-agent automatic planning mode, task flow orchestration mode, single agent mode, and native application mode**
**GraphRAG supports graph community summarization and hybrid retrieval.**
The graph construction and retrieval performance have obvious advantages compared to community solutions, and it supports cool visualization. GraphRAG is an enhanced retrieval generation system based on knowledge graphs. Through the construction and retrieval of knowledge graphs, it further enhances the accuracy of retrieval and the stability of recall, while reducing the illusion of large models and enhancing the effects of domain applications. DB-GPT combines with TuGraph to build efficient retrieval enhancement generation capabilities
Based on the universal RAG framework launched in DB-GPT version 0.5.6 that integrates vector index, graph index, and full-text index, DB-GPT version 0.6.0 has enhanced the capabilities of graph index (GraphRAG) to support graph community summary and hybrid retrieval. ability. In the new version, we introduced TuGraph’s built-in Leiden community discovery algorithm, combined with large models to extract community subgraph summaries, and finally used similarity recall of community summaries to cope with generalized questioning scenarios, namely QFS (Query Focused Summarization). question. In addition, in the knowledge extraction stage, we upgraded the original triple extraction to graph extraction with point edge information summary, and optimized cross-text block associated information extraction through text block history to further enhance the information density of the knowledge graph.
Based on the above design, we used the open source knowledge graph corpus (OSGraph) provided by the TuGraph community and the product introduction materials of DB-GPT and TuGraph (about 43k tokens in total), and conducted comparative tests with Microsoft's GraphRAG system. Finally, DB-GPT It only consumes 50% of the token overhead and generates a knowledge graph of the same scale. And on the premise that the quality of the question and answer test is equivalent, the global search performance has been significantly improved.
For the final generated knowledge graph, we used AntV's G6 engine to upgrade the front-end rendering logic, which can intuitively preview the knowledge graph data and community segmentation results.
**GPT-Vis: GPT-Vis is an interactive visualization solution for LLM and data, supporting rich visual chart display and intelligent recommendations**
**Text2GQL and Text2NLU fine-tuning: Newly supports fine-tuning from natural language to graph language, as well as fine-tuning for semantic classification.**
## Acknowledgements
This iteration is inseparable from the participation of developers and users in the community, and it also further cooperates with the [TuGraph](https://github.com/TuGraph-family) and [AntV](https://github.com/antvis) communities. Thanks to all the contributors who made this release possible!
@Aries-ckt, @Dreammy23, @Hec-gitHub, @JxQg, @KingSkyLi, @M1n9X, @bigcash, @chaplinthink, @csunny, @dusens, @fangyinc, @huangjh131, @hustcc, @lhwan, @whyuds and @yhjun1026
## Reference
- [中文手册](https://www.yuque.com/eosphoros/dbgpt-docs/ym574wh2hddunfbd)
---
### Blog 2025 03 24 Dbgpt V0.7.0 Release (`docs/blog/2025-03-24-dbgpt-v0.7.0-release.md`)
---
slug: db-gpt-v070-release
tags: [DeepSeek, LLM, MCP]
---
# DB-GPT V0.7.0, MCP + DeepSeek R1: Bringing More Possibilities to LLM Applications
**DB-GPT V0.7.0 Release: MCP Protocol Support, DeepSeek R1 Model Integration, Complete Architecture Upgrade, GraphRAG Retrieval Chain Enhancement, and More..**
`DB-GPT` is an open-source AI Native Data App Development framework with AWEL and Agents. In version `V0.7.0`, we have reorganized the `DB-GPT` module packages, splitting the original modules, restructuring the entire framework configuration system, and providing a clearer, more flexible, and more extensible management and development capability for building AI native data applications around large models.
## V0.7.0 version mainly adds and enhances the following core features
🍀 **Support for** `MCP(Model Context Protocol)` **protocol.**
🍀 **Integrated** `DeepSeek R1`, `QWQ` **inference models, all original** `DB-GPT` **Chat scenarios now cover deep thinking capabilities.**
🍀 `GraphRAG` **retrieval chain enhancement: support for "Vector" and "Intent Recognition+Text2GQL" graph retrievers.**
🍀 `DB-GPT` **module package restructuring, original** `dbgpt` **package split into** `dbgpt-core`, `dbgpt-ext`, `dbgpt-serve`, `dbgpt-client`, `dbgpt-acclerator`, `dbgpt-app`.
🍀 **Reconstructed** `DB-GPT` **configuration system, configuration files changed to "**`.toml`**" format, abolishing the original** `.env` **configuration logic.**
## ✨New Features
### 1. **Support for** `MCP(Model Context Protocol)` **protocol**
Usage instructions:
a. Run the MCP SSE Server gateway:
```bash
npx -y supergateway --stdio "uvx mcp-server-fetch"
```
Here we are running the web scraping `mcp-server-fetch`
b. Create a `Multi-agent`+ `Auto-Planning`+ `MCP` web page scraping and summarization APP.
c. Configure the APP, select the `ToolExpert` and `Summarizer` agents, and add a resource of type `tool(mcp(sse))` to `ToolExpert`, where `mcp_servers` should be filled with the service address started in step a (default is: `http://127.0.0.1:8000/sse`), then save the application.
d. Select the newly created `MCP Web Fetch` APP to chat, provide a webpage for the APP to summarize:
The example input question is: `What does this webpage talk about https://www.cnblogs.com/fnng/p/18744210"`
### 2. Integrated DeepSeek R1 inference model
**And all Chat scenarios in original DB-GPT now have deep thinking capabilities.**
For quick usage reference: [http://docs.dbgpt.cn/docs/next/quickstart](http://docs.dbgpt.cn/docs/next/quickstart)
Data analysis scenario:
Knowledge base scenario:
### 3. `GraphRAG` **retrieval chain enhancement: support for "Vector" and "Intent Recognition+Text2GQL" graph retrievers.**
+ **"Vector" graph retriever**
During the knowledge graph construction process, vectors are added to all nodes and edges and indexes are established. When querying, the question is vectorized and through TuGraph-DB's built-in vector indexing capability, based on the HNSW algorithm, topk related nodes and edges are queried. Compared to keyword graph retrieval, it can identify more ambiguous questions.
Configuration example:
```toml
[rag.storage.graph]
type = "TuGraph"
host="127.0.0.1"
port=7687
username="admin"
password="73@TuGraph"
enable_summary="True"
triplet_graph_enabled="True"
document_graph_enabled="True"
# Vector graph retrieval configuration items
enable_similarity_search="True"
knowledge_graph_embedding_batch_size=20
similarity_search_topk=5
extract_score_threshold=0.7
```
+ **"Intent Recognition+Text2GQL" graph retriever**
The question is rewritten through the intent recognition module, extracting true intent and involved entities and relationships, and then translated using the Text2GQL model into GQL statements for direct querying. It can perform more precise graph queries and display corresponding query statements. In addition to calling large model API services, you can also use ollama to call local Text2GQL models.
Configuration example:
```toml
[rag.storage.graph]
type = "TuGraph"
host="127.0.0.1"
port=7687
username="admin"
password="73@TuGraph"
enable_summary="True"
triplet_graph_enabled="True"
document_graph_enabled="True"
# Intent Recognition+Text2GQL graph retrieval configuration items
enable_text_search="True"
# Use Ollama to deploy independent text2gql model, enable the following configuration items
# text2gql_model_enabled="True"
# text2gql_model_name="tugraph/CodeLlama-7b-Cypher-hf:latest"
```
### 4. `DB-GPT` module package restructuring
Original `dbgpt` package split into `dbgpt-core`, `dbgpt-ext`, `dbgpt-serve`, `dbgpt-client`, `dbgpt-acclerator`, `dbgpt-app`
As dbgpt has gradually developed, the service modules have increased, making functional regression testing difficult and compatibility issues more frequent. Therefore, the original dbgpt content has been modularized:
+ **dbgpt-core**: Mainly responsible for core module interface definitions of dbgpt's awel, model, agent, rag, storage, datasource, etc., releasing Python SDK.
+ **dbgpt-ext**: Mainly responsible for implementing dbgpt extension content, including datasource extensions, vector-storage, graph-storage extensions, and model access extensions, making it easier for community developers to quickly use and extend new module content, releasing Python SDK.
+ **dbgpt-serve**: Mainly provides Restful interfaces for dbgpt's atomized services of each module, making it easy for community users to quickly integrate. No Python SDK is released at this time.
+ **dbgpt-app**: Mainly responsible for business scenario implementations such as `App`, `ChatData`, `ChatKnowledge`, `ChatExcel`, `Dashboard`, etc., with no Python SDK.
+ **dbgpt-client**: Provides a unified Python SDK client for integration.
+ **dbgpt-accelerator:** Model inference acceleration module, including compatibility and adaptation for different versions (different torch versions, etc.), platforms (Windows, MacOS, and Linux), hardware environments (CPU, CUDA, and ROCM), inference frameworks (vLLM, llama.cpp), quantization methods (AWQ, bitsandbytes, GPTQ), and other acceleration modules (accelerate, flash-attn), providing cross-platform, installable underlying environments on-demand for other DB-GPT modules.
### 5. Restructured DB-GPT configuration system
The new configuration files using `".toml"` format, abolishing the original `.env` configuration logic, each module can have its own configuration class, and automatically generate front-end configuration pages.
For quick usage reference: [http://docs.dbgpt.cn/docs/next/quickstart](http://docs.dbgpt.cn/docs/next/quickstart)
For all configurations reference: [http://docs.dbgpt.cn/docs/next/config-reference/app/config_chatdashboardconfig_2480d0](http://docs.dbgpt.cn/docs/next/config-reference/app/config_chatdashboardconfig_2480d0)
```toml
[system]
# Load language from environment variable(It is set by the hook)
language = "${env:DBGPT_LANG:-zh}"
api_keys = []
encrypt_key = "your_secret_key"
# Server Configurations
[service.web]
host = "0.0.0.0"
port = 5670
[service.web.database]
type = "sqlite"
path = "pilot/meta_data/dbgpt.db"
[service.model.worker]
host = "127.0.0.1"
[rag.storage]
[rag.storage.vector]
type = "chroma"
persist_path = "pilot/data"
# Model Configurations
[models]
[[models.llms]]
name = "deepseek-reasoner"
# name = "deepseek-chat"
provider = "proxy/deepseek"
api_key = "your_deepseek_api_key"
```
### 6. **Support for S3, OSS storage**
DB-GPT unified storage extension OSS and S3 implementation, where the S3 implementation supports most cloud storage compatible with the S3 protocol. DB-GPT knowledge base original files, Chat Excel related intermediate files, AWEL Flow node parameter files, etc. all support cloud storage.
Configuration example:
```toml
[[serves]]
type = "file"
# Default backend for file server
default_backend = "s3"
[[serves.backends]]
type = "oss"
endpoint = "https://oss-cn-beijing.aliyuncs.com"
region = "oss-cn-beijing"
access_key_id = "${env:OSS_ACCESS_KEY_ID}"
access_key_secret = "${env:OSS_ACCESS_KEY_SECRET}"
fixed_bucket = "{your_bucket_name}"
[[serves.backends]]
# Use Tencent COS s3 compatible API as the file server
type = "s3"
endpoint = "https://cos.ap-beijing.myqcloud.com"
region = "ap-beijing"
access_key_id = "${env:COS_SECRETID}"
access_key_secret = "${env:COS_SECRETKEY}"
fixed_bucket = "{your_bucket_name}
```
For detailed configuration instructions, please refer to: [http://docs.dbgpt.cn/docs/next/config-reference/utils/config_s3storageconfig_f0cdc9](http://docs.dbgpt.cn/docs/next/config-reference/utils/config_s3storageconfig_f0cdc9)
### 7. **Production-level llama.cpp inference support**
Based on llama.cpp HTTP Server, supporting continuous batching, multi-user parallel inference, etc., llama.cpp inference moves towards production systems.
Configuration example:
```toml
# Model Configurations
[models]
[[models.llms]]
name = "DeepSeek-R1-Distill-Qwen-1.5B"
provider = "llama.cpp.server"
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# https://huggingface.co/bartowski/DeepSeek-R1-Distill-Qwen-1.5B-GGUF
# path = "the-model-path-in-the-local-file-system"
path = "models/DeepSeek-R1-Distill-Qwen-1.5B-Q4_K_M.gguf
```
### 8. **Multi-model deployment persistence**
Currently, most models can be integrated on the DB-GPT page, with configuration information persistently saved and models automatically loaded when the service starts.
### 9. **LLM, Embedding, Reranker extension capability enhancement**
Optimized the model extension approach, requiring only a few lines of code to integrate new models.
### 10. **Native scenario support for conversation-round and token-based memory, with independent configuration support for each scenario**
Configuration example:
```toml
[app]
# Unified temperature configuration for all scenarios
temperature = 0.6
[[app.configs]]
name = "chat_excel"
# Use custom temperature configuration
temperature = 0.1
duckdb_extensions_dir = []
force_install = true
[[app.configs]]
name = "chat_normal"
memory = {type="token", max_token_limit=20000}
[[app.configs]]
name = "chat_with_db_qa"
schema_retrieve_top_k = 50
memory = {type="window", keep_start_rounds=0, keep_end_rounds=10}
```
### 11. **Chat Excel, Chat Data & Chat DB and Chat Dashboard native scenario optimization**
+ Chat Data, Chat Dashboard support for streaming output.
+ Optimization of library table field knowledge processing and recall
+ Chat Excel optimization, supporting more complex table understanding and chart conversations, even small parameter-scale open-source LLMs can handle it well.
### 12. **Front-end page support for LaTeX mathematical formula rendering**
### 13. **AWEL Flow support for simple conversation templates**
### 14. **Support for lightweight Docker images containing only proxy models (arm64 & amd64)**
One-click deployment command for DB-GPT:
```bash
docker run -it --rm -e SILICONFLOW_API_KEY=${SILICONFLOW_API_KEY} \
-p 5670:5670 --name dbgpt eosphorosai/dbgpt-openai
```
You can also use the build script to build your own image:
```bash
bash docker/base/build_image.sh --install-mode openai
```
For details, see the documentation: [http://docs.dbgpt.cn/docs/next/installation/docker-build-guide](http://docs.dbgpt.cn/docs/next/installation/docker-build-guide)
### 15. **DB-GPT API compatible with OpenAI SDK**
```python
from openai import OpenAI
DBGPT_API_KEY = "dbgpt"
client = OpenAI(
api_key=DBGPT_API_KEY,
base_url="http://localhost:5670/api/v2",
)
messages = [
{
"role": "user",
"content": "Hello, how are you?",
},
]
has_thinking = False
reasoning_content = ""
for chunk in client.chat.completions.create(
model="deepseek-chat",
messages=messages,
extra_body={
"chat_mode": "chat_normal",
},
stream=True,
max_tokens=4096,
):
delta_content = chunk.choices[0].delta.content
if hasattr(chunk.choices[0].delta, "reasoning_content"):
reasoning_content = chunk.choices[0].delta.reasoning_content
if reasoning_content:
if not has_thinking:
print("", flush=True)
print(reasoning_content, end="", flush=True)
has_thinking = True
if delta_content:
if has_thinking:
print("", flush=True)
print(delta_content, end="", flush=True)
has_thinking = False
```
### 16. **Data source extension capability enhancement**
After the backend supports new data sources, the frontend can automatically identify and dynamically configure them.
### 17. **Agent resource support for dynamic parameter configuration**
Frontend automatically identifies resource configuration parameters while remaining compatible with old configurations.
### 18. **ReAct Agent support, Agent tool calling capability enhancement**
### 19. **IndexStore extension capability enhancement**
IndexStore configuration restructuring, new storage implementations automatically scanned and discovered
### 20. **AWEL flow compatibility enhancement**
Cross-version compatibility for AWEL flow based on multi-version metadata.
## 🐞 Bug Fixes
Chroma support for Chinese knowledge base spaces, AWEL Flow issue fixes, fixed multi-platform Lyric installation error issues and local embedding model error issues, along with **40+** other bugs.
## 🛠️Others
Support for Ruff code formatting, multi-version documentation building, unit test fixes, and **20+** other issue fixes or feature enhancements.
**Upgrade Guide:**
### 1. Metadata database upgrade
For SQLite upgrades, table structures will be automatically upgraded by default. For MySQL upgrades, DDL needs to be executed manually. The `assets/schema/dbgpt.sql` file contains the complete DDL for the current version. Specific version change DDLs can be found in the `assets/schema/upgrade` directory. For example, if you are upgrading from `v0.6.3` to `v0.7.0`, you can execute the following DDL:
```bash
mysql -h127.0.0.1 -uroot -p{your_password} < ./assets/schema/upgrade/v0_7_0/upgrade_to_v0.7.0.sql
```
### 2. Vector database upgrade
Due to underlying changes in Chroma storage in v0.7.0, version 0.7.0 does not support reading content from older versions. Please re-import knowledge bases and refresh data sources. Other vector storage solutions are not affected.
## ✨Official Documentation
**English**
[Overview | DB-GPT](http://docs.dbgpt.site/docs/overview)
**Chinese**
[概览](https://www.yuque.com/eosphoros/dbgpt-docs/bex30nsv60ru0fmx)
## ✨Acknowledgements
Thanks to all contributors for making this release possible!
**283569391@qq.com, @15089677014, @Aries-ckt, @FOkvj, @Jant1L, @SonglinLyu, @TenYearOldJAVA, @Weaxs, @cinjoseph, @csunny, @damonqin, @dusx1981, @fangyinc, @geebytes, @haawha, @utopia2077, @vnicers, @xuxl2024, @yhjun1026, @yunfeng1993, @yyhhyyyyyy and tam**
This version took nearly three months to develop and has been merged to the main branch for over a month. Hundreds of users participated in testing version 0.7.0, with GitHub receiving hundreds of issues feedback. Some users directly submitted PR fixes. The DB-GPT community sincerely thanks every user and contributor who participated in version 0.7.0!
## ✨Appendix
+ [Quick Start](http://docs.dbgpt.cn/docs/next/quickstart)
+ [Docker Quick Deployment](http://docs.dbgpt.cn/docs/next/installation/docker)
---
### Blog 2025 04 29 Db Gpt Qwen3 Support (`docs/blog/2025-04-29-db-gpt-qwen3-support.md`)
---
slug: db-gpt-qwen3-support
title: DB-GPT Now Supports Qwen3 Series Models
authors: fangyinc
tags: [Qwen, Qwen3, LLM]
---
We are thrilled to announce that DB-GPT now supports inference with the Qwen3 series models!
## Introducing Qwen3
Qwen3 is the latest generation of large language models in Qwen series, offering a comprehensive suite of dense and mixture-of-experts (MoE) models. Built upon extensive training, Qwen3 delivers groundbreaking advancements in reasoning, instruction-following, agent capabilities, and multilingual support, with the following key features:
- **Uniquely support of seamless switching between thinking mode** (for complex logical reasoning, math, and coding) and **non-thinking mode** (for efficient, general-purpose dialogue) **within single model**, ensuring optimal performance across various scenarios.
- **Significantly enhancement in its reasoning capabilities**, surpassing previous QwQ (in thinking mode) and Qwen2.5 instruct models (in non-thinking mode) on mathematics, code generation, and commonsense logical reasoning.
- **Superior human preference alignment**, excelling in creative writing, role-playing, multi-turn dialogues, and instruction following, to deliver a more natural, engaging, and immersive conversational experience.
- **Expertise in agent capabilities**, enabling precise integration with external tools in both thinking and unthinking modes and achieving leading performance among open-source models in complex agent-based tasks.
- **Support of 100+ languages and dialects** with strong capabilities for **multilingual instruction following** and **translation**.
## How to Access Qwen3
Your can access the Qwen3 models according to [Access to Hugging Face](https://huggingface.co/collections/Qwen/qwen3-67dd247413f0e2e4f653967f) or [ModelScope](https://modelscope.cn/collections/Qwen3-9743180bdc6b48)
## Using Qwen3 in DB-GPT
Please read the [Source Code Deployment](../docs/installation/sourcecode) to learn how to install DB-GPT from source code.
Qwen3 needs upgrade your transformers >= 4.51.0, please upgrade your transformers.
Here is the command to install the required dependencies for Qwen3:
```bash
# Use uv to install dependencies needed for Qwen3
# Install core dependencies and select desired extensions
uv sync --all-packages \
--extra "base" \
--extra "cuda121" \
--extra "hf" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "quant_bnb" \
--extra "dbgpts" \
--extra "hf_qwen3"
```
To run DB-GPT with the local Qwen3 model. You can provide a configuration file to specify the model path and other parameters.
Here is an example configuration file `configs/dbgpt-local-qwen3.toml`:
```toml
# Model Configurations
[models]
[[models.llms]]
name = "Qwen/Qwen3-14B"
provider = "hf"
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# path = "the-model-path-in-the-local-file-system"
[[models.embeddings]]
name = "BAAI/bge-large-zh-v1.5"
provider = "hf"
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# path = "the-model-path-in-the-local-file-system"
```
In the above configuration file, [[models.llms]] specifies the LLM model, and [[models.embeddings]] specifies the embedding model. If you not provide the path parameter, the model will be downloaded from the Hugging Face model hub according to the name parameter.
Then run the following command to start the webserver:
```bash
uv run dbgpt start webserver --config configs/dbgpt-local-qwen3.toml
```
Open your browser and visit `http://localhost:5670` to use the Qwen3 models in DB-GPT.
Enjoy the power of Qwen3 in DB-GPT!
## Advanced Configurations
> Uniquely support of seamless switching between thinking mode (for complex logical reasoning, math, and coding) and non-thinking mode (for efficient, general-purpose dialogue) within single model, ensuring optimal performance across various scenarios.
By default, Qwen3 has thinking capabilities enabled. If you want to disable the thinking capabilities, you can set the `reasoning_model=false` configuration in your toml file.
```toml
[models]
[[models.llms]]
name = "Qwen/Qwen3-14B"
provider = "hf"
# Force the model to be used in non-thinking mode
reasoning_model = false
# If not provided, the model will be downloaded from the Hugging Face model hub
# uncomment the following line to specify the model path in the local file system
# path = "the-model-path-in-the-local-file-system"
```
---
### Docs Use Cases (`docs/docs/use_cases.mdx`)
---
title: Show Cases
sidebar_position: 1
---
# Show Cases
DB-GPT helps teams turn data questions into SQL, code, charts, dashboards, reports, and knowledge-driven workflows.
## What you can do with DB-GPT
📈
Analyze CSV / Excel files
Upload files, inspect data, compute metrics, and generate visual reports.
🗄️
Connect to databases
Explore schemas, query production-like data, and produce profiling reports.
🧾
Natural language to SQL
Ask business questions and let AI generate SQL automatically.
💹
Financial report analysis
Combine documents, code, charts, and summaries for decision support.
🧰
Build reusable skills
Create domain workflows and reusable SQL / analysis skills for repeated tasks.
🧠
Combine code, SQL, retrieval, and tools
Build next-generation AI + Data assistants for teams and products.
## Featured scenarios
## End-to-end examples
### 1. Agentic data analysis
Use DB-GPT to plan tasks, break work into steps, call tools, and complete end-to-end analysis workflows.
### 2. Autonomous SQL + code execution
Generate SQL and code to query data, clean datasets, compute metrics, and produce outputs.
### 3. Intelligent database insight and analysis report
Built on the new Agentic architecture, the engine autonomously performs data diagnostics, feature extraction, and multi-dimensional analysis, generating exclusive analysis reports with beautiful charts and deep insights that make data value crystal clear.
### 4. Skills-driven extensibility
Package domain knowledge, analysis methods, and execution workflows into reusable skills.
### 5. Sandboxed execution
Run code and tools in isolated environments for safer, more reliable analysis.
## Outcome
DB-GPT is designed for teams that want to go beyond simple chatbots and build practical AI + Data systems that can connect to data, reason with tools, and deliver reports, insights, and action.
---
### Docs Api App (`docs/docs/api/app.md`)
# App
Get started with the App API
# Chat App
```python
POST /api/v2/chat/completions
```
### Examples
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
### Stream Chat App
```shell
DBGPT_API_KEY=dbgpt
APP_ID={YOUR_APP_ID}
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\", \"chat_mode\": \"chat_app\", \"chat_param\": \"$APP_ID\"}"
```
```python
from dbgpt_client import Client
DBGPT_API_KEY = "dbgpt"
APP_ID="{YOUR_APP_ID}"
client = Client(api_key=DBGPT_API_KEY)
async for data in client.chat_stream(
messages="Introduce AWEL",
model="gpt-4o",
chat_mode="chat_app",
chat_param=APP_ID
):
print(data)
```
### Chat Completion Stream Response
```commandline
data: {"id": "109bfc28-fe87-452c-8e1f-d4fe43283b7d", "created": 1710919480, "model": "gpt-4o", "choices": [{"index": 0, "delta": {"role": "assistant", "content": "```agent-plans\n[{\"name\": \"Introduce Awel\", \"num\": 2, \"status\": \"complete\", \"agent\": \"Human\", \"markdown\": \"```agent-messages\\n[{\\\"sender\\\": \\\"Summarizer\\\", \\\"receiver\\\": \\\"Human\\\", \\\"model\\\": \\\"gpt-4o\\\", \\\"markdown\\\": \\\"Agentic Workflow Expression Language (AWEL) is a specialized language designed for developing large model applications with intelligent agent workflows. It offers flexibility and functionality, allowing developers to focus on business logic for LLMs applications without getting bogged down in model and environment details. AWEL uses a layered API design architecture, making it easier to work with. You can find examples and source code to get started with AWEL, and it supports various operators and environments. AWEL is a powerful tool for building native data applications through workflows and agents.\"}]\n```"}}]}
data: [DONE]
```
### Get App
```python
GET /api/v2/serve/apps/{app_id}
```
```shell
DBGPT_API_KEY=dbgpt
APP_ID={YOUR_APP_ID}
curl -X GET "http://localhost:5670/api/v2/serve/apps/$APP_ID" -H "Authorization: Bearer $DBGPT_API_KEY"
```
```python
from dbgpt_client import Client
from dbgpt_client.app import get_app
DBGPT_API_KEY = "dbgpt"
app_id = "{your_app_id}"
client = Client(api_key=DBGPT_API_KEY)
res = await get_app(client=client, app_id=app_id)
```
#### Query Parameters
________
app_id string Required
app id
________
#### Response body
Return App Object
### List App
```python
GET /api/v2/serve/apps
```
```shell
DBGPT_API_KEY=dbgpt
curl -X GET 'http://localhost:5670/api/v2/serve/apps' -H "Authorization: Bearer $DBGPT_API_KEY"
```
```python
from dbgpt_client import Client
from dbgpt_client.app import list_app
DBGPT_API_KEY = "dbgpt"
app_id = "{your_app_id}"
client = Client(api_key=DBGPT_API_KEY)
res = await list_app(client=client)
```
#### Response body
Return App Object List
### The App Model
________
app_code string
unique app id
________
app_name string
app name
________
app_describe string
app describe
________
team_mode string
team mode
________
language string
language
________
team_context string
team context
________
user_code string
user code
________
sys_code string
sys code
________
is_collected string
is collected
________
icon string
icon
________
created_at string
created at
________
updated_at string
updated at
________
details string
app details List[AppDetailModel]
________
### The App Detail Model
________
app_code string
app code
________
app_name string
app name
________
agent_name string
agent name
________
node_id string
node id
________
resources string
resources
________
prompt_template string
prompt template
________
llm_strategy string
llm strategy
________
llm_strategy_value string
llm strategy value
________
created_at string
created at
________
updated_at string
updated at
________
---
### Docs Api Benchmark (`docs/docs/api/benchmark.md`)
# Datasets Benchmark
Get started with the Benchmark API
### Create Dataset Benchmark Task
```python
POST /api/v2/serve/evaluate/execute_benchmark_task
```
```shell
DBGPT_API_KEY=dbgpt
SPACE_ID={YOUR_SPACE_ID}
curl -X POST "http://localhost:5670/api/v2/serve/evaluate/execute_benchmark_task" \
-H "Authorization: Bearer $DBGPT_API_KEY" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"scene_value": "Falcon_benchmark_01",
"model_list": ["DeepSeek-V3.1", "Qwen3-235B-A22B"]
}'
```
#### The Benchmark Request Object
________
scene_key string Required
The scene type of the evaluation, e.g. support app, recall
--------
scene_value string Required
The scene value of the benchmark, e.g. The marking evaluation task name
--------
model_list object Required
The model name list of the benchmark will execute, e.g. ["DeepSeek-V3.1","Qwen3-235B-A22B"]
Notice: The model name configured on the db-gpt platform needs to be entered.
--------
temperature float
The temperature of the llm model, Default is 0.7
--------
max_tokens int
The max tokens of the llm model, Default is None
--------
#### The Benchmark Result
________
status string
The benchmark status，e.g. success, failed, running
________
### Query Benchmark Task List
```python
GET /api/v2/serve/evaluate/benchmark_task_list
```
```shell
DBGPT_API_KEY=dbgpt
SPACE_ID={YOUR_SPACE_ID}
curl -X GET "http://localhost:5670/api/v2/serve/evaluate/benchmark_task_list?page=1&page_size=20" \
-H "Authorization: Bearer $DBGPT_API_KEY" \
-H "accept: application/json" \
-H "Content-Type: application/json"
```
#### The Benchmark Task List Request Object
________
page string Required
Query task list page number, Default is 1
--------
page_size string Required
Query task list page size, Default is 20
--------
#### The Benchmark Task List Result
```
/* Detailed source-code truncated for AI context efficiency. */
```
________
evaluate_code string
The benchmark task unique code
________
scene_key string
The benchmark task scene, e.g. dataset
________
scene_value string
The benchmark task name
________
datasets_name string
The benchmark execute dataset name
________
input_file_path string
The benchmark dataset file path
________
output_file_path string
The benchmark execute result file path
________
model_list object
The benchmark execute model list
________
context object
The benchmark task context
________
user_name string
The benchmark task user name
________
user_id string
The benchmark task user id
________
sys_code string
The benchmark task system code, e.g. benchmark_system
________
parallel_num int
The benchmark task execute parallel num
________
state string
The benchmark task state, e.g. running, success, failed
________
temperature float
The benchmark task LLM temperature
________
max_tokens int
The benchmark task LLM max tokens
________
log_info int
If benchmark task execute error, It will show error message,
________
gmt_create string
Task create time
________
gmt_modified string
Task Finish time
________
cost_time int
Benchmark Task cost time
________
round_time int
Benchmark Task execute round time
________
### Benchmark Compare Result
```python
GET /api/v2/serve/evaluate/benchmark/result/{evaluate_code}
```
```shell
DBGPT_API_KEY=dbgpt
SPACE_ID={YOUR_SPACE_ID}
curl -X GET "http://localhost:5670/api/v2/serve/evaluate/benchmark/result/{evaluate_code}" \
-H "Authorization: Bearer $DBGPT_API_KEY" \
-H "accept: application/json" \
-H "Content-Type: application/json"
```
#### The Benchmark Request Object
________
evaluate_code string Required
The benchMark task unique code
--------
#### The Benchmark Result
```json
{
"success": true,
"err_code": null,
"err_msg": null,
"data": {
"evaluate_code": "c827a274b4084f5dbce4c630f5267239",
"scene_value": "Falcon评测集_benchmark",
"summaries": [
{
"roundId": 1,
"llmCode": "Qwen3-Coder-480B-A35B-Instruct",
"right": 136,
"wrong": 269,
"failed": 95,
"exception": 0,
"accuracy": 0.272,
"execRate": 0.81,
"outputPath": "/DB-GPT/pilot/benchmark_meta_data/result/c827a274b4084f5dbce4c630f5267239/202510181449_multi_round_benchmark_result.xlsx"
}
]
}
}
```
________
roundId string
The benchmark task execute round time
________
llmCode string
The benchmark task execute model name
________
right int
The benchmark task execute right question number
________
wrong int
The benchmark task execute wrong question number
________
failed int
The benchmark task execute failed question number
________
exception int
The benchmark task execute exception question number
________
accuracy float
The benchmark task question list execute accuracy rate
________
execRate float
The benchmark task question list executable rate
________
outputPath string
The benchmark task execute result output file path
________
---
### Docs Api Chat (`docs/docs/api/chat.md`)
# Chat
Given a list of messages comprising a conversation, the model will return a response.
# Create Chat Completion
```python
POST /api/v2/chat/completions
```
### Examples
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
### Stream Chat Completion
```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}"
```
```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 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)
```
### Chat Completion Stream Response
```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: {"id": "chatcmpl-ba6fb52e-e5b2-11ee-b031-acde48001122", "model": "gpt-4o", "choices": [{"index": 0, "delta": {"role": "assistant", "content": " How"}}]}
data: {"id": "chatcmpl-ba6fb52e-e5b2-11ee-b031-acde48001122", "model": "gpt-4o", "choices": [{"index": 0, "delta": {"role": "assistant", "content": " can"}}]}
data: {"id": "chatcmpl-ba6fb52e-e5b2-11ee-b031-acde48001122", "model": "gpt-4o", "choices": [{"index": 0, "delta": {"role": "assistant", "content": " I"}}]}
data: {"id": "chatcmpl-ba6fb52e-e5b2-11ee-b031-acde48001122", "model": "gpt-4o", "choices": [{"index": 0, "delta": {"role": "assistant", "content": " assist"}}]}
data: {"id": "chatcmpl-ba6fb52e-e5b2-11ee-b031-acde48001122", "model": "gpt-4o", "choices": [{"index": 0, "delta": {"role": "assistant", "content": " you"}}]}
data: {"id": "chatcmpl-ba6fb52e-e5b2-11ee-b031-acde48001122", "model": "gpt-4o", "choices": [{"index": 0, "delta": {"role": "assistant", "content": " today"}}]}
data: {"id": "chatcmpl-ba6fb52e-e5b2-11ee-b031-acde48001122", "model": "gpt-4o", "choices": [{"index": 0, "delta": {"role": "assistant", "content": "?"}}]}
data: [DONE]
```
### Chat Completion
```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}"
```
```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()
```
### Chat Completion Response
```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
}
}
```
### Request body
________
messages string Required
A list of messages comprising the conversation so far. Example Python code.
________
model string Required
ID of the model to use. See the model endpoint compatibility table for details on which models work with the Chat API.
________
chat_mode string Optional
The DB-GPT chat mode, which can be one of the following: `chat_normal`, `chat_app`, `chat_knowledge`, `chat_flow`, default is `chat_normal`.
________
chat_param string Optional
The DB-GPT The chat param value of chat mode: `{app_id}`, `{space_id}`, `{flow_id}`, default is `None`.
________
max_new_tokens integer Optional
The maximum number of tokens that can be generated in the chat completion.
The total length of input tokens and generated tokens is limited by the model's context length.
________
stream integer Optional
If set, partial message deltas will be sent.
Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a `data: [DONE]`
________
temperature integer Optional
What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
________
conv_uid string Optional
The conversation id of the model inference, default is `None`
________
span_id string Optional
The span id of the model inference, default is `None`
________
sys_code string Optional
The system code, default is `None`
________
user_name string Optional
The web server user name, default is `None`
________
### Chat Stream Response Body
________
id string
conv_uid of the convsersation.
________
model string
The model used for the chat completion.
________
created string
The Unix timestamp (in seconds) of when the chat completion was created.
________
choices array
A list of chat completion choices. Can be more than one if n is greater than 1.
- index integer
The index of the choice in the list of choices.
- delta object
The chat completion delta.
- role string
The role of the speaker. Can be `user` or `assistant`.
- content string
The content of the message.
- finish_reason string
The reason the chat completion finished. Can be `max_tokens` or `stop`.
________
### Chat Response Body
________
id string
conv_uid of the convsersation.
________
model string
The model used for the chat completion.
________
created string
The Unix timestamp (in seconds) of when the chat completion was created.
________
object string
The object type of the chat completion.
________
choices array
A list of chat completion choices. Can be more than one if n is greater than 1.
- index integer
The index of the choice in the list of choices.
- delta object
The chat completion delta.
- role string
The role of the speaker. Can be `user` or `assistant`.
- content string
The content of the message.
- finish_reason string
The reason the chat completion finished. Can be `max_tokens` or `stop`.
________
usage object
The usage statistics for the chat completion.
- prompt_tokens integer
The number of tokens in the prompt.
- total_tokens integer
The total number of tokens in the chat completion.
- completion_tokens integer
The number of tokens in the chat completion.
---
### Docs Api Datasource (`docs/docs/api/datasource.md`)
# Datasource
Get started with the Datasource API
# Chat Datasource
```python
POST /api/v2/chat/completions
```
### Examples
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
### Chat Datasource
```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
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
)
```
```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:
delta_content = chunk.choices[0].delta.content
print(delta_content, end="", flush=True)
```
#### Chat Completion Response
```
/* Detailed source-code truncated for AI context efficiency. */
```
### Create Datasource
```python
POST /api/v2/serve/datasources
```
#### Request body
Request Datasource Object
#### Response body
Return Datasource Object
### Update Datasource
```python
PUT /api/v2/serve/datasources
```
#### Request body
Request Datasource Object
#### Response body
Return Datasource Object
### Delete Datasource
```python
DELETE /api/v2/serve/datasources
```
```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
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)
```
#### Delete Parameters
________
datasource_id string Required
datasource id
________
#### Response body
Return Datasource Object
### Get Datasource
```python
GET /api/v2/serve/datasources/{datasource_id}
```
```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
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)
```
#### Query Parameters
________
datasource_id string Required
datasource id
________
#### Response body
Return Datasource Object
### List Datasource
```python
GET /api/v2/serve/datasources
```
```shell
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)
```
#### Response body
Return Datasource Object
### The Datasource Object
________
id string
The unique id for the datasource.
________
db_name string
The Database name
________
db_type string
Database type, e.g. sqlite, mysql, etc.
________
db_path string
File path for file-based database.
________
db_host string
Database host.
________
db_port object
Database port.
________
db_user string
Database user.
________
db_pwd string
Database password.
________
comment string
Comment for the database.
________
---
### Docs Api Evaluation (`docs/docs/api/evaluation.md`)
# Evaluation
Get started with the Evaluation API
### Create Evaluation
```python
POST /api/v2/serve/evaluate/evaluation
```
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
```shell
DBGPT_API_KEY=dbgpt
SPACE_ID={YOUR_SPACE_ID}
curl -X POST "http://localhost:5670/api/v2/serve/evaluate/evaluation"
-H "Authorization: Bearer $DBGPT_API_KEY" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"scene_key": "recall",
"scene_value":147,
"context":{"top_k":5},
"sys_code":"xx",
"evaluate_metrics":["RetrieverHitRateMetric","RetrieverMRRMetric","RetrieverSimilarityMetric"],
"datasets": [{
"query": "what awel talked about",
"doc_name":"awel.md"
}]
}'
```
```python
from dbgpt_client import Client
from dbgpt_client.evaluation import run_evaluation
from dbgpt.serve.evaluate.api.schemas import EvaluateServeRequest
DBGPT_API_KEY = "dbgpt"
client = Client(api_key=DBGPT_API_KEY)
request = EvaluateServeRequest(
# The scene type of the evaluation, e.g. support app, recall
scene_key="recall",
# e.g. app id(when scene_key is app), space id(when scene_key is recall)
scene_value="147",
context={"top_k": 5},
evaluate_metrics=[
"RetrieverHitRateMetric",
"RetrieverMRRMetric",
"RetrieverSimilarityMetric",
],
datasets=[
{
"query": "what awel talked about",
"doc_name": "awel.md",
}
],
)
data = await run_evaluation(client, request=request)
```
#### Request body
Request Evaluation Object
when scene_key is app, the request body should be like this:
```json
{
"scene_key": "app",
"scene_value":"2c76eea2-83b6-11ef-b482-acde48001122",
"context":{"top_k":5, "prompt":"942acd7e33b54ce28565f89f9b278044","model":"zhipu_proxyllm"},
"sys_code":"xx",
"evaluate_metrics":["AnswerRelevancyMetric"],
"datasets": [{
"query": "what awel talked about",
"doc_name":"awel.md"
}]
}
```
when scene_key is recall, the request body should be like this:
```json
{
"scene_key": "recall",
"scene_value":"2c76eea2-83b6-11ef-b482-acde48001122",
"context":{"top_k":5, "prompt":"942acd7e33b54ce28565f89f9b278044","model":"zhipu_proxyllm"},
"evaluate_metrics":["RetrieverHitRateMetric", "RetrieverMRRMetric", "RetrieverSimilarityMetric"],
"datasets": [{
"query": "what awel talked about",
"doc_name":"awel.md"
}]
}
```
#### Response body
Return Evaluation Object List
### The Evaluation Request Object
________
scene_key string Required
The scene type of the evaluation, e.g. support app, recall
--------
scene_value string Required
The scene value of the evaluation, e.g. app id(when scene_key is app), space id(when scene_key is recall)
--------
context object Required
The context of the evaluation
- top_k int Required
- prompt string prompt code
- model string llm model name
--------
evaluate_metrics array Required
The evaluate metrics of the evaluation,
e.g.
- AnswerRelevancyMetric: the answer relevancy metric(when scene_key is app)
- RetrieverHitRateMetric: Hit rate calculates the fraction of queries where the correct answer is found
within the top-k retrieved documents. In simpler terms, it’s about how often our
system gets it right within the top few guesses. (when scene_key is recall)
- RetrieverMRRMetric: For each query, MRR evaluates the system’s accuracy by looking at the rank of the
highest-placed relevant document. Specifically, it’s the average of the reciprocals
of these ranks across all the queries. So, if the first relevant document is the
top result, the reciprocal rank is 1; if it’s second, the reciprocal rank is 1/2,
and so on. (when scene_key is recall)
- RetrieverSimilarityMetric: Embedding Similarity Metric (when scene_key is recall)
--------
datasets array Required
The datasets of the evaluation
--------
### The Evaluation Result
________
prediction string
The prediction result
________
contexts string
The contexts of RAG Retrieve chunk
________
score float
The score of the prediction
________
passing bool
The passing of the prediction
________
metric_name string
The metric name of the evaluation
________
prediction_cost int
The prediction cost of the evaluation
________
query string
The query of the evaluation
________
raw_dataset object
The raw dataset of the evaluation
________
feedback string
The feedback of the llm evaluation
________
---
### Docs Api Flow (`docs/docs/api/flow.md`)
# Flow
Get started with the Flow API
# Chat Flow
```python
POST /api/v2/chat/completions
```
### Examples
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
### Stream Chat Flow
```shell
DBGPT_API_KEY=dbgpt
FLOW_ID={YOUR_FLOW_ID}
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\", \"chat_mode\": \"chat_flow\", \"chat_param\": \"$FLOW_ID\"}"
```
```python
from dbgpt_client import Client
DBGPT_API_KEY = "dbgpt"
FLOW_ID="{YOUR_FLOW_ID}"
client = Client(api_key=DBGPT_API_KEY)
async for data in client.chat_stream(
messages="Introduce AWEL",
model="gpt-4o",
chat_mode="chat_flow",
chat_param=FLOW_ID
):
print(data)
```
```python
from openai import OpenAI
DBGPT_API_KEY = "dbgpt"
FLOW_ID="{YOUR_FLOW_ID}"
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_flow",
"chat_param": FLOW_ID,
},
stream=True,
max_tokens=2048,
)
for chunk in response:
delta_content = chunk.choices[0].delta.content
print(delta_content, end="", flush=True)
```
#### Chat Completion Stream Response
```commandline
data: {"id": "579f8862-fc4b-481e-af02-a127e6d036c8", "created": 1710918094, "model": "gpt-4o", "choices": [{"index": 0, "delta": {"role": "assistant", "content": "\n\n"}}]}
```
### Create Flow
```python
POST /api/v2/serve/awel/flows
```
#### Request body
Request Flow Object
#### Response body
Return Flow Object
### Update Flow
```python
PUT /api/v2/serve/awel/flows/{uid}
```
#### Request body
Request Flow Object
#### Response body
Return Flow Object
### Delete Flow
```python
DELETE /api/v2/serve/awel/flows/{uid}
```
```shell
DBGPT_API_KEY=dbgpt
FLOW_ID={YOUR_FLOW_ID}
curl -X DELETE "http://localhost:5670/api/v2/serve/awel/flows/$FLOW_ID" \
-H "Authorization: Bearer $DBGPT_API_KEY" \
```
```python
from dbgpt_client import Client
from dbgpt_client.flow import delete_flow
DBGPT_API_KEY = "dbgpt"
flow_id = "{your_flow_id}"
client = Client(api_key=DBGPT_API_KEY)
res = await delete_flow(client=client, flow_id=flow_id)
```
#### Delete Parameters
________
uid string Required
flow id
________
#### Response body
Return Flow Object
### Get Flow
```python
GET /api/v2/serve/awel/flows/{flow_id}
```
```shell
DBGPT_API_KEY=dbgpt
FLOW_ID={YOUR_FLOW_ID}
curl -X GET "http://localhost:5670/api/v2/serve/awel/flows/$FLOW_ID" -H "Authorization: Bearer $DBGPT_API_KEY"
```
```python
from dbgpt_client import Client
from dbgpt_client.flow import get_flow
DBGPT_API_KEY = "dbgpt"
flow_id = "{your_flow_id}"
client = Client(api_key=DBGPT_API_KEY)
res = await get_flow(client=client, flow_id=flow_id)
```
#### Query Parameters
________
uid string Required
flow id
________
#### Response body
Return Flow Object
### List Flow
```python
GET /api/v2/serve/awel/flows
```
```shell
DBGPT_API_KEY=dbgpt
curl -X GET "http://localhost:5670/api/v2/serve/awel/flows" -H "Authorization: Bearer $DBGPT_API_KEY"
```
```python
from dbgpt_client import Client
from dbgpt_client.flow import list_flow
DBGPT_API_KEY = "dbgpt"
client = Client(api_key=DBGPT_API_KEY)
res = await list_flow(client=client)
```
#### Response body
Return Flow Object
### The Flow Object
________
uid string
The unique id for the flow.
________
name string
The name of the flow.
________
description string
The description of the flow.
________
label string
The label of the flow.
________
flow_category string
The category of the flow. Default is FlowCategory.COMMON.
________
flow_data object
The flow data.
________
state string
The state of the flow.Default is INITIALIZING.
________
error_message string
The error message of the flow.
________
source string
The source of the flow. Default is DBGPT-WEB.
________
source_url string
The source url of the flow.
________
version string
The version of the flow. Default is 0.1.0.
________
editable boolean
Whether the flow is editable. Default is True.
________
user_name string
The user name of the flow.
________
sys_code string
The system code of the flow.
________
dag_id string
The dag id of the flow.
________
gmt_created string
The created time of the flow.
________
gmt_modified string
The modified time of the flow.
________
---
### Docs Api Introduction (`docs/docs/api/introduction.md`)
# Introduction
This is the introduction to the DB-GPT API documentation. You can interact with the API through HTTP requests from any language, via our official Python Client bindings.
## Authentication
The DB-GPT API uses API keys for authentication. Visit your API Keys page to retrieve the API key you'll use in your requests.
Production requests must be routed through your own backend server where your API key can be securely loaded from an environment variable or key management service.
All API requests should include your API key in an Authorization HTTP header as follows:
```http
Authorization: Bearer DBGPT_API_KEY
```
Example with the DB-GPT API curl command:
```bash
curl "http://localhost:5670/api/v2/chat/completions" \
-H "Authorization: Bearer $DBGPT_API_KEY" \
```
Example with the DB-GPT Client Python package:
```python
from dbgpt_client import Client
DBGPT_API_KEY = "dbgpt"
client = Client(api_key=DBGPT_API_KEY)
```
Set the API Key in .env file as follows:
:::info note
API_KEYS - The list of API keys that are allowed to access the API. Each of the below are an option, separated by commas.
:::
```python
API_KEYS=dbgpt
```
## Using the DB-GPT official Python Client
If you use Python, you should install the official DB-GPT Client package from PyPI:
```bash
pip install "dbgpt-client>=0.7.1rc0"
```
## Using the OpenAI Python SDK
In some chat cases, you can use the OpenAI Python SDK to interact with the DB-GPT API. The DB-GPT API is compatible with the OpenAI API.
```bash
pip install openai
```
---
### Docs Api Knowledge (`docs/docs/api/knowledge.md`)
# Knowledge
Get started with the Knowledge API
# Chat Knowledge Space
```python
POST /api/v2/chat/completions
```
### Examples
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
### Chat Knowledge
```shell
DBGPT_API_KEY=dbgpt
SPACE_NAME={YOUR_SPACE_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\":\"Hello\",\"model\":\"gpt-4o\", \"chat_mode\": \"chat_knowledge\", \"chat_param\": \"$SPACE_NAME\"}"
```
```python
from dbgpt_client import Client
DBGPT_API_KEY = "dbgpt"
SPACE_NAME="{YOUR_SPACE_NAME}"
client = Client(api_key=DBGPT_API_KEY)
async for data in client.chat_stream(
messages="Introduce AWEL",
model="gpt-4o",
chat_mode="chat_knowledge",
chat_param=SPACE_NAME
):
print(data)
```
```python
from openai import OpenAI
DBGPT_API_KEY = "dbgpt"
SPACE_NAME="{YOUR_SPACE_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_knowledge",
"chat_param": SPACE_NAME,
},
stream=True,
max_tokens=2048,
)
for chunk in response:
delta_content = chunk.choices[0].delta.content
print(delta_content, end="", flush=True)
```
#### Chat Completion Response
```json
{
"id": "acb050ab-eb2c-4754-97e4-6f3b94b7dac2",
"object": "chat.completion",
"created": 1710917272,
"model": "gpt-4o",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Agentic Workflow Expression Language (AWEL) is a specialized language designed for developing large model applications with intelligent agent workflows. It offers flexibility and functionality, allowing developers to focus on business logic for LLMs applications without getting bogged down in model and environment details. AWEL uses a layered API design architecture, making it easier to work with. You can find examples and source code to get started with AWEL, and it supports various operators and environments. AWEL is a powerful tool for building native data applications through workflows and agents."
},
"finish_reason": null
}
],
"usage": {
"prompt_tokens": 0,
"total_tokens": 0,
"completion_tokens": 0
}
}
```
#### Chat Completion Stream Response
```
/* Detailed source-code truncated for AI context efficiency. */
```
### Create Knowledge Space
```python
POST /api/v2/serve/knowledge/spaces
```
```shell
DBGPT_API_KEY="dbgpt"
curl --location --request POST 'http://localhost:5670/api/v2/serve/knowledge/spaces' \
--header 'Authorization: Bearer $DBGPT_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{"desc": "for client space desc", "name": "test_space_2", "owner": "dbgpt", "vector_type": "Chroma"
}'
```
```python
from dbgpt_client import Client
from dbgpt_client.knowledge import create_space
from dbgpt_client.schema import SpaceModel
DBGPT_API_KEY = "dbgpt"
client = Client(api_key=DBGPT_API_KEY)
res = await create_space(client, SpaceModel(
name="test_space",
vector_type="Chroma",
desc="for client space",
owner="dbgpt"
))
```
#### Request body
________
name string Required
knowledge space name
________
vector_type string Required
vector db type, `Chroma`, `Milvus`, default is `Chroma`
________
desc string Optional
description of the knowledge space
________
owner integer Optional
The owner of the knowledge space
________
context integer Optional
The context of the knowledge space argument
________
#### Response body
Return Space Object
### Update Knowledge Space
```python
PUT /api/v2/serve/knowledge/spaces
```
```shell
DBGPT_API_KEY="dbgpt"
curl --location --request PUT 'http://localhost:5670/api/v2/serve/knowledge/spaces' \
--header 'Authorization: Bearer $DBGPT_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{"desc": "for client space desc v2", "id": "49", "name": "test_space_2", "owner": "dbgpt", "vector_type": "Chroma"
}'
```
```python
from dbgpt_client import Client
from dbgpt_client.knowledge import update_space
from dbgpt_client.schema import SpaceModel
DBGPT_API_KEY = "dbgpt"
client = Client(api_key=DBGPT_API_KEY)
res = await update_space(client, SpaceModel(
name="test_space",
vector_type="Chroma",
desc="for client space update",
owner="dbgpt"
))
```
#### Request body
________
id string Required
knowledge space id
________
name string Required
knowledge space name
________
vector_type string Optional
vector db type, `Chroma`, `Milvus`, default is `Chroma`
________
desc string Optional
description of the knowledge space
________
owner integer Optional
The owner of the knowledge space
________
context integer Optional
The context of the knowledge space argument
________
#### Response body
Return Space Object
### Delete Knowledge Space
```python
DELETE /api/v2/serve/knowledge/spaces
```
```shell
DBGPT_API_KEY=dbgpt
SPACE_ID={YOUR_SPACE_ID}
curl -X DELETE "http://localhost:5670/api/v2/serve/knowledge/spaces/$SPACE_ID" \
-H "Authorization: Bearer $DBGPT_API_KEY" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
```
```python
from dbgpt_client import Client
from dbgpt_client.knowledge import delete_space
DBGPT_API_KEY = "dbgpt"
space_id = "{your_space_id}"
client = Client(api_key=DBGPT_API_KEY)
res = await delete_space(client=client, space_id=space_id)
```
#### Delete Parameters
________
id string Required
knowledge space id
________
#### Response body
Return Space Object
### Get Knowledge Space
```python
GET /api/v2/serve/knowledge/spaces/{space_id}
```
```shell
DBGPT_API_KEY=dbgpt
SPACE_ID={YOUR_SPACE_ID}
curl -X GET "http://localhost:5670/api/v2/serve/knowledge/spaces/$SPACE_ID" -H "Authorization: Bearer $DBGPT_API_KEY"
```
```python
from dbgpt_client import Client
from dbgpt_client.knowledge import get_space
DBGPT_API_KEY = "dbgpt"
space_id = "{your_space_id}"
client = Client(api_key=DBGPT_API_KEY)
res = await get_space(client=client, space_id=space_id)
```
#### Query Parameters
________
id string Required
knowledge space id
________
#### Response body
Return Space Object
### List Knowledge Space
```python
GET /api/v2/serve/knowledge/spaces
```
```shell
DBGPT_API_KEY=dbgpt
curl -X GET 'http://localhost:5670/api/v2/serve/knowledge/spaces' -H "Authorization: Bearer $DBGPT_API_KEY"
```
```python
from dbgpt_client import Client
from dbgpt_client.knowledge import list_space
DBGPT_API_KEY = "dbgpt"
space_id = "{your_space_id}"
client = Client(api_key=DBGPT_API_KEY)
res = await list_space(client=client)
```
#### Response body
Return Space Object List
### The Space Object
________
id string
space id
________
name string
knowledge space name
________
vector_type string
vector db type, `Chroma`, `Milvus`, default is `Chroma`
________
desc string Optional
description of the knowledge space
________
owner integer Optional
The owner of the knowledge space
________
context integer Optional
The context of the knowledge space argument
________
---
### Docs Application Awel (`docs/docs/application/awel.md`)
# Use Data App With AWEL
## What Is AWEL?
> Agentic Workflow Expression Language(AWEL) is a set of intelligent agent workflow expression language specially designed for large model application
development.
You can found more information about AWEL in [AWEL](../awel/awel.md) and
[AWEL Tutorial](../awel/tutorial/) if you want to know more about AWEL.
In short, you can use AWEL to develop LLM applications with AWEL Python API.
## What Is AWEL Flow?
AWEL flow allows you to develop LLM applications without writing code. It is built on top of AWEL Python API.
## Visit Your AWEL Flows in `AWEL Flow` Page
In the `AWEL Flow` page, you can see all the AWEL flows you have created. You can also create a new AWEL flow by clicking the `Create Flow` button.
## Examples
### Build Your RAG Application
To build your RAG application, you need to create a knowledge space according to [Chat Knowledge Base](./apps/chat_knowledge.md) first.
Then, click the `Create Flow` button to create a new flow.
In the flow editor, you can drag and drop the nodes to build your RAG application.
1. You will see an empty flow editor like below:
2. Drag a `Streaming LLM Operator` node to the flow editor.
3. Drag a `Knowledge Operator` node to the flow editor.
You can click the "+" button in the `Streaming LLM Operator` node's second input(`"HOContext"`),
it will show a list of nodes that can be connected to current node of input, then you can select the `Knowledge Operator` node.
The options of nodes can be connected as follows:
Then, drag the `Knowledge Operator` node and connect it to the `Streaming LLM Operator` node.
Please select your knowledge space in the `Knowledge Operator` node's `Knowledge Space Name` option.
4. Drag a `Common LLM Http Trigger` node to the flow editor.
4. Drag a `Common Chat Prompt Template` **resource** node to the flow editor.
And you can type your prompt template in the `Common Chat Prompt Template` parameters.
5. Drag a `OpenAI Streaming Output Operator` node to the flow editor.
6. Click the `Save` button in the top right corner to save your flow.
Lastly, you will see your RAG application in the `AWEL Flow` page.
After that, you can use it to build your APP according to [App Manage](./apps/app_manage.md).
## Reference
- [AWEL](../awel/awel.md)
- [AWEL CookBook](../awel/cookbook/)
- [AWEL Tutorial](../awel/tutorial/)
---
📖 Want to learn more about AWEL? Check out the [AWEL Tutorial](../awel/tutorial/) for step-by-step guides from basics to advanced patterns.
---
### Docs Application Datasources (`docs/docs/application/datasources.md`)
# Datasources
The DB-GPT data source module is designed to manage the structured and semi-structured data assets of an enterprise, connect databases, data warehouses, data lakes, etc. to the DB-GPT framework, and quickly build data-based intelligent applications and large models. Currently, DB-GPT supports some common data sources and also supports custom extensions.
You can add data sources through the upper right corner **Add a data source** button to add. In the pop-up dialog box, select the corresponding database type and fill in the required parameters to complete the addition.
## Supported Datasource Types
The current documentation covers or is being extended for the following datasources:
- MySQL
- SQLite
- ClickHouse
- PostgreSQL
- DuckDB
- Hive
- MSSQL
- Oracle
- OceanBase
- GaussDB
- openGauss
- Apache Doris
- StarRocks
- Vertica
---
### Docs Application Graph Rag (`docs/docs/application/graph_rag.md`)
# Graph RAG
Graph RAG is the retrieval mode that uses DB-GPT's **knowledge-graph index**. When you enable the `KnowledgeGraph` index method on a knowledge space, DB-GPT builds a *family of graphs* and retrieves by graph traversal instead of (or in addition to) vector / keyword search.
## What gets built
| Graph | Built for | Captures |
|---|---|---|
| **LLM triplet graph** | any text | `(subject, predicate, object)` facts and relations |
| **Document–paragraph graph** | any document | `document → chunk → chunk` structure (`include` / `next`) |
| **Markdown heading graph** | `.md` files | `file → H1 → H2 → H3` heading hierarchy (`contains`) |
| **Code graph** | code files / `GIT_REPO` spaces | code AST parsed with **tree-sitter** → `function` / `class` / `method` nodes with `file → defines` edges |
All four share one build path and write into the configured graph store (TuGraph / Neo4j / Memgraph).
## How retrieval works
The `GraphRetriever` matches graph nodes by keyword, by vector similarity on node embeddings, by natural-language-to-graph-query (Text2GQL), and via document–graph associations — then expands along edges. Every edge remembers the chunk it came from, so answers remain citable.
:::note
The retriever can traverse `CALLS` / `INHERITS` / `IMPLEMENTS` edges, but the current code-graph builder only emits `contains` and `defines`. Call-chain and inheritance queries will be empty unless those edges were produced by another builder.
:::
## Learn more
- [Knowledge Base Indexing Principles](/docs/design/kb_index_principles) — the graph family and code-graph AST parsing in depth
- [Agentic RAG Conversation Principles](/docs/design/agentic_rag_principles) — how graph retrieval fits into the agentic loop
- [Graph RAG Cookbook](/docs/cookbook/rag/graph_rag_app_develop) — build a Graph RAG app programmatically
- [TuGraph integration](/docs/installation/integrations/graph_rag_install) — install the graph-store backend
---
### Docs Application Llms (`docs/docs/application/llms.md`)
# LLMs
In the new version, the location of model management has moved to **Application Management** Under the panel, other functional modules remain unchanged
For the use of multi-model management, please refer to the following documents.
- [Multi-Model Management](../application/advanced_tutorial/smmf.md)
- [Model Service deployment](../installation/model_service/)
- [Introduction to the principles of multi-model management](../modules/smmf.md)
---
### Docs Application Mcp Connectors (`docs/docs/application/mcp_connectors.md`)
---
sidebar_position: 1
title: MCP Connectors
---
# MCP Connectors
**MCP Connectors** let your DB-GPT agents reach beyond the database — sending messages, reading and writing documents, managing issues, and searching the web — by connecting to external services through the **Model Context Protocol (MCP)**.
Activate a built-in template or plug in any custom MCP server, then pick the connectors you want in the composer. The agent only sees the tools you select, and any write action pauses for your confirmation first.
:::info What is MCP?
The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that gives AI applications a uniform way to talk to external tools and services. Each connector in DB-GPT is backed by an MCP server, so adding a new capability is as simple as pointing to its endpoint.
:::
## Highlights
- **Built-in templates** — One-click activation for Feishu, DingTalk, Yuque, GitHub, Notion, Linear, Tavily, Keenable Search, and DeepWiki.
- **Custom MCP servers** — Connect any SSE or Streamable HTTP MCP endpoint with your own auth.
- **Per-conversation selection** — Choose which connectors to attach in the composer; the agent's prompt stays focused and token-efficient.
- **Human-in-the-loop confirmation** — Write actions (create / update / delete) pop a confirmation dialog before they run.
- **Tool transparency** — Inspect the full tool list of any connector, with parameters and descriptions.
- **Secure credentials** — Tokens are encrypted at rest and survive process restarts.
## How it works
```mermaid
graph LR
User[You] -->|select connectors| Composer[Home Composer]
Composer -->|connector_ids| Agent[ReAct Agent]
Agent -->|only selected tools| MCPClient[MCP Client]
MCPClient --> S1[Feishu / DingTalk / Yuque ...]
MCPClient --> S2[Custom MCP Server]
Agent -.write action.-> Confirm{Confirm?}
Confirm -->|approve| MCPClient
Confirm -->|reject| Skip[Skip action]
```
A connector lives in one of three states:
| State | Meaning |
| --- | --- |
| **Available** | A template in the catalog, or the generic "custom MCP" entry — not yet configured. |
| **Active** | Configured with credentials and connected; its tools are ready to use. |
| **Attached** | Selected in the current conversation — the agent actually injects its tools. |
## Built-in connectors
| Connector | Category | Default transport | Typical tools |
| --- | --- | --- | --- |
| Feishu | Communication | SSE | Send messages, read / write docs, calendar |
| DingTalk | Communication | SSE | Group messages, bot notifications |
| Yuque | Document | SSE | Read / write knowledge base docs |
| GitHub | Project | Streamable HTTP | Issues, PRs, repository management |
| Notion | Document | Streamable HTTP | Pages and databases read / write |
| Linear | Project | Streamable HTTP | Issues / projects collaboration |
| Tavily | Search | Streamable HTTP | LLM-optimized web search, returns Markdown |
| Keenable Search | Search | Streamable HTTP | Web search and page fetch; works without an account or API key |
| DeepWiki | Dev Tools | Streamable HTTP | AI reading & Q&A over any GitHub repo |
## Managing connectors
Open the **Connectors** page to see every template and custom server as a card. Each card shows the icon, name, a `Template` / `Custom` badge, its category, the `MCP / SSE` (or Streamable HTTP) transport, and a short description. Use the search box and the **All / Active / Inactive / Needs attention** tabs to filter.
- **Template cards** show an `Activate` button — click it to fill in credentials and connect.
- **Active cards** show an `● Active` badge and quick actions to test the connection, edit, or delete.
### Add a connector
Click **Add Connector** to open the dialog:
| Field | Description |
| --- | --- |
| **Connector name** | A display name for this connector. |
| **Connector type** | Pick a built-in template or **Custom MCP Server**. |
| **Transport protocol** | **Streamable HTTP** (default) or **SSE**. |
| **Auth type** | `none`, `bearer`, or `token` — show the token / header fields as needed. |
| **Connector description** | Optional. Shown in the agent's tool description. |
For a custom server, just provide the endpoint URL, transport, and authentication. Credentials are encrypted before they are stored.
### Example: activate Keenable Search
Keenable Search is a hosted MCP server for web search and page fetching. It does not require an account or an API key: the public tier is rate-limited, and an optional `KEENABLE_API_KEY` raises those limits. Queries and URLs are sent to Keenable.
1. On the **Keenable Search** card, click **Activate**.
2. Set **Streamable HTTP Endpoint URL** to `https://api.keenable.ai/mcp`.
3. Leave **Auth type** as `none`. To use an API key instead, choose `bearer` and paste the key into the token field (it is sent as `Authorization: Bearer `).
4. Save. The connector exposes two read-only tools, `search_web_pages` and `fetch_page_content`, so no confirmation dialog is involved.
### Inspect the tools
Open a connector's detail to browse every tool it exposes. The panel lists each tool name with its description and an **Input parameters** table (name, type, required, description) — useful for understanding exactly what the agent can call.
## Using connectors in a conversation
1. On the home page, open the connector picker in the composer toolbar (**Select MCP**).
2. Tick one or more connectors. The composer shows the selected count, and the agent will only be given those connectors' tools.
3. Ask your question. When the agent needs a tool, it calls it automatically.
4. If the agent triggers a **write action** (for example, creating a doc or sending a message), a confirmation dialog appears. Approve to run it, or reject to skip — the agent continues either way.
:::tip Why selection matters
Attaching only the connectors you need keeps the agent's prompt focused, reduces token usage, and prevents the model from picking the wrong tool.
:::
## Notes & limitations
- Built-in templates ship with sensible `confirm` actions (write operations require confirmation); custom MCP tools run without confirmation in this release.
- Credentials are scoped per user and restored automatically after a restart.
- If a server is offline at startup, its connector is marked so you can re-test it from the card.
---
### Docs Application Prompts (`docs/docs/application/prompts.md`)
# Prompts
In the actual application development process, Prompt needs to be customized in different scenarios, Agent, RAG and other modules. In order to make the editing and adjustment of Prompt more flexible, an independent Prompt module is created.
## Browse
As shown in the figure below, click **Application Management** ->**Prompt** You can enter the corresponding management interface. The interface displays a custom prompt list by default, and you can manage all prompts.
## Added
Next, let's see how to create a new prompt. Click the **Add Prompt** button and the prompt edit box will pop up.
We define four types of prompts:
- AGENT: Agent Prompt
- SCENE: Scene Prompt
- NORMAL: Normal prompt word
- EVALUATE: Evaluation Mode Prompt
When the AGENT type is selected, all registered agents can be seen in the drop-down list menu, and you can select an agent to set the prompt.
After setting the prompt, a unique UID will be generated. You can bind the corresponding prompt according to the ID when using it.
## Usage
Enter the AWEL editing interface, as shown below, click **Application Management** -> **Create Workflow**
Find the Agent resource and select the AWEL Layout Agent operator. We can see that each Agent contains the following information:
- Profile
- Role
- Goal
- Resource (AWELResource): The resource that Agent depends on
- AgentConfig(AWELAgentConfig) Agent Config
- AgentPrompt: Prompt
Click the [+] next to **AgentPrompt**, select the Prompt operator that pops up, and select the corresponding Prompt name or UID in the parameter panel to bind our newly created Prompt to the Agent, and debug the Agent's behavior in turn.
---
### Docs Application Scheduled Tasks (`docs/docs/application/scheduled_tasks.md`)
---
sidebar_position: 2
title: Scheduled Tasks
---
# Scheduled Tasks
**Scheduled Tasks** turn a one-off conversation into a recurring job. Run a data analysis once, save it as a task, and DB-GPT replays the whole ReAct Agent flow on a cron schedule — generating a fresh report every time.
Every run produces a brand-new conversation you can replay later, so you always have a full history of what was generated and when.
:::info Built-in, zero config
The scheduler runs inside the webserver process and starts automatically. No extra service to deploy.
:::
## Highlights
- **Save any conversation** — Freeze a finished conversation (question + model + selected skill / connectors) into a repeatable task.
- **Flexible scheduling** — Pick a preset (Hourly / Daily / Weekly / Monthly) or write a custom cron expression, with a live "next run" preview.
- **Automatic replay** — At each cron tick the agent re-runs the full flow and writes the result to history.
- **Execution history** — Every run records its status, duration, and a result summary.
- **Replay without re-running** — Open any past run to view its conversation snapshot — pure read, zero LLM calls.
- **Restart self-healing** — Enabled tasks are reloaded into the scheduler when the process restarts.
## How it works
```mermaid
graph TB
Conv[Finished conversation] -->|Save as task| Task[Scheduled Task
cron + snapshot]
Task --> Scheduler[In-process Scheduler]
Scheduler -->|cron tick| Runner[Chat Replay Runner]
Runner -->|replay| Agent[ReAct Agent flow]
Agent --> NewConv[New conversation + report]
NewConv --> History[Run history]
History -.View.-> Replay[Read-only replay]
```
## Saving a conversation as a task
After a conversation has produced a report, open **Save as Scheduled Task** from the home page.
| Field | Description |
| --- | --- |
| **Task name** | Required. A name for the task. |
| **Description** | Optional. A note about what the task does. |
| **Frequency** | `Hourly` / `Daily` / `Weekly` / `Monthly`, or `Custom` for a raw cron expression. |
| **Cron expression** | Shown live as you adjust the frequency (e.g. `0 9 * * *`). |
The **"Will reuse this conversation environment (read-only)"** section shows the frozen context — the model and the original question — that each run will replay. Click **Save & enable** to create the task and schedule it.
## Managing tasks
The **Scheduled Tasks** page lists every task with its status, cron expression, next run time, and creator. Use the search box and the **All / Enabled / Paused** tabs to filter, and the **Enable** toggle to pause or resume a task.
| Column | Description |
| --- | --- |
| **Task name** | Name and description. |
| **Status** | `Enabled` or `Paused`. |
| **Cron expression** | The active schedule. |
| **Next run** | When the task will fire next. |
| **Creator** | Who created the task. |
| **Enable** | Toggle to pause / resume. |
| **Actions** | Edit or delete. |
## Task detail & execution history
Open a task to see its full configuration and run history.
- **Basic info** — status, cron expression, next run, creator, created time.
- **Task environment (read-only)** — the original question, model, and database that every run replays.
- **Execution history** — the most recent runs, each with status (`Success` / `Failed` / `Timeout` / `Running`), start time, duration, and a result summary.
Click **View** on any run to jump to the home page and **replay that run's conversation** — the full step stream and report are restored from history with no LLM calls. A banner at the top reminds you the conversation was generated by a scheduled task, with a link back to the task detail.
## How it runs
1. The in-process scheduler holds one job per enabled task, keyed by its cron expression.
2. When a job fires, the runner starts a **new conversation** and replays the saved request against the agent.
3. The run is recorded with its status, a summary, and the new conversation id used for replay.
4. Runs are independent — a failure is logged against that run and the task simply waits for the next tick.
:::tip Replay is read-only
"View" loads a past run's stored conversation from the database. It never re-executes the agent, so it's instant and free.
:::
## Notes & limitations
- Tasks do not retry on failure — a failed or timed-out run is recorded and the task waits for the next scheduled time.
- Each run has a hard execution timeout to guard against runaway agents.
- In this release tasks are shared across users (the creator is shown for auditing); per-user isolation and notifications are planned for later.
---
### Docs Awel Awel (`docs/docs/awel/awel.md`)
# What is AWEL?
Agentic Workflow Expression Language(AWEL) is a set of intelligent agent workflow expression language specially designed for large model application
development. It provides great functionality and flexibility. Through the AWEL API, you can focus on the development of business logic for LLMs applications
without paying attention to cumbersome model and environment details.
AWEL adopts a layered API design. AWEL's layered API design architecture is shown in the figure below.
## AWEL Design
AWEL is divided into three levels in deign, namely the operator layer, AgentFream layer and DSL layer. The following is a brief introduction
to the three levels.
- **Operator layer**
The operator layer refers to the most basic operation atoms in the LLM application development process,
such as when developing a RAG application. Retrieval, vectorization, model interaction, prompt processing, etc.
are all basic operators. In the subsequent development, the framework will further abstract and standardize the design of operators.
A set of operators can be quickly implemented based on standard APIs
- **AgentFream layer**
The AgentFream layer further encapsulates operators and can perform chain calculations based on operators.
This layer of chain computing also supports distribution, supporting a set of chain computing operations such as filter, join, map, reduce, etc. More calculation logic will be supported in the future.
- **DSL layer**
The DSL layer provides a set of standard structured representation languages, which can complete the operations of AgentFream and operators by writing DSL statements, making it more deterministic to write large model applications around data, avoiding the uncertainty of writing in natural language, and making it easier to write around data. Application programming with large models becomes deterministic application programming.
## Examples
The preliminary version of AWEL has also been released, and we have provided some built-in usage examples.
## Operators
### Example of API-RAG
You can find [source code](https://github.com/eosphoros-ai/DB-GPT/blob/main/examples/awel/simple_rag_example.py) from `examples/awel/simple_rag_example.py`
```python
with DAG("simple_rag_example") as dag:
trigger_task = HttpTrigger(
"/examples/simple_rag", methods="POST", request_body=ConversationVo
)
req_parse_task = RequestParseOperator()
# TODO should register prompt template first
prompt_task = PromptManagerOperator()
history_storage_task = ChatHistoryStorageOperator()
history_task = ChatHistoryOperator()
embedding_task = EmbeddingEngingOperator()
chat_task = BaseChatOperator()
model_task = ModelOperator()
output_parser_task = MapOperator(lambda out: out.to_dict()["text"])
(
trigger_task
>> req_parse_task
>> prompt_task
>> history_storage_task
>> history_task
>> embedding_task
>> chat_task
>> model_task
>> output_parser_task
)
```
Bit operations will arrange the entire process in the form of DAG
#### Example of LLM + cache
### AgentFream Example
```python
af = AgentFream(HttpSource("/examples/run_code", method = "post"))
result = (
af
.text2vec(model="text2vec")
.filter(vstore, store = "chromadb", db="default")
.llm(model="vicuna-13b", temperature=0.7)
.map(code_parse_func)
.map(run_sql_func)
.reduce(lambda a, b: a + b)
)
result.write_to_sink(type='source_slink')
```
### DSL Example
``` python
CREATE WORKFLOW RAG AS
BEGIN
DATA requestData = RECEIVE REQUEST FROM
http_source("/examples/rags", method = "post");
DATA processedData = TRANSFORM requestData USING embedding(model = "text2vec");
DATA retrievedData = RETRIEVE DATA
FROM vstore(database = "chromadb", key = processedData)
ON ERROR FAIL;
DATA modelResult = APPLY LLM "vicuna-13b"
WITH DATA retrievedData AND PARAMETERS (temperature = 0.7)
ON ERROR RETRY 2 TIMES;
RESPOND TO http_source WITH modelResult
ON ERROR LOG "Failed to respond to request";
END;
```
## Currently supported operators
- **Basic Operators**
- BaseOperator
- JoinOperator
- ReduceOperator
- MapOperator
- BranchOperator
- InputOperator
- TriggerOperator
- **Stream Operators**
- StreamifyAbsOperator
- UnstreamifyAbsOperator
- TransformStreamAbsOperator
## Executable environment
- Stand-alone environment
- Ray environment
---
### Docs Awel Get Started (`docs/docs/awel/get_started.md`)
# Get Started
AWEL(Agentic Workflow Expression Language) makes it easy to build complex llm apps, and it provides great functionality and flexibility.
## Basic example use AWEL: http request + output rewrite
The basic usage about AWEL is to build a http request and rewrite some output value. To see how this works, let's see an example.
### DAG Planning
First, let's look at an introductory example of basic AWEL orchestration. The core function of the example is the handling of input and output for an HTTP request. Thus, the entire orchestration consists of only two steps:
- HTTP Request
- Processing HTTP Response Result
In DB-GPT, some basic dependent operators have already been encapsulated and can be referenced directly.
```python
from dbgpt._private.pydantic import BaseModel, Field
from dbgpt.core.awel import DAG, HttpTrigger, MapOperator
```
### Custom Operator
Define an HTTP request body that accepts two parameters: name and age.
```python
class TriggerReqBody(BaseModel):
name: str = Field(..., description="User name")
age: int = Field(18, description="User age")
```
Define a Request handler operator called `RequestHandleOperator`, which is an operator that extends the basic `MapOperator`. The actions of the `RequestHandleOperator` are straightforward: parse the request body and extract the name and age fields, then concatenate them into a sentence. For example:
> "Hello, zhangsan, your age is 18."
```python
class RequestHandleOperator(MapOperator[TriggerReqBody, str]):
def __init__(self, **kwargs):
super().__init__(**kwargs)
async def map(self, input_value: TriggerReqBody) -> str:
print(f"Receive input value: {input_value}")
return f"Hello, {input_value.name}, your age is {input_value.age}"
```
### DAG Pipeline
After writing the above operators, they can be assembled into a DAG orchestration. This DAG has a total of two nodes: the first node is an `HttpTrigger`, which primarily processes HTTP requests (this operator is built into DB-GPT), and the second node is the newly defined `RequestHandleOperator` that processes the request body. The DAG code below can be used to link the two nodes together.
```python
with DAG("simple_dag_example") as dag:
trigger = HttpTrigger("/examples/hello", request_body=TriggerReqBody)
map_node = RequestHandleOperator()
trigger >> map_node
```
### Access Verification
Before performing access verification, the project needs to be started first: `python dbgpt/app/dbgpt_server.py`
```bash
% curl -X GET http://127.0.0.1:5670/api/v1/awel/trigger/examples/hello\?name\=zhangsan
"Hello, zhangsan, your age is 18"
```
Of course, to make it more convenient for users to test, we also provide a test environment. This test environment allows testing without starting the dbgpt_server. Add the following code below simple_dag_example, then directly run the simple_dag_example.py script to run the test script without starting the project.
```python
if __name__ == "__main__":
if dag.leaf_nodes[0].dev_mode:
# Development mode, you can run the dag locally for debugging.
from dbgpt.core.awel import setup_dev_environment
setup_dev_environment([dag], port=5555)
else:
# Production mode, DB-GPT will automatically load and execute the current file after startup.
pass
```
```bash
curl -X GET http://127.0.0.1:5555/api/v1/awel/trigger/examples/hello\?name\=zhangsan
"Hello, zhangsan, your age is 18"
```
[simple_dag_example](/examples/awel/simple_dag_example.py)
---
### Docs Awel Why Use Awel (`docs/docs/awel/why_use_awel.md`)
# Why use AWEL?
AWEL (Agentic Workflow Expression Language) is an intelligent agent workflow expression language specifically designed for the development of LLMs applications. In the design of DB-GPT, Agents are considered first-class citizens. RAGs, Datasources (DS), SMMF(Service-oriented Multi-model Management Framework), and Plugins are all resources that agents depend on.
We currently also see that the auto-orchestration capabilities of multi-agents are greatly limited by the model's capabilities, and at the same time, for scenarios that require determinism. For instance, tasks like pipeline work do not need to utilize the auto-orchestration capabilities of large models. Therefore, in DB-GPT, the integration of AWEL with agents can satisfy the implementation of a production-level pipeline and the auto-orchestration of agents systems that address open-ended problems.
Through the orchestration capabilities of AWEL, it is possible to develop large language model applications with a minimal amount of code.
**AWEL and agents are all you need**.
---
### Docs Changelog Released V0.5.0 (`docs/docs/changelog/Released_V0.5.0.md`)
# Released V0.5.0 | Develop native data applications through workflows and agents
## Release Notes for Version 0.5.0
After a period of intensive development, version 0.5.0 has taken over two months to come to fruition. This marks the first stable release that will be maintained over an extended period within the DB-GPT project. Concurrently, the long-term vision for DB-GPT has been officially set: it aims to be an AI native data application development framework utilizing Agentic Workflow Expression Language (AWEL) and agents.
In essence, this framework facilitates the creation of data-centric applications through an intelligent agent-based expression language.
## Introduction to Version Update
In its early releases, the DB-GPT project offered six default use cases, namely:
- [ChatData](https://docs.dbgpt.site/docs/application/started_tutorial/chat_data)
- [ChatExcel](https://docs.dbgpt.site/docs/application/started_tutorial/chat_excel)
- [ChatDB](https://docs.dbgpt.site/docs/application/started_tutorial/chat_db)
- [ChatKnowledge](https://docs.dbgpt.site/docs/application/started_tutorial/chat_knowledge)
- [ChatAgents](https://docs.dbgpt.site/docs/agents)
- [ChatDashboard](https://docs.dbgpt.site/docs/application/started_tutorial/chat_dashboard)
These scenarios were designed to satisfy basic and simple use requirements. However, for large-scale production deployment, particularly when dealing with complex business scenarios, it becomes necessary to develop custom scenarios tailored to specific business conditions. This presents significant challenges in terms of flexibility and development complexity.
To further enhance the usability and flexibility of the business framework, we have built upon our existing features, including the multi-model management (SMMF), knowledge base, Agents, data sources, plugins, and Prompts. We have abstracted the capabilities of intelligent agent orchestration (AWEL) and application construction. Additionally, to facilitate application management and distribution, we have introduced the [dbgpts](https://github.com/eosphoros-ai/dbgpts) subproject, which specifically manages the construction of native intelligent data applications, AWEL common operators, AWEL generic workflow templates, and Agents on top of DB-GPT.
This version update will not affect the usage of the previously established six scenarios. However, with subsequent iterations, these default scenarios will gradually be rewritten as Data Apps. We also plan to incorporate them into the `dbgpts` project as default applications, making them readily available for installation and use.
Now, let's provide a systematic explanation of the main updates in this local release.
### Glossary of Terms:
1. **Data App**: an intelligent Data application built on DB-GPT.
2. **AWEL**: Agentic Workflow Expression Language, intelligent Workflow Expression Language
3. **AWEL Flow**: workflow orchestration using the intelligent workflow Expression Language
4. **SMMF**: a service-oriented multi-model management framework.
5. **Datasource**: data sources, such as MySQL, PG, StarRocks, and Clickhouse.
## AWEL workflow and application
As shown in the following figure, in the left-side navigation pane, there is an AWEL workflow menu. After you open it, you can orchestrate the workflow.
After the default installation, there is no content in the AWEL stream. You can build it in two ways.
1. Install it from the application repository provided by DB-GPT.
2. Create it yourself. The following describes the simple use of the following two methods. For more detailed use, see DB-GPT following tutorial.
### To install from the official repository:
Ensure that you first install and deploy DB-GPT.
Following the installation and deployment, you can utilize the default `dbgpt` command for various operations.
:::info NOTE
This process will allow you to subsequently install the AWEL workflow.
:::
As shown in the figure, the dbgpt command supports multiple operations, including model-related operations, knowledge base operations, and Trace logs. Here we will focus on the operation of the app.
Pass `dbgpt app` list-remote command, we can see that there are three AWEL workflows available in the current warehouse. Here we install `awel-flow-web-info-search` this workflow. Run the command `dbgpt app install awel-flow-web-info-search`
After the installation is successful, restart the DB-GPT service (dynamic hot loading is on the way), refresh the page, and then `AWEL workflow page` see the corresponding workflow.
### Building Your Own
In addition to installing the default AWEL flows using the official commands, you'll often need to build your own in practical scenarios. As illustrated below, by clicking on `New AWEL Flow`, you will be brought to the editing page as shown.
During the editing process, each task's downstream nodes and operators support auto-completion. By clicking the plus sign (➕) located at the bottom right of each operator, you can bring up a list of potential downstream operators that can be connected to the current one. This feature enhances the user experience by providing suggestions and making it easier to construct complex workflows without needing to remember the exact names or types of operators that are available for use.
## Create a data application
We introduced the construction and installation of AWEL workflow. Next, we will introduce how to create a data application based on a large model.
### Search Chat App
The core capability of the search dialog application is to search for relevant knowledge through search engines (such as Baidu and Google) and then summarize and answer. The effect is as follows:
Creating the preceding application is very simple. On the application creation panel, click `create` , enter the following parameters to complete the creation. Note several parameters. 1. Working mode 2. Flows the working mode we use here is `awel_layout` the selected AWEL workflow is installed earlier. `awel-flow-web-info-search` this workflow.
### Data analysis assistant
Use Multi-Agents to write a data analysis Assistant application. The results are as follows.
## Other Update Details
- Release of dbgpt core sdk (#1092): Now includes AWEL operator orchestration capabilities.
To install, you can use the command: `pip install dbgpt`
- Support for Jina Embeddings (#1105): The update integrates with Jina AI, which provides a way to create and manage embeddings for various data types, enhancing search and similarity tasks within the applications.
- New example of schema-linking using AWEL (#1081): There's a new example available demonstrating how to use AWEL for schema-linking, which can be valuable for tasks that require mapping between different data schemas.
- Unified card UI style, including knowledge base cards, model management cards, etc.: This update brings a more consistent look and feel across different UI components that display information in a card format.
## Bug Fixes
- MySQL databases no longer support automatic table creation and field auto-updates (#1133): This change may require developers to manually handle database schema changes, improving control over database migrations.
- Fixed the issue with default dialogues carrying history message records (#1117): This addresses potential privacy or performance issues by ensuring that history records are handled properly.
- Fixed the issue in examples/awel where model_name was fetched from model_config improperly (#1112): This improves the reliability of AWEL examples by ensuring that the model configuration is fetched and used correctly.
- Fixed DAGs sharing data issue (#1102): This fix might relate to data isolation in Directed Acyclic Graphs (DAGs) to ensure that workflows do not inadvertently share or overwrite data.
- Fixed issue with examples/awel default loading model text2vec-large-chinese (#1095): This fix ensures that the large Chinese text-to-vector model loads as expected in the given examples.
These changes reflect ongoing improvements to the dbgpt project, enhancing its capabilities, fixing known issues, and refining user experience. Users should refer to the official documentation or release notes for detailed instructions and information on these updates.
## Upgrade to V0.5.0
If your current version is V0.4.6 or V0.4.7, you need to upgrade to V0.5.0.
1. Suspend Service
2. upgrade the database table structure
```
/* Detailed source-code truncated for AI context efficiency. */
```
```SQL
ALTER TABLE `gpts_conversations`
ADD COLUMN `team_mode` varchar(255) NULL COMMENT 'agent team work mode';
ALTER TABLE `gpts_conversations`
ADD COLUMN `current_goal` text COMMENT 'The target corresponding to the current message';
```
3. Reinstall dependencies
```shell
pip install -e ".[default]"
```
4. Start the service
## Acknowledgments
We would like to express our deepest gratitude to all the contributors who made this release possible!
@Aralhi, @Aries-ckt, @JoanFM, @csunny, @fangyinc, @Hzh_97, @junewgl, @lcxadml, @likenamehaojie, @xiuzhu9527 and @yhjun1026
## Appendix
- DB-GPT framework: https://github.com/eosphoros-ai
- Text2SQL fine tuning: https://github.com/eosphoros-ai/DB-GPT-Hub
- DB-GPT-Web : https://github.com/eosphoros-ai/DB-GPT-Web
- official English documentation: http://docs.dbgpt.site/docs/overview
- official Chinese documentation: https://www.yuque.com/eosphoros/dbgpt-docs/bex30nsv60ru0fmx
---
### Docs Changelog Released V0.6.0 (`docs/docs/changelog/Released_V0.6.0.md`)
# DB-GPT V0.6.0, Defining new standards for AI-native data applications.
## Introduction
DB-GPT is an open source AI native data application development framework with AWEL and agents. In the V0.6.0 version, we further provide flexible and scalable AI native data application management and development capabilities around large models, which can help enterprises quickly build and deploy intelligent AI data applications, and achieve enterprise digital transformation and business growth through intelligent data analysis, insights and decisions
### The V0.6.0 version mainly adds and enhances the following core features
- AWEL protocol upgrade 2.0, supporting more complex orchestration
- Supports the creation and lifecycle management of data applications, and supports multiple application construction modes, such as: multi-agent automatic planning mode, task flow orchestration mode, single agent mode, and native application mode
- GraphRAG supports graph community summary and hybrid retrieval, and the graph index cost is reduced by 50% compared to Microsoft GraphRAG.
- Supports multiple Agent Memories, such as perceptual memory, short-term memory, long-term memory, hybrid memory, etc.
- Supports intent recognition and prompt management, and newly added support for Text2NLU and Text2GQL fine-tuning
- GPT-Vis front-end visualization upgrade to support richer visualization charts
## Features
**AWEL protocol upgrade 2.0 supports more complex orchestration and optimizes front-end visualization and interaction capabilities.**
AWEL (Agentic Workflow Expression Language) is an agent-based workflow expression language designed specifically for large model application development, providing powerful functions and flexibility. Through the AWEL API, developers can focus on large model application logic development without having to pay attention to cumbersome model, environment and other details. In AWEL2.0, we support more complex orchestration and visualization
**Supports the creation and life cycle management of data applications, and supports multiple modes to build applications, such as: multi-agent automatic planning mode, task flow orchestration mode, single agent mode, and native application mode**
**GraphRAG supports graph community summarization and hybrid retrieval.**
The graph construction and retrieval performance have obvious advantages compared to community solutions, and it supports cool visualization. GraphRAG is an enhanced retrieval generation system based on knowledge graphs. Through the construction and retrieval of knowledge graphs, it further enhances the accuracy of retrieval and the stability of recall, while reducing the illusion of large models and enhancing the effects of domain applications. DB-GPT combines with TuGraph to build efficient retrieval enhancement generation capabilities
Based on the universal RAG framework launched in DB-GPT version 0.5.6 that integrates vector index, graph index, and full-text index, DB-GPT version 0.6.0 has enhanced the capabilities of graph index (GraphRAG) to support graph community summary and hybrid retrieval. ability. In the new version, we introduced TuGraph’s built-in Leiden community discovery algorithm, combined with large models to extract community subgraph summaries, and finally used similarity recall of community summaries to cope with generalized questioning scenarios, namely QFS (Query Focused Summarization). question. In addition, in the knowledge extraction stage, we upgraded the original triple extraction to graph extraction with point edge information summary, and optimized cross-text block associated information extraction through text block history to further enhance the information density of the knowledge graph.
Based on the above design, we used the open source knowledge graph corpus (OSGraph) provided by the TuGraph community and the product introduction materials of DB-GPT and TuGraph (about 43k tokens in total), and conducted comparative tests with Microsoft's GraphRAG system. Finally, DB-GPT It only consumes 50% of the token overhead and generates a knowledge graph of the same scale. And on the premise that the quality of the question and answer test is equivalent, the global search performance has been significantly improved.
For the final generated knowledge graph, we used AntV's G6 engine to upgrade the front-end rendering logic, which can intuitively preview the knowledge graph data and community segmentation results.
**GPT-Vis: GPT-Vis is an interactive visualization solution for LLM and data, supporting rich visual chart display and intelligent recommendations**
**Text2GQL and Text2NLU fine-tuning: Newly supports fine-tuning from natural language to graph language, as well as fine-tuning for semantic classification.**
## How to Upgrade?
[Upgrade to v0.6.0](../upgrade/v0.6.0.md)
## User Manual
- [Apps](../application/apps/app_manage.md)
- [AWEL](../awel/awel.md)
- [GraphRAG](../application/graph_rag.md)
## Acknowledgements
This iteration is inseparable from the participation of developers and users in the community, and it also further cooperates with the [TuGraph](https://github.com/TuGraph-family) and [AntV](https://github.com/antvis) communities. Thanks to all the contributors who made this release possible!
@Aries-ckt, @Dreammy23, @Hec-gitHub, @JxQg, @KingSkyLi, @M1n9X, @bigcash, @chaplinthink, @csunny, @dusens, @fangyinc, @huangjh131, @hustcc, @lhwan, @whyuds and @yhjun1026
## Reference
- [中文手册](https://www.yuque.com/eosphoros/dbgpt-docs/ym574wh2hddunfbd)
---
### Docs Changelog Released V0.8.0 (`docs/docs/changelog/Released_V0.8.0.md`)
# DB-GPT V0.8.0 — Paradigm Shift: AI + Data Driven Analytics Experience
A paradigm shift from "conversational Q&A" to "task delivery" — from passive answering to autonomous analysis, exploring true Agentic productivity.
## Introduction
DB-GPT V0.8.0 introduces a self-driven AI Data Assistant that autonomously handles the entire analytics pipeline:
🎯 Business Goal → 🧠 Task Decomposition → 🧩 Skill Invocation → 💻 Code Generation (SQL/Python) → 🛡️ Sandbox Execution → 📊 Chart Generation → 📝 Report Delivery
You no longer need to know which table your data lives in, nor write Python scripts for intermediate data cleaning. Simply state your business objective, and the **DB-GPT AI Data Assistant** will take care of everything.
### Key Highlights
- 🌟 **Autonomous Data Analytics** — A brand-new autonomous data analytics experience, orchestrating AI-driven analysis through Skills
- 🤖 **Agent Skills** — Support for Agent Skills, enabling more powerful and flexible agent capabilities
- 📊 **Autonomous SQL Generation** — AI agents can now autonomously write SQL queries for data analysis
- 💻 **Autonomous Code Execution** — AI agents can automatically generate and execute Python code for data analysis tasks
- 🛡️ **Sandbox Environment** — A secure, isolated sandbox environment for executing untrusted code
- 💬 **Conversation Sharing & Replay** — View not only the final polished HTML reports, but also replay the entire reasoning process
- 🚀 **One-Click Setup Script** — A new streamlined installation script to get DB-GPT up and running faster than ever
## Features
### ✨ Agentic Data Analytics Engine
The DB-GPT AI Data Assistant can now autonomously orchestrate an entire execution pipeline around your analysis goals, moving beyond the limitations of traditional single-turn conversations to deliver a brand-new autonomous data analytics experience:
- **Multi-Source Data Integration**: Seamlessly connect to relational databases, CSV/Excel files, data warehouses, knowledge bases, documents, and more.
- **Autonomous Reasoning & Exploration**: For complex problems, the AI Data Assistant automatically analyzes database schemas or data files and plans multi-step execution strategies.
- **Execution Capabilities**: Autonomously generates and executes SQL / Python code.
- **Out-of-the-Box Experience**: A newly designed Welcome Page with rich analysis examples, reducing the learning curve for new users to nearly zero.
#### CSV/Excel Autonomous Data Analysis
Upload local spreadsheet files with one click, and the AI automatically understands the data structure, autonomously performs data cleaning, multi-dimensional calculations, and chart visualization — making routine report processing easier than ever.
#### Intelligent Database Insights & Analysis Reports
Built on the new Agentic architecture, the engine autonomously performs data diagnostics, feature extraction, and multi-dimensional analysis, generating dedicated analysis reports with beautiful charts and deep insights — making data value crystal clear.
#### Deep Financial Report Analysis
Purpose-built for financial scenarios, precisely extracting core metrics such as revenue and profit. Automatically performs year-over-year / quarter-over-quarter calculations and trend forecasting, generating professional financial health diagnostic reports with one click.
#### Autonomous SQL Generation & Code Execution
Powered by advanced large language models, the system not only accurately translates natural language into complex SQL queries, but also supports autonomous Python code execution in a secure sandbox — handling even the most demanding computational requirements.
### 🤖 Agent Skill Ecosystem
The LLM determines the intelligence baseline, but ecosystem extensibility determines the business ceiling. Different business scenarios require vastly different analysis approaches. V0.8.0 officially introduces the **Agent Skill** system — a new way to codify team expertise into reusable assets:
- 📦 **Custom Skill Packaging**: Encapsulate your unique data cleaning logic, business analysis models, and more into standalone Skills — write once, reuse across the entire team.
- 🔗 **One-Click GitHub Import**: Import high-quality Skills directly from community or enterprise private repositories, breaking down information silos.
- 📊 **Built-in Skills**: Ships with CSV/Excel deep analysis Skill, financial report analysis Skill, Agent Browser Skill, and more. Create business-specific Skills with one click using the Skill Creator.
### 🛡️ Sandbox Secure Execution Environment
Granting AI the power to execute code often comes with system-level risks. To address this, we introduce the isolated **Sandbox**:
- 🛡️ **Isolated Sandbox Execution**: All shell code generated by Agents that hasn't been manually reviewed runs in isolated containers. Supports strict resource threshold limits and execution timeout controls — protecting the host system while balancing agent execution power with enterprise-grade data security.
- ⚙️ **Resource Configuration**: Session-level sandbox resource limits and execution timeout guarantees, making analysis artifacts more reproducible and auditable.
### 💬 Collaboration & Product Experience Upgrades
Great tools need to flow smoothly, transforming analysis reports and processes from "personal use" to "team reuse":
- 💬 **Conversation Sharing & Execution Replay**: Generate share links with one click. Your team members can not only view the final polished HTML reports, but also replay every step of the Agent's thinking and reasoning process — making retrospectives and knowledge sharing simpler.
- 📝 **Conversation Task List**: Search historical conversation records at any time, facilitating review and documentation.
- 🔗 **Native App & Agent Modes**: Retains native application, Agent, AWEL, and other capabilities, supporting diverse product enhancements and feature usage.
### 🚀 One-Click Setup Script
We provide multiple new streamlined installation scripts to get DB-GPT up and running faster.
**Option 1: Install via PyPI**
```bash
# Step 1: Install dbgpt-app
pip install dbgpt-app
# Step 2: Start DB-GPT
dbgpt start
```
**Option 2: Install via Shell Script**
```bash
# Using OpenAI as an example, quickly initialize the environment
curl -fsSL https://raw.githubusercontent.com/eosphoros-ai/DB-GPT/main/scripts/install/install.sh \
| OPENAI_API_KEY=sk-xxx bash -s -- --profile openai
# Start DB-GPT
cd ~/.dbgpt/DB-GPT && uv run dbgpt start webserver --config ~/.dbgpt/configs/.toml
```
**Option 3: Install from Source (same as previous versions)**
```bash
uv sync --all-packages \
--extra "base" \
--extra "proxy_openai" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "dbgpts"
uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml
```
🚀 Open your browser and visit [http://localhost:5670](http://localhost:5670)
For detailed installation instructions, see the [Installation Guide](http://docs.dbgpt.cn/docs/next/installation/).
### 📖 Documentation Overhaul with Multi-Language Support
The official documentation has been completely revamped and now officially supports multiple languages! A fresh UI design, clearer directory structure, and one-click language switching deliver a better reading and development experience.
👉 [Browse the New Documentation](http://docs.dbgpt.cn/docs/next/overview/)
## Other Improvements
- Add MiniMax Provider support ([#2989](https://github.com/eosphoros-ai/DB-GPT/pull/2989))
- Fix React parser handling of vis-thinking blocks ([#2996](https://github.com/eosphoros-ai/DB-GPT/pull/2996))
- README and documentation updates ([#2991](https://github.com/eosphoros-ai/DB-GPT/pull/2991))
## How to Upgrade
[Upgrade to v0.8.0](../upgrade/v0.8.0.md)
## Acknowledgements
### 🎉 New Contributors
V0.8.0 welcomes **2 new contributors**:
- @octo-patch
- @LXW2019124
🔥🔥 Thank you to all our contributors for making this release possible!
@Aries-ckt, @Copilot, @LXW2019124, @chenliang15405, @copilot-swe-agent, @fangyinc and @octo-patch
## Reference
- [Quick Start](http://docs.dbgpt.cn/docs/overview/)
- [Docker Quick Deploy](http://docs.dbgpt.cn/docs/next/installation/docker/)
---
### Docs Changelog Released V0.8.1 (`docs/docs/changelog/Released_V0.8.1.md`)
# 🚀 DB-GPT V0.8.1 — Production-Ready AI Data Assistant: Scheduling, Connectors, and Long-Running Agents
V0.8.1 continues the direction introduced by the V0.8.0 AI Data Assistant. It turns one-off analysis into production-oriented workflows that are **schedulable, connectable, observable, and easier to operate**.
## Introduction
DB-GPT V0.8.0 moved the product experience from "conversational Q&A" to "task delivery." V0.8.1 focuses on the practical questions teams face when they use the AI Data Assistant continuously in real environments:
- A successful analysis is valuable. How can it be **rerun on a schedule** without repeating the conversation each time?
- An agent connected only to databases is limited. How can it **safely connect to external systems and business tools**?
- Complex analysis often runs through many steps. How can it **stay within the context window** while letting users **see what it is doing**?
- Production databases can have large schemas. How can connector construction, schema indexing, and vector search become **faster and more reliable**?
To address these needs, this release introduces **Scheduled Tasks**, **MCP Connectors**, and **context management with task-plan tracking**. It also expands the model, datasource, vector-store, and cache ecosystem, and includes a set of production-focused performance, security, and compatibility fixes.
The core value of V0.8.1 is straightforward: DB-GPT AI Data Assistant moves from completing one complex analysis to supporting repeatable, long-running, team-ready workflows.
### Key Highlights
- ⏰ **Scheduled Tasks** — Save a finished conversation as a recurring task and replay the Agent flow on a cron schedule
- 🔌 **MCP Connectors** — Connect Agents to external tools through the Model Context Protocol, with built-in templates and custom MCP server support
- 🧠 **Context Management and Task-Plan Tracking** — Keep long-running ReAct/Data Agent tasks within the context window and show progress in the frontend
- 🚀 **Datasource Connector Cache** — Add TTL caching for expensive connector construction, reducing warm connector lookup from about 63s to under 10ms in large-schema scenarios
- 🧱 **Ecosystem Expansion** — Add LiteLLM, Qdrant, Valkey for cache and vector storage, openGauss, StarRocks binary types, DeepSeek V4 Pro, and MiniMax-M3
- 🛡️ **Security and Reliability Hardening** — Tighten config-file permissions, validate uploaded filenames, restrict personal Skill execution, and improve indexing fault tolerance
## Features
### ⏰ Scheduled Tasks: Turn a Successful Analysis into Continuous Output
Many data analysis jobs are naturally recurring: daily business reports, weekly risk checks, monthly financial summaries, or diagnostics repeated over fresh database snapshots. V0.8.1 introduces **Scheduled Tasks**, allowing a successful analysis conversation to become a repeatable task.
Run the analysis once, save the conversation as a task, and DB-GPT will replay the full ReAct Agent flow on a cron schedule. Each run creates a new conversation and report while preserving execution history for auditing, review, and team sharing.
#### Save a Conversation as a Recurring Task
- **Save finished conversations in one click**: Turn any completed analysis conversation into a scheduled task.
- **Use flexible schedules**: Run hourly, daily, weekly, monthly, or with a custom cron expression.
- **Freeze the execution context**: The original question, model, selected Skill, and connector environment are stored in the task snapshot, so every replay runs under the same conditions.
- **Pause and resume tasks**: Manage task status directly from the Scheduled Tasks page.
#### Run History and Read-Only Replay
Every scheduled run records its status, duration, result summary, and generated conversation ID. You can open any historical run and replay the generated conversation directly from history. Replay does not trigger another LLM call, making review low-cost and reproducible.
### 🔌 MCP Connectors: Safely Connect Agents to External Tools
V0.8.1 extends DB-GPT Agents beyond databases and local Skills through **MCP Connectors**. Agents can now access external tools through the Model Context Protocol, while users control which connectors are attached to each conversation.
Built-in connector templates currently include Feishu, DingTalk, Yuque, GitHub, Notion, Linear, Tavily, and DeepWiki. You can also connect any custom MCP server that supports SSE or Streamable HTTP.
#### External Tool Access for Agentic Workflows
| Capability | Description |
| --- | --- |
| Built-in templates | Cover collaboration, documentation, project management, search, and developer-tool scenarios |
| Custom MCP servers | Configure endpoints, transport protocols, and authentication methods |
| Per-conversation connector selection | Agents only receive tools relevant to the current task, reducing noise and token usage |
| Tool transparency | Inspect each connector's tool names, descriptions, and input parameters |
| Human confirmation | Write actions from built-in connectors ask for confirmation before execution |
| Encrypted credentials | Connector credentials are encrypted in DB-GPT metadata and restored after service restart |
### 🧠 Context Management and Task-Plan Tracking: More Stable and Transparent Long-Running Tasks
Agentic data analysis is rarely a short conversation. It often involves multi-step exploration, retries, and intermediate artifacts. V0.8.1 adds context management and task-plan tracking to the ReAct/Data Agent flow, making long-running tasks more stable and easier to understand.
- **Multi-layer context compaction** keeps long tasks from exceeding the model context window.
- **Live context-usage events** stream context-window usage to the frontend in real time.
- **Task-plan tracking** lets the Agent maintain a structured todo list and push plan updates as steps progress.
- **Clearer action explanations** show what each step is doing and why it is needed.
- **Frontend task-plan cards and context indicators** make the execution process visible.
Under the hood, `ContextManager` orchestrates **progressive multi-layer compaction** driven by token-budget state. As usage crosses warning and error thresholds, compaction becomes more aggressive: from truncating earlier observations, to dropping earlier rounds, to generating structured summaries with an LLM. If the model still reports `context_too_long`, an emergency fallback layer is available.
These improvements make DB-GPT better suited for complex data analysis workflows that require multi-step reasoning, retries, and intermediate artifact management.
### 🧱 Broader Model, Datasource, and Storage Ecosystem
V0.8.1 expands the ecosystem around DB-GPT, making it easier for teams to reuse existing model, database, vector-store, and cache infrastructure.
#### LiteLLM Embedded AI Gateway
DB-GPT adds **LiteLLM** as an embedded proxy provider, registered as `proxy/litellm`. It is not a separate proxy service; DB-GPT calls LiteLLM in process, giving you a unified entry point to OpenAI, Anthropic, Vertex AI, Bedrock, Azure, Cohere, Mistral, Groq, Ollama, and other LiteLLM-supported backends.
```toml
[[models.llms]]
name = "anthropic/claude-3-5-sonnet-20241022"
provider = "proxy/litellm"
```
#### New Vector Search and Cache Backends
- **Qdrant vector search**: Support for high-performance vector search scenarios.
- **Valkey vector store**: Use Valkey and `valkey-search` to build vector retrieval pipelines.
- **Valkey cache storage**: Support LLM response caching and embedding caching scenarios.
- **Configurable distance metrics**: Configure vector-search distance metrics as needed.
- **Valkey vector client `CLIENT SETNAME`**: Make DB-GPT connections easier to identify in Valkey monitoring tools.
#### New Datasource and Model Support
- **openGauss datasource**: Adds connection, display, and documentation support.
- **StarRocks `VARBINARY` and `BINARY` types**: Improves StarRocks type compatibility.
- **MiniMax-M3**: Upgrades the MiniMax provider default model to M3 while keeping MiniMax-M2.7 available.
- **DeepSeek V4 Pro**: Adds model support.
### 🚀 Performance Improvements for Large Schemas and Production Databases
V0.8.1 includes important performance improvements for large schemas, production databases, and indexing pipelines.
- **Datasource connector cache**: `ConnectorManager.get_connector(db_name)` now TTL-caches constructed connectors. In a production SQL Server database with nearly 900 tables, warm connector lookup improved from about **63 seconds to under 10ms**.
- **Per-database indexing lock**: Avoids concurrent competition between schema indexing and refresh operations, reducing the risk of empty indexes.
- **Per-chunk fault tolerance**: A single failed embedding chunk no longer fails the entire indexing task.
- **MSSQL metadata compatibility**: Uses SQL Server-compatible `INFORMATION_SCHEMA` and extended-property queries for field metadata.
- **Milvus 2.5+ compatibility**: Improves compatibility with newer Milvus vector-store versions.
### 🛡️ Security and Reliability Hardening
This release also includes several production-oriented security and reliability improvements:
- Local profile config files at `~/.dbgpt/configs/.toml` are written with stricter `0o600` permissions.
- Knowledge module APIs add authentication dependencies.
- Skill upload filenames, example filenames, and Python upload filenames are validated more strictly.
- Personal Skill script execution is restricted to reduce uncontrolled execution risk.
- Code Interpreter temporary scripts are written with explicit UTF-8 encoding.
- Markdown knowledge uses size chunking by default, making indexing more predictable.
- The ReAct parser handles multi-step output more robustly.
- Chat DB prompts clarify that retrieved table schemas are a top-K subset, improving accuracy for whole-database meta questions.
## Enhancements
- Support Scheduled Tasks and MCP Connectors ([#3095](https://github.com/eosphoros-ai/DB-GPT/pull/3095))
- Add context management, task-plan tracking, and the corresponding frontend UI ([#3053](https://github.com/eosphoros-ai/DB-GPT/pull/3053))
- Add LiteLLM as an embedded AI gateway provider ([#3043](https://github.com/eosphoros-ai/DB-GPT/pull/3043))
- Add Qdrant vector search support ([#3034](https://github.com/eosphoros-ai/DB-GPT/pull/3034))
- Add Valkey vector store integration ([#3051](https://github.com/eosphoros-ai/DB-GPT/pull/3051))
- Add Valkey cache integration ([#3057](https://github.com/eosphoros-ai/DB-GPT/pull/3057))
- Add `CLIENT SETNAME` to the Valkey vector client ([#3090](https://github.com/eosphoros-ai/DB-GPT/pull/3090))
- Support configurable vector-search distance metrics ([#3044](https://github.com/eosphoros-ai/DB-GPT/pull/3044))
- Add TTL caching to `ConnectorManager.get_connector` (warm cache from about 63s to under 10ms) ([#3046](https://github.com/eosphoros-ai/DB-GPT/pull/3046))
- Add openGauss datasource support ([#3007](https://github.com/eosphoros-ai/DB-GPT/pull/3007))
- Implement `VARBINARY` and `BINARY` types for StarRocks ([#3062](https://github.com/eosphoros-ai/DB-GPT/pull/3062))
- Upgrade the MiniMax default model to M3 ([#3093](https://github.com/eosphoros-ai/DB-GPT/pull/3093))
- Harden `~/.dbgpt/configs/.toml` file permissions to `0o600` ([#3077](https://github.com/eosphoros-ai/DB-GPT/pull/3077))
## Bug Fixes
- Fix DuckDB datasource creation from the Web UI ([#3009](https://github.com/eosphoros-ai/DB-GPT/pull/3009))
- Support DeepSeek V4 Pro ([#3079](https://github.com/eosphoros-ai/DB-GPT/pull/3079))
- Use size chunking by default for Markdown knowledge (Fixes [#3030](https://github.com/eosphoros-ai/DB-GPT/issues/3030)) ([#3033](https://github.com/eosphoros-ai/DB-GPT/pull/3033))
- Restrict personal Skill script execution ([#3071](https://github.com/eosphoros-ai/DB-GPT/pull/3071))
- Validate example filenames ([#3066](https://github.com/eosphoros-ai/DB-GPT/pull/3066))
- Validate Skill upload filenames ([#3065](https://github.com/eosphoros-ai/DB-GPT/pull/3065))
- Constrain Python upload filenames ([#3064](https://github.com/eosphoros-ai/DB-GPT/pull/3064))
- Handle knowledge space ID responses ([#3070](https://github.com/eosphoros-ai/DB-GPT/pull/3070))
- Tolerate multi-step ReAct output ([#3074](https://github.com/eosphoros-ai/DB-GPT/pull/3074))
- Tell the LLM that the current table list is a top-K subset, not the full database table list ([#3045](https://github.com/eosphoros-ai/DB-GPT/pull/3045))
- Expand the `gpts_messages.content` column to hold longer Agent messages ([#3055](https://github.com/eosphoros-ai/DB-GPT/pull/3055))
- Make MilvusStore compatible with Milvus 2.5+ ([#3042](https://github.com/eosphoros-ai/DB-GPT/pull/3042))
- Add per-chunk fault tolerance and a per-database indexing lock ([#3040](https://github.com/eosphoros-ai/DB-GPT/pull/3040))
- Override MSSQL `get_fields()` with SQL Server-compatible `INFORMATION_SCHEMA` queries ([#3039](https://github.com/eosphoros-ai/DB-GPT/pull/3039))
- Add authentication dependencies to knowledge module APIs ([#3038](https://github.com/eosphoros-ai/DB-GPT/pull/3038))
- Fix BranchOperator incorrectly skipping shared downstream nodes (Fixes [#2935](https://github.com/eosphoros-ai/DB-GPT/issues/2935)) ([#3035](https://github.com/eosphoros-ai/DB-GPT/pull/3035))
- Honor the configured Tongyi embedding model name (Fixes [#3029](https://github.com/eosphoros-ai/DB-GPT/issues/3029)) ([#3032](https://github.com/eosphoros-ai/DB-GPT/pull/3032))
- Use explicit UTF-8 encoding when writing Code Interpreter temporary scripts ([#3023](https://github.com/eosphoros-ai/DB-GPT/pull/3023))
## How to Upgrade
This guide applies to upgrades from **v0.8.0** to **v0.8.1**.
The V0.8.1 metadata changes include one column change and three new tables. Upgrade scripts are available under `assets/schema/upgrade/v0_8_1/`:
- `upgrade_to_v0.8.1.sql`: incremental script to run on top of a v0.8.0 database.
- `v0.8.1.sql`: full V0.8.1 schema for fresh installations.
> As in previous releases, the incremental script targets MySQL. SQLite users should back up the metadata database before upgrading; the new tables are created automatically when the service starts.
### Prepare
#### Back Up the Database
:::warning
To avoid data loss, back up the metadata database before upgrading. Choose the method that matches your database type, such as `mysqldump` for MySQL or copying the database file for SQLite.
:::
### Upgrade the Database
The V0.8.1 upgrade includes one column change and three new metadata tables:
| Change | Description |
| --- | --- |
| `gpts_messages.content` -> `longtext` | Supports longer Agent messages and execution traces. |
| `connector_instance` | Stores MCP connector instances, encrypted credentials, transport/extra config, and lifecycle status. |
| `dbgpt_serve_scheduled_task` | Stores scheduled task definitions, cron expressions, and frozen conversation snapshots. |
| `dbgpt_serve_scheduled_run` | Stores scheduled run history: status, summaries, error messages, and output conversation IDs. |
Apply the incremental script to your MySQL metadata database:
```bash
mysql -u -p dbgpt < assets/schema/upgrade/v0_8_1/upgrade_to_v0.8.1.sql
```
### Install Dependencies
Install or update dependencies according to your deployment method. For a source installation with the default setup:
```bash
uv sync --all-packages
```
Install optional extras as needed:
```bash
# LiteLLM proxy provider
uv sync --all-packages --extra "proxy_litellm"
# Qdrant vector store
uv sync --all-packages --extra "storage_qdrant"
# Valkey cache / vector store
uv sync --all-packages --extra "storage_valkey"
```
### Restart DB-GPT
Restart DB-GPT using your usual startup method. After startup, we recommend checking that:
- Existing conversations load correctly.
- MCP Connector pages can list, activate, and test connectors.
- Scheduled Tasks can be saved from completed conversations and show run history.
- Long-running ReAct/Data Agent conversations show task-plan and context-usage status.
## References
- [DB-GPT V0.8.0 Release Notes](http://docs.dbgpt.cn/docs/next/changelog/Released_V0.8.0)
- [Quick Start](http://docs.dbgpt.cn/docs/overview/)
- [Installation Guide](http://docs.dbgpt.cn/docs/next/installation/)
- [Scheduled Tasks](http://docs.dbgpt.cn/docs/next/application/scheduled_tasks)
- [MCP Connectors](http://docs.dbgpt.cn/docs/next/application/mcp_connectors)
---
### Docs Changelog Released V0.8.2 (`docs/docs/changelog/Released_V0.8.2.md`)
# 🚀 DB-GPT V0.8.2 — A More Complete Agentic Data Workflow: Multi-File Analysis, Knowledge Retrieval, and Parallel Sub-Agents
In complex data-analysis tasks, business information is often distributed across multiple files and knowledge sources. The analysis may also include work that can proceed in parallel and critical conditions that require confirmation from business users. When file handling, knowledge retrieval, task execution, and human confirmation are disconnected, the Agent struggles to preserve context and the workflow is repeatedly interrupted.
V0.8.2 addresses this end-to-end workflow from input and retrieval through execution and confirmation. **Multi-file Agentic analysis** manages related inputs together, **Agentic Knowledge-Base Search** keeps looking for relevant information as the task develops, **parallel sub-agent delegation** advances independent work at the same time, and **human-in-the-loop questions** collect decisions that only the user can provide.
### Key Highlights
- 📎 **Multi-File Agentic Analysis** — Upload, preview, and use multiple files as one session-scoped task context
- 🔎 **Agentic Knowledge-Base Search** — Let the Agent iteratively explore, search, and read knowledge sources instead of relying on one retrieval pass
- 🧩 **Parallel Sub-Agent Delegation** — Execute independent analyses concurrently and expose each sub-task's progress and artifacts
- 🙋 **Human-in-the-Loop Questions** — Let the Agent pause for structured user input when requirements or choices are unclear
- 🛡️ **Security and Reliability Hardening** — Sandbox Jinja2 rendering, constrain upload paths, remove shell interpretation from macOS TTS, and improve client, storage, and RAG reliability
## Features
### 📎 Multi-File Analysis: Treat a File Set as One Task Context
Data work often starts with a group of related files rather than one isolated spreadsheet: an orders table and a customer table, several monthly exports, or a report accompanied by supporting data. V0.8.2 lets users attach multiple files to one conversation and keeps that set available as part of the task context.
#### Upload, Inspect, and Manage Files in the Composer
- **Add several files at once** through the file picker or drag and drop them into the composer.
- **Track each file independently** through upload, inspection, ready, and failure states.
- **Preview before running the task** with bounded table or document previews; partial previews are marked explicitly.
- **Add or remove attachments throughout the conversation** without rebuilding the file set from scratch.
- **Use server-advertised limits** for file count, size, concurrency, timeout, and supported extensions, so deployments can tune the upload policy.
The default extension set covers CSV, TSV, Excel, JSON/JSONL, Parquet, PDF, Word, PowerPoint, Markdown, and plain text files. Availability of a preview parser still depends on the installed optional dependencies.
#### Analyze the Files Together
The Agent receives stable file identifiers rather than client-provided server paths. Files are scoped to the owning user and the current conversation, then materialized only when an execution tool needs them. This allows `load_file`, Code Interpreter, and analysis tools to work across the selected file set while keeping storage locations private.
When a conversation with attachments is saved as a Scheduled Task, DB-GPT freezes task-scoped copies of those files. Each scheduled run can therefore replay against the same file snapshot instead of depending on mutable session uploads.
### 🔎 Agentic Knowledge-Base Search: Retrieval as an Iterative Process
Traditional RAG usually retrieves once, builds a prompt, and generates an answer. That approach is efficient for simple questions, but it gives the model little room to recover when the first query is incomplete or the relevant evidence is spread across several sources.
V0.8.2 turns knowledge-base chat into an Agentic loop. The Agent can inspect the knowledge space, rewrite or narrow its search, retrieve more than once, open relevant files, and stop when it has enough evidence to answer. Knowledge-only chat receives a focused tool set such as semantic search, file listing, glob, grep, and file reading, reducing interference from unrelated tools.
#### Index Methods and Structural Views
| Capability | How it is used |
| --- | --- |
| Vector search | Semantic similarity over embedded chunks |
| File and exact search | File matching, keyword search, and bounded file reading within the selected knowledge space |
| Knowledge graph | Entity and structural relationships when the graph has been built |
| Structural view | Reconstructs heading and parent-child context at query time |
| Code graph | When available, indexes repositories, files, and symbol definitions for code-oriented exploration |
Knowledge-space configuration offers three index-method options: `VectorStore`, `FullText`, and `KnowledgeGraph`. Git repositories, when used as a knowledge source, support full and incremental synchronization. Once a code graph has been built for a Git repository or code files, code can be retrieved structurally by repository, file, class, and function.
Large tool results no longer have to be discarded when they exceed the inline context budget. They can be persisted and read back through a bounded file-reading tool. Citations are also carried separately from the final answer as structured data, so the frontend can render traceable source excerpts without mixing reference payloads into the answer text.
### 🧩 Parallel Sub-Agents: Execute Independent Work Concurrently
Complex tasks often contain independent branches: profile several datasets, compare multiple candidate approaches, or investigate unrelated causes before producing one conclusion. V0.8.2 lets the lead Agent delegate such branches to sub-agents and run them concurrently.
The lead Agent first records a task plan, then calls `dispatch_parallel_tasks` with independent work items. Each sub-agent runs with its own context, memory, conversation, and working directory. Database, knowledge-base, and read-only tool access can be inherited from the lead task, while recursive delegation is disabled.
| Capability | Description |
| --- | --- |
| Bounded concurrency | Runs up to three sub-agents per dispatch by default; the limit is configurable |
| Live progress | Streams running, completed, failed, and timed-out states to the frontend |
| Inspectable work | Shows each sub-agent's goal, verified steps, outputs, and artifacts |
| Final synthesis | Returns structured results to the lead Agent for one consolidated answer |
| Execution constraints | Keeps dependent work serial and prevents sub-agents from recursively delegating more work |
The per-dispatch limit can be set with `service.web.agent_context.max_parallel_subagents` or `DBGPT_MAX_PARALLEL_SUBAGENTS`. Increasing it also increases concurrent model calls and token consumption.
Parallel delegation reduces unnecessary serial waiting when work items are genuinely independent. It does not change the ordering requirements of steps that depend on one another.
### 🙋 Human-in-the-Loop Questions: Clarify Before Continuing
Some tasks cannot be completed responsibly without a user choice: which metric definition to use, which date range applies, whether an ambiguous field should be included, or which output format is preferred. V0.8.2 adds a standard interactive question flow for these cases.
The Agent can pause execution, present one or more structured questions, and continue in the same run after the user replies. The frontend supports single choice, multiple choice, custom input, confirmation, and cancellation. Waiting is bounded so an abandoned question does not leave an execution open indefinitely.
### 🛡️ Security and Reliability Hardening
V0.8.2 also tightens several boundaries used by Agentic workflows:
- Python file uploads validate `user_id` and verify that resolved paths remain inside the managed upload directory.
- macOS TTS passes text to `say` as an argument rather than through a shell command.
- Agent Jinja2 prompt rendering uses a sandboxed environment.
- CORS allowed origins are configurable, and wildcard/credential handling is corrected.
- Only files named exactly `SKILL.md` are loaded as Markdown Skills.
- Agent citations use a structured final-answer protocol instead of being appended to the answer body.
- MySQL uses a real `LONGTEXT` variant for large Agent messages and action reports at the ORM layer.
- Excel knowledge loading handles headerless sheets and multi-sheet workbooks more reliably.
## Enhancements
- Add session-scoped multi-file upload, preview, and Agentic analysis ([#3206](https://github.com/eosphoros-ai/DB-GPT/pull/3206))
- Add Agentic Knowledge-Base Search with index-method configuration and iterative RAG ([#3160](https://github.com/eosphoros-ai/DB-GPT/pull/3160))
- Add parallel sub-agent delegation and execution ([#3161](https://github.com/eosphoros-ai/DB-GPT/pull/3161))
- Add interactive human-in-the-loop questions to the built-in Agent tools ([#3107](https://github.com/eosphoros-ai/DB-GPT/pull/3107))
- Add the OrcaRouter proxy provider through an OpenAI-compatible endpoint ([#3186](https://github.com/eosphoros-ai/DB-GPT/pull/3186))
- Add an Alibaba Cloud MaxCompute (ODPS) datasource backed by the PyODPS SQLAlchemy dialect and configurable from the Web UI (Fixes [#3105](https://github.com/eosphoros-ai/DB-GPT/issues/3105)) ([#3178](https://github.com/eosphoros-ai/DB-GPT/pull/3178))
## Bug Fixes
- Avoid a `KeyError` when a chart or SQL run does not include `db_name` ([#3199](https://github.com/eosphoros-ai/DB-GPT/pull/3199))
- Include the flow UID in the `update_flow` PUT path (Fixes [#3193](https://github.com/eosphoros-ai/DB-GPT/issues/3193)) ([#3196](https://github.com/eosphoros-ai/DB-GPT/pull/3196))
- Use MySQL `LONGTEXT` for large Agent messages and action reports at the ORM layer ([#3189](https://github.com/eosphoros-ai/DB-GPT/pull/3189))
- Move `EXAMPLE_1` database creation to the end of the schema file ([#3183](https://github.com/eosphoros-ai/DB-GPT/pull/3183))
- Separate citations from final answers with a structured final-answer protocol ([#3182](https://github.com/eosphoros-ai/DB-GPT/pull/3182))
- Validate `user_id` and constrain resolved paths for Python file uploads (Fixes [#3104](https://github.com/eosphoros-ai/DB-GPT/issues/3104)) ([#3184](https://github.com/eosphoros-ai/DB-GPT/pull/3184))
- Load only files named exactly `SKILL.md` as Markdown Skills ([#3175](https://github.com/eosphoros-ai/DB-GPT/pull/3175))
- Prevent command injection in macOS TTS by removing shell interpretation (Fixes [#3129](https://github.com/eosphoros-ai/DB-GPT/issues/3129)) ([#3174](https://github.com/eosphoros-ai/DB-GPT/pull/3174))
- Handle LLM output containing multiple JSON code fences ([#3117](https://github.com/eosphoros-ai/DB-GPT/pull/3117))
- Render Agent Jinja2 templates in a sandboxed environment ([#3111](https://github.com/eosphoros-ai/DB-GPT/pull/3111))
- Stop `inner_copy_and_install` from reporting a failed build as successful ([#3141](https://github.com/eosphoros-ai/DB-GPT/pull/3141))
- Deserialize table chunks when separated chunks are present ([#3140](https://github.com/eosphoros-ai/DB-GPT/pull/3140))
- Use POST rather than GET in client `create_datasource` and `create_flow` calls ([#3138](https://github.com/eosphoros-ai/DB-GPT/pull/3138))
- Make CORS allowed origins configurable and correct wildcard/credential handling ([#3123](https://github.com/eosphoros-ai/DB-GPT/pull/3123))
- Honor negative read sizes and preserve the `SEEK_END` position in `StreamedBytesIO` ([#3136](https://github.com/eosphoros-ai/DB-GPT/pull/3136))
- Handle native Boolean values in `VariablesProvider._convert_to_value_type` ([#3135](https://github.com/eosphoros-ai/DB-GPT/pull/3135))
- Preserve bucket names in simplified fsspec paths ([#3134](https://github.com/eosphoros-ai/DB-GPT/pull/3134))
- Handle headerless sheets and multi-sheet workbooks in `ExcelKnowledge._load` ([#3137](https://github.com/eosphoros-ai/DB-GPT/pull/3137))
- Correct the empty/non-list result guard in `TeiRerankEmbeddings._parse_results` ([#3133](https://github.com/eosphoros-ai/DB-GPT/pull/3133))
- Avoid the `handleChat` temporal dead zone in the frontend ([#3132](https://github.com/eosphoros-ai/DB-GPT/pull/3132))
- Allow the Milvus vector-store type in TOML configuration ([#3127](https://github.com/eosphoros-ai/DB-GPT/pull/3127))
## How to Upgrade
This guide applies to upgrades from **v0.8.1** to **v0.8.2**.
The V0.8.2 incremental metadata script adds one table for session- and task-scoped file persistence, three code-graph tables, the knowledge-space index-method column, and a column-width fix for Agent messages. Upgrade scripts are available under `assets/schema/upgrade/v0_8_2/`:
- `upgrade_to_v0.8.2.sql`: incremental script to run on top of a v0.8.1 database.
- `v0.8.2.sql`: full V0.8.2 schema for fresh installations.
> As in previous releases, the incremental script targets MySQL. SQLite users should back up the metadata database before upgrading; ORM-managed tables are created when the service starts.
### Prepare
#### Back Up the Database
:::warning
To avoid data loss, back up the metadata database before upgrading. Choose the method that matches your database type, such as `mysqldump` for MySQL or copying the database file for SQLite.
:::
### Upgrade the Database
The V0.8.2 incremental upgrade applies the following metadata changes:
| Change | Description |
| --- | --- |
| `dbgpt_session_file` | Stores owner-bound session and scheduled-task file metadata, stable public file IDs, managed storage URIs, inspection status, and task-file lineage. |
| `code_graph_vertex`, `code_graph_edge`, `code_graph_meta` | Persist code-graph indexes (AST nodes, structural relationships, and per-space build metadata) for code-oriented knowledge retrieval. |
| `knowledge_space.index_methods` | New nullable column storing the JSON list of selected index methods (for example `["VectorStore", "FullText", "KnowledgeGraph"]`). |
| `gpts_messages.content` | Widened to `LONGTEXT` so large Agent messages and action reports no longer fail to write. |
Apply the incremental script to your MySQL metadata database:
```bash
mysql -u -p dbgpt < assets/schema/upgrade/v0_8_2/upgrade_to_v0.8.2.sql
```
### Install Dependencies
Install or update dependencies according to your deployment method. For a source installation with the default setup:
```bash
uv sync --all-packages
```
Install optional extras as needed:
```bash
# Agentic Knowledge-Base Search and RAG dependencies
uv sync --all-packages --extra "rag"
# Milvus vector store
uv sync --all-packages --extra "storage_milvus"
```
### Restart DB-GPT
Restart DB-GPT using your usual startup method. After startup, we recommend checking that:
- Existing conversations and knowledge spaces load correctly.
- Multiple files can be uploaded, previewed, removed, and analyzed in one conversation.
- Scheduled Tasks created from a conversation with attachments can access their frozen task files.
- Agentic Knowledge-Base Search can retrieve from the configured index methods and display source references.
- Parallel sub-agent tasks and interactive questions update correctly in the frontend.
## Acknowledgements
Thank you to everyone who contributed to this release: @Aries-ckt, @Bartok9, @Carbene, @Dellorchid, @DreamZhongJu, @Osamaali313, @XiaoHuo888-hue, @chen-alan, @chenliang15405, @chuenchen309, @mumubuku, and @yyyCode.
## References
- [DB-GPT V0.8.1 Release Notes](http://docs.dbgpt.cn/docs/next/changelog/Released_V0.8.1)
- [Quick Start](http://docs.dbgpt.cn/docs/overview/)
- [Installation Guide](http://docs.dbgpt.cn/docs/next/installation/)
- [RAG Concepts](http://docs.dbgpt.cn/docs/next/getting-started/concepts/rag)
- [Knowledge Base Indexing Principles](http://docs.dbgpt.cn/docs/next/design/kb_index_principles)
---
### Docs Changelog Doc (`docs/docs/changelog/doc.md`)
# ChangeLog
Our version release information is maintained on GitHub. For more details, please visit [ReleaseNotes](https://github.com/eosphoros-ai/DB-GPT/releases)
---
### Docs Config Reference Config Applicationconfig 72fd1c (`docs/docs/config-reference/config_applicationconfig_72fd1c.mdx`)
---
title: "ApplicationConfig Configuration"
description: "Application configuration."
---
import { ConfigDetail } from "@site/src/components/mdx/ConfigDetail";
---
### Docs Config Reference Config Systemparameters Fd92b9 (`docs/docs/config-reference/config_systemparameters_fd92b9.mdx`)
---
title: "SystemParameters Configuration"
description: "System parameters."
---
import { ConfigDetail } from "@site/src/components/mdx/ConfigDetail";
---
### Docs Config Reference Manager Hookconfig D9a481 (`docs/docs/config-reference/manager_hookconfig_d9a481.mdx`)
---
title: "HookConfig Configuration"
description: "Hook configuration.
You can define a hook configuration with a path and optional parameters.
It will be used to dynamically load and execute a hook function or a callable
object."
---
import { ConfigDetail } from "@site/src/components/mdx/ConfigDetail";
---
### Docs Dbgpts How To Use Custom Skill (`docs/docs/dbgpts/how-to-use-custom-skill.md`)
# Use Custom Skills
DB-GPT supports three ways to use custom skills: create from scratch with the built-in `skill-creator`, upload a zip package, or import via a GitHub link.
## Option 1: Create with skill-creator
`skill-creator` is the built-in meta-skill in DB-GPT, designed to help you create business-specific custom skills. Simply describe your requirements in a conversation, and `skill-creator` handles the entire process from design to packaging.
### Steps
1. Select the `skill-creator` skill in the DB-GPT chat interface.
2. Describe the skill you want to create in natural language, for example: "Create a data analysis skill that reads CSV files and generates visual reports."
3. `skill-creator` will automatically:
- Analyze your requirements and plan the skill structure
- Generate `SKILL.md` (including metadata and execution instructions)
- Create necessary scripts, reference docs, and asset files
- Validate and package into a distributable `.skill` file
For more details on `skill-creator`, see the [skill-creator documentation](./built-in-skills/skill-creator.md).
## Option 2: Upload a Zip Package
If you already have a packaged skill (`.zip` or `.skill` file), you can upload it directly through the DB-GPT Web UI.
### Steps
1. Navigate to the **Skills** page in DB-GPT.
2. Click the upload button and select your local `.zip` or `.skill` file.
3. Once uploaded, the skill appears in the list and is ready to use in conversations.
## Option 3: Import via GitHub Link
DB-GPT supports importing skills directly from GitHub repositories — ideal for community or team-shared skills.
### Steps
1. Navigate to the **Skills** page in DB-GPT.
2. Click the GitHub import button and paste the repository URL of the skill.
3. The system automatically fetches the repository contents and completes the import. The skill is ready to use once imported.
## Related reading
- [skill-creator](./built-in-skills/skill-creator.md) — Learn about the full capabilities and resources of skill-creator
- [Skills Overview](./introduction.md) — Understand skill definitions, structure, and how they work
---
### Docs Dbgpts How To Use Skill (`docs/docs/dbgpts/how-to-use-skill.md`)
# How to Use Skill
## Basic usage flow
In practice, using a skill usually follows this pattern:
1. Identify the right skill for the task.
2. Load the skill instructions.
3. Follow the skill-defined workflow.
4. Use the required built-in tools.
5. Return the final result or render the final report.
## Common tool flow
Depending on the skill, the execution path often looks like this:
- `load_skill` → load the skill instructions
- `sql_query` → retrieve structured data if needed
- `code_interpreter` → compute metrics, transform data, generate charts
- `shell_interpreter` → run shell commands when required
- `html_interpreter` → render the final HTML report or page
## Example scenarios
### Financial report analysis
The agent can:
1. load the financial-report skill
2. execute the required data extraction and analysis steps
3. generate charts and metrics
4. use `html_interpreter` to render the final report
### CSV / Excel analysis
The agent can:
1. load a data analysis skill
2. inspect the uploaded file
3. use Python analysis to calculate metrics and visualize results
4. render the output as a report if needed
## Good practices
- use skills when the workflow should be repeatable
- follow the skill instructions strictly
- prefer the tools required by the skill over ad-hoc alternatives
- use `html_interpreter` for final report rendering when the skill produces a webpage or report
## Related reading
- [dbgpts Introduction](./introduction.md)
- [Tools Overview](../agents/introduction/tools.md)
- [Built-in tools](../agents/modules/resource/tools.md)
---
### Docs Dbgpts Introduction (`docs/docs/dbgpts/introduction.md`)
# Skills Overview
> The skill definition on this page is adapted from the [Agent Skills](https://agentskills.io/what-are-skills) description, which frames skills as lightweight, self-contained capability packages that agents can discover, load, and apply on demand.
## What is a skill?
In DB-GPT, a skill is a reusable capability package that gives an agent a structured way to solve a task.
Instead of relying only on free-form reasoning, a skill provides a stable execution pattern for a specific kind of work.
## Skill definition
Adapted from the Agent Skills description, a skill can be understood as:
- a **lightweight extension format** for giving agents specialized knowledge and workflows
- a **package of know-how**, not just facts, APIs, or prompts
- a **progressive-disclosure unit** that can be discovered first and fully loaded only when needed
- a **self-contained bundle** of instructions, scripts, templates, and reference files
- a way to make agent behavior more **consistent, repeatable, and domain-aware**
In DB-GPT terms, a skill is not just “something the model knows.” It is a packaged workflow that helps the agent decide:
- what problem it is solving
- what tools it should use
- what order the steps should follow
- what outputs should be produced
- what constraints it should obey
## What a skill usually contains
A DB-GPT skill package often includes:
- a name
- instructions in `SKILL.md`
- optional scripts
- optional templates
- optional static resources or examples
At its core, a skill is a folder containing a `SKILL.md` file. This file includes metadata and instructions that tell an agent how to perform a specific task. Skills can also bundle scripts, templates, and reference materials.
```text
my-skill/
├── SKILL.md # Required: instructions + metadata
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation loaded as needed
└── assets/ # Optional: templates, output resources, static files
```
## Skill anatomy
Following the structure used by DB-GPT's own skill-creator guidance, a skill is organized as a small self-contained package:
| Part | Required | Purpose |
|------|----------|---------|
| `SKILL.md` | Yes | Defines the skill's identity and instructions |
| `scripts/` | No | Stores executable code such as Python or shell helpers |
| `references/` | No | Stores documents that can be loaded into context only when needed |
| `assets/` | No | Stores templates, fonts, icons, boilerplate files, or other output resources |
### `SKILL.md`
`SKILL.md` is the entry point of the skill. It usually contains:
- metadata such as `name` and `description`
- the workflow instructions the agent should follow
- guidance on when to read additional references or use bundled resources
### `scripts/`
Use `scripts/` for executable helpers, such as:
- Python data-processing utilities
- shell scripts
- report-generation helpers
- automation code used by the skill
### `references/`
Use `references/` for supporting knowledge that should not always live inside `SKILL.md`, such as:
- API documentation
- business logic references
- schemas
- workflow guides
- policy or domain documents
This keeps `SKILL.md` smaller while still making deeper context available when the task requires it.
### `assets/`
Use `assets/` for files that support the output rather than the reasoning process, such as:
- HTML templates
- icons and logos
- fonts
- boilerplate frontend files
- report resources
## Why skills matter
Skills are useful when:
- a workflow should be standardized
- the task requires domain-specific reasoning
- reporting or analysis should follow a known pattern
- the agent should use curated instructions instead of improvising everything
## How skills work
The common execution pattern is:
1. The agent identifies that a task matches a skill.
2. The skill instructions are loaded.
3. The agent follows the skill-defined workflow.
4. The required tools are executed.
5. The final answer, report, or page is returned.
## Skills and built-in tools
Skills often orchestrate the built-in execution tools together:
- `load_skill` → load the skill instructions
- `sql_query` → retrieve structured data if needed
- `code_interpreter` → compute metrics, transform data, and generate charts
- `shell_interpreter` → run shell commands when required
- `html_interpreter` → render the final report or webpage
## Practical examples
### Financial report analysis
A financial-report skill can define:
- how to inspect uploaded reports
- how to compute indicators and compare periods
- how to generate charts and summaries
- how to render the final HTML report
### CSV / Excel analysis
A data-analysis skill can define:
- how to inspect a dataset
- how to calculate core metrics
- how to visualize outputs
- how to turn the result into a reusable report
## Good practices
- use skills when the workflow should be repeatable
- follow the skill instructions strictly
- prefer the tools required by the skill over ad-hoc alternatives
- use `html_interpreter` for final report rendering when the skill produces a webpage or report
## Next step
See [How to Use Skill](./how-to-use-skill.md) for the practical workflow.
---
### Docs Design Agentic Rag Principles (`docs/docs/design/agentic_rag_principles.md`)
---
id: agentic_rag_principles
title: Agentic RAG Conversation Principles
sidebar_label: Agentic RAG Principles
---
# Agentic RAG Conversation Principles
> This document explains how DB-GPT combines Agent + RAG to answer knowledge-base questions, from query to a cited final answer. Intended for product/design readers — no code.
## 1. Agentic RAG vs Traditional RAG
```
Traditional RAG (single retrieval)
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Question │ → │Retrieve │ → │ Build │ → │ LLM │
└──────────┘ │ once │ │ Prompt │ │ Answer │
└──────────┘ └──────────┘ └──────────┘
retrieval once stuff into ctx one-shot
Weakness: quality hinges on one similarity pass; can't iterate; no multi-step lookahead
Agentic RAG (multi-round) ← DB-GPT uses this
┌──────────┐ ┌──────────────────────────────────────┐ ┌──────────┐
│ Question │ → │ ReAct Agent Loop │ → │ Cited │
└──────────┘ │ ┌────────┐ ┌────────┐ ┌────────┐ │ │ Answer │
│ │ Thought│→ │ Action │→ │Observe │ │ └──────────┘
│ └────────┘ └────────┘ └────────┘ │
│ ↑ │ │
│ └── not enough? ──────┘ │
│ (multi-round, pick tools) │
└──────────────────────────────────────┘
Strength: iterative retrieval, multiple tools, traceable citations
```
## 2. End-to-End Agent Conversation Flow
```
/* Detailed source-code truncated for AI context efficiency. */
```
## 3. The ReAct Loop (core of the agent)
```
┌─────────────────┐
│ User query │
└────────┬────────┘
│
▼
┌─────────────────────────┐
│ Thought (LLM reasoning)│ ← analyze state, decide next step
└────────────┬────────────┘
│
▼
┌─────────────────────────┐
│ Action (tool + args) │ ← pick one from available tools
└────────────┬────────────┘
│
▼
┌─────────────────────────┐
│ Observation (tool ret) │ ← execute, get result
└────────────┬────────────┘
│
┌────────┴────────┐
│ │
enough info? need more?
│ │
▼ │
┌──────────┐ │
│ Terminate│ │
│ Answer │ │
└──────────┘ │
│ yes → back to Thought (next round)
│
(max N rounds to prevent loops)
```
**Key**: the agent doesn't blindly retrieve once — it judges "is this enough?" from the observation; if not, it switches tools/queries and searches again.
## 4. Citation Traceability Pipeline
```
Tool exec Backend collect Frontend display
───────── ───────────────── ────────────────
kb_semantic_search -> _cited_chunks[0] = { -> [1] blue badge
Result 1: "Pi... " content: "Pi...", hover shows:
score: 0.67 recall_score: 0.67, "Pi... · recall 0.67"
}
kb_cat -> _cited_chunks[1] = { -> [2] blue badge
"Hermes freezes..." content: "Hermes...", hover shows:
recall_score: null, "Hermes..."
}
│
Auto-annotate -> answer text: -> [1][2] inserted
_auto_annotate "Pi rebuilds[1]" after cited
_citations "Hermes freezes[2]" sentence
Ref panel -> XML -> 🔗 View References
_build_references_xml references='[{ click → Drawer
name:"prompt cache.md", tabs per doc
chunks:[{index:1,...}, all chunks
{index:2,...}]
}]'
```
## 5. Tool Modes: Knowledge-Agent vs Full-Agent
```
KB detail-page chat (knowledge-agent) Generic agent chat (react-agent)
───────────────────────────────────── ────────────────────────────────
┌─────────────────────────┐ ┌─────────────────────────────┐
│ KB tools only: │ │ All tools: │
│ • kb_semantic_search │ │ • kb_* (knowledge) │
│ • kb_grep / kb_cat │ │ • shell_interpreter │
│ • kb_ls / kb_glob │ │ • sql_query │
│ • kb_codegraph_* │ │ • html_interpreter │
│ • todowrite / terminate│ │ • code_interpreter │
└─────────────────────────┘ │ • execute_skill_script │
↑ │ • todowrite / terminate │
focused on KB retrieval └─────────────────────────────┘
no noise from irrelevant tools ↑
ideal for pure KB Q&A capable, for complex tasks
but many tools → easy to drift
```
## 6. Key Design Principles
1. **Agent-driven retrieval**: not one-shot; LLM decides whether to search again or switch tools based on observation
2. **Tools scoped to scene**: pure KB chat gets only KB tools, preventing the agent from calling shell/sql
3. **Citations auto-collected**: every tool-returned chunk enters `_cited_chunks` — doesn't rely on LLM compliance
4. **Post-processing fallback**: when the LLM ignores the "mark [1][2]" instruction, backend string-matches and inserts badges automatically
5. **Chunk content cleaning**: HTML tags stripped before matching so clean LLM text aligns with chunk text
6. **References shipped with answer**: `` XML appended to the answer; frontend parses it to render badges + panel
7. **Closed-loop traceability**: every badge → chunk → document → viewable in the references panel
---
### Docs Design Dashboard (`docs/docs/design/dashboard.md`)
---
id: dashboard
title: Dashboard Workspace Design
sidebar_label: Dashboard Workspace
---
# Dashboard Workspace Design
Dashboard turns a data-analysis request into a saved, editable and publishable workspace. This document describes its architecture, data contract, workflows and deployment requirements. It covers the workspace under `/dashboards`; the existing [Chat Dashboard](../application/apps/chat_dashboard.md) guide describes the older chat application.
The design separates **Schema** (what to query and display) from **Snapshot** (the result of an execution). An agent proposes a plan or a change; the server authorizes, validates, executes and persists it. The browser provides review and interaction, but does not authorize database access.
## Architecture
```mermaid
flowchart TD
Request[User request and selected data] --> Agent[Agent: explore, plan, confirm]
Agent --> Schema[Versioned Dashboard Schema]
Editor[Editor: charts, filters and AI proposals] --> Schema
Schema --> Service[API: identity, permissions and validation]
Service --> Query[Read-only query executor]
Query --> Source[(Authorized data sources)]
Service --> Store[(Drafts, revisions and snapshots)]
Service --> Publish[Publication and share grants]
Publish --> Reader[Read-only public viewer]
```
| Component | Responsibility | Main implementation |
| --- | --- | --- |
| Agent and tools | Explore data, plan without SQL, obtain confirmation and propose changes | `tools/dashboard.py`, `planner.py`, `confirmation.py` |
| Contract | Validate structure, cross-field references and version compatibility | `schemas.py`, `schema/dashboard.schema.json`, `web/types/dashboard.ts` |
| Queries | Validate SQL ASTs, table/column allowlists and parameters; enforce execution limits | `sql_security.py`, `query_executor.py`, `lineage.py` |
| Assets | Save drafts, record revisions, detect conflicts, refresh and publish | `service.py`, `models.py`, `api.py` |
| Access and sharing | Resolve identity, check source permissions and manage public grants | `identity.py`, `access.py`, `publication.py`, `live_share.py`, `share_vault.py` |
| UI | Edit components, review AI changes, render results and publish | `DashboardEditor.tsx`, `DashboardRenderer.tsx`, `DashboardPublishDialog.tsx` |
Backend filenames are relative to the [Dashboard backend](https://github.com/eosphoros-ai/DB-GPT/tree/main/packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/dashboard); the tools directory is its sibling. UI filenames are relative to the [Dashboard components](https://github.com/eosphoros-ai/DB-GPT/tree/main/web/new-components/dashboard).
## Data contract
The Pydantic model and server-side cross-field checks define the accepted contract. The checked-in JSON Schema is exposed by `GET /api/v1/dashboards/schema` for client validation; TypeScript describes the browser types. Passing client validation does not bypass server validation.
| Schema field | Meaning |
| --- | --- |
| `schema_version` | Versions 1.0–1.4; later versions add federation, metric context, publication presentation and theme capabilities. |
| `dashboard` | Identity, title, description, source, state, theme and refresh policy. |
| `metric_context` | Grain, time coverage, freshness, provenance and metric definitions. |
| `filters` | Filter type, field, options, defaults and query-parameter bindings. |
| `widgets` | Component queries, output fields, visual encodings and public-filter aggregation. |
| `layouts` | Grid position, size and mobile presentation. |
| `metadata` | Conversation, generation, template and compatibility information. |
The five base widget types are `kpi`, `line`, `bar`, `pie` and `table`; visualization settings express additional presentations. Filters support dates, single/multiple selections, text and numeric ranges. Their actual effect depends on query parameters and publication bindings. See the [Schema definition](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/dashboard/schemas.py) for field-level rules.
## Creation and AI changes
1. Select an authorized data source or attach files. The agent explores tables, fields, samples and time columns.
2. Review a plan describing metrics, dimensions, filters and widgets without SQL, then confirm it.
3. Generate the Schema and queries. The server checks permissions, structure, SQL and actual query results before accepting the result.
4. Open the draft, inspect values and queries, adjust titles/layouts/filters, and save. Planning, query-preview and saved-asset events are separate states.
5. To change an existing dashboard, describe the requested edit or add an AI annotation. The assistant reads the current object and returns a proposal for review before application. Explanation and anomaly analysis do not silently edit the draft.
A proposal that changes related widgets and filters must keep references, parameters and public aggregation consistent. Applying a proposal is not the same as publishing it.
Data templates offer preset, manual-mapping and AI-adaptation paths. For a built-in source with the default requirements, adaptation can reuse verified preset queries without calling a model; the resulting preview uses the preset creation path. Custom requirements retain model adaptation and validation. A successful preset preview is therefore not evidence of model-generation success.
## Saving, revisions and publication
```mermaid
flowchart TD
Draft[Editable draft] -->|Save with expected_revision| Revision[Saved revision]
Revision -->|Authorize and validate| Publication[Published definition]
Publication --> Frozen[Fixed historical snapshot]
Publication --> Latest[Latest publication alias]
Publication --> Live[Live share: refresh published queries]
Revision -->|Edit and save| Draft
```
Saving carries `expected_revision`; a stale revision returns a conflict instead of silently overwriting changes. Publishing also performs a conditional database update against the expected revision and checks the affected row count. This avoids relying on a row lock that SQLite does not provide. If a save commits after another session publishes the previously read revision, the save explicitly writes `draft`; the older publication remains attached to its own revision.
| Object | What changes | Reader behavior |
| --- | --- | --- |
| Draft | Explicit saves create revisions | Editing does not automatically replace published content. |
| Fixed historical publication | Schema and data are frozen for that publication | Filters recompute only over materialized dimensions; later source changes do not alter it. |
| Latest publication alias | Follows a later explicit publication | Its target can change; it is distinct from a fixed historical URL. |
| Live share | Re-materializes data using the published definition | Expiry, revocation and source authorization apply; polling does not guarantee real-time updates. |
Publication validates access, Schema, queries and filter bindings. Public readers can view and use permitted filters, but cannot submit arbitrary SQL, replace the source or modify the draft. Project ZIP export contains Schema, Plan and SQL for inspection; it is not a standalone offline application.
## Identity, authorization and execution
Dashboard uses the upstream request identity, preferring a stable user ID rather than a display nickname. Object roles are `viewer`, `editor` and `owner`; having edit access to a dashboard does not itself grant access to its data sources. Source checks cover the primary source and all sources referenced by federated queries before connectors read metadata, including static validation.
SQL is parsed with the connector's supported dialect and restricted to allowed read-only ASTs. Table and column allowlists are checked within query scope. Qualified names require authorization for the full name; a same-named CTE or a table in another catalog does not grant access. If a connector supplies only unqualified names, queries should use those names. Filter values use bound parameters, with multi-value expansion handled by the executor.
Queries have row, timeout and total-wait limits. A refresh timeout prevents subsequent publication, with another check before the publication transaction commits. A running driver call cannot always be interrupted by Python: the scheduler keeps renewing its lease while waiting for the worker to exit, and lease loss cancels execution. Configure driver/database query timeouts as well.
Public-token lookup uses hashes. The encrypted token needed by an authorized publisher to recover a link is stored separately. Audit records redact sensitive details. Historical shares without a creator require a verifiable conversation owner; legacy files under `pilot/data/` still require an ownership check. Display names are not used to infer ownership.
## Deployment and upgrades
### Metadata database
Entities are registered through the existing `db_model_initialization.py`. SQLite uses DB-GPT's startup table creation and migration entry point; there is no separate Dashboard Alembic revision chain. Do not depend on a request creating missing tables.
MySQL follows the existing versioned full/incremental SQL convention:
| Deployment | Script under `assets/schema/upgrade/v0_8_3/` | Procedure |
| --- | --- | --- |
| New empty database | [v0.8.3.sql](https://github.com/eosphoros-ai/DB-GPT/blob/main/assets/schema/upgrade/v0_8_3/v0.8.3.sql) | Initialize the full schema, equivalent to `assets/schema/dbgpt.sql`. Do not also run the incremental script. |
| Existing v0.8.2 database | [upgrade_to_v0.8.3.sql](https://github.com/eosphoros-ai/DB-GPT/blob/main/assets/schema/upgrade/v0_8_3/upgrade_to_v0.8.3.sql) | Stop the service, back up the database, run the script once, then start the new version. Upgrade older databases to v0.8.2 through the historical scripts first. |
The incremental script uses `ALTER TABLE ... ADD COLUMN`, `ADD INDEX` / `ADD UNIQUE INDEX` for existing chat and scheduled-task tables, and `CREATE TABLE IF NOT EXISTS` for new tables. It does not delete business data or backfill owner IDs from display names.
**Existing MySQL deployments must upgrade before starting the new version.** Skipping the script leaves scheduled-task `owner_id`, `resource_*`, `lease_*` fields and run-idempotency indexes missing. This can cause `Unknown column` errors and break existing scheduled tasks as well as Dashboard features. Adjust the database name in the scripts if it is not `dbgpt`. The incremental script is not a repeatable initializer: if an older Dashboard script or manual DDL was already applied, compare existing columns/indexes and execute only missing changes.
### Production services
- Use trusted authentication and enable `DBGPT_DASHBOARD_PRODUCTION_MODE`. The development fallback identity is rejected in this mode. A deployment-specific identity adapter can be provided through `DBGPT_DASHBOARD_IDENTITY_PROVIDER`.
- Connect the deployment's data-source authorization policy through `DBGPT_DASHBOARD_DATA_SOURCE_POLICY` or the application integration hook. Production mode requires a policy; an object role alone is insufficient. Verify cross-user and external-connector access in the target environment.
- Production collaboration requires Redis. Missing collaboration configuration makes that API unavailable without preventing ordinary chat and dashboard services from starting.
- Preserve the share-encryption key. Automatic atomic key creation requires hard-link support; unsupported filesystems report an error. A deployment can instead supply `DBGPT_SHARE_ENCRYPTION_KEY`.
- File analysis uses the configured `SANDBOX_RUNTIME`; Dashboard does not independently switch it to Lyric. Validate driver cancellation behavior and sustained load in the actual deployment.
## Development and validation
From `web/`, use `yarn test:dashboard` and `yarn test` for frontend tests, `yarn build --webpack` for a production build, and `yarn compile` for static export. Browser regressions use `yarn test:e2e:dashboard` with the environment expected by `playwright.dashboard.config.ts`. A build is not a substitute for browser interaction or strict type checking.
After installing backend test dependencies, run the following from the repository root in Bash. It keeps package paths and external-service markers explicit without adding another pytest configuration:
```sh
python -m pytest -c pyproject.toml --rootdir=. --import-mode=importlib -p no:cacheprovider \
-o addopts= \
-o "pythonpath=packages/dbgpt-app/src packages/dbgpt-client/src packages/dbgpt-core/src packages/dbgpt-ext/src packages/dbgpt-sandbox/src packages/dbgpt-serve/src" \
-o "markers=mysql_integration: requires DASHBOARD_TEST_MYSQL_URL and a disposable MySQL database
redis_integration: requires DASHBOARD_TEST_REDIS_URL and a disposable Redis database" \
packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/dashboard/tests \
packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/tests/test_question_contract.py \
packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/tests/test_share_privacy.py \
packages/dbgpt-serve/src/dbgpt_serve/scheduled_task/tests \
packages/dbgpt-app/src/dbgpt_app/tests/test_multi_file_tools.py \
packages/dbgpt-app/src/dbgpt_app/tests/test_olist_dashboard_case.py \
packages/dbgpt-app/src/dbgpt_app/tests/test_uploaded_dataset.py \
packages/dbgpt-app/src/dbgpt_app/tests/test_uploaded_dataset_registry.py \
packages/dbgpt-app/src/dbgpt_app/tests/test_python_upload_api.py \
packages/dbgpt-app/src/dbgpt_app/tests/test_workspace_provisioning.py \
packages/dbgpt-app/src/dbgpt_app/tests/test_dashboard_skill_orchestration.py \
examples/dashboard/tests
```
Set `DASHBOARD_TEST_MYSQL_URL` (database name must contain `test`) and `DASHBOARD_TEST_REDIS_URL` to run external-service integration tests. Without them, those tests explicitly skip. MySQL tests recreate tables: connect only to disposable test databases.
Validate the behavior being changed: manual dates must reach the query, save/publish interleavings must retain the right revision/state, revoked source permissions must prevent metadata reads, and template creation must be tested beyond its preview. Model generation, preset creation and frozen-publication filtering need separate checks. Record the tested commit and environment with results; historical screenshots are illustrations, not evidence for a newer commit.
## Implementation and examples
- [Schema contract](https://github.com/eosphoros-ai/DB-GPT/tree/main/packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/dashboard/schema) and [REST implementation](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/dashboard/api.py).
- [Agent tools](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/tools/dashboard.py) and [frontend components](https://github.com/eosphoros-ai/DB-GPT/tree/main/web/new-components/dashboard).
- [Reproducible example data and Schemas](https://github.com/eosphoros-ai/DB-GPT/tree/main/examples/dashboard) and [browser fixtures](https://github.com/eosphoros-ai/DB-GPT/blob/main/web/tests/dashboard-e2e/fixtures/README.md).
- Business walkthroughs: [Walmart](../application/dashboard/walmart.md) and [Apple](../application/dashboard/apple.md). Both are available in English and Chinese and document data provenance, operating steps and historical checks separately from this design.
## Capability boundaries
| Area | Current boundary |
| --- | --- |
| SQL dialects | With SQLGlot 26.13.2, Vertica, MaxCompute, GaussDB, openGauss and OceanBase are rejected as `unsupported_data_source` before execution, without a generic-dialect fallback. Parser support alone does not certify a connector on a target database. |
| DuckDB | Queries may use registered tables, not file paths or table functions that read arbitrary external files. |
| Unsaved inputs | Reloading the new-dashboard page loses inputs/options kept only in page memory. Saved assets remain accessible from the dashboard list. |
| AI semantics | A structurally valid result can still use the wrong business definition. Review metrics, grain, units and source values. Fixed prompts or preset runs do not establish a general generation success rate. |
| Layout presets | `layout_templates` is disabled in the checked-in release feature contract. It is not a deployment environment switch and is separate from the data-template gallery. |
| Style cards | The style skills are bundled, but the home-page parameter handoff from the gallery is not connected. Treat these cards as presentation references, not a completed creation flow. Use the data-template setup or the dedicated creation page. |
| Filters and refresh | Fixed publications can only filter materialized dimensions. Live sharing needs an authorized source and offers periodic refresh, not a real-time guarantee. |
| Local preferences | Template favorites persist in the browser; account-wide, cross-device synchronization is not provided. |
| Demo data | Synthetic retail data and historical Walmart data are different sources. Synthetic totals are not real business totals; matching source files does not establish redistribution rights. |
---
### Docs Design Kb Index Principles (`docs/docs/design/kb_index_principles.md`)
---
id: kb_index_principles
title: Knowledge Base Indexing Principles
sidebar_label: KB Indexing Principles
---
# Knowledge Base Indexing Principles
> How DB-GPT indexes an uploaded document — from raw file to searchable indexes.
> Intended for product / design readers. No code, but the mechanisms match the implementation.
## What "indexing" means here
Indexing happens at **document-sync time**, not at chat time. Chat only *retrieves*; it never re-indexes.
The pipeline for every document:
```
upload ──► load file ──► chunk ──► embed ──► persist into one or more indexes
│
└─► optionally build graph(s)
```
A knowledge space declares which indexes to build via `index_methods` (a string list). Three index
*methods* are selectable; "structural index" and "code graph" are capabilities layered on top
(structural index is built at retrieve time; the code/heading graph is built on top of the
`KnowledgeGraph` method or for `GIT_REPO` spaces).
| Index entry point | Code name (`index_methods`) | Built at sync time? | What it gives you |
|---|---|---|---|
| Vector index | `VectorStore` | yes | semantic similarity ranking |
| Keyword index | `FullText` | yes | exact keyword / BM25 hits |
| Knowledge-graph index | `KnowledgeGraph` | yes | graph-traversal over entities, headings, code |
| Structural index | *(retrieve-time tree)* | no — rebuilt at query time | markdown-header tree / parent-child navigation |
| Code graph | *(layered on `KnowledgeGraph` / `GIT_REPO`)* | yes | AST of code files as `function` / `class` nodes |
> In short: **vector, keyword, knowledge-graph** are the three persisted index methods. **Structural**
> index and **code graph** are two extra shapes of indexing that DB-GPT builds on top of those.
---
## 1. Structural index — navigate by document structure
### What it is
A *view* over the already-chunked document that arranges chunks into a tree by their Markdown
heading level (H1 → H2 → H3 …). Every chunk already carries `Header1/Header2/...` metadata from
chunking (see *Metadata pipeline* below); the structural index simply *organises* those chunks into a
tree so retrieval can walk up to a parent section and then back down to its children — instead of
treating every chunk as an isolated island.
### Why it's a separate concept (even though it has no own index method)
During indexing, DB-GPT **persists** the heading path on each chunk but does **not** persist the tree.
At **retrieve time** the retriever reconstructs the tree from those `HeaderN` fields in memory and
walks it ("find this leaf chunk, then expand its whole parent section, then rank"). So the "structural
index" is really *structural metadata + a tree-view retriever*, not a separate store.
### Principle (how it's built + used)
```
markdown file chunking writes HeaderN on every chunk
───────────── ────────────────────────────────────────
# Prompt Cache Design ──► chunk A { H1: "Prompt Cache Design" }
## Core Principle ──► chunk B { H1: "Prompt Cache", H2: "Core Principle" }
### Hit Condition ──► chunk C { H1..H3: "Hit Condition" }
## Three Strategies ──► chunk D { H1: "Prompt Cache", H2: "Three Strategies" }
│
retrieve-time ▼ organise into tree by H1>H2>H3
┌── H1 Prompt Cache ──┐
│ │
H2 Core Principle H2 Three Strategies
│ │
H3 Hit Condition (chunk D)
(chunk C)
```
- Best for: "what's in this whole section?", "summarise chapter 3", parent-context expansion.
- Note: for non-Markdown documents there is no heading hierarchy, so the structural tree degrades to a
flat list — its value is concentrated on Markdown / structured docs.
---
## 2. Knowledge-graph index — relational retrieval
This is the richest index, and internally it is **not one graph but several** that all get built when
the `KnowledgeGraph` method is enabled:
```
enable index_methods = KnowledgeGraph
│
├── (a) LLM triplet graph semantic: (entity) -predicate- (entity)
├── (b) document–paragraph graph structural: document → chunk → chunk (include / next)
├── (c) Markdown heading graph structural: file → H1 → H2 → H3 (contains)
└── (d) code graph structural: repository → file → function/class (defines)
```
(a) and (b) live in the **knowledge-graph store** (TuGraph / Neo4j / Memgraph); (c) and (d) both land
in the **code-graph tables** and share one builder.
### 2a. LLM triplet-extraction graph (semantic)
Each chunk is sent to an LLM with an extraction prompt that asks for `(subject, predicate, object)`
triplets. The returned triplets are upserted into the graph store as `entity -edge- entity`. This is
the classic "knowledge graph from text": it captures facts and relations that pure keyword/vector
search cannot.
```
chunk text: "Anthropic's prompt cache reuses the KV matrix to cut cost"
│ LLM triplet extraction prompt
▼
(Anthropic) ──has──▶ (Prompt Cache)
(Prompt Cache) ──reuses──▶ (KV matrix)
(Prompt Cache) ──cuts──▶ (cost)
```
Retrieval traverses edges: an entity hit expands to its neighbours, and each edge knows which chunk
it came from (via a `_chunk_id` edge property) so answers can still be cited back to source.
### 2b. Document–paragraph graph
Independently of triplets, the KG store also builds a structural skeleton:
`document -include- chunk`, `chunk -include- chunk` (parent/child when chunks nest), and
`chunk -next- chunk` (reading order). This lets retrieval hop from an entity → the chunk that
contains it → the document → neighbouring chunks. (When the community-summary variant is enabled, it
also runs community detection and summarises each community with an LLM.)
### 2c. Markdown heading graph
For `.md` files under a `KnowledgeGraph`-method space, the builder reconstructs each file's content
from its stored chunks, scans `^(#{1,6})\s+` heading lines (skipping headings inside fenced code
blocks), and emits `heading` vertices connected by `contains` edges:
`file → H1 → H2 → H3`. This is the graph analogue of the structural index above — queryable via edge
traversal instead of an in-memory tree.
### 2d. Code graph (代码图谱)
This is the part most worth understanding. The **same** `RepoGraphBuilder` that builds the Markdown
heading graph is also able to build a graph from **source code**, and it is what powers code-level
retrieval over a `GIT_REPO` space (or over code files uploaded into a `KnowledgeGraph`-method space).
**Principle — parse with an AST, not with regex:**
```
walk repo
repository ──contains──▶ file
│ language inferred from extension
┌──────────────────────────┼───────────────────────────┐
│ │ │
.py/.java/.js/.ts/ .md/.markdown other languages
.go/.rs/.c/.cpp (heading graph 2c) (regex fallback)
│ │
▼ parse with tree-sitter ▼ regex def/class lines
function_definition / class_definition / ... file ──defines──▶ function|class
│
▼ for each AST target node
create a vertex: type=function|class|method|class|interface|impl|struct|enum|trait
name, file_path, start_line, end_line, language
add edge: file ──defines──▶
```
- **Nodes** created: `repository`, `file`, and code nodes `function` / `class` / `method` /
`interface` / `impl` / `struct` / `enum` / `trait`.
- **Edges** created by the builder: `contains` (repo→file, file→heading) and `defines` (file→code node).
- **Parser:** [tree-sitter](https://tree-sitter.github.io/) for Python / Java / JavaScript /
TypeScript / Go / Rust / C / C++. Each target AST node type (e.g. `function_definition`,
`class_definition`, `method_declaration`, `interface_declaration`, `struct_item`) is mapped to a
semantic node type. Languages without a tree-sitter grammar here fall back to a regex `def`/`class`
scan that still emits `file -defines-> function|class` edges.
- **What it buys you:** "where is `apply_anthropic_cache_control` defined?", "list all methods of
class `PromptCache`" — answered by vertex lookup + `defines` edge traversal, instead of fuzzy
vector match.
> **Honest caveat about edges.** The retrieval layer also supports `CALLS` / `INHERITS` /
> `IMPLEMENTS` / `IMPORTS` / `REFERENCES` edges (for call-chain and class-hierarchy queries). The
> current `RepoGraphBuilder`, however, only emits `contains` and `defines`. So call-chain and
> inheritance traversals only return data when those edges were produced by another builder; for
> graphs built purely by this builder they will be empty. Call it out when designing features that
> depend on call graphs.
---
## 3. Vector index — semantic similarity
```
chunk ──embedding model──► [0.12, -0.34, 0.56, …] (e.g. 1024-d) ──► vector store
query ──embedding model──► query vector ──cosine similarity──► top-K chunks
```
### Principle
Each chunk is run through an embedding model that maps text to a high-dimensional vector; the
vector + the chunk's metadata are bulk-upserted into a vector database (Chroma / Milvus / PGVector /
Qdrant / Weaviate / …) as chosen by the space config. At query time the question is embedded the same
way and the store returns the chunks whose vectors are nearest (cosine / inner-product) to the query
vector.
### Why it's the default
Vector search catches *paraphrase*: "caching mechanism" still retrieves "prompt cache" because the
vectors live nearby even though no words match. It doesn't need any structural information about the
document and works on every file type.
### Weakness
A vector averages a whole chunk into one point — if the chunk mixes two topics it blurs; if the exact
term matters (an API name, an error code) it may miss. That's why keyword + vector are usually
enabled together.
---
## 4. Keyword index — exact-term match (BM25)
```
chunk ──indexed as text in search engine──► BM25 term index
query ──tokenize──► "terms" ──BM25 score over chunks──► top-K chunks
```
### Principle
Chunks are stored verbatim as text documents in a full-text search engine (Elasticsearch with BM25
scoring; `k1` / `b` tunable). Retrieval tokenises the query and returns chunks ranked by BM25 score —
i.e. by term frequency × inverse document frequency, with length normalisation. No embedding, no LLM,
pure lexical matching.
### When it wins
Precise identifiers: `apply_anthropic_cache_control`, `ERR_CONN_REFUSED`, a config key. Vector search
may dilute such exact tokens into "similar" but wrong neighbours; BM25 returns the exact hit and
ranks it at the very top.
### Weakness
It cannot match synonyms or paraphrase ("caching" will not find "cache" reliably once tokenised, and
definitely won't find "缓存"). It is purely complementary to the vector index.
---
## How the four combine at retrieval time
```
user question
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
vector keyword (BM25) knowledge graph
semantic exact term / structural / code
hits hits hits
│ │ │
└──────────────────┼──────────────────┘
▼
fusion + rerank (structural tree can expand parents here)
│
▼
Top-K chunks ──► into the LLM prompt ──► cited answer
```
---
## Chunking & metadata pipeline (the foundation under all four)
All four indexes operate on the *same chunks*, so chunking quality dominates retrieval quality.
**Chunking strategies**
- Markdown header split (`H1→H2→H3`): preserves semantic boundary + heading path — best for tech docs.
- Size split (fixed chars): for plain text without structure.
- Separator split (paragraph / newline / table cell): for tabular / unstructured content.
**Metadata written on every chunk during indexing** (used later by every index and by citation
tracing):
```
upload chunking storage
────── ──────── ───────
file_name: prompt.md → chunk_id: 101 → vector: [0.12, ...]
file_path: /docs/... → doc_name: prompt.md → content: "Prefix..."
doc_type: DOCUMENT → chunk_type: text → meta_info: {
index_methods: → file_path: /docs/... → "Header1": "Prompt Cache",
[Vector, FullText, → header_path: H1>H2>H3 → "Header2": "Core Principle",
KG] → "Header3": "Hit Condition"
→ }
```
---
## Key design principles
1. **Three persisted index methods** — `VectorStore`, `FullText`, `KnowledgeGraph` — combinable per space.
2. **Structural index is metadata + a retrieve-time tree**, not a separate store; it relies on the
`HeaderN` written during chunking.
3. **The knowledge-graph index is a family of graphs** — LLM triplets, document–paragraph skeleton,
Markdown headings, and the code graph (AST) — that share the build path.
4. **Code graph parses with tree-sitter**, emitting `function`/`class` nodes + `defines` edges; it is
what makes code-level question-answering precise. Mind that call/inheritance edges are not
populated by the current builder.
5. **One chunking, four indexes** — chunk quality and the `HeaderN` metadata underpin everything;
chunk per doc type (Markdown→headers, text→size, table→separator).
6. **Index/chat decoupled** — indexing runs at sync time; chat only retrieves.
---
### Docs Design Traceable Report Regression Tests (`docs/docs/design/traceable-report-regression-tests.md`)
# F12 / F16 / F18 / F19 regression tests
Python tool regressions live beside the tools in
`packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/tools/tests/`.
Live backend tests use the repository's existing `tests/intetration_tests/`
directory (the spelling is retained for consistency). Browser cases and their
fixtures live under `web/tests/report-e2e/` and use the Playwright test runner.
These tests use real file I/O and subprocesses, on-disk SQLite, the production
tool/assembler/DAO/download implementations, a live OceanBase server, a local
Spark JVM, and Chrome with the full React report component and actual G2 renderer.
They do not substitute fake Spark sessions or OceanBase clients.
## Python
Use the project's configured Python environment with its normal dependencies,
plus `pytest`, `pytest-asyncio`, `httpx`, `pyobvector==0.2.10` and `pyspark==3.5.2`.
Spark also needs Java and `SPARK_HOME` / `JAVA_HOME` configured. On Windows,
`SPARK_LOCAL_IP=127.0.0.1` avoids hostname binding problems. `PYSPARK_PYTHON`
should name the same Python executable used for the tests. An existing Spark
Python installation can be provided through `DBGPT_SPARK_PYTHON_PATH`.
File security tests do not need an external service:
```powershell
python -m pytest packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/tools/tests/test_input_file_security.py -q
```
Real CSV analysis tests also run without OceanBase/Spark:
```powershell
python -m pytest packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/tools/tests/test_analysis_integration.py -q
```
They use the public analysis tool, actual pandas CSV reads and the real local
Python executor. They cover legacy uploads, all attachments, ordered subsets
excluding the primary attachment, capture on/off, valid conversation IDs and
unsafe IDs rejected before creating the runner's working directory.
For the live database tests, use a disposable OceanBase tenant/database with
HNSW vector support. Verified server image: `oceanbase/oceanbase-ce:4.3.5-lts`.
For example:
```powershell
docker run -d --name dbgpt-report-regression-ob -p 127.0.0.1:12881:2881 -e MODE=mini oceanbase/oceanbase-ce:4.3.5-lts
```
After the tenant is ready, execute SQL as its administrator:
```sql
ALTER SYSTEM SET ob_vector_memory_limit_percentage=30;
CREATE DATABASE dbgpt_f16_regression;
```
Run the live backend regressions explicitly:
```powershell
$env:DBGPT_RUN_LIVE_REGRESSIONS='1'
$env:DBGPT_OB_HOST='127.0.0.1'
$env:DBGPT_OB_PORT='12881'
$env:DBGPT_OB_USER='root@test'
$env:DBGPT_OB_PASSWORD=''
$env:DBGPT_OB_DATABASE='dbgpt_f16_regression'
python -m pytest tests/intetration_tests/vector_store/test_oceanbase_identity_integration.py tests/intetration_tests/datasource/test_spark_chart_integration.py -q --junitxml=pytest.xml
```
Live tests are opt-in so routine test discovery does not require running
OceanBase/Spark. Once enabled, missing dependencies or unavailable services fail
the run; they are not replaced with mocks or silently skipped. Tests create
unique vector tables and drop only their own tables. They never modify production
knowledge records. SQLite is isolated under pytest's temporary directory.
The embedding vectors in the OceanBase test are small, deterministic numerical
inputs: the tested contract is source identity after real vector writes/searches,
not embedding model accuracy. Public search intentionally deduplicates equal
bodies; the test checks all three backend UUIDs before that step and every
reference retained by the public search afterward.
## Browser
Install the web workspace dependencies and Chrome, then from the `web` directory:
```powershell
npm run test:e2e:report
```
This bundles the working-tree `HtmlReportEvidence`, `ReportIframe`, `AutoChart`
and export implementations, then runs them in installed Chrome through Playwright.
An actual local HTTP fixture delays the report metadata response to trigger the
race. The HTTP response is controlled test data; this is a component integration
test, not a claim that the entire Next.js application/backend was deployed.
Assertions cover opaque-to-trusted, empty-to-untrusted and missing-trust metadata,
actual parent DOM access, child script execution, G2's real render observation,
native chart canvas, exported PNG snapshots, and standalone PDF generation.
The three transitions are separate Playwright test cases. Results, screenshots,
HTML exports and PDFs are saved under `web/node_modules/.cache/report-e2e/results/`.
Playwright also retains a trace when a case fails. Override the output directory
with `npm run test:e2e:report -- --output `.
For the same browser assertions against the audited iframe implementation:
```powershell
$env:DBGPT_BROWSER_BASELINE='1'
npm run test:e2e:report -- --grep opaque-to-trusted
npm run test:e2e:report -- --grep empty-to-untrusted
Remove-Item Env:DBGPT_BROWSER_BASELINE
```
Python tests import the installed project packages using the same environment as
the surrounding module tests. No audit-specific source-path override is needed.
---
### Docs Design Traceable Analysis Report (`docs/docs/design/traceable_analysis_report.md`)
---
id: traceable_analysis_report
title: Traceable Analysis Report Technical Design
sidebar_label: Traceable Analysis Report
---
This document describes the design of the data analysis report capability: how real execution results are persisted as artifacts, how values and charts in a report are bound to their sources, and how a failed report can reuse existing results instead of rerunning the analysis. The design is based on the protocols, execution tools, report service, and frontend implementation of the current DB-GPT branch.
## 1. Overall Architecture and Responsibilities
The system is organized around one principle: capture execution artifacts first, then generate the report from references. The task agent plans the analysis and invokes tools; the capture layer persists real execution results; the dedicated report agent selects evidence and composes content; the template engine resolves values and validates bindings; the report service stores documents and indexes, which the frontend uses for display and source lookup. Modules exchange artifact identifiers and selectors, as shown in Figure 1.
*Figure 1. Collaboration design for execution capture and the report service*
The main task and its parallel subtasks write results to the same conversation-level ArtifactSink. The shared report_capture layer records execution evidence; the application-layer report agent and html_interpreter compose and bind report content; dbgpt_serve.report handles persistence and queries. Large results and files are stored in content storage, while metadata and relationships are stored in the report database.
## 2. Data Model for Artifacts and Evidence
The model records two distinct kinds of relationships. Production dependencies answer which inputs produced a given result; body citations answer which result is used at a given place in the report. The former links artifacts through input_artifact_ids; the latter links a report target to a source location through EvidenceReference. A report revision freezes both relationships together with their content snapshots, as shown in Figure 2.
*Figure 2. Independent modeling of production dependencies and body citations*
| Data object | Key fields | Relationship meaning |
| --- | --- | --- |
| Artifact | artifact_id, execution, status, input_artifact_ids | One real execution and its input dependencies |
| ArtifactContent | inline, uri, sha256, size | Content snapshot of an execution result, citation, or file |
| ReportDocument | sections, blocks, artifacts | Persistable report structure and artifact set |
| EvidenceReference | artifact_id, selector, target_selector, role | Source value location and its location of use in the body |
| ReportRun | owner_id, report_id, run_id, revision | Immutable report revision isolated per user |
| RenderObservation | artifact_id, renderer, status, timing | Independent observation of what the browser actually rendered |
For example, a GMV value reference can be declared as artifact_id = sql_A, path = ["rows", 0, "gmv"]. The engine reads the actual result, formats the display value, and assigns a target identifier to that fragment. A single SQL artifact can support multiple places in the body; when Python computation or a chart consumes it, that input dependency is recorded separately.
## 3. Execution Capture and Report Recovery
Report construction starts from completed artifacts and proceeds through spec construction, reference resolution, binding validation, rendering, and persistence. Errors return to the relevant stage through checkpoints instead of restarting the entire analysis; a completed report and an unfinished task return distinct statuses. The flow is shown in Figure 3.
*Figure 3. Report generation validation and failure recovery flow*
Capture happens at the tool-execution boundary: SQL captures the query, columns, and result rows; Python captures the code, exit status, and REPORT_RESULT; skills capture the script and arguments; knowledge reads capture the source text and location. A result is snapshotted before any UI preview is produced. Python reads SQL results through SQL_RESULTS and tracks the actual inputs; local subprocesses use the backend module path so they do not read the wrong directory when multiple worktrees exist.
The report agent declares sections and data references with REPORT_SPEC. The engine validates artifact status, field paths, and display values, expands tables, and creates a separate artifact plus local bindings for each chart. Structured paragraphs render text and references separately so internal objects are never exposed directly as body text.
A failure checkpoint stores the original request, template parameters, artifacts, progress, and error location. On resume, the engine first re-renders with the original parameters, then repairs references, appends sections, or computes only the missing metrics. The recovery layer builds an error fingerprint from the error code and target location and tracks invocation, specification, and rendering failures separately. Repeated failures or an exhausted total budget stop the run and preserve the remaining work. Text values that may degrade are shown as -- with a diagnostic record and are not published as verified values.
## 4. Version Persistence and Source Lookup
After rendering, the assembler combines sections, body fragments, artifacts, and bindings into a ReportDocument. ReportDao appends the ReportRun, artifact snapshots, artifact dependencies, and evidence index in one transaction and updates the report's latest-revision pointer. Saved revisions are never rewritten in place; re-analysis or repair creates a new revision, so a user looking up a past revision sees the evidence that revision actually used.
The storage layer uses dbgpt_report, dbgpt_report_run, dbgpt_report_artifact, dbgpt_report_artifact_dependency, and dbgpt_report_evidence for report entry points, revisions, artifacts, dependencies, and body evidence, respectively. Large results and files use artifact:// content addresses and SHA256 snapshots. Reads verify content integrity, and truncation in a UI preview never changes the underlying referenced value.
The frontend pins a revision through `/api/v1/reports/{report_id}/runs/{run_id}`; clicking a body target requests `/blocks/{block_id}/evidence`, and downloading a snapshot requests `/artifacts/{artifact_id}/content`. The service checks visibility by owner_id, then uses the evidence index to locate the artifact and selector and returns the code, result, or source text. Source lookup preserves both the location of use in the report and the actual location of the value.
## 5. Graph Rendering and Report Delivery
The evidence graph is a view projection of the saved relationships. Sources are organized by database, knowledge file, and uploaded file; execution groups status and results by conversation, task, run, and step identifier; outputs show only the actual report or task files. Knowledge chunks are aggregated under file nodes while their source text and locations remain available in detail; production edges come from explicit input dependencies, never from filename or timestamp guesses.
The frontend mounts charts from the data and ECharts option in the chart artifact, and stores the actual render result, renderer, duration, and error separately as a RenderObservation. Server-side generation success and browser-side drawing success are observed independently; browser feedback never mutates a saved report revision.
For export, the system waits for fonts and charts to finish rendering, clones the current report, expands collapsed tables, converts readable canvases to images, removes scripts and source-review controls, and then produces an HTML reading copy or hands the document to the browser for PDF printing. The offline copy preserves reading content; interactive charts and source inspection remain available in the online report.
# Olist Business Analysis Report Case Study
## Step 1: Select Data and Start Analysis
On the home page, the user selects the Olist_Ecommerce database and the Olist_Analytics_Governance knowledge base and asks a business review question covering GMV, order volume, average order value, category and regional performance, and the relationship between delivery and ratings. After submission, the user follows task progress on the left and reads the report's definitions, core metrics, and improvement recommendations on the right, then decides which questions to verify next, as shown in Figure 4.
*Figure 4. Selecting data, running the analysis, and generating the business report*
## Step 2: Verify SQL Results for Core Metrics
The user first checks GMV in the report and clicks the SQL badge next to the value to open its source details, including execution status, duration, database, query statement, and result snapshot. By comparing the displayed value with the query result, the user can confirm which field the metric used and inspect the query conditions when the definition is in doubt, without searching the full conversation for the execution record. See Figure 5.
*Figure 5. Opening execution evidence through the GMV SQL badge*
## Step 3: Confirm the Knowledge Basis for Metric Definitions
The user then clicks the KB badge next to the methodology note to inspect the knowledge file, source excerpt, and read location used by this analysis, confirming the order filter, deduplication, currency unit, and delivery grouping rules. When a metric name is ambiguous, the user can compare this rule with the query conditions to judge whether the report answers the original business question. See Figure 6.
*Figure 6. Following a methodology note to the knowledge-base source*
## Step 4: Compare Categories and Trace Chart Data
The user continues to the category analysis, first identifying the main sales categories from the bar chart and then reviewing the detail table below it. To verify the visualization, the user clicks the chart badge, and the source panel shows the SQL result and chart artifact behind the chart. The user can then check that categories, values, ordering, and units agree before deciding which categories merit deeper analysis or operational priority. See Figure 7.
*Figure 7. Inspecting query results and chart artifacts from a category chart*
## Step 5: Review Metrics Computed by Python
For statistics computed in Python, the user clicks the PY badge next to the body value to inspect the executed code, result snapshot, and input files. Verification starts with the referenced field, then checks grouping, quantiles, or other computation steps, and opens the input file when the data source needs confirmation. This lets the user trace a specific value in the report back to its calculation basis, as shown in Figure 8.
*Figure 8. Tracing a body value back to Python computation and input files*
## Step 6: Compare Numeric Results with Business Rules
For important metrics, the user expands both the SQL result and the knowledge-base source and reviews the computed value together with the rule that should apply. For example, the user checks the result field used for GMV, whether orders are deduplicated, and whether multi-table joins aggregate at the correct grain. When a value is unexpected, these details help the user decide whether to adjust the query, the metric definition, or the report wording. See Figure 9.
*Figure 9. Comparing a SQL result snapshot with the knowledge-base source*
## Step 7: Inspect the Full Source and Execution Chain
After local verification, the user switches to Evidence Graph, reviews databases and knowledge files in the left column, follows the execution steps in the middle to understand the analysis, and checks report and chart files on the right. Clicking a node opens details with execution status, results, or file information. This shows which materials the report depends on and helps locate failed or still-questionable steps. See Figure 10.
*Figure 10. Inspecting the complete chain from sources to execution and output files*
## Step 8: Choose the Report Delivery Format
When verification is complete, the user returns to Analysis Report and opens the Export menu in the upper-right corner, choosing HTML or PDF for the intended audience. Choose HTML for an offline-readable web page, or PDF for printing or archiving. Work that still needs interactive charts and source details should continue in the online report. See Figure 11.
*Figure 11. Choosing HTML or PDF from the report export menu*
## Step 9: Check the Print Layout and Save as PDF
After choosing Export as PDF, the user enters the browser print preview and checks pagination, table width, charts, and font rendering, adjusting orientation, scale, and background graphics as needed. Once key content is confirmed not to be clipped, the user saves the PDF and completes delivery. The preview step lets the user verify the final reading experience before sending the file. See Figure 12.
*Figure 12. Checking pagination in print preview and saving as PDF*
---
### Docs Faq Install (`docs/docs/faq/install.md`)
# Installation FAQ
### Q1: sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) unable to open database file
make sure you pull latest code or create directory with mkdir pilot/data
### Q2: The model keeps getting killed.
your GPU VRAM size is not enough, try replace your hardware or replace other llms.
### Q3: How to access website on the public network
You can try to use gradio's [network](https://github.com/gradio-app/gradio/blob/main/gradio/networking.py) to achieve.
```python
import secrets
from gradio import networking
token=secrets.token_urlsafe(32)
local_port=5670
url = networking.setup_tunnel('0.0.0.0', local_port, token)
print(f'Public url: {url}')
time.sleep(60 * 60 * 24)
```
Open `url` with your browser to see the website.
### Q4: (Windows) execute `pip install -e .` error
The error log like the following:
```
× python setup.py bdist_wheel did not run successfully.
│ exit code: 1
╰─> [11 lines of output]
running bdist_wheel
running build
running build_py
creating build
creating build\lib.win-amd64-cpython-310
creating build\lib.win-amd64-cpython-310\cchardet
copying src\cchardet\version.py -> build\lib.win-amd64-cpython-310\cchardet
copying src\cchardet\__init__.py -> build\lib.win-amd64-cpython-310\cchardet
running build_ext
building 'cchardet._cchardet' extension
error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-cpp-build-tools/
[end of output]
```
Download and install `Microsoft C++ Build Tools` from [visual-cpp-build-tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
### Q5: `Torch not compiled with CUDA enabled`
```
2023-08-19 16:24:30 | ERROR | stderr | raise AssertionError("Torch not compiled with CUDA enabled")
2023-08-19 16:24:30 | ERROR | stderr | AssertionError: Torch not compiled with CUDA enabled
```
1. Install [CUDA Toolkit](https://developer.nvidia.com/cuda-toolkit-archive)
2. Reinstall PyTorch [start-locally](https://pytorch.org/get-started/locally/#start-locally) with CUDA support.
### Q6: `How to migrate meta table chat_history and connect_config from duckdb to sqlite`
```commandline
python docker/examples/metadata/duckdb2sqlite.py
```
### Q7: `How to migrate meta table chat_history and connect_config from duckdb to mysql`
```commandline
1. update your mysql username and password in docker/examples/metadata/duckdb2mysql.py
2. python docker/examples/metadata/duckdb2mysql.py
```
### Q8: `How to manage and migrate my database`
You can use the command of `dbgpt db migration` to manage and migrate your database.
See the following command for details.
```commandline
dbgpt db migration --help
```
First, you need to create a migration script(just once unless you clean it).
This command with create a `alembic` directory in your `pilot/meta_data` directory and a initial migration script in it.
```commandline
dbgpt db migration init
```
Then you can upgrade your database with the following command.
```commandline
dbgpt db migration upgrade
```
Every time you change the model or pull the latest code from DB-GPT repository, you need to create a new migration script.
```commandline
dbgpt db migration migrate -m "your message"
```
Then you can upgrade your database with the following command.
```commandline
dbgpt db migration upgrade
```
### Q9: `alembic.util.exc.CommandError: Target database is not up to date.`
**Solution 1:**
Run the following command to upgrade the database.
```commandline
dbgpt db migration upgrade
```
**Solution 2:**
Run the following command to clean the migration script and migration history.
```commandline
dbgpt db migration clean -y
```
**Solution 3:**
If you have already run the above command, but the error still exists,
you can try the following command to clean the migration script, migration history and your data.
warning: This command will delete all your data!!! Please use it with caution.
```commandline
dbgpt db migration clean --drop_all_tables -y --confirm_drop_all_tables
```
or
```commandline
rm -rf pilot/meta_data/alembic/versions/*
rm -rf pilot/meta_data/alembic/dbgpt.db
```
---
### Docs Faq Kbqa (`docs/docs/faq/kbqa.md`)
# KBQA FAQ
### Q1: text2vec-large-chinese not found
make sure you have download text2vec-large-chinese embedding model in right way
```tip
centos:yum install git-lfs
ubuntu:apt-get install git-lfs -y
macos:brew install git-lfs
```
```bash
cd models
git lfs clone https://huggingface.co/GanymedeNil/text2vec-large-chinese
```
### Q2:How to change Vector DB Type in DB-GPT.
Update .env file and set VECTOR_STORE_TYPE.
DB-GPT currently support Chroma(Default), Milvus(>2.1), Weaviate, Valkey, OceanBase vector database.
If you want to change vector db, Update your .env, set your vector store type, VECTOR_STORE_TYPE=Chroma (now only support Chroma and Milvus(>2.1), if you set Milvus, please set MILVUS_URL and MILVUS_PORT).
If you want to use OceanBase, please first start a docker container via the following command:
```shell
docker run --name=ob433 -e MODE=slim -p 2881:2881 -d quay.io/oceanbase/oceanbase-ce:4.3.3.0-100000142024101215
```
Download the partner package:
```shell
pip install --upgrade --quiet pyobvector
```
Check the connection to OceanBase and set the memory usage ratio for vector data:
```python
from pyobvector import ObVecClient
tmp_client = ObVecClient()
tmp_client.perform_raw_text_sql(
"ALTER SYSTEM ob_vector_memory_limit_percentage = 30"
)
```
Then set the following variables in the .env file:
```shell
VECTOR_STORE_TYPE=OceanBase
OB_HOST=127.0.0.1
OB_PORT=2881
OB_USER=root@test
OB_DATABASE=test
## Optional
# OB_PASSWORD=
## Optional: If {OB_ENABLE_NORMALIZE_VECTOR} is set, the vector stored in OceanBase is normalized.
# OB_ENABLE_NORMALIZE_VECTOR=True
```
If you want to support more vector db, you can integrate yourself.[how to integrate](https://db-gpt.readthedocs.io/en/latest/modules/vector.html)
```commandline
#*******************************************************************#
#** VECTOR STORE SETTINGS **#
#*******************************************************************#
VECTOR_STORE_TYPE=Chroma
#MILVUS_URL=127.0.0.1
#MILVUS_PORT=19530
#MILVUS_USERNAME
#MILVUS_PASSWORD
#MILVUS_SECURE=
#WEAVIATE_URL=https://kt-region-m8hcy0wc.weaviate.network
```
### Q3:When I use vicuna-13b, found some illegal character like this.
Set KNOWLEDGE_SEARCH_TOP_SIZE smaller or set KNOWLEDGE_CHUNK_SIZE smaller, and reboot server.
### Q4:space add error (pymysql.err.OperationalError) (1054, "Unknown column 'knowledge_space.context' in 'field list'")
1.shutdown dbgpt_server(ctrl c)
2.add column context for table knowledge_space
```commandline
mysql -h127.0.0.1 -uroot -p {your_password}
```
3.execute sql ddl
```commandline
mysql> use knowledge_management;
mysql> ALTER TABLE knowledge_space ADD COLUMN context TEXT COMMENT "arguments context";
```
4.restart dbgpt serve
### Q5:Use Mysql, how to use DB-GPT KBQA
build Mysql KBQA system database schema.
```bash
$ mysql -h127.0.0.1 -uroot -p{your_password} < ./assets/schema/knowledge_management.sql
```
---
### Docs Faq Llm (`docs/docs/faq/llm.md`)
# LLM USE FAQ
### Q1:how to use openai chatgpt service
change your LLM_MODEL
````shell
LLM_MODEL=proxyllm
````
set your OPENAPI KEY
````shell
PROXY_API_KEY={your-openai-sk}
PROXY_SERVER_URL=https://api.openai.com/v1/chat/completions
````
make sure your openapi API_KEY is available
### Q2 What difference between `python dbgpt_server --light` and `python dbgpt_server`
:::tip
python dbgpt_server --light` dbgpt_server does not start the llm service. Users can deploy the llm service separately by using `python llmserver`, and dbgpt_server accesses the llm service through set the LLM_SERVER environment variable in .env. The purpose is to allow for the separate deployment of dbgpt's backend service and llm service.
python dbgpt_server service and the llm service are deployed on the same instance. when dbgpt_server starts the service, it also starts the llm service at the same time.
:::
### Q3 how to use MultiGPUs
DB-GPT will use all available gpu by default. And you can modify the setting `CUDA_VISIBLE_DEVICES=0,1` in `.env` file
to use the specific gpu IDs.
Optionally, you can also specify the gpu ID to use before the starting command, as shown below:
````shell
# Specify 1 gpu
CUDA_VISIBLE_DEVICES=0 python3 dbgpt/app/dbgpt_server.py
# Specify 4 gpus
CUDA_VISIBLE_DEVICES=3,4,5,6 python3 dbgpt/app/dbgpt_server.py
````
You can modify the setting `MAX_GPU_MEMORY=xxGib` in `.env` file to configure the maximum memory used by each GPU.
### Q4 Not Enough Memory
DB-GPT supported 8-bit quantization and 4-bit quantization.
You can modify the setting `QUANTIZE_8bit=True` or `QUANTIZE_4bit=True` in `.env` file to use quantization(8-bit quantization is enabled by default).
Llama-2-70b with 8-bit quantization can run with 80 GB of VRAM, and 4-bit quantization can run with 48 GB of VRAM.
Note: you need to install the latest dependencies according to [requirements.txt](https://github.com/eosphoros-ai/DB-GPT/blob/main/requirements.txt).
Note: you need to install the latest dependencies according to [requirements.txt](https://github.com/eosphoros-ai/DB-GPT/blob/main/requirements.txt).
---
### Docs Getting Started Model Providers Ui (`docs/docs/getting-started/model-providers-ui.md`)
---
sidebar_position: 3
title: Model Providers UI
summary: "Connect LLM providers and manage models from the settings page, no code required"
read_when:
- You want to connect a provider (OpenAI, Copilot, DeepSeek…) without editing config files
- You need to enable/disable specific models or add an OpenAI-compatible custom provider
---
# Model Providers UI
import useBaseUrl from '@docusaurus/useBaseUrl';
})
The **Model Providers** page is a settings page where you connect LLM providers and manage their models entirely from the UI — no `.toml` editing and no code required.
Key properties:
- **Connect once, enable models individually.** Credentials are stored per provider; each model under a provider can be enabled or disabled independently.
- **Takes effect immediately.** Enabling a model starts its worker in the running server; the model is selectable in chat right away — no restart.
- **Survives restarts.** Connected providers and enabled models are persisted and restored automatically when the server boots.
## Opening the page
Use the top navigation: **Model Providers**. The page has three worker-type tabs — `llm`, `text2vec`, `reranker`. The provider list on the left shows every built-in provider with its model count; providers with a green **Connected** tag already have stored credentials.
## Built-in providers (pre-integrated)
27 providers ship pre-integrated — each comes with a ready-made model catalog (label, context length, function-calling support), so you only need to provide credentials:
| Group | Providers |
| --- | --- |
| Global model providers | OpenAI, GitHub Copilot, Anthropic (Claude), Google Gemini, xAI (Grok), Mistral AI, NVIDIA NIM |
| Chinese model providers | DeepSeek, Zhipu AI (GLM), Kimi (Moonshot), Tongyi Qwen, Volcengine (Doubao), MiniMax, Baichuan, Yi (01.AI), iFlytek Spark, Baidu Qianfan (ERNIE) |
| Gateways & aggregators | OrcaRouter (orcarouter.ai), Vercel AI Gateway, SiliconFlow, LiteLLM, Groq, AIML API, BurnCloud, Gitee AI, Infini AI |
| Local | Ollama (local models, no API key needed) |
Notes on a few of them:
- **Ollama** — connects without any API key (probed against your local server at `http://localhost:11434`).
- **Baidu Qianfan** — API Key uses the `AccessKey:SecretKey` format.
- **iFlytek Spark / LiteLLM** — credentials cannot be verified at connect time (no model-list endpoint); the connection is accepted as-is and model startup is the source of truth.
- **GitHub Copilot** — see [GitHub Copilot (OAuth sign-in)](#github-copilot-oauth-sign-in) below; Personal Access Tokens are not supported.
## Connecting a provider
Select a provider and click **Connect**:
})
- **API Key** (required for most providers) — the provider's API key.
- **API Base** (optional) — override the default endpoint. Leave empty to use the provider's official address.
On connect the credentials are **verified against the real provider** (e.g. a model-list probe) before anything is saved, and the provider's 5 most recently updated models are enabled automatically. A failed verification saves nothing.
## Enabling and disabling models
})
Each model row shows its label, function-calling support and context length, with a switch to enable or disable it:
- **Enable** starts the model's worker — the model becomes usable in chat immediately.
- **Disable** stops the worker and frees the concurrency slot.
Use the **Search models** box to filter long catalogs; large catalogs show the first 50 rows with a **show all** button. Once a provider is connected you can **Reconnect** (to change credentials) or **Disconnect** (which stops its models and clears the stored key).
## GitHub Copilot (OAuth sign-in)
GitHub Copilot requires a Copilot subscription and uses the same GitHub device-flow sign-in as OpenCode: open the connect dialog, visit [github.com/login/device](https://github.com/login/device), enter the confirmation code, and the connection completes automatically once you authorize. Personal Access Tokens are **not** accepted by GitHub for Copilot.
})
One-time server setup: register a GitHub OAuth App at [github.com/settings/developers](https://github.com/settings/developers) (enable **Device Flow**), then start the server with:
```bash
export GITHUB_COPILOT_OAUTH_CLIENT_ID=Iv1_your_client_id
```
## Adding a custom provider
If your service is not in the built-in list, any **OpenAI-compatible** endpoint (vLLM, LiteLLM gateway, one-api, FastChat, Xinference, company gateways…) can be added without code via **Add Custom Provider**:
})
| Field | Description |
| --- | --- |
| Name | Display name of the provider (shown in the left list) |
| API Base | Base URL, e.g. `http://localhost:8000/v1` |
| API Key | Bearer token (fill any placeholder like `sk-xxx` for unauthenticated local servers) |
| Model list | The available model ids, comma or newline separated |
How it works:
1. On submit, the backend first probes the endpoint (`GET {API Base}/models`) to verify reachability.
2. The provider is persisted as a `custom/` provider and every listed model is started immediately — usable in chat without a restart.
3. The available models are **exactly what you list** — there is no auto-discovery. To add or remove models later, disconnect and re-create the provider, or enable/disable the existing ones from its detail page.
4. Custom providers survive server restarts like built-in ones.
:::tip
Try it in the UI first to validate connectivity and model quality; if you later want a first-class provider (branded icon, curated model catalog with metadata, default-enabled models), add a real adapter — see `packages/dbgpt-core/src/dbgpt/model/proxy/llms/` for templates.
:::
---
### Docs Getting Started Next Steps (`docs/docs/getting-started/next-steps.md`)
---
sidebar_position: 99
title: Next Steps
summary: "Where to go after the first successful DB-GPT setup"
read_when:
- You already completed the quick start and want the next useful docs
- You are deciding whether to go deeper into apps, APIs, deployment, or operations
---
# Next Steps
You have the basics working. Use this page to jump to the next useful docs.
## Build applications
| Goal | Resource |
|---|---|
| Build a data analysis app | [App Development Guide](/docs/cookbook/app/data_analysis_app_develop) |
| Create custom agents | [Agent Development](/docs/agents/introduction/) |
| Build AWEL workflows in Python | [AWEL Tutorial](/docs/awel/tutorial) |
| Use the visual AWEL editor | [AWEL Flow](/docs/getting-started/tools/awel-flow) |
## Deepen your knowledge
| Topic | Resource |
|---|---|
| AWEL language deep dive | [AWEL Documentation](/docs/awel/) |
| Agent modules (memory, planning, tools) | [Agent Modules](/docs/agents/modules/profile/) |
| RAG advanced configuration | [RAG Tutorial](/docs/application/advanced_tutorial/rag) |
| Multi-model management (SMMF) | [SMMF Guide](/docs/application/advanced_tutorial/smmf) |
| Graph RAG | [Graph RAG Development](/docs/cookbook/rag/graph_rag_app_develop) |
## Production deployment
| Topic | Resource |
|---|---|
| Docker deployment | [Docker Guide](/docs/getting-started/deploy/docker) |
| Docker Compose | [Docker Compose Guide](/docs/getting-started/deploy/docker-compose) |
| Cluster deployment | [Cluster Guide](/docs/getting-started/deploy/cluster) |
| Observability & debugging | [Debugging Guide](/docs/application/advanced_tutorial/debugging) |
| CLI reference | [CLI Guide](/docs/application/advanced_tutorial/cli) |
## API integration
| Topic | Resource |
|---|---|
| REST API overview | [API Introduction](/docs/api/introduction) |
| Chat API | [Chat API](/docs/api/chat) |
| App API | [App API](/docs/api/app) |
| Knowledge API | [Knowledge API](/docs/api/knowledge) |
| Flow API | [Flow API](/docs/api/flow) |
## Community & resources
| Resource | Link |
|---|---|
| GitHub Repository | [eosphoros-ai/DB-GPT](https://github.com/eosphoros-ai/DB-GPT) |
| Community Apps | [dbgpts](https://github.com/eosphoros-ai/dbgpts) |
| GitHub Issues | [Report a bug](https://github.com/eosphoros-ai/DB-GPT/issues) |
| Discussions | [GitHub Discussions](https://github.com/orgs/eosphoros-ai/discussions) |
| Slack | [Join Slack](https://join.slack.com/t/slack-inu2564/shared_invite/zt-29rcnyw2b-N~ubOD9kFc7b7MDOAM1otA) |
| Twitter/X | [@DBGPT_AI](https://x.com/DBGPT_AI) |
| Paper | [DB-GPT Paper (arXiv)](https://arxiv.org/pdf/2312.17449.pdf) |
| DeepWiki | [DB-GPT DeepWiki](https://deepwiki.com/eosphoros-ai/DB-GPT) |
## FAQ
Common questions organized by topic:
- [Installation FAQ](/docs/faq/install) — Setup and dependency issues
- [LLM FAQ](/docs/faq/llm) — Model configuration and performance
- [Knowledge Base FAQ](/docs/faq/kbqa) — RAG and document retrieval
---
### Docs Getting Started Prerequisites (`docs/docs/getting-started/prerequisites.md`)
---
sidebar_position: 1
title: Prerequisites
summary: "What you need before running DB-GPT locally or with Docker"
read_when:
- You want to confirm Python, uv, Docker, or GPU requirements before setup
- You are deciding between API-proxy mode and local-model mode
---
# Prerequisites
Everything you need before installing DB-GPT.
:::tip Quick check
Already have Python 3.10+ and uv? Skip to [Getting Started](/docs/getting-started/quick-start).
:::
## Required
| Requirement | Version | Check command |
|---|---|---|
| **Python** | 3.10 or newer | `python --version` |
| **uv** | Latest | `uv --version` |
| **Git** | Any recent | `git --version` |
### Python
DB-GPT requires **Python 3.10+**. We recommend Python 3.11 for the best compatibility.
```bash
python --version
# Python 3.11.x
```
:::info
If you need to manage multiple Python versions, consider using [pyenv](https://github.com/pyenv/pyenv) or [conda](https://docs.conda.io/).
:::
### uv (package manager)
Starting from v0.7.0, DB-GPT uses [uv](https://docs.astral.sh/uv/) for environment and package management, providing faster and more stable dependency resolution.
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
```bash
python -m pip install --upgrade pip
python -m pip install --upgrade pipx
python -m pipx ensurepath
pipx install uv --global
```
See the full [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for Homebrew, Scoop, and other methods.
Verify the installation:
```bash
uv --version
```
## Choose the right setup first
- **Fastest setup:** API proxy model (OpenAI, DeepSeek, Qwen, SiliconFlow) — no GPU required
- **Privacy-first local setup:** Ollama — local model runtime, optional GPU
- **High-performance local inference:** vLLM or HuggingFace GPU stack — NVIDIA GPU required
## Optional (based on deployment)
### For Web UI development
| Requirement | Version | Check command |
|---|---|---|
| **Node.js** | 20.19 or newer (frontend development) | `node --version` |
| **Yarn Classic** | 1.x (validated with 1.22.22) | `yarn --version` |
### For local model deployment
| Requirement | Details |
|---|---|
| **NVIDIA GPU** | CUDA 12.1+ for GPU-accelerated inference |
| **CUDA Toolkit** | Required for vLLM, HuggingFace Transformers with GPU |
| **Sufficient VRAM** | 8 GB+ for 7B models, 24 GB+ for 13B+ models |
:::info
If you only use API proxy models (OpenAI, DeepSeek, etc.), **no GPU is required**. You can run on a CPU-only machine.
:::
### For Docker deployment
| Requirement | Version | Check command |
|---|---|---|
| **Docker** | 20.10+ | `docker --version` |
| **Docker Compose** | 2.0+ | `docker compose version` |
| **NVIDIA Container Toolkit** | Latest (GPU only) | `nvidia-smi` |
## System resources
| Deployment Type | CPU | RAM | Disk |
|---|---|---|---|
| **API proxy only** | 2 cores | 4 GB | 10 GB |
| **Local 7B model** | 4 cores | 16 GB | 30 GB |
| **Local 13B+ model** | 8 cores | 32 GB | 60 GB |
## Network considerations (China)
If you are in the China region, configure a PyPI mirror for faster package downloads:
```bash
# Set the mirror as environment variable
echo "export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple" >> ~/.bashrc
source ~/.bashrc
```
Or append `--index-url` to each `uv sync` command:
```bash
uv sync --all-packages \
--extra "base" \
--extra "proxy_openai" \
--index-url=https://pypi.tuna.tsinghua.edu.cn/simple
```
## Next step
Ready to go? Head to [Getting Started](/docs/getting-started/quick-start) for a 5-minute setup.
---
### Docs Getting Started Quick Start (`docs/docs/getting-started/quick-start.md`)
---
sidebar_position: 2
title: Getting Started
summary: "Shortest path from clone to a working DB-GPT chat"
read_when:
- You want the first successful DB-GPT run with the least setup
- You need a concrete first-run checklist and quick verification
---
# Getting Started
Goal: go from zero to a first working chat with minimal setup.
:::info Fastest path
Use an **API proxy** (OpenAI or DeepSeek) — no GPU required. You will have a working DB-GPT chat in under 5 minutes.
:::
## What you need
* Python 3.10 or newer
* uv package manager
:::tip
Check your versions with `python --version` and `uv --version`. Full requirements: [Prerequisites](/docs/getting-started/prerequisites).
:::
## Quick setup
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
### Step 1 — Clone the repository
```bash
git clone https://github.com/eosphoros-ai/DB-GPT.git
cd DB-GPT
```
### Step 2 — Install dependencies
```bash
uv sync --all-packages \
--extra "base" \
--extra "proxy_openai" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "dbgpts"
```
```bash
uv sync --all-packages \
--extra "base" \
--extra "proxy_openai" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "dbgpts"
```
```bash
uv sync --all-packages \
--extra "base" \
--extra "proxy_ollama" \
--extra "rag" \
--extra "storage_chromadb" \
--extra "dbgpts"
```
### Step 3 — Configure your model
Edit `configs/dbgpt-proxy-openai.toml` and set your API key:
```toml
[models]
[[models.llms]]
name = "chatgpt_proxyllm"
provider = "proxy/openai"
api_key = "your-openai-api-key" # <-- replace this
[[models.embeddings]]
name = "text-embedding-3-small"
provider = "proxy/openai"
api_key = "your-openai-api-key" # <-- replace this
```
Edit `configs/dbgpt-proxy-deepseek.toml` and set your API key:
```toml
[models]
[[models.llms]]
name = "deepseek-reasoner"
provider = "proxy/deepseek"
api_key = "your-deepseek-api-key" # <-- replace this
[[models.embeddings]]
name = "BAAI/bge-large-zh-v1.5"
provider = "hf"
```
:::info
The default embedding model is `BAAI/bge-large-zh-v1.5`. If using a HuggingFace embedding, also add `--extra "hf"` and `--extra "cpu"` to the install command.
:::
Make sure [Ollama](https://ollama.ai) is running, then edit `configs/dbgpt-proxy-ollama.toml`:
```toml
[models]
[[models.llms]]
name = "qwen2.5:latest"
provider = "proxy/ollama"
api_base = "http://localhost:11434"
[[models.embeddings]]
name = "nomic-embed-text:latest"
provider = "proxy/ollama"
api_base = "http://localhost:11434"
```
### Step 4 — Start the server
```bash
uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml
```
```bash
uv run dbgpt start webserver --config configs/dbgpt-proxy-deepseek.toml
```
```bash
uv run dbgpt start webserver --config configs/dbgpt-proxy-ollama.toml
```
### Step 5 — Open the Web UI
Open your browser and visit **[http://localhost:5670](http://localhost:5670)**.
:::tip Verify it works
If the Web UI loads and you can start a chat conversation, your DB-GPT is ready for use.
:::
## Verify
- The webserver is running
- Your model config loads without errors
- The Web UI opens at `http://localhost:5670`
- SQLite is available as the default metadata store
## Common first-run issues
- **`uv: command not found`**
- Install uv first: [Prerequisites](/docs/getting-started/prerequisites)
- **Model key/auth errors**
- Re-check the provider config under `configs/`
- Start here: [Model Providers](/docs/getting-started/providers/)
- **Web UI does not load**
- Confirm the server is listening on port `5670`
- Check the server logs in the terminal where you started DB-GPT
- **Local model does not respond**
- Confirm Ollama or your local inference backend is already running
## If you need more
- **Run the web front-end separately**
```bash
cd web && npm install
cp .env.template .env
# Edit .env — set API_BASE_URL=http://localhost:5670
npm run dev
```
Then open [http://localhost:3000](http://localhost:3000).
- **Use the install helper**
```bash
uv run install_help.py install-cmd --interactive
uv run install_help.py list
```
- **Use a different database**
- Default is SQLite
- For MySQL, PostgreSQL, and others, see [Data Sources](/docs/getting-started/concepts/data-sources)
- **Useful environment variables**
- `UV_INDEX_URL` — PyPI mirror URL
- `OPENAI_API_KEY` — alternative to storing the key in TOML
- `CUDA_VISIBLE_DEVICES` — GPU device selection
- Full reference: [Config Reference](/docs/config/config-reference)
## Go deeper
| Topic | Link |
|---|---|
| Full architecture overview | [Architecture](/docs/getting-started/concepts/architecture) |
| Connect more model providers | [Model Providers](/docs/getting-started/providers/) |
| Docker deployment | [Docker](/docs/getting-started/deploy/docker) |
| Knowledge base setup | [Knowledge Base](/docs/getting-started/web-ui/knowledge-base) |
## Next steps
* Configure model providers: [Model Providers](/docs/getting-started/providers/)
* Deploy with Docker: [Docker Deployment](/docs/getting-started/deploy/docker)
* Explore the Web UI: [Web UI Guide](/docs/getting-started/web-ui/)
* Build your first AWEL workflow: [AWEL Quickstart](/docs/awel/cookbook/quickstart_basic_awel_workflow)
---
### Docs Installation Build Image (`docs/docs/installation/build_image.md`)
---
id: docker-build-guide
title: DB-GPT Docker Build Guide
sidebar_label: Docker Build Guide
description: Comprehensive guide for building DB-GPT Docker images with various configurations
keywords:
- DB-GPT
- Docker
- Build
- CUDA
- OpenAI
- VLLM
- Llama-cpp
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import CodeBlock from '@theme/CodeBlock';
# DB-GPT Docker Build Guide
This guide provides comprehensive instructions for building DB-GPT Docker images with various configurations using the `docker/base/build_image.sh` script.
## Overview
The DB-GPT build script allows you to create Docker images tailored to your specific requirements. You can choose from predefined installation modes or customize the build with specific extras, environment variables, and other settings.
## Available Installation Modes
CUDA-based image with standard features.
```bash
bash docker/base/build_image.sh
```
Includes: CUDA support, proxy integrations (OpenAI, Ollama, Zhipuai, Anthropic, Qianfan, Tongyi), RAG capabilities, graph RAG, Hugging Face integration, and quantization support.
CPU-based image optimized for OpenAI API usage.
```bash
bash docker/base/build_image.sh --install-mode openai
```
Includes: Basic functionality, all proxy integrations, and RAG capabilities without GPU acceleration.
CUDA-based image with VLLM for optimized inference.
```bash
bash docker/base/build_image.sh --install-mode vllm
```
Includes: All default features plus VLLM support for high-performance inference.
CUDA-based image with Llama-cpp support.
```bash
bash docker/base/build_image.sh --install-mode llama-cpp
```
Includes: All default features plus Llama-cpp and Llama-cpp server with CUDA acceleration enabled via `CMAKE_ARGS="-DGGML_CUDA=ON"`.
CUDA-based image with all available features.
```bash
bash docker/base/build_image.sh --install-mode full
```
Includes: All features from other modes plus embedding capabilities.
## Basic Usage
### View Available Modes
To see all available installation modes and their configurations:
```bash
bash docker/base/build_image.sh --list-modes
```
### Get Help
Display all available options:
```bash
bash docker/base/build_image.sh --help
```
## Customization Options
### Python Version
DB-GPT requires Python 3.10 or higher. The default is Python 3.11, but you can specify a different version:
```bash
bash docker/base/build_image.sh --python-version 3.10
```
### Custom Image Name
Set a custom name for the built image:
```bash
bash docker/base/build_image.sh --image-name mycompany/dbgpt
```
### Image Name Suffix
Add a suffix to the image name for versioning or environment identification:
```bash
bash docker/base/build_image.sh --image-name-suffix v1.0
```
This will generate `eosphorosai/dbgpt-v1.0` for the default mode or `eosphorosai/dbgpt-MODE-v1.0` for specific modes.
### PIP Mirror
Choose a different PIP index URL:
```bash
bash docker/base/build_image.sh --pip-index-url https://pypi.org/simple
```
### Ubuntu Mirror
Control whether to use Tsinghua Ubuntu mirror:
```bash
bash docker/base/build_image.sh --use-tsinghua-ubuntu false
```
### Language Preference
Set your preferred language (default is English):
```bash
bash docker/base/build_image.sh --language zh
```
## Advanced Customization
### Custom Extras
You can customize the Python package extras installed in the image:
Completely replace the default extras with your own selection:
```bash
bash docker/base/build_image.sh --extras "base,proxy_openai,rag,storage_chromadb"
```
Keep the default extras and add more:
```bash
bash docker/base/build_image.sh --add-extras "storage_milvus,storage_elasticsearch,datasource_postgres"
```
Add specific extras to a particular installation mode:
```bash
bash docker/base/build_image.sh --install-mode vllm --add-extras "storage_milvus,datasource_postgres"
```
#### Available Extra Options
Here are some useful extras you can add:
| Extra Package | Description |
|--------------|-------------|
| `storage_milvus` | Vector store integration with Milvus |
| `storage_valkey` | Vector store integration with Valkey |
| `storage_elasticsearch` | Vector store integration with Elasticsearch |
| `datasource_postgres` | Database connector for PostgreSQL |
| `vllm` | VLLM integration for optimized inference |
| `llama_cpp` | Llama-cpp Python bindings |
| `llama_cpp_server` | Llama-cpp HTTP server |
You can run `uv run install_help.py list` in your local DB-GPT repository to see all available extras.
### Environment Variables
DB-GPT build supports environment variables for specialized builds. The main environment variable used is `CMAKE_ARGS` which is particularly important for Llama-cpp compilation.
Replace the default environment variables:
```bash
bash docker/base/build_image.sh --env-vars "CMAKE_ARGS=\"-DGGML_CUDA=ON -DLLAMA_CUBLAS=ON\""
```
Add additional environment variables:
```bash
bash docker/base/build_image.sh --install-mode llama-cpp --add-env-vars "FORCE_CMAKE=1"
```
:::note
For Llama-cpp mode, `CMAKE_ARGS="-DGGML_CUDA=ON"` is automatically set to enable CUDA acceleration.
:::
### Docker Network
Specify a Docker network for building:
```bash
bash docker/base/build_image.sh --network host
```
### Custom Dockerfile
Use a custom Dockerfile:
```bash
bash docker/base/build_image.sh --dockerfile Dockerfile.custom
```
## Example Scenarios
### Enterprise DB-GPT with PostgreSQL and Elasticsearch
Build a full-featured enterprise version with PostgreSQL and Elasticsearch support:
```bash
bash docker/base/build_image.sh --install-mode full \
--add-extras "storage_elasticsearch,datasource_postgres" \
--image-name-suffix enterprise \
--python-version 3.10 \
--load-examples false
```
### Optimized Llama-cpp for Specific Hardware
Build with custom Llama-cpp optimization flags:
```bash
bash docker/base/build_image.sh --install-mode llama-cpp \
--env-vars "CMAKE_ARGS=\"-DGGML_CUDA=ON -DGGML_AVX2=OFF -DGGML_AVX512=ON\"" \
--python-version 3.11
```
### Lightweight OpenAI Proxy
Build a minimal OpenAI proxy image:
```bash
bash docker/base/build_image.sh --install-mode openai \
--use-tsinghua-ubuntu false \
--pip-index-url https://pypi.org/simple \
--load-examples false
```
### Development Build with Milvus
Build a development version with Milvus support:
```bash
bash docker/base/build_image.sh --install-mode vllm \
--add-extras "storage_milvus" \
--image-name-suffix dev
```
## Troubleshooting
Common Build Issues
### CUDA Not Found
If you encounter CUDA-related errors:
```bash
# Try building with a different CUDA base image
bash docker/base/build_image.sh --base-image nvidia/cuda:12.1.0-devel-ubuntu22.04
```
### Package Installation Failures
If extras fail to install:
```bash
# Try building with fewer extras to isolate the problem
bash docker/base/build_image.sh --extras "base,proxy_openai,rag"
```
### Network Issues
If you encounter network problems:
```bash
# Use a specific network
bash docker/base/build_image.sh --network host
```
## API Reference
### Script Options
| Option | Description | Default Value |
|--------|-------------|---------------|
| `--install-mode` | Installation mode | `default` |
| `--base-image` | Base Docker image | `nvidia/cuda:12.4.0-devel-ubuntu22.04` |
| `--image-name` | Docker image name | `eosphorosai/dbgpt` |
| `--image-name-suffix` | Suffix for image name | ` ` |
| `--pip-index-url` | PIP mirror URL | `https://pypi.tuna.tsinghua.edu.cn/simple` |
| `--language` | Interface language | `en` |
| `--load-examples` | Load example data | `true` |
| `--python-version` | Python version | `3.11` |
| `--use-tsinghua-ubuntu` | Use Tsinghua Ubuntu mirror | `true` |
| `--extras` | Extra packages to install | Mode dependent |
| `--add-extras` | Additional extra packages | ` ` |
| `--env-vars` | Build environment variables | Mode dependent |
| `--add-env-vars` | Additional environment variables | ` ` |
| `--dockerfile` | Dockerfile to use | `Dockerfile` |
| `--network` | Docker network to use | ` ` |
## Additional Resources
- [DB-GPT Documentation](https://github.com/eosphoros-ai/DB-GPT)
- [Docker Documentation](https://docs.docker.com/)
- [CUDA Documentation](https://docs.nvidia.com/cuda/)
---
### Docs Installation Docker (`docs/docs/installation/docker.md`)
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Docker Deployment
## Docker image preparation
There are two ways to prepare a Docker image.
1. Pull from the official image
2. Build locally, see [Build Docker Image](./build_image.md)
You can **choose any one** during actual use.
## Deploy With Proxy Model
In this deployment, you don't need an GPU environment.
1. Pull from the official image repository, [Eosphoros AI Docker Hub](https://hub.docker.com/u/eosphorosai)
```bash
docker pull eosphorosai/dbgpt-openai:latest
```
2. Run the Docker container
This example requires you provide a valid API key for the SiliconFlow API. You can obtain one by signing up at [SiliconFlow](https://siliconflow.cn/) and creating an API key at [API Key](https://cloud.siliconflow.cn/account/ak). Alternatively, set `AIMLAPI_API_KEY` to use the AI/ML API service.
```bash
docker run -it --rm -e SILICONFLOW_API_KEY=${SILICONFLOW_API_KEY} \
-p 5670:5670 --name dbgpt eosphorosai/dbgpt-openai
```
Or with AI/ML API:
```bash
docker run -it --rm -e AIMLAPI_API_KEY=${AIMLAPI_API_KEY} \
-p 5670:5670 --name dbgpt eosphorosai/dbgpt-openai
```
Please replace `${SILICONFLOW_API_KEY}` or `${AIMLAPI_API_KEY}` with your own API key.
Then you can visit [http://localhost:5670](http://localhost:5670) in the browser.
## Deploy With GPU (Local Model)
In this deployment, you need an GPU environment.
Before running the Docker container, you need to install the NVIDIA Container Toolkit. For more information, please refer to the official documentation [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html).
In this deployment, you will use a local model instead of downloading it from the Hugging Face or ModelScope model hub. This is useful if you have already downloaded the model to your local machine or if you want to use a model from a different source.
### Step 1: Download the Model
Before running the Docker container, you need to download the model to your local machine. You can use either Hugging Face or ModelScope (recommended for users in China) to download the model.
1. Install `git` and `git-lfs` if you haven't already:
```bash
sudo apt-get install git git-lfs
```
2. Create a `models` directory in your current working directory:
```bash
mkdir -p ./models
```
3. Use `git` to clone the model repositories into the `models` directory:
```bash
cd ./models
git lfs install
git clone https://www.modelscope.cn/Qwen/Qwen2.5-Coder-0.5B-Instruct.git
git clone https://www.modelscope.cn/BAAI/bge-large-zh-v1.5.git
cd ..
```
This will download the models into the `./models/Qwen2.5-Coder-0.5B-Instruct` and `./models/bge-large-zh-v1.5` directories.
1. Install `git` and `git-lfs` if you haven't already:
```bash
sudo apt-get install git git-lfs
```
2. Create a `models` directory in your current working directory:
```bash
mkdir -p ./models
```
3. Use `git` to clone the model repositories into the `models` directory:
```bash
cd ./models
git lfs install
git clone https://huggingface.co/Qwen/Qwen2.5-Coder-0.5B-Instruct
git clone https://huggingface.co/BAAI/bge-large-zh-v1.5
cd ..
```
This will download the models into the `./models/Qwen2.5-Coder-0.5B-Instruct` and `./models/bge-large-zh-v1.5` directories.
---
### Step 2: Prepare the Configuration File
Create a `toml` file named `dbgpt-local-gpu.toml` and add the following content:
```toml
[models]
[[models.llms]]
name = "Qwen2.5-Coder-0.5B-Instruct"
provider = "hf"
# Specify the model path in the local file system
path = "/app/models/Qwen2.5-Coder-0.5B-Instruct"
[[models.embeddings]]
name = "BAAI/bge-large-zh-v1.5"
provider = "hf"
# Specify the model path in the local file system
path = "/app/models/bge-large-zh-v1.5"
```
This configuration file specifies the local paths to the models inside the Docker container.
---
### Step 3: Run the Docker Container
Run the Docker container with the local `models` directory mounted:
```bash
docker run --ipc host --gpus all \
-it --rm \
-p 5670:5670 \
-v ./dbgpt-local-gpu.toml:/app/configs/dbgpt-local-gpu.toml \
-v ./models:/app/models \
--name dbgpt \
eosphorosai/dbgpt \
dbgpt start webserver --config /app/configs/dbgpt-local-gpu.toml
```
#### Explanation of the Command:
- `--ipc host`: Enables host IPC mode for better performance.
- `--gpus all`: Allows the container to use all available GPUs.
- `-v ./dbgpt-local-gpu.toml:/app/configs/dbgpt-local-gpu.toml`: Mounts the local configuration file into the container.
- `-v ./models:/app/models`: Mounts the local `models` directory into the container.
- `eosphorosai/dbgpt`: The Docker image to use.
- `dbgpt start webserver --config /app/configs/dbgpt-local-gpu.toml`: Starts the webserver with the specified configuration file.
---
### Step 4: Access the Application
Once the container is running, you can visit [http://localhost:5670](http://localhost:5670) in your browser to access the application.
---
### Step 5: Persist Data (Optional)
To ensure that your data is not lost when the container is stopped or removed, you can map the `pilot/data` and `pilot/message` directories to your local machine. These directories store application data and messages.
1. Create local directories for data persistence:
```bash
mkdir -p ./pilot/data
mkdir -p ./pilot/message
mkdir -p ./pilot/alembic_versions
```
2. Modify the `dbgpt-local-gpu.toml` configuration file to point to the correct paths:
```toml
[service.web.database]
type = "sqlite"
path = "/app/pilot/message/dbgpt.db"
```
3. Run the Docker container with the additional volume mounts:
```bash
docker run --ipc host --gpus all \
-it --rm \
-p 5670:5670 \
-v ./dbgpt-local-gpu.toml:/app/configs/dbgpt-local-gpu.toml \
-v ./models:/app/models \
-v ./pilot/data:/app/pilot/data \
-v ./pilot/message:/app/pilot/message \
-v ./pilot/alembic_versions:/app/pilot/meta_data/alembic/versions \
--name dbgpt \
eosphorosai/dbgpt \
dbgpt start webserver --config /app/configs/dbgpt-local-gpu.toml
```
This ensures that the `pilot/data` and `pilot/message` directories are persisted on your local machine.
---
### Summary of Directory Structure
After completing the steps, your directory structure should look like this:
```
.
├── dbgpt-local-gpu.toml
├── models
│ ├── Qwen2.5-Coder-0.5B-Instruct
│ └── bge-large-zh-v1.5
├── pilot
│ ├── data
│ └── message
```
This setup ensures that the models and application data are stored locally and mounted into the Docker container, allowing you to use them without losing data.
```
---
--- METRICS ---
- Files Extracted: 101
- Estimated Token Budget: ~126782 tokens
- Canonical Reference: https://codewiki.google/github.com/eosphoros-ai/DB-GPT
