# Understanding the Model Adapter Pattern in DB-GPT: How to Add a New LLM Provider

> Learn the DB-GPT model adapter pattern to easily add new LLM providers. Explore how to integrate custom LLMs by subclassing LLMModelAdapter and registering your implementation.

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

---

**The model adapter pattern in DB-GPT treats every LLM as a plug-in that implements the `LLMModelAdapter` abstract base class, enabling automatic discovery via the `get_model_adapter()` factory. To add a new provider, subclass `LLMModelAdapter` in `packages/dbgpt-core/src/dbgpt/model/adapter/`, implement the required interface methods (`match()`, `model_param_class()`, `load()`, `get_generate_function()`), and register it using `register_model_adapter()`.**

The DB-GPT project (eosphoros-ai/DB-GPT) decouples language model implementations from the core framework through a flexible **model adapter pattern** in `dbgpt-core`. This architecture allows you to integrate proprietary APIs, local inference servers, or custom endpoints without modifying the underlying agent or chat logic.

## What Is the Model Adapter Pattern in DB-GPT?

The pattern centers on three core components defined in [`packages/dbgpt-core/src/dbgpt/model/adapter/base.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/model/adapter/base.py):

**`LLMModelAdapter`** (lines 21-49): The abstract base class that defines the contract every provider must implement. It specifies methods for matching logic, parameter parsing, model loading, and text generation.

**`register_model_adapter()`** (lines 51-68): A helper function that adds concrete adapter instances to the global `model_adapters` registry. This registry holds `AdapterEntry` objects that map provider strings to implementations.

**`get_model_adapter()`** (lines 70-112): The factory function that iterates the registry and returns the first adapter whose `match()` method returns `True` for the requested provider, model name, or path.

This design enables DB-GPT to **discover** adapters automatically from configuration strings like `openai`, `vllm`, or `hf`, and **swap** implementations without touching downstream components.

## How to Add a New LLM Provider to DB-GPT

To integrate a custom LLM service (referred to here as `myprovider`), you must implement four critical interface methods and register the class.

### Step 1: Create a Concrete Adapter Class

Create a new Python file in [`packages/dbgpt-core/src/dbgpt/model/adapter/myprovider_adapter.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/model/adapter/myprovider_adapter.py). Define a parameter dataclass and an adapter subclass:

```python
from typing import Optional
from dbgpt.core.interface.parameter import LLMDeployModelParameters
from dbgpt.model.adapter.base import LLMModelAdapter, register_model_adapter

class MyProviderDeployParams(LLMDeployModelParameters):
    """Deployment configuration for MyProvider."""
    provider: str = "myprovider"
    api_key: str = ""
    endpoint: str = "https://api.myprovider.com/v1"

class MyProviderAdapter(LLMModelAdapter):
    """Adapter for MyProvider LLM API."""
    
    def match(
        self,
        provider: str,
        model_name: Optional[str] = None,
        model_path: Optional[str] = None,
    ) -> bool:
        """Return True when this adapter should handle the request."""
        return provider.lower() == "myprovider"
    
    def model_param_class(self, model_type: str = None) -> type[LLMDeployModelParameters]:
        """Return the parameter dataclass for this provider."""
        return MyProviderDeployParams
    
    def load(self, model_path: str, from_pretrained_kwargs: dict):
        """Instantiate the client. Returns (model, tokenizer)."""
        from myprovider.sdk import MyProviderClient
        
        api_key = from_pretrained_kwargs.get("api_key")
        client = MyProviderClient(api_key=api_key, endpoint=model_path)
        return client, None  # No tokenizer needed for API-only services

    
    def get_generate_function(self, model, deploy_model_params: LLMDeployModelParameters):
        """Return a callable that executes generation."""
        def _generate(prompt: str, **kwargs):
            return model.chat(prompt, **kwargs)
        return _generate

```

Key implementation details:

- **`match()`**: Must return `True` for your provider string (e.g., `"myprovider"`). The factory calls this for every registered adapter until it finds a match.
- **`model_param_class()`**: Supplies the dataclass that DB-GPT uses to parse deployment configurations from YAML or environment variables.
- **`load()`**: Returns a tuple of `(model_instance, tokenizer)`. For remote APIs, return the client handle and `None`.
- **`get_generate_function()`**: Provides the inference callable. For streaming support, implement `get_generate_stream_function()` instead.

### Step 2: Register the Adapter

At the bottom of your adapter file, invoke the registration helper:

```python
register_model_adapter(MyProviderAdapter)

```

Optionally, pass a `supported_models` list containing `ModelMetadata` objects if you want the adapter to advertise specific model IDs.

### Step 3: Ensure Module Discovery

