1. 核心接入模式
1.1 统一鉴权与路由
1.2 特殊处理要点
- 空工具修复:当
tools=[]
且存在tool_choice
时,自动移除tool_choice
- 文件扩展名:根据
mediaType
自动设置正确的文件扩展名 - 缓存控制:支持
<cache>
标签实现缓存控制
2. 统一接入实现
2.1 核心客户端封装
2.2 特殊处理与工具函数
3. 部署与配置
3.1 环境变量
3.2 错误处理
4. 参考实现与对齐清单
4.1 cherry-studio 客户端参考(TypeScript)
下述要点来自cherry-studio
的 AihubmixAPIClient.ts
,可作为第三方前端/桌面端在 TypeScript 侧接入 aihubmix 的落地范式:
- 统一追加折扣码:在 Provider 级别合并
extra_headers
并设置APP-Code
(项目中为MLTG2087
) - 多客户端路由:
claude*
→ 使用 Anthropic 客户端gemini*
/imagen*
且不以-nothink
/-search
结尾且不包含embedding
→ 使用 Gemini 客户端(apiHost: https://aihubmix.com/gemini
)- OpenAI 系列(排除
gpt-oss
)→ 使用 OpenAI 兼容响应客户端 - 其他 → 回退到默认 OpenAI 客户端
- BaseURL 获取:从当前已路由的具体客户端导出,保持各家端点差异
4.2 dify-plugin-aihubmix 参考(Python)
下述要点来自dify-plugin-aihubmix
的实现,可作为第三方 Python 工具接入 aihubmix 的落地范式:
- 统一追加折扣码:在 Provider 级别合并
extra_headers
并设置APP-Code
(项目中为Dify2025
) - 多客户端路由:
claude*
→ 使用 Anthropic 客户端gemini*
/imagen*
且不以-nothink
/-search
结尾且不包含embedding
→ 使用 Gemini 客户端(apiHost: https://aihubmix.com/gemini
)- OpenAI 系列(排除
gpt-oss
)→ 使用 OpenAI 兼容响应客户端 - 其他 → 回退到默认 OpenAI 客户端
- BaseURL 获取:从当前已路由的具体客户端导出,保持各家端点差异
4.3 对齐清单
- Provider 入口统一合并
extra_headers
并注入APP-Code
- Gemini 客户端使用
https://aihubmix.com/gemini
作为apiHost
- 路由规则与
claude*
、gemini*/imagen*
、OpenAI 系列(排除gpt-oss
)一致 - 默认回退到 OpenAI 客户端,保持与 OpenAI 兼容接口行为
-
getBaseURL()
始终从当前路由客户端导出,避免硬编码
5. 迁移检查清单
- 替换 API Key 为 aihubmix API Key
- 替换 Base URL 为
https://aihubmix.com
- 添加
APP-Code
header 享受折扣 - 实现模型路由逻辑(claude/gemini/openai)
- 处理空工具时的
tool_choice
修复 - 配置文件上传的 MIME 类型处理
- 测试各种模型调用
- 配置错误处理和重试机制