模型适配器使用指南

✅ 集成状态

适配器系统已完全集成到所有 OpenAI 兼容接口！

所有本地模型调用现在都通过统一的 _handle_local_model_request() 方法，该方法会：

自动检测提供商（基于 Base URL）
将 OpenAI 格式的请求转换为提供商特定格式
发送请求到本地模型
将提供商响应转换回 OpenAI 格式
提供统一的错误处理和友好的错误提示

已集成的接口：

✅ chat_completions - 对话补全
✅ embeddings - 文本嵌入
✅ image_generations - 文生图
✅ image_edits - 图生图
✅ audio_speech - 文字转语音 (TTS)
✅ audio_transcriptions - 语音转文字 (STT)
✅ video_generations - 文生视频
✅ image_to_video_generations - 图生视频

概述

模型适配器系统提供了统一的接口，让平台能够兼容各种不同的 AI 模型提供商，无需修改业务代码。

核心功能

1. 自动提供商检测

系统会根据模型的 base_url 自动识别提供商：

# 硅基流动
base_url = "https://api.siliconflow.cn/v1"  → ModelProvider.SILICONFLOW

# 阿里云百炼
base_url = "https://dashscope.aliyuncs.com"  → ModelProvider.DASHSCOPE

# 智谱AI
base_url = "https://open.bigmodel.cn/api"  → ModelProvider.ZHIPU

# 月之暗面
base_url = "https://api.moonshot.cn/v1"  → ModelProvider.MOONSHOT

# DeepSeek
base_url = "https://api.deepseek.com/v1"  → ModelProvider.DEEPSEEK

# 通用 OpenAI 兼容
其他 URL  → ModelProvider.GENERIC

2. 请求参数自动适配

输入：统一的 OpenAI 格式参数输出：提供商特定格式的参数

示例：图像生成

# OpenAI 格式（用户输入）
{
    "model": "dall-e-3",
    "prompt": "a beautiful sunset",
    "size": "1024x1024",
    "n": 1
}

# 自动转换为阿里云格式
{
    "model": "wanx-v1",
    "input": {
        "prompt": "a beautiful sunset"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}

3. 响应结果自动适配

输入：提供商特定格式的响应输出：统一的 OpenAI 格式响应

示例：阿里云图像生成响应

# 阿里云原始响应
{
    "request_id": "xxx",
    "output": {
        "results": [
            {"url": "https://..."}
        ]
    }
}

# 自动转换为 OpenAI 格式
{
    "created": "xxx",
    "data": [
        {"url": "https://...", "revised_prompt": null}
    ]
}

支持的接口

1. Chat Completions（对话）

✅ OpenAI
✅ 硅基流动
✅ 阿里云百炼
✅ 智谱AI
✅ 月之暗面
✅ DeepSeek
✅ 通用 OpenAI 兼容

2. Image Generation（图像生成）

✅ OpenAI DALL-E
✅ 硅基流动
✅ 阿里云通义万相（自动适配）
✅ 通用 OpenAI 兼容

3. Audio Speech（TTS）

✅ OpenAI TTS
✅ 硅基流动
✅ 阿里云 CosyVoice（自动适配）
✅ 通用 OpenAI 兼容

特殊处理：

自动检测响应类型（JSON URL vs 直接音频数据）
支持两种返回模式

4. Audio Transcription（STT）

✅ OpenAI Whisper
✅ 硅基流动
✅ 阿里云 Paraformer（自动适配）
✅ 通用 OpenAI 兼容

5. Embeddings（向量嵌入）

✅ OpenAI
✅ 硅基流动
✅ 阿里云（自动适配）
✅ 通用 OpenAI 兼容

6. Video Generation（视频生成）

✅ 硅基流动
✅ 阿里云（自动适配）
✅ 通用 OpenAI 兼容

如何添加新的提供商

步骤1：在 `ModelProvider` 枚举中添加

class ModelProvider(str, Enum):
    # ... 现有提供商
    NEW_PROVIDER = "new_provider"  # 新提供商

步骤2：在 `detect_provider` 中添加检测规则

@staticmethod
def detect_provider(base_url: str, model_name: str) -> ModelProvider:
    base_url_lower = base_url.lower()
    
    # ... 现有规则
    
    if "newprovider" in base_url_lower:
        return ModelProvider.NEW_PROVIDER

步骤3：在相应的适配器中添加转换逻辑

class ImageAdapter:
    @staticmethod
    def adapt_request(provider: ModelProvider, openai_request: Dict[str, Any]) -> Dict[str, Any]:
        # ... 现有逻辑
        
        if provider == ModelProvider.NEW_PROVIDER:
            # 添加新提供商的请求转换逻辑
            adapted = {
                "custom_field": openai_request.get("prompt"),
                # ...
            }
            return adapted
        
        return openai_request
    
    @staticmethod
    def adapt_response(provider: ModelProvider, provider_response: Dict[str, Any]) -> Dict[str, Any]:
        # ... 现有逻辑
        
        if provider == ModelProvider.NEW_PROVIDER:
            # 添加新提供商的响应转换逻辑
            return {
                "created": ...,
                "data": [...]
            }
        
        return provider_response

使用示例

在服务层中使用

from app.services.model_adapters import BaseAdapter, get_adapter

# 1. 检测提供商
provider = BaseAdapter.detect_provider(base_url, model_name)

# 2. 获取适配器
adapter = get_adapter("image")  # "chat", "image", "audio_tts", etc.

# 3. 适配请求
adapted_request = adapter.adapt_request(provider, openai_format_request)

# 4. 发送请求
response = await client.post(api_url, json=adapted_request)

# 5. 适配响应
openai_format_response = adapter.adapt_response(provider, response.json())

优势

用户无感知：用户始终使用标准 OpenAI 格式
提供商透明：自动检测和适配，无需手动配置
易于扩展：添加新提供商只需修改适配器
统一错误处理：所有提供商的错误都转换为统一格式
向后兼容：不影响现有代码

注意事项

参数兼容性：某些提供商可能不支持所有 OpenAI 参数
响应格式：适配器会尽力转换，但某些字段可能为 null
性能影响：适配过程开销极小，可忽略不计
测试覆盖：添加新提供商后需要充分测试

故障排查

问题：提供商检测错误

解决：检查 base_url 是否包含正确的关键词，或在 detect_provider 中添加更精确的规则

问题：参数转换失败

解决：检查适配器中的 adapt_request 方法，确保所有必需字段都已映射

问题：响应解析失败

解决：检查适配器中的 adapt_response 方法，确保响应格式正确转换

未来计划

支持更多提供商（百度文心、讯飞星火等）
添加参数验证和自动补全
提供商能力矩阵（哪些提供商支持哪些功能）
性能监控和统计
自动降级和重试机制

MODEL_ADAPTER_GUIDE.md 6.7 KB 文件歷史 原始文件