Embedding Models in DB-GPT: Supported Providers and Configuration Guide

DB-GPT supports 10+ embedding providers—including HuggingFace, OpenAI, Azure, Tongyi, SiliconFlow, Baidu Qianfan, Ollama, and Jina AI—through a pluggable architecture centered on EmbeddingFactory and register_embedding_adapter, configurable via TOML files or the Python SDK.

DB-GPT is an open-source LLM agent framework designed for database interaction that ships with a modular embedding subsystem. The framework allows you to switch between local sentence-transformers models and remote API-based embeddings without modifying application code. This guide covers the complete catalog of embedding models supported in DB-GPT and their configuration via the TOML configuration system or programmatically through the SDK.

Architecture of the Embedding Layer

DB-GPT implements a factory-based embedding architecture that decouples model implementation from configuration. The core components reside in the dbgpt-core package and work together to provide runtime model discovery.

EmbeddingFactory serves as the central registry and instantiation mechanism. Located in packages/dbgpt-core/src/dbgpt/rag/embedding/embedding_factory.py, this class maintains a lookup table that maps model names to concrete implementation classes. At runtime, the factory reads EmbeddingModelMetadata entries to build the model_name → class mapping.

Concrete embedding implementations register themselves using the register_embedding_adapter decorator defined in packages/dbgpt-core/src/dbgpt/model/adapter/base.py. This decorator accepts a list of EmbeddingModelMetadata objects (defined in packages/dbgpt-core/src/dbgpt/core/interface/embeddings.py) that specify the model name, dimension, context length, and description.

When DB-GPT starts, the factory scans all registered adapters and constructs the embedding backend based on the [[models.embeddings]] section of your active *.toml configuration file.

Supported Embedding Models in DB-GPT

The following providers are available out-of-the-box, each implemented as a specific Python class and registered with canonical model identifiers:

HuggingFace (sentence-transformers)

• Class: HuggingFaceEmbeddings in packages/dbgpt-core/src/dbgpt/rag/embedding/embeddings.py
• Models: thenlper/gte-large-zh, thenlper/gte-large, moka-ai/m3e-base, moka-ai/m3e-large

HuggingFace Instruct

• Class: HuggingFaceInstructEmbeddings in packages/dbgpt-core/src/dbgpt/rag/embedding/embeddings.py
• Models: hkunlp/instructor-large, hkunlp/instructor-base

HuggingFace BGE

• Class: HuggingFaceBgeEmbeddings in packages/dbgpt-core/src/dbgpt/rag/embedding/embeddings.py
• Models: BAAI/bge-m3, BAAI/bge-large-zh-v1.5, BAAI/bge-large-en-v1.5

OpenAI / Azure OpenAI

• Class: OpenAPIEmbeddings in packages/dbgpt-core/src/dbgpt/rag/embedding/embeddings.py
• Models: text-embedding-3-small (1536 or 3072 dimensions)

Alibaba Tongyi (DashScope)

• Class: TongYiEmbeddings in packages/dbgpt-ext/src/dbgpt_ext/rag/embeddings/tongyi.py
• Models: text-embedding-v3

SiliconFlow

• Class: SiliconFlowEmbeddings in packages/dbgpt-ext/src/dbgpt_ext/rag/embeddings/siliconflow.py
• Models: BAAI/bge-m3, BAAI/bge-large-zh-v1.5, BAAI/bge-large-en-v1.5

Baidu Qianfan

• Class: QianFanEmbeddings in packages/dbgpt-ext/src/dbgpt_ext/rag/embeddings/qianfan.py
• Models: embedding-v1

Ollama (Local)

• Class: OllamaEmbeddings in packages/dbgpt-ext/src/dbgpt_ext/rag/embeddings/ollama.py
• Models: Any embedding model served by your local Ollama instance (e.g., BAAI/bge-m3)

Jina AI

• Class: JinaEmbeddings in packages/dbgpt-ext/src/dbgpt_ext/rag/embeddings/jina.py
• Models: jinaai/jina-embeddings-v3

Auto-registered HuggingFace Models Additional models are automatically registered via metadata definitions in packages/dbgpt-core/src/dbgpt/model/adapter/embed_metadata.py, including:

• Qwen: Qwen/Qwen3-Embedding-0.6B, Qwen/Qwen3-Embedding-4B, Qwen/Qwen3-Embedding-8B
• Jina: jinaai/jina-embeddings-v3

How to Configure Embedding Models in DB-GPT

TOML Configuration

DB-GPT uses TOML configuration files (located in the configs/ directory) to select embedding providers. The embedding configuration resides in the [[models.embeddings]] array:

[[models.embeddings]]
name = "text-embedding-3-small"
api_url = "https://api.openai.com/v1/embeddings"
api_key = "${env:OPENAI_API_KEY}"

