# 重构 sync_models_from_api.py 统一使用 AIHubMixClient

**日期**: 2026-01-30  
**类型**: 重构  
**影响范围**: AI 模型同步脚本

## 背景

之前 `sync_models_from_api.py` 直接使用 `httpx` 调用 AIHubMix API，而项目中已有封装好的 `AIHubMixClient` 客户端。这导致：

1. **代码重复**：API 调用逻辑分散在多处
2. **维护困难**：修改 API 调用需要同步多个文件
3. **不一致性**：不同脚本使用不同的调用方式

## 改动内容

### 1. 配置文件更新

#### `server/app/core/config.py`

添加 AIHubMix 配置：

```python
# AI 服务配置
AIHUBMIX_API_KEY: str = ""
AIHUBMIX_BASE_URL: str = "https://aihubmix.com/v1"
```

#### `server/.env.example`

添加配置示例：

```bash
# AIHubMix API 配置
AIHUBMIX_API_KEY=
AIHUBMIX_BASE_URL=https://aihubmix.com/v1
```

### 2. 脚本重构

#### `server/scripts/sync_models_from_api.py`

**修改前**：

```python
import httpx

async def fetch_models_from_api(...):
    url = "https://aihubmix.com/api/v1/models"
    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.get(url, params=params)
        # ... 处理响应
```

**修改后**：

```python
from app.clients.aihubmix_client import AIHubMixClient

async def fetch_models_from_api(...):
    # 检查 API Key 配置
    if not settings.AIHUBMIX_API_KEY:
        logger.error("AIHUBMIX_API_KEY 未配置")
        return []
    
    # 使用统一客户端
    client = AIHubMixClient(
        api_key=settings.AIHUBMIX_API_KEY,
        base_url=settings.AIHUBMIX_BASE_URL
    )
    
    models = await client.list_models(model_type=model_type)
    # ... 处理结果
```

### 3. 文档更新

#### `server/scripts/README_MANAGE_AI_MODELS.md`

- 调整文档结构，将 `sync_models_from_api.py` 作为推荐方式
- 添加前置条件：配置 `AIHUBMIX_API_KEY`
- 更新使用流程和故障排查

## 优势

### 1. 代码复用

- 统一使用 `AIHubMixClient`，避免重复实现
- 所有 AIHubMix API 调用逻辑集中管理

### 2. 易于维护

- 修改 API 调用逻辑只需更新 `aihubmix_client.py`
- 自动继承客户端的错误处理和重试逻辑

### 3. 配置统一

- 从 `settings` 读取配置，支持环境变量
- 与其他 AI 服务配置保持一致

### 4. 更好的错误处理

- 客户端已实现完善的异常处理
- 统一的日志格式

## 使用方法

### 配置 API Key

在 `server/.env` 中添加：

```bash
AIHUBMIX_API_KEY=your-api-key-here
```

### 同步模型

```bash
# 同步所有模型
docker exec jointo-server-app python scripts/sync_models_from_api.py

# 同步视频模型
docker exec jointo-server-app python scripts/sync_models_from_api.py --type video

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

### 查看结果

```bash
docker exec jointo-server-app python scripts/manage_ai_models.py list --type video
```

## 测试验证

### 1. 配置验证

```bash
# 检查配置是否生效
docker exec jointo-server-app python -c "from app.core.config import settings; print(settings.AIHUBMIX_API_KEY[:10] + '...')"
```

### 2. 功能测试

```bash
# 预览模式测试
docker exec jointo-server-app python scripts/sync_models_from_api.py --type video --dry-run

# 实际同步测试
docker exec jointo-server-app python scripts/sync_models_from_api.py --type video

# 验证结果
docker exec jointo-server-app python scripts/manage_ai_models.py list --type video
```

## 兼容性

- ✅ 向后兼容：命令行参数保持不变
- ✅ 功能一致：同步逻辑完全相同
- ⚠️ 需要配置：必须设置 `AIHUBMIX_API_KEY`

## 相关文件

### 修改的文件

- `server/app/core/config.py` - 添加 AIHubMix 配置
- `server/scripts/sync_models_from_api.py` - 重构使用客户端
- `server/.env.example` - 添加配置示例
- `server/scripts/README_MANAGE_AI_MODELS.md` - 更新文档

### 依赖的文件

- `server/app/clients/aihubmix_client.py` - AIHubMix 统一客户端

## 后续优化建议

### 优先级 1（高）

1. **汇率配置化**：将硬编码的汇率 `7.0` 移到配置中
2. **Provider 识别优化**：改进 `guess_provider()` 逻辑，添加 `UNKNOWN` 类型

### 优先级 2（中）

3. **成本计算文档化**：添加详细注释说明转换逻辑
4. **统一日志格式**：全部使用 `%s` 占位符（符合 jointo-tech-stack 规范）

### 优先级 3（低）

5. **添加单元测试**：测试类型映射、Provider 识别、成本计算
6. **批量操作优化**：使用 `bulk_insert_mappings` 提升性能

## 总结

本次重构统一了 AIHubMix API 调用方式，提升了代码质量和可维护性。所有 AI 模型同步功能保持不变，但底层实现更加规范和可靠。