9.3 KiB

Raw Permalink Blame History

RFC 143: 模型同步架构重构

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

概述

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

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

背景

现有问题

职责混淆：
- sync_models_from_api.py 混合了 AIHubMix 和 ElevenLabs 逻辑
- 模型同步和本地化配置耦合在一起
- 硬编码的 ElevenLabs 模型配置
维护困难：
- 单一脚本超过 400 行代码
- 新增 Provider 需要修改核心逻辑
- 配置文件语义不清晰
扩展性差：
- 无法独立管理本地化配置
- 难以支持多语言
- 缺乏统一的同步入口

设计方案

架构设计

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  # 本地化配置

核心原则

单一职责：
- 同步器：仅负责从 API 获取模型并写入数据库
- 本地化脚本：仅负责更新展示配置
开闭原则：
- 新增 Provider 只需实现 BaseSyncer 接口
- 无需修改现有代码
配置分离：
- 技术属性：由 API 同步获取
- 业务属性：由本地化配置管理

工作流程

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 抽象类

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

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

字段说明:

is_active: 系统是否启用该模型
is_visible: 前端 API 是否返回该模型
display_name: 中文显示名称
description: 中文描述

4. 使用方式

同步模型:

# 同步所有 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: 强制覆盖所有字段（危险）

更新本地化:

# 更新所有配置的模型
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

命令映射

# 旧命令
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. 多语言支持

{
    "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: 性能问题

影响: 同步大量模型耗时过长
缓解:
- 支持增量同步
- 添加并发控制
- 优化数据库批量写入

总结

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

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

问题背景

原有同步逻辑存在缺陷：

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

解决方案

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

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 原始值相同时更新

使用示例

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

数据库当前状态：

{
    "cost_per_unit": 0.0014,
    "is_active": True,
    "is_visible": True
}

API 返回：

{
    "cost_per_unit": 0.0016,  # 官方调价
    "is_active": False,
    "is_visible": False
}

智能更新后：

{
    "cost_per_unit": 0.0016,  # ✅ 更新
    "is_active": True,         # ✅ 保留
    "is_visible": True         # ✅ 保留
}

优势

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

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

9.3 KiB Raw Permalink Blame History