# RFC 143: 模型同步架构重构

**状态**: 已实施  
**创建日期**: 2026-02-10  
**最后更新**: 2026-02-10（新增智能更新功能）  
**作者**: AI Assistant  
**类型**: 架构重构

## 概述

将模型同步脚本重构为模块化架构，分离同步逻辑和本地化配置，提升可维护性和扩展性。

**2026-02-10 更新**：新增智能更新模式，支持自动同步官方变更的同时保留本地配置。

## 背景

### 现有问题

1. **职责混淆**：
   - `sync_models_from_api.py` 混合了 AIHubMix 和 ElevenLabs 逻辑
   - 模型同步和本地化配置耦合在一起
   - 硬编码的 ElevenLabs 模型配置

2. **维护困难**：
   - 单一脚本超过 400 行代码
   - 新增 Provider 需要修改核心逻辑
   - 配置文件语义不清晰

3. **扩展性差**：
   - 无法独立管理本地化配置
   - 难以支持多语言
   - 缺乏统一的同步入口

## 设计方案

### 架构设计

```
server/
└── scripts/
    ├── sync_models/              # 模型同步模块
    │   ├── __init__.py
    │   ├── base.py              # 抽象基类
    │   ├── utils.py             # 共用工具
    │   ├── aihubmix_sync.py    # AIHubMix 同步器
    │   └── elevenlabs_sync.py  # ElevenLabs 同步器
    ├── sync_all_models.py       # 统一同步入口
    ├── update_model_localization.py  # 本地化更新脚本
    └── model_localization.json  # 本地化配置
```

### 核心原则

1. **单一职责**：
   - 同步器：仅负责从 API 获取模型并写入数据库
   - 本地化脚本：仅负责更新展示配置

2. **开闭原则**：
   - 新增 Provider 只需实现 `BaseSyncer` 接口
   - 无需修改现有代码

3. **配置分离**：
   - 技术属性：由 API 同步获取
   - 业务属性：由本地化配置管理

### 工作流程

```mermaid
graph LR
    A[sync_all_models.py] --> B[AIHubMixSyncer]
    A --> C[ElevenLabsSyncer]
    B --> D[数据库]
    C --> D
    D --> E[update_model_localization.py]
    E --> F[model_localization.json]
    F --> D
```

## 实施细节

### 1. BaseSyncer 抽象类

```python
class BaseSyncer(ABC):
    @property
    @abstractmethod
    def provider_name(self) -> str:
        """Provider 名称"""
        pass
    
    @abstractmethod
    async def fetch_models(self, model_type, model_name) -> List[Dict]:
        """从 API 获取模型列表"""
        pass
    
    @abstractmethod
    def map_to_db_model(self, api_model) -> Optional[Dict]:
        """映射到数据库结构"""
        pass
    
    async def sync(self, model_type, model_name, dry_run, force):
        """同步模型到数据库"""
        pass
```

### 2. 同步器实现

**AIHubMixSyncer**:
- 使用 httpx 调用 AIHubMix API
- 支持按类型过滤（llm, video, image, tts 等）
- 自动映射 Provider 和模型类型

**ElevenLabsSyncer**:
- 使用官方 API 替代硬编码
- 实时获取模型列表和定价
- 自动计算成本和积分

### 3. 本地化配置

**配置文件**: `server/scripts/model_localization.json`

```json
{
    "gpt-4o": {
        "is_active": true,
        "is_visible": true,
        "display_name": "GPT-4o",
        "description": "OpenAI 多模态模型，支持文本和图像"
    }
}
```

**字段说明**:
- `is_active`: 系统是否启用该模型
- `is_visible`: 前端 API 是否返回该模型
- `display_name`: 中文显示名称
- `description`: 中文描述

### 4. 使用方式

**同步模型**:
```bash
# 同步所有 Provider（默认智能更新）
docker exec jointo-server-app python scripts/sync_all_models.py

# 仅同步 AIHubMix
docker exec jointo-server-app python scripts/sync_all_models.py --provider aihubmix

# 预览模式
docker exec jointo-server-app python scripts/sync_all_models.py --dry-run

# 跳过已存在的模型
docker exec jointo-server-app python scripts/sync_all_models.py --skip-existing

# 强制覆盖所有字段
docker exec jointo-server-app python scripts/sync_all_models.py --force
```

**更新模式**:
- `--update-official`: 智能更新官方字段，保留本地配置（默认）
- `--skip-existing`: 跳过已存在的模型
- `--force`: 强制覆盖所有字段（危险）

**更新本地化**:
```bash
# 更新所有配置的模型
docker exec jointo-server-app python scripts/update_model_localization.py

# 预览模式
docker exec jointo-server-app python scripts/update_model_localization.py --dry-run
```

## 优势

### 1. 职责清晰
- 同步归同步，本地化归本地化
- 每个模块只做一件事

### 2. 易于扩展
- 新增 Provider：实现 `BaseSyncer` 接口
- 新增语言：扩展配置文件结构
- 新增字段：修改 `update_model_localization.py`

