# AI 模型同步智能更新功能实现

**日期**: 2026-02-10  
**类型**: 功能增强  
**影响范围**: 模型同步脚本

## 背景

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

## 解决方案

实现智能更新模式，区分"官方字段"和"本地字段"：

### 字段分类

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

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

**混合字段**（条件更新）：
- `display_name` - 仅当数据库值与 API 原始值相同时更新（避免覆盖用户自定义的中文名称）

### 更新模式

新增 `UpdateMode` 枚举：

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

## 实施内容

### 1. 修改 `base.py`

**新增**：
- `UpdateMode` 枚举类
- 智能更新逻辑（区分字段类型）

**修改**：
- `sync()` 方法参数：`force: bool` → `update_mode: UpdateMode`
- 默认使用 `UpdateMode.SMART`

### 2. 修改 `sync_all_models.py`

**命令行参数**：
```bash
# 跳过已存在的模型（不更新）
--skip-existing

# 智能更新官方字段（默认行为）
--update-official

# 强制覆盖所有字段（危险操作）
--force
```

**默认行为**：使用 `--update-official` 模式

### 3. 更新 `init_data.py`

使用智能更新模式（默认）

## 使用示例

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

## 智能更新示例

假设数据库中已有模型：
```python
{
    "model_name": "eleven_turbo_v2",
    "display_name": "ElevenLabs Turbo V2",  # 本地自定义
    "description": "快速 TTS",
    "cost_per_unit": 0.0014,
    "is_active": True,  # 本地配置
    "is_visible": True  # 本地配置
}
```

官方 API 返回：
```python
{
    "model_name": "eleven_turbo_v2",
    "display_name": "ElevenLabs Turbo V2",
    "description": "快速文本转语音，低延迟",  # 官方更新
    "cost_per_unit": 0.0016,  # 官方调价
    "is_active": False,
    "is_visible": False
}
```

**智能更新后**：
```python
{
    "model_name": "eleven_turbo_v2",
    "display_name": "ElevenLabs Turbo V2",  # 保留（与 API 相同）
    "description": "快速文本转语音，低延迟",  # ✅ 更新
    "cost_per_unit": 0.0016,  # ✅ 更新
    "is_active": True,  # ✅ 保留本地配置
    "is_visible": True  # ✅ 保留本地配置
}
```

## 优势

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

## 影响范围

- ✅ `server/scripts/sync_models/base.py`
- ✅ `server/scripts/sync_all_models.py`
- ✅ `server/scripts/init_data.py`（使用默认智能模式）
- ✅ `server/scripts/README.md`（文档更新）
- ✅ `docs/server/rfcs/143-model-sync-refactoring.md`（RFC 更新）

## 测试建议

1. 测试智能更新：修改数据库中某个模型的 `cost_per_unit`，运行同步，验证价格更新但 `is_active` 保持不变
2. 测试跳过模式：使用 `--skip-existing`，验证已存在模型完全不变
3. 测试强制模式：使用 `--force`，验证所有字段被覆盖

## 后续优化

- 考虑添加 `api_version` 字段追踪 API 版本
- 考虑添加 `last_synced_at` 字段记录同步时间
- 考虑添加变更日志记录字段变更历史