# 模型同步白名单优化

**日期**: 2026-02-13  
**类型**: 优化  
**影响范围**: 模型同步脚本

## 变更概述

优化 `sync_all_models.py` 脚本，默认仅同步 `model_localization.json` 中配置的模型（白名单模式），减少数据库冗余数据。

## 变更动机

**问题**：
- `sync_all_models.py` 会从 Provider API 同步所有模型（可能数百个）
- 实际只需要 `model_localization.json` 中配置的约 20 个模型
- 导致数据库存储大量未使用的模型记录

**解决方案**：
- 默认启用白名单模式，仅同步配置文件中的模型
- 保留 `--sync-all` 参数支持全量同步（用于探索新模型）

## 技术实现

### 1. 新增白名单加载函数

```python
def load_model_whitelist() -> set[str]:
    """加载模型白名单（从 model_localization.json）"""
    config_file = Path(__file__).parent / 'model_localization.json'
    
    try:
        if not config_file.exists():
            logger.warning("配置文件不存在: %s，将同步所有模型", config_file)
            return set()
        
        with open(config_file, 'r', encoding='utf-8') as f:
            config = json.load(f)
            whitelist = set(config.keys())
            logger.info("从配置文件加载 %d 个模型白名单", len(whitelist))
            return whitelist
    except Exception as e:
        logger.error("加载配置文件失败: %s，将同步所有模型", str(e))
        return set()
```

### 2. 修改 `sync_all` 函数

**新增参数**：
- `sync_all: bool = False` - 是否同步所有模型（默认 False）

**白名单过滤逻辑**：
```python
# 加载白名单
whitelist = set() if sync_all else load_model_whitelist()

# 获取所有模型
api_models = await syncer.fetch_models(model_type, model_name)

# 应用白名单过滤
if whitelist:
    original_count = len(api_models)
    api_models = [
        m for m in api_models
        if m.get('model_id') in whitelist
    ]
    filtered_count = len(api_models)
    logger.info("白名单过滤: %d -> %d 个模型", original_count, filtered_count)
```

### 3. 重构 `BaseSyncer`

**拆分 `sync` 方法**：
- `sync()` - 公共接口，获取模型并调用内部方法
- `_sync_models()` - 内部方法，同步已获取的模型列表

**目的**：允许 `sync_all_models.py` 在获取模型后应用白名单过滤，再调用内部同步方法。

### 4. 新增命令行参数

```bash
--sync-all    # 同步所有模型（全量模式）
```

## 使用方法

### 默认模式（白名单）

```bash
# 仅同步 model_localization.json 中配置的模型
docker exec jointo-server-app python scripts/sync_all_models.py
```

### 全量同步模式

```bash
# 同步所有模型（用于探索新模型）
docker exec jointo-server-app python scripts/sync_all_models.py --sync-all
```

### 其他参数组合

```bash
# 白名单 + 预览模式
docker exec jointo-server-app python scripts/sync_all_models.py --dry-run

# 白名单 + 仅同步 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 --sync-all --type video
```

## 影响范围

### 修改文件

1. `server/scripts/sync_all_models.py`
   - 新增 `load_model_whitelist()` 函数
   - 修改 `sync_all()` 函数，新增 `sync_all` 参数
   - 新增白名单过滤逻辑
   - 修改 `main()` 函数，新增 `--sync-all` 参数

2. `server/scripts/sync_models/base.py`
   - 拆分 `sync()` 方法为公共接口和内部方法
   - 新增 `_sync_models()` 内部方法

### 行为变更

**之前**：
- 默认同步所有 Provider 的所有模型

**之后**：
- 默认仅同步 `model_localization.json` 中配置的模型
- 使用 `--sync-all` 可恢复原有全量同步行为

## 优势

1. **减少数据库冗余**：仅存储实际使用的模型
2. **提升同步速度**：减少 API 请求和数据库写入
3. **配置即真理**：模型配置与同步逻辑一致
4. **保留灵活性**：`--sync-all` 支持探索新模型

## 测试建议

```bash
# 1. 预览白名单模式
docker exec jointo-server-app python scripts/sync_all_models.py --dry-run

# 2. 执行白名单同步
docker exec jointo-server-app python scripts/sync_all_models.py

# 3. 验证数据库中的模型数量
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "SELECT COUNT(*) FROM ai_models;"

# 4. 更新本地化配置
docker exec jointo-server-app python scripts/update_model_localization.py
```

## 后续优化

1. 考虑在 `model_localization.json` 中添加模型分组（如 `video`, `image`, `tts`）
2. 支持从配置文件中读取 Provider 过滤规则
3. 添加模型同步日志记录（记录每次同步的模型列表）