# model-providers：简洁的 LLM 与 Embedding 多提供商架构

> model-providers 是一个基于简单 OOP 继承的 LLM 和 Embedding 模型提供商系统，支持通过环境变量或配置灵活切换不同提供商，实现模型的混合搭配使用。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-09T19:50:11.000Z
- 最近活动: 2026-04-09T20:23:24.088Z
- 热度: 157.4
- 关键词: LLM, Embedding, 模型提供商, OOP, 工厂模式, Python, 配置管理
- 页面链接: https://www.zingnex.cn/forum/thread/model-providers-llm-embedding
- Canonical: https://www.zingnex.cn/forum/thread/model-providers-llm-embedding
- Markdown 来源: ingested_event

---

# model-providers：简洁的 LLM 与 Embedding 多提供商架构

## 项目概述

model-providers 是一个设计简洁的模型提供商系统，专注于解决一个具体问题：**如何在不同 LLM 和 Embedding 提供商之间灵活切换，而无需修改业务代码。**

它采用基于继承的面向对象设计，没有魔法装饰器或元类，一切清晰可见。这种设计理念使得代码易于理解、测试和扩展。

## 核心设计原则

### 1. 无魔法，纯类

项目明确拒绝使用装饰器或元类，所有功能通过普通类实现：

```python
class BaseLLMProvider:
    @classmethod
    def create(cls, cfg: LLMProviderConfig) -> ResolvedProvider:
        raise NotImplementedError

class OllamaProvider(BaseLLMProvider):
    @classmethod
    def create(cls, cfg):
        # 构建并返回 ResolvedProvider
        ...
```

这种设计的优势：
- **显式注册**：所有提供商在一个字典中可见
- **易于扩展**：子类化 + 添加到字典 = 完成
- **简单测试**：可直接模拟提供商类
- **清晰依赖**：导入树直观明了
- **IDE 友好**：自动补全和导航完美工作

### 2. 工厂模式

通过统一的工厂函数获取提供商实例：

```python
from model_providers import get_llm_provider, LLMProviderConfig

# 使用环境配置
resolved = get_llm_provider()

# 或显式配置
cfg = LLMProviderConfig(provider="azure", model_name="gpt-4o-2")
resolved = get_llm_provider(cfg)

# 构建聊天模型
from pydantic_ai.models.openai import OpenAIChatModel
model = OpenAIChatModel(
    model_name=resolved.model_name,
    provider=resolved.provider,
)
```

## 支持的提供商

### LLM 提供商

| 提供商 | 默认模型 | 最大 Token | 上下文窗口 |
|-------|---------|-----------|-----------|
| Ollama | qwen3-vl:32b | 131072 | 131072 |
| Azure | gpt-4o-2 | 8192 | 8192 |
| Grok | grok-2-latest | 8192 | 8192 |
| Groq | llama-3.3-70b-versatile | 32768 | 32768 |

### Embedding 提供商

| 提供商 | 默认模型 |
|-------|---------|
| Ollama | nomic-embed-text |
| Azure | text-embedding-3-large |

## 架构优势

model-providers 的设计带来了六个关键好处：

1. **无魔法**：纯类实现，没有装饰器或元类
2. **显式注册**：在一个字典中查看所有提供商
3. **易于扩展**：子类化并添加到字典即可完成
4. **简单测试**：可直接模拟提供商类
5. **清晰依赖**：导入树直观明了
6. **IDE 友好**：自动补全和导航完美工作

## 添加新提供商

扩展 model-providers 非常简单，只需四步：

### 1. 创建提供商类

```python
# 在 llm.py 中
class MyCustomProvider(BaseLLMProvider):
    @classmethod
    def create(cls, cfg: LLMProviderConfig) -> ResolvedProvider:
        from pydantic_ai.providers.openai import OpenAIProvider
        api_key = os.getenv("MYCUSTOM_API_KEY")
        provider = OpenAIProvider(
            api_key=api_key,
            base_url="https://api.mycustom.com/v1"
        )
        return ResolvedProvider(provider=provider, model_name=cfg.model_name)
```

### 2. 注册到字典

```python
LLM_PROVIDERS = {
    "ollama": OllamaProvider,
    "azure": AzureProvider,
    "grok": GrokProvider,
    "groq": GroqProvider,
    "mycustom": MyCustomProvider,  # 添加到这里
}
```

### 3. 更新支持列表

```python
SUPPORTED_PROVIDERS = {"ollama", "azure", "grok", "groq", "mycustom"}
```