### 3. 维护友好
- 代码模块化，易于理解
- 配置文件语义明确
- 支持独立测试

### 4. 灵活性高
- 可以随时调整可见性，无需重新同步
- 支持批量更新本地化配置
- 支持选择性同步 Provider

## 迁移指南

### 旧脚本映射

| 旧脚本 | 新脚本 | 说明 |
|--------|--------|------|
| `sync_models_from_api.py` | `sync_all_models.py` | 统一同步入口 |
| `models_override_config.json` | `model_localization.json` | 本地化配置 |
| `elevenlabs_models_config.json` | 已删除 | 使用官方 API |

### 命令映射

```bash
# 旧命令
docker exec jointo-server-app python scripts/sync_models_from_api.py

# 新命令（两步）
docker exec jointo-server-app python scripts/sync_all_models.py
docker exec jointo-server-app python scripts/update_model_localization.py
```

## 未来扩展

### 1. 多语言支持

```json
{
    "gpt-4o": {
        "is_active": true,
        "is_visible": true,
        "locales": {
            "zh-CN": {
                "display_name": "GPT-4o",
                "description": "OpenAI 多模态模型"
            },
            "en-US": {
                "display_name": "GPT-4o",
                "description": "OpenAI multimodal model"
            }
        }
    }
}
```

### 2. 更多 Provider

- Anthropic (Claude)
- Cohere
- Mistral AI
- 国内厂商（通义千问、文心一言等）

### 3. 自动化同步

- 定时任务：每日自动同步新模型
- Webhook：Provider 更新时触发同步
- 版本管理：跟踪模型版本变化

## 风险与缓解

### 风险 1: API 变更
- **影响**: Provider API 格式变化导致同步失败
- **缓解**: 
  - 添加 API 版本检测
  - 实现降级策略
  - 监控同步失败率

### 风险 2: 配置不一致
- **影响**: 本地化配置与数据库不同步
- **缓解**:
  - 提供配置校验工具
  - 添加配置版本号
  - 定期审计配置

### 风险 3: 性能问题
- **影响**: 同步大量模型耗时过长
- **缓解**:
  - 支持增量同步
  - 添加并发控制
  - 优化数据库批量写入

## 总结

本次重构实现了模型同步架构的模块化和职责分离，为未来扩展奠定了基础。通过分离同步逻辑和本地化配置，提升了系统的可维护性和灵活性。

## 相关文档

- [RFC 142: ElevenLabs 集成](./142-elevenlabs-integration.md)
- [Changelog: AI 模型可见性控制](../changelogs/2026-02-10-ai-models-visibility-control.md)


## 智能更新功能（2026-02-10 新增）

### 问题背景

原有同步逻辑存在缺陷：
- 默认跳过已存在的模型，无法自动同步官方变更（定价、描述等）
- 使用 `--force` 会覆盖所有字段，包括本地化配置
- 无法在保留本地配置的同时更新官方数据

### 解决方案

新增 `UpdateMode` 枚举，支持三种更新模式：

```python
class UpdateMode(str, Enum):
    SKIP = "skip"    # 跳过已存在的模型
    SMART = "smart"  # 智能更新：仅更新官方字段，保留本地配置（默认）
    FORCE = "force"  # 强制更新：覆盖所有字段（危险操作）
```

### 字段分类

**官方字段**（自动更新）：
- `description` - 模型描述
- `cost_per_unit` - 单位成本
- `unit_type` - 计费单位类型
- `credits_per_unit` - 积分消耗
- `config` - 模型配置
- `provider` - Provider 类型
- `model_type` - 模型类型

**本地字段**（保留不变）：
- `is_active` - 是否启用
- `is_visible` - 是否可见
- `is_beta` - 是否测试版

**混合字段**（条件更新）：
- `display_name` - 仅当数据库值与 API 原始值相同时更新

### 使用示例

```bash
# 默认：智能更新官方字段
docker exec jointo-server-app python scripts/sync_all_models.py

# 跳过已存在的模型
docker exec jointo-server-app python scripts/sync_all_models.py --skip-existing

# 强制覆盖所有字段
docker exec jointo-server-app python scripts/sync_all_models.py --force
```

### 智能更新示例

**场景**：官方调整了 `eleven_turbo_v2` 的定价

**数据库当前状态**：
```python
{
    "cost_per_unit": 0.0014,
    "is_active": True,
    "is_visible": True
}
```

**API 返回**：
```python
{
    "cost_per_unit": 0.0016,  # 官方调价
    "is_active": False,
    "is_visible": False
}
```

**智能更新后**：
```python
{
    "cost_per_unit": 0.0016,  # ✅ 更新
    "is_active": True,         # ✅ 保留
    "is_visible": True         # ✅ 保留
}
```

### 优势

1. **自动化**：官方变更自动同步，无需手动干预
2. **安全性**：本地配置不会被覆盖
3. **灵活性**：提供三种模式满足不同场景
4. **可追溯**：日志清晰记录更新的字段

详见：`docs/server/changelogs/2026-02-10-model-sync-smart-update.md`