Add the module to the package imports so DB-GPT loads it at runtime. Edit [`packages/dbgpt-core/src/dbgpt/model/adapter/__init__.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/model/adapter/__init__.py):

```python
from .myprovider_adapter import *  # noqa: F401,F403

```

### Step 4: Verify the Registration

Test that the factory correctly resolves your adapter:

```python
from dbgpt.model.adapter.base import get_model_adapter

adapter = get_model_adapter(provider="myprovider", model_name="gpt-large")
print(type(adapter))  # <class 'myprovider_adapter.MyProviderAdapter'>

```

If the factory returns your class, the integration is active.

## Complete Integration Example

The following script demonstrates the entire lifecycle: configuration, adapter retrieval, model loading, and generation:

```python
from dbgpt.model.adapter.myprovider_adapter import MyProviderDeployParams
from dbgpt.model.adapter.base import get_model_adapter

# 1. Define deployment parameters

params = MyProviderDeployParams(
    provider="myprovider",
    model_name="mygpt-large",
    api_key="sk-...",
    endpoint="https://api.myprovider.com/v1"
)

# 2. Retrieve adapter via factory

adapter = get_model_adapter(provider=params.provider, model_name=params.model_name)

# 3. Load the remote client

model, _ = adapter.load(
    model_path=params.endpoint,
    from_pretrained_kwargs=params.to_dict()
)

# 4. Execute generation

generate = adapter.get_generate_function(model, params)
response = generate("Explain the model adapter pattern in DB-GPT.")
print(response)

```

## Key Source Files for Reference

To understand the pattern's implementation or troubleshoot issues, examine these files in the eosphoros-ai/DB-GPT repository:

- [`packages/dbgpt-core/src/dbgpt/model/adapter/base.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/model/adapter/base.py) – Core abstract class (`LLMModelAdapter`), registration logic (lines 51-68), and factory implementation (`get_model_adapter`, lines 70-112).
- [`packages/dbgpt-core/src/dbgpt/model/adapter/hf_adapter.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/model/adapter/hf_adapter.py) – Reference implementation for HuggingFace models showing `NewHFChatModelAdapter`.
- [`packages/dbgpt-core/src/dbgpt/model/adapter/vllm_adapter.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/model/adapter/vllm_adapter.py) – Example of integrating a local inference server.
- [`packages/dbgpt-core/src/dbgpt/model/adapter/model_metadata.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/model/adapter/model_metadata.py) – Definitions for `ModelMetadata` used in optional `supported_models` registration.

## Summary

- The **model adapter pattern** in `dbgpt-core` abstracts LLM interactions through the `LLMModelAdapter` interface, enabling provider-agnostic architecture.
- **Registration** occurs via `register_model_adapter()`, which populates the global registry inspected by `get_model_adapter()`.
- To **add a new LLM provider**, subclass `LLMModelAdapter`, implement `match()`, `model_param_class()`, `load()`, and generation methods, then register the class and ensure it is imported.
- The factory automatically selects your adapter when the provider string matches, requiring no changes to DB-GPT's core logic, CLI, or UI components.

## Frequently Asked Questions

### What is the model adapter pattern in DB-GPT?

The model adapter pattern is a plug-in architecture in `dbgpt-core` that treats every language model as an interchangeable component implementing the `LLMModelAdapter` abstract base class. It consists of a global registry (`model_adapters`), a registration helper (`register_model_adapter`), and a factory (`get_model_adapter`) that discovers the correct implementation based on provider strings. This allows DB-GPT to support diverse backends—from OpenAI APIs to local vLLM servers—through a unified interface defined in [`packages/dbgpt-core/src/dbgpt/model/adapter/base.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/model/adapter/base.py).

### How do I register a custom LLM provider in dbgpt-core?

To register a custom provider, create a concrete subclass of `LLMModelAdapter` in `packages/dbgpt-core/src/dbgpt/model/adapter/`, then call `register_model_adapter(YourAdapterClass)` at the module level. Ensure the module is imported by adding it to [`packages/dbgpt-core/src/dbgpt/model/adapter/__init__.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/model/adapter/__init__.py). Once registered, the `get_model_adapter()` factory will automatically instantiate your class when the configuration specifies your provider string.

### What methods must I implement when adding a new model adapter?

You must implement four critical methods: `match()` to identify when your adapter should handle a request (typically by checking the provider string); `model_param_class()` to return the dataclass defining your provider's configuration parameters; `load()` to instantiate the model client and return it with an optional tokenizer; and `get_generate_function()` (or `get_generate_stream_function()` for streaming) to return a callable that executes the actual inference against your LLM.

### Where should I place my custom adapter code in the DB-GPT repository?

Place your adapter implementation in a new file within `packages/dbgpt-core/src/dbgpt/model/adapter/`, such as [`myprovider_adapter.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/myprovider_adapter.py). Update [`packages/dbgpt-core/src/dbgpt/model/adapter/__init__.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/model/adapter/__init__.py) to import the new module so the registration code executes at startup. For reference implementations, examine [`hf_adapter.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/hf_adapter.py) or [`vllm_adapter.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/vllm_adapter.py) in the same directory.