### 4. 使用

```bash
export LLM_PROVIDER=mycustom
export MYCUSTOM_API_KEY=your-key
export LLM_MODEL=model-name
```

## 环境变量配置

### LLM 提供商选择

```bash
LLM_PROVIDER=ollama|azure|grok|groq  # 默认：ollama
LLM_MODEL=override-default-model
LLM_MAX_TOKENS=override-default-max-tokens
LLM_CONTEXT_WINDOW=override-default-context-window
LLM_TIMEOUT=request-timeout-in-seconds  # 默认：604800
```

### Azure 特定配置

```bash
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_VERSION=2024-08-01-preview
AZURE_OPENAI_DEPLOYMENT=deployment-name  # 默认：gpt-4o-2
AZURE_USE_TOKEN_AUTH=true  # 默认，使用 az login | false 使用 API key
AZURE_OPENAI_API_KEY=API-key（如果 AZURE_USE_TOKEN_AUTH=false）
AZURE_OPENAI_KEYVAULT_URL=Key Vault URL for API key retrieval
AZURE_OPENAI_SECRET_NAME=secret-name  # 默认：azure-openai-api-key
AZURE_COGNITIVE_SERVICE_SCOPE=token-scope  # 默认：https://cognitiveservices.azure.com/.default
```

### Embedding 提供商选择

```bash
EMBEDDING_PROVIDER=ollama|azure  # 默认：ollama
EMBEDDING_MODEL=override-default-embedding-model
EMBEDDING_DIMENSIONS=embedding-dimension-override
EMBED_TIMEOUT=request-timeout  # 默认：60
```

### Azure Embedding 配置

```bash
AZURE_OPENAI_EMBED_DEPLOYMENT=deployment-name  # 默认：text-embedding-3-large
AZURE_OPENAI_EMBED_DIMENSIONS=dimensions-override（Azure-specific）
```

### 其他提供商配置

```bash
OLLAMA_BASE_URL=https://ollama.valiantlynx.com/v1  # 默认
GROK_API_KEY=x.ai API key
GROQ_API_KEY=Groq API key
GCP_API_KEY=Google Cloud API key
```

## 使用场景

model-providers 特别适合以下场景：

### 1. 多环境部署

开发环境使用 Ollama（本地免费），生产环境使用 Azure（企业级 SLA）：

```bash
# 开发
LLM_PROVIDER=ollama
LLM_MODEL=qwen3-vl:32b

# 生产
LLM_PROVIDER=azure
LLM_MODEL=gpt-4o-2
```

无需修改代码，仅通过环境变量切换。

### 2. 模型降级策略

当主模型不可用时，自动降级到备用模型：

```python
from model_providers import get_llm_provider, LLMProviderConfig

providers = ["azure", "groq", "ollama"]
for provider_name in providers:
    try:
        cfg = LLMProviderConfig(provider=provider_name)
        resolved = get_llm_provider(cfg)
        break
    except Exception:
        continue
```

### 3. A/B 测试不同模型

通过配置动态切换模型，比较不同提供商的效果：

```python
# 实验组 A
config_a = LLMProviderConfig(provider="azure", model_name="gpt-4o-2")

# 实验组 B
config_b = LLMProviderConfig(provider="groq", model_name="llama-3.3-70b")
```

### 4. Embedding 与 LLM 解耦

使用不同提供商的 Embedding 和 LLM：

```bash
# 使用 Azure 的 Embedding（高质量）
EMBEDDING_PROVIDER=azure
EMBEDDING_MODEL=text-embedding-3-large

# 使用 Groq 的 LLM（速度快）
LLM_PROVIDER=groq
LLM_MODEL=llama-3.3-70b-versatile
```

## 与 machine-core 的关系

model-providers 是 machine-core 框架的配套组件，专门负责模型提供商的抽象。这种模块化设计使得：

- machine-core 专注于 Agent 逻辑和工具管理
- model-providers 专注于模型提供商的统一接口
- 两者可以独立使用，也可以组合使用

如果你正在使用 machine-core，model-providers 已经作为依赖集成其中。如果你只需要一个简洁的模型提供商抽象，也可以单独使用 model-providers。

## 结语

model-providers 展示了一种务实的工程设计：用简单的 OOP 继承解决复杂的多提供商切换问题。它没有过度设计，没有魔法，只有清晰的类和显式的注册。对于需要灵活切换 LLM 或 Embedding 提供商的项目来说，这是一个轻量且可靠的选择。