# Understanding dbgpt-core, dbgpt-app, and dbgpt-serve Packages in DB-GPT

> Discover the roles of dbgpt-core, dbgpt-app, and dbgpt-serve in DB-GPT. Learn how core provides SDKs, app builds the UI, and serve powers the runtime for models and RAG.

- Repository: [eosphoros/DB-GPT](https://github.com/eosphoros-ai/db-gpt)
- Tags: deep-dive
- Published: 2026-02-23

---

**dbgpt-core provides the foundational SDK and utilities, dbgpt-app implements the user-facing FastAPI web interface, and dbgpt-serve delivers the headless runtime service layer for models, RAG, and conversations.**

The DB-GPT repository by eosphoros-ai organizes its functionality into three distinct Python packages: `dbgpt-core`, `dbgpt-app`, and `dbgpt-serve`. Understanding the architectural boundaries between these dbgpt-core, dbgpt-app, and dbgpt-serve packages is essential for extending the framework, deploying custom agents, or building headless AI services. Each package serves a specific role in the stack, from low-level utilities to high-level web interfaces.

## dbgpt-core: The Foundation SDK

The `dbgpt-core` package acts as the **engine** of the DB-GPT ecosystem. It provides reusable SDK components, data model definitions, and low-level services that other packages consume.

### Core Responsibilities

This package implements the **public API surface** for the entire framework. Key classes like `BaseComponent`, `SystemApp`, and `Tracer` reside here, providing the dependency injection and observability infrastructure. The package also abstracts storage mechanisms, vector stores, datasource connectors, and RAG helpers through clean interfaces.

According to the source code in [`packages/dbgpt-core/src/dbgpt/__init__.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/__init__.py), the package uses **lazy loading** via `__getattr__` to ensure modules are loaded only when accessed, improving startup performance.

### Key Components and File Structure

- **[`packages/dbgpt-core/src/dbgpt/util/tracer/tracer_impl.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/util/tracer/tracer_impl.py)**: Central tracing implementation used throughout the stack for observability.
- **[`packages/dbgpt-core/src/dbgpt/storage/vector_store/base.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/storage/vector_store/base.py)**: Abstract `VectorStore` API that concrete implementations (Milvus, Chroma) extend.
- **`packages/dbgpt-core/src/dbgpt/rag/`**: RAG utilities and retriever implementations.
- **`packages/dbgpt-core/src/dbgpt/datasource/`**: Database connector abstractions.

### Code Example: Using the Tracer

The following example demonstrates how to use the tracing utility from `dbgpt-core`:

```python
from dbgpt.util.tracer import initialize_tracer, root_tracer, SpanType

# Initialize the tracer with a JSONL output file

initialize_tracer("trace.jsonl")

# Create a span for observability

with root_tracer.start_span("example_operation", span_type=SpanType.RUN):
    print("Executing traced operation in the core library")

```

## dbgpt-app: The User-Facing Web Interface

The `dbgpt-app` package implements the **frontend** of DB-GPT—a FastAPI-based web server that hosts the chat UI, knowledge-base management interfaces, and configuration loading.

### Application Responsibilities

This package is responsible for **bootstrapping the FastAPI application**, mounting static UI assets, and registering routers from both the app itself and the `dbgpt-serve` package. It handles user-facing concerns such as chat scenes, knowledge-base APIs, and configuration file parsing (TOML).

The entry point `python -m dbgpt_app.dbgpt_server` invokes the `run_webserver()` function, which orchestrates the entire startup sequence.

### Server Architecture and Entry Points

Key files in `dbgpt-app` include:

- **[`packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py)**: Contains `create_app()`, `initialize_app()`, and `run_webserver()` functions that bootstrap the FastAPI server and mount routers from `dbgpt-serve`.
- **[`packages/dbgpt-app/src/dbgpt_app/scene/chat_normal/chat.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-app/src/dbgpt_app/scene/chat_normal/chat.py)**: Example chat scene implementation that consumes core RAG utilities.
- **[`packages/dbgpt-app/src/dbgpt_app/knowledge/api.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-app/src/dbgpt_app/knowledge/api.py)**: Knowledge-base management endpoints (app-level).

The `mount_routers()` function in [`dbgpt_server.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/dbgpt_server.py) specifically integrates routers from the `dbgpt-serve` package, bridging the app and service layers.

### Code Example: Starting the Web Server

Start the DB-GPT UI from the command line:

```bash

# From the repository root

python -m dbgpt_app.dbgpt_server \
    --config configs/dbgpt-proxy-openai.toml

```

Programmatically start the server for testing or custom deployments:

```python
from dbgpt_app.dbgpt_server import initialize_app, load_config

# Load TOML configuration

cfg = load_config("configs/dbgpt-proxy-openai.toml")

# Initialize the FastAPI app with all routers and middleware

app = initialize_app(cfg)

# This mounts routers from both dbgpt_app and dbgpt_serve

```

## dbgpt-serve: The Runtime Service Layer

The `dbgpt-serve` package delivers the **backend runtime**—a headless service layer that hosts agents, conversation management, file handling, datasource connectors, and model-deployment utilities.

### Service Layer Responsibilities

Unlike `dbgpt-app`, which focuses on UI concerns, `dbgpt-serve` implements **reusable HTTP services** that can run independently or be mounted into other FastAPI applications. It manages:

- **Conversation services**: Chat history and session management
- **RAG services**: Retrieval and generation pipelines
- **Datasource services**: Database connection management (SQL, Redis, etc.)
- **File services**: Document upload and processing

This package is designed for operators who need to expose LLMs and RAG pipelines as HTTP services without the full web UI. It also provides `initialize_worker_manager_in_client()` for model-server orchestration in distributed deployments.

### Service Architecture and Base Classes

All services in `dbgpt-serve` inherit from a base class defined in:

- **[`packages/dbgpt-serve/src/dbgpt_serve/core/service.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/core/service.py)**: Provides the `Service` base class and exception handling patterns.

Key service implementations include:

- **[`packages/dbgpt-serve/src/dbgpt_serve/conversation/service/service.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/conversation/service/service.py)**: Conversation management APIs.
- **[`packages/dbgpt-serve/src/dbgpt_serve/rag/service/service.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/rag/service/service.py)**: RAG pipeline service used by both the app and external clients.
- **[`packages/dbgpt-serve/src/dbgpt_serve/datasource/service/service.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/datasource/service/service.py)**: Datasource connector management.

### Code Example: Running a Standalone RAG Service

Deploy the RAG service independently without the full web UI:

```python
from dbgpt_serve.rag.service import Service as RagService
from dbgpt.component import SystemApp
from fastapi import FastAPI

# Create FastAPI application

app = FastAPI()
system_app = SystemApp(app)

# Initialize and start the RAG service

rag_service = RagService(system_app)
rag_service.start()  # Registers RAG endpoints under /api/rag

# Run with: uvicorn main:app --host 0.0.0.0 --port 8000

```

This pattern allows operators to expose specific capabilities (RAG, conversation, datasource) as microservices while reusing the same core implementations.

## Package Comparison and Selection Guide

When deciding which package to use or modify, consider the following architectural boundaries:

| Aspect | dbgpt-core | dbgpt-app | dbgpt-serve |
|--------|------------|-----------|-------------|
| **Primary Role** | Foundation SDK and utilities | User-facing web interface | Headless service runtime |
| **Entry Point** | `import dbgpt` | `python -m dbgpt_app.dbgpt_server` | Mounted as routers or run standalone |
| **Key Classes** | `BaseComponent`, `SystemApp`, `Tracer` | `create_app()`, `run_webserver()` | `Service` (base class) |
| **Typical Use** | Building extensions, custom components | Running the full DB-GPT UI | Deploying specific APIs as services |
| **Depends On** | None (base layer) | dbgpt-core, dbgpt-serve | dbgpt-core |

**Selection Guidelines:**

- Use **dbgpt-core** when building custom plugins, extending vector stores, or implementing new datasource connectors that need to integrate with the DB-GPT ecosystem.
- Use **dbgpt-app** when deploying the complete web interface, customizing chat scenes, or modifying the FastAPI bootstrap logic and UI routing.
- Use **dbgpt-serve** when exposing specific capabilities (conversation management, RAG, datasource access) as standalone HTTP services or when building headless AI backends without UI concerns.

## Summary

The DB-GPT repository organizes functionality across three distinct packages to maintain clean architectural boundaries:

- **dbgpt-core** provides the foundational SDK, including `BaseComponent`, `SystemApp`, tracing utilities, and abstractions for storage, vector stores, and datasources. It uses lazy loading via `__getattr__` in [`packages/dbgpt-core/src/dbgpt/__init__.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/__init__.py) to optimize startup performance.

- **dbgpt-app** implements the user-facing FastAPI web server, handling UI routing, static assets, configuration loading, and chat scene management. The entry point in [`packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py) orchestrates startup via `run_webserver()` and mounts routers from `dbgpt-serve`.

- **dbgpt-serve** delivers the headless runtime service layer for conversation management, RAG pipelines, file handling, and datasource connectors. Services inherit from the base class in [`packages/dbgpt-serve/src/dbgpt_serve/core/service.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/core/service.py) and can run standalone or mount into other FastAPI applications.

Understanding these boundaries enables developers to extend DB-GPT efficiently—whether building new components against the core SDK, customizing the web interface, or deploying headless AI services.

## Frequently Asked Questions

### What is the relationship between dbgpt-app and dbgpt-serve?

The `dbgpt-app` package depends on `dbgpt-serve` and mounts its routers during initialization. While `dbgpt-serve` provides headless REST APIs for conversations, RAG, and datasources, `dbgpt-app` adds the web UI, static assets, and application-specific routing. In [`packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py), the `mount_routers()` function specifically integrates `dbgpt-serve` endpoints into the main FastAPI application.

### Can I use dbgpt-serve without dbgpt-app?

Yes. The `dbgpt-serve` package is designed to run independently as a headless service. You can instantiate specific services like `RagService` from [`packages/dbgpt-serve/src/dbgpt_serve/rag/service/service.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/rag/service/service.py) or `ConvService` from [`packages/dbgpt-serve/src/dbgpt_serve/conversation/service/service.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-serve/src/dbgpt_serve/conversation/service/service.py) and mount them into a standalone FastAPI application without importing any UI components from `dbgpt-app`.

### What are the main classes in dbgpt-core that other packages depend on?

The most critical classes in `dbgpt-core` include `BaseComponent` and `SystemApp` for dependency injection and lifecycle management, and `Tracer` for observability. These are defined in the core package and imported by both `dbgpt-app` and `dbgpt-serve`. The lazy loading mechanism in [`packages/dbgpt-core/src/dbgpt/__init__.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/__init__.py) ensures these classes are available via `import dbgpt` without loading unnecessary submodules.

### How do I start the DB-GPT web server?

To start the complete DB-GPT web interface, use the entry point provided by `dbgpt-app`:

```bash
python -m dbgpt_app.dbgpt_server --config configs/dbgpt-proxy-openai.toml

```

This command invokes `run_webserver()` from [`packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py), which initializes the FastAPI application, mounts routers from `dbgpt-serve`, loads the TOML configuration, and starts the Uvicorn server.