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

> Explore supported embedding models in DB-GPT including HuggingFace OpenAI Azure and Ollama. Learn how to configure them using TOML or the Python SDK for your AI projects.

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

---

**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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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:

```toml
[[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:

```toml
[[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`:

```python
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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/configs/dbgpt-proxy-openai.toml) (or create a custom config):

```toml
[[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**

```python
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**

```toml
[[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`](https://github.com/eosphoros-ai/DB-GPT/blob/main/packages/dbgpt-core/src/dbgpt/rag/embedding/embedding_factory.py) and [`embeddings.py`](https://github.com/eosphoros-ai/DB-GPT/blob/main/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()`.