4.2 KiB

Raw Blame History

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 枚举：

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`

命令行参数：

# 跳过已存在的模型（不更新）
--skip-existing

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

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

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

3. 更新 `init_data.py`

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

使用示例

# 默认：智能更新官方字段
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

智能更新示例

假设数据库中已有模型：

{
    "model_name": "eleven_turbo_v2",
    "display_name": "ElevenLabs Turbo V2",  # 本地自定义
    "description": "快速 TTS",
    "cost_per_unit": 0.0014,
    "is_active": True,  # 本地配置
    "is_visible": True  # 本地配置
}

官方 API 返回：

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

智能更新后：

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

优势

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

影响范围

✅ 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 更新）

测试建议

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

后续优化

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

4.2 KiB Raw Blame History