# 模型适配器使用指南

## ✅ 集成状态

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

所有本地模型调用现在都通过统一的 `_handle_local_model_request()` 方法，该方法会：
1. 自动检测提供商（基于 Base URL）
2. 将 OpenAI 格式的请求转换为提供商特定格式
3. 发送请求到本地模型
4. 将提供商响应转换回 OpenAI 格式
5. 提供统一的错误处理和友好的错误提示

**已集成的接口：**
- ✅ `chat_completions` - 对话补全
- ✅ `embeddings` - 文本嵌入
- ✅ `image_generations` - 文生图
- ✅ `image_edits` - 图生图
- ✅ `audio_speech` - 文字转语音 (TTS)
- ✅ `audio_transcriptions` - 语音转文字 (STT)
- ✅ `video_generations` - 文生视频
- ✅ `image_to_video_generations` - 图生视频

## 概述

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

## 核心功能

### 1. 自动提供商检测

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

```python
# 硅基流动
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 格式参数
**输出**：提供商特定格式的参数

#### 示例：图像生成

```python
# 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 格式响应

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

```python
# 阿里云原始响应
{
    "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` 枚举中添加

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

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

```python
@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：在相应的适配器中添加转换逻辑

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

## 使用示例

### 在服务层中使用

```python
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())
```

## 优势

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

## 注意事项

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

## 故障排查

### 问题：提供商检测错误

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

### 问题：参数转换失败

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

### 问题：响应解析失败

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

## 未来计划

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