docs/v1.0/server/changelogs/2026-01-30-sync-models-aihubmix-client-refactor.md

重构 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 配置：

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

server/.env.example

添加配置示例：

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

2. 脚本重构

server/scripts/sync_models_from_api.py

修改前：

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)
        # ... 处理响应

修改后：

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 中添加：

AIHUBMIX_API_KEY=your-api-key-here

同步模型

# 同步所有模型
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

查看结果

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

测试验证

1. 配置验证

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

2. 功能测试

# 预览模式测试
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 模型同步功能保持不变，但底层实现更加规范和可靠。