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

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:

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. Define a parameter dataclass and an adapter subclass:

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:

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:

from .myprovider_adapter import *  # noqa: F401,F403

Step 4: Verify the Registration

Test that the factory correctly resolves your adapter:

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:

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 – 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 – Reference implementation for HuggingFace models showing NewHFChatModelAdapter.
• 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 – 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.

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. 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. Update 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 or vllm_adapter.py in the same directory.

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