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

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, 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: Central tracing implementation used throughout the stack for observability.
• 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:

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: 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: Example chat scene implementation that consumes core RAG utilities.
• packages/dbgpt-app/src/dbgpt_app/knowledge/api.py: Knowledge-base management endpoints (app-level).

The mount_routers() function in 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:

# 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:

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: Provides the Service base class and exception handling patterns.

Key service implementations include:

• packages/dbgpt-serve/src/dbgpt_serve/conversation/service/service.py: Conversation management APIs.
• 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: Datasource connector management.

Code Example: Running a Standalone RAG Service

Deploy the RAG service independently without the full web UI:

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 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 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 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, 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 or ConvService from 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 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:

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, which initializes the FastAPI application, mounts routers from dbgpt-serve, loads the TOML configuration, and starts the Uvicorn server.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}