• name: Must match a canonical model identifier from the supported catalog.
• api_url: Optional override for the provider's endpoint. Required for Azure OpenAI or custom endpoints; omit for local HuggingFace models.
• api_key: Use the ${env:VARIABLE_NAME} syntax to reference environment variables and avoid committing secrets to version control.

To switch to a local HuggingFace model, modify the block to:

[[models.embeddings]]
name = "BAAI/bge-m3"

# No api_url or api_key required for local inference

Programmatic Configuration (Python SDK)

You can instantiate embeddings directly in Python without modifying TOML files by using the EmbeddingFactory:

from dbgpt.rag.embedding import EmbeddingFactory

# Create an embedding instance by model name

factory = EmbeddingFactory.get_instance()
embeddings = factory.create(model_name="BAAI/bge-m3")

# Generate embeddings

documents = ["DB-GPT supports multiple embedding providers.", "Configuration is flexible."]
document_vectors = embeddings.embed_documents(documents)
query_vector = embeddings.embed_query("How do I configure embeddings?")

The factory consults the same runtime registry used by the TOML parser, ensuring consistent behavior across configuration methods.

Adding Custom Models

To integrate a model not listed in the default catalog:

1. Create a subclass of Embeddings implementing embed_documents() and embed_query().
2. Register it using register_embedding_adapter(MyCustomEmbeddings, supported_models=[EmbeddingModelMetadata(...)]).
3. Import the module at runtime to trigger registration.
4. Reference the custom name in your TOML configuration or EmbeddingFactory.create() call.

Practical Code Examples

Example 1: Configure Local BGE Model via TOML

Edit configs/dbgpt-proxy-openai.toml (or create a custom config):

[[models.embeddings]]
name = "BAAI/bge-large-en-v1.5"

No additional parameters are required; DB-GPT downloads and caches the model locally using the HuggingFace sentence-transformers library.

Example 2: Use Jina AI Embeddings Programmatically

from dbgpt.rag.embedding import EmbeddingFactory

# Initialize Jina embeddings

emb = EmbeddingFactory.get_instance().create(
    model_name="jinaai/jina-embeddings-v3"
)

# Embed a batch of texts

texts = [
    "DB-GPT provides unified embedding abstractions.",
    "Vector search powers RAG applications."
]
vectors = emb.embed_documents(texts)
print(f"Embedding dimension: {len(vectors[0])}")

Example 3: Environment-Based API Key Configuration

[[models.embeddings]]
name = "text-embedding-v3"
api_url = "https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding"
api_key = "${env:DASHSCOPE_API_KEY}"

DB-GPT resolves the ${env:DASHSCOPE_API_KEY} placeholder at startup, keeping credentials out of configuration files.

Summary

• DB-GPT supports 10+ embedding providers ranging from local HuggingFace models (BAAI/bge-m3, thenlper/gte-large) to cloud APIs (OpenAI, Azure, Tongyi, Jina AI).
• Configuration is provider-agnostic through the [[models.embeddings]] TOML block or the EmbeddingFactory Python SDK.
• File locations: Core logic resides in packages/dbgpt-core/src/dbgpt/rag/embedding/embedding_factory.py and embeddings.py, while extended providers live in packages/dbgpt-ext/src/dbgpt_ext/rag/embeddings/.
• Security best practice: Use ${env:VARIABLE} syntax in TOML files to inject API keys from environment variables.
• Extensibility: New providers integrate via the register_embedding_adapter decorator and EmbeddingModelMetadata definitions.

Frequently Asked Questions

How do I switch from OpenAI to a local HuggingFace embedding model in DB-GPT?

Change the name field in your [[models.embeddings]] block from text-embedding-3-small to a HuggingFace model identifier like BAAI/bge-m3 or thenlper/gte-large, then remove the api_url and api_key fields. DB-GPT automatically loads the model locally using the HuggingFaceEmbeddings class.

Can I use environment variables for API keys in DB-GPT embedding configuration?

Yes. DB-GPT supports the ${env:VARIABLE_NAME} syntax in TOML configuration files. For example, set api_key = "${env:OPENAI_API_KEY}" and ensure the OPENAI_API_KEY environment variable is set before starting the application.

What is the embedding dimension for OpenAI models in DB-GPT?

The text-embedding-3-small model supports both 1536 and 3072 dimensions depending on configuration. The specific dimension and context length are stored in the EmbeddingModelMetadata class and enforced by the EmbeddingFactory during instantiation.

How do I add a custom embedding provider not listed in the default catalog?

Implement a subclass of Embeddings with embed_documents() and embed_query() methods, then register it using the register_embedding_adapter decorator from dbgpt.model.adapter.base with a corresponding EmbeddingModelMetadata object. Once imported, the model becomes available to both the TOML configuration and EmbeddingFactory.create().

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