This page documents the process of installing DB-GPT from source code. It covers environment preparation, dependency installation using the uv package manager, configuration management, and launching the web server. Source code installation provides maximum flexibility and access to all features, including local model deployment, proxy model integration, and RAG capabilities.
For containerized deployment options, see Docker Compose Deployment. For configuration details after installation, see Configuration Management.
DB-GPT uses a monorepo structure managed by the uv package manager (introduced in v0.7.0). The installation process varies depending on the deployment mode:
The installation involves:
uv package managerThe resource requirements depend on the chosen deployment mode:
| Deployment Mode | CPU | Memory | GPU | Notes |
|---|---|---|---|---|
| Proxy Model | 4 cores | 8 GB | None | API-based models, no GPU required |
| Local Model | 8 cores | 32 GB | 24 GB | Local inference requires GPU (24GB+ recommended) |
| Development | 4 cores | 16 GB | Optional | For development and testing |
Software Requirements:
curl or pipx (for installing uv)Sources: docs/docs/installation/sourcecode.md3-9 README.md139-143
Installation Flow Diagram
The diagram shows the key decision points and steps in the installation process, from repository cloning to server verification.
Sources: docs/docs/installation/sourcecode.md11-212 docs/docs/quickstart.md13-95
Clone the DB-GPT repository from GitHub:
The repository structure follows a monorepo pattern managed by the workspace configuration in pyproject.toml31-40:
Monorepo Structure
The workspace is defined in pyproject.toml31-40 with seven member packages:
packages/dbgpt-core: Core framework (published as dbgpt on PyPI) - AWEL engine, model interfaces, RAG abstractions packages/dbgpt-core/pyproject.toml1-205packages/dbgpt-app: Main application server with web interface packages/dbgpt-app/pyproject.toml1-65packages/dbgpt-serve: Service layer for RAG, evaluation, and storage management packages/dbgpt-serve/pyproject.toml1-44packages/dbgpt-ext: Extensions for vector stores, knowledge graphs, and data sources packages/dbgpt-ext/pyproject.toml1-106packages/dbgpt-client: Client SDK for API access packages/dbgpt-client/pyproject.toml1-47packages/dbgpt-accelerator/dbgpt-acc-auto: Hardware acceleration dependencies (CUDA, quantization) packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml1-197packages/dbgpt-accelerator/dbgpt-acc-flash-attn: Flash Attention integration packages/dbgpt-accelerator/dbgpt-acc-flash-attn/pyproject.toml1-33packages/dbgpt-sandbox: Code execution sandbox pyproject.toml31-40All packages are versioned at 0.7.5 as seen in packages/dbgpt-core/src/dbgpt/_version.py1 packages/dbgpt-app/src/dbgpt_app/_version.py1 etc.
Sources: pyproject.toml31-40 packages/dbgpt-core/pyproject.toml1-205 packages/dbgpt-app/pyproject.toml1-65 packages/dbgpt-ext/pyproject.toml1-106 packages/dbgpt-serve/pyproject.toml1-44 packages/dbgpt-client/pyproject.toml1-47 packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml1-197
DB-GPT uses uv for fast and reliable dependency management. Install uv using one of the following methods:
See the uv installation documentation for additional installation methods including Windows, Homebrew, and package managers.
Verify Installation:
Expected output: uv 0.x.x or higher.
China Region Mirror (Optional):
For users in China, configure a PyPI mirror to improve download speeds:
Sources: docs/docs/installation/sourcecode.md22-65 docs/docs/quickstart.md31-74
Dependencies are installed using uv sync with package-specific --extra flags. The flags determine which optional dependencies are included based on your deployment needs.
The available installation extras are defined across multiple pyproject.toml files in the monorepo. The following diagram maps extras to their source packages:
Package Extras and Dependencies
This diagram shows the available --extra flags mapped to their defining packages and key dependencies. Extras are defined in:
Sources: packages/dbgpt-core/pyproject.toml34-163 packages/dbgpt-ext/pyproject.toml27-89 packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml26-104 packages/dbgpt-app/pyproject.toml32-48
For proxy-based deployment using OpenAI-compatible APIs:
Extras Explained:
base: Aggregates simple_framework (SQLAlchemy, Jinja2, DuckDB) and framework (alembic, openpyxl, GitPython) from packages/dbgpt-core/pyproject.toml56-101proxy_openai: OpenAI SDK (>=1.59.6) and tiktoken tokenizer from packages/dbgpt-core/pyproject.toml132-136rag: Document parsers (spacy, pypdf, pdfplumber) from packages/dbgpt-ext/pyproject.toml28-37storage_chromadb: ChromaDB (>=0.4.22) and onnxruntime from packages/dbgpt-ext/pyproject.toml76-79dbgpts: Build tools for custom applications from packages/dbgpt-app/pyproject.toml44-48This mode does not require GPU resources and connects to external API providers.
Sources: packages/dbgpt-core/pyproject.toml56-101 packages/dbgpt-core/pyproject.toml132-136 packages/dbgpt-ext/pyproject.toml28-37 packages/dbgpt-ext/pyproject.toml76-79 packages/dbgpt-app/pyproject.toml44-48
For local model deployment using HuggingFace Transformers with GPU:
Extras Explained:
cuda121: PyTorch with CUDA 12.1 from pytorch-cu121 index packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml51-55hf: HuggingFace Transformers (>=4.46.0), sentencepiece, sentence-transformers packages/dbgpt-core/pyproject.toml102-106quant_bnb: BitsAndBytes (>=0.39.0) for 4-bit/8-bit quantization with accelerate packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml78-81Alternative CUDA Versions:
--extra "cuda118": CUDA 11.8 from pytorch-cu118 index packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml46-50--extra "cuda124": CUDA 12.4 from pytorch-cu124 index packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml57-61--extra "cpu": CPU-only PyTorch (auto platform detection) packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml37-45The CUDA extras configure torch installation via custom PyPI indexes defined in packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml125-143 with platform-specific markers in packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml151-189
Sources: packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml26-104 packages/dbgpt-core/pyproject.toml102-106 packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml125-189
For high-performance inference using vLLM:
vLLM provides optimized inference with features like continuous batching and PagedAttention. The vllm extra is defined in packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml67-70 and requires vLLM >=0.7.0 on Linux systems only. It requires a GPU with sufficient VRAM (16GB+ recommended).
Sources: packages/dbgpt-accelerator/dbgpt-acc-auto/pyproject.toml67-70 docs/docs/quickstart.md254-267
For DeepSeek API with local embedding models:
This configuration uses DeepSeek's API for LLM calls but runs embedding models locally (e.g., BAAI/bge-large-zh-v1.5).
Sources: docs/docs/installation/sourcecode.md119-176 docs/docs/quickstart.md150-176
DB-GPT uses TOML configuration files located in the configs/ directory. Each configuration file defines:
Configuration Structure Diagram
Sources: docs/docs/installation/sourcecode.md92-104 docs/docs/quickstart.md124-143
File: configs/dbgpt-proxy-openai.toml
Key Configuration Parameters:
name: Model identifier from the providerprovider: Format is "proxy/{provider_name}" for proxy modelsapi_key: API authentication key (can also be set via environment variable OPENAI_API_KEY)Sources: docs/docs/installation/sourcecode.md94-104
File: configs/dbgpt-local-glm.toml
Key Configuration Parameters:
provider: "hf" for HuggingFace models, "vllm" for vLLM inferencepath: Optional local filesystem path (if omitted, downloads from HuggingFace Hub)name: Model identifier on HuggingFace HubIf the path parameter is not provided, models are automatically downloaded to the HuggingFace cache directory (typically ~/.cache/huggingface/hub/).
Sources: docs/docs/installation/sourcecode.md184-202 docs/docs/quickstart.md226-244
File: configs/dbgpt-proxy-deepseek.toml
This configuration uses DeepSeek's R1 reasoning model via API while running embeddings locally. The path parameter points to a pre-downloaded model to avoid repeated downloads.
Sources: docs/docs/installation/sourcecode.md135-152
RAG storage backends are configured in the [rag.storage] section:
Supported Vector Stores:
chroma: Default, file-based vector storeMilvus: Distributed vector databaseoceanbase: OceanBase vector extensionpgvector: PostgreSQL with pgvector extensionTo use alternative storage backends, install the corresponding extra (e.g., --extra "storage_milvus").
Sources: docs/docs/installation/integrations/oceanbase_rag_install.md26-37 docs/docs/installation/integrations/milvus_rag_install.md26-37
The webserver is the main entry point for DB-GPT. It initializes the AWEL engine, loads models, and starts the FastAPI application.
Command Syntax:
Examples:
Alternative Command (direct Python execution):
The dbgpt CLI command is a wrapper that invokes the dbgpt_server.py script.
Sources: docs/docs/installation/sourcecode.md106-116 docs/docs/quickstart.md139-147
Server Startup Sequence Diagram
The diagram shows the initialization flow through actual code components. The entry point is defined in packages/dbgpt-core/pyproject.toml204-205 as the dbgpt CLI command, which invokes packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py1 The TOML configuration sections [models], [rag.storage], and [server] are parsed to initialize the Model Manager (SMMF) and AWEL DAG engine before starting the FastAPI application via uvicorn.
Sources: packages/dbgpt-core/pyproject.toml204-205 packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py1 docs/docs/quickstart.md139-147
During startup, the server outputs logs indicating initialization progress:
INFO: Loading configuration from configs/dbgpt-proxy-openai.toml
INFO: Initializing model manager
INFO: Loading LLM: gpt-4o-mini (provider: proxy/openai)
INFO: Loading embeddings: text-embedding-3-small (provider: proxy/openai)
INFO: Initializing AWEL engine
INFO: Registering workflow operators
INFO: Starting FastAPI application
INFO: Uvicorn running on http://0.0.0.0:5670
Common Startup Issues:
API key not found: Ensure API keys are set in configuration or environment variablesModel download failed: Check network connectivity or specify local model pathsPort already in use: Another service is using port 5670; stop it or change the port in configurationSources: docs/docs/installation/sourcecode.md106-116
Open a web browser and navigate to:
http://localhost:5670
The DB-GPT web interface should load, displaying:
Verify the API is responding:
Expected response:
For development purposes, you can run the Next.js frontend independently:
The frontend will be available at http://localhost:3000 and will proxy API requests to the backend at port 5670.
Sources: docs/docs/installation/sourcecode.md214-235
The following table summarizes the key differences between deployment modes:
| Aspect | Proxy Mode | Local Model (HF) | Local Model (vLLM) |
|---|---|---|---|
| GPU Required | No | Yes (8GB+) | Yes (16GB+) |
| Latency | Network-dependent | Local inference | Optimized local |
| Throughput | API rate-limited | Single request | Batched requests |
| Model Selection | Provider's models | Any HF model | Compatible models |
| Cost | Per-token API fees | Hardware + electricity | Hardware + electricity |
| Configuration | API key | Model path or name | Model path or name |
| Use Case | Quick prototyping | Full control | Production inference |
Installation Extras:
--extra "proxy_openai"--extra "hf" --extra "cuda121"--extra "vllm" --extra "cuda121"Sources: docs/docs/installation/sourcecode.md3-9 docs/docs/quickstart.md6-11
Issue: uv: command not found
uv is installed and in PATH. Run source ~/.bashrc or restart the terminal.Issue: Dependency conflicts during uv sync
--all-packages flag and ensure Python version is 3.10+uv sync --all-packages --no-cacheIssue: Model download fails (HuggingFace)
HF_ENDPOINT environment variablepath in configIssue: CUDA out of memory
--extra "quant_bnb")nvidia-smiIssue: Port 5670 already in use
[server] port = 5671lsof -i :5670Issue: API key errors (proxy mode)
export OPENAI_API_KEY="sk-..."Sources: docs/docs/installation/sourcecode.md1-235
After successful installation:
Key Files Reference:
configs/packages/dbgpt-core/, packages/dbgpt-app/, etc.Refresh this wiki