Daily Study
更新: 7/14/2025 字数: 0 字 时长: 0 分钟
Daily Plan
#todo
- [ ]
Zen-Mcp 使用中转api
概述
当您需要使用自定义中转API（如OneAPI、New API等）来访问各种AI模型时，zen-mcp-server提供了灵活的Custom API配置方式。本文档将详细说明如何配置和使用自定义中转API。
配置步骤
1. 环境变量配置 (.env文件)
在项目根目录的.env文件中配置以下参数：
bash
# Option 3: Use custom API endpoints for local models (Ollama, vLLM, LM Studio, etc.)
CUSTOM_API_URL=https://your-api-proxy.com/v1
CUSTOM_API_KEY=your_api_key_here
CUSTOM_MODEL_NAME=gemini-2.5-pro # Default model name
# Optional: Default model to use
DEFAULT_MODEL=gemini-2.5-pro
# 注释掉其他API配置，避免冲突
# GEMINI_API_KEY=...
# OPENAI_API_KEY=...
# OPENROUTER_API_KEY=...重要配置说明：
CUSTOM_API_URL: 中转API的完整端点地址，通常以/v1结尾CUSTOM_API_KEY: 中转API提供的访问密钥CUSTOM_MODEL_NAME: 默认使用的模型名称DEFAULT_MODEL: 系统默认模型，应与CUSTOM_MODEL_NAME保持一致
2. 模型配置 (custom_models.json)
在conf/custom_models.json文件中添加或修改模型配置：
bash
{
"model_name": "gemini-2.5-pro",
"aliases": ["gemini-2.5-pro", "gemini-custom", "gemini-proxy"],
"context_window": 1048576,
"max_output_tokens": 65536,
"supports_extended_thinking": false,
"supports_json_mode": true,
"supports_function_calling": false,
"supports_images": true,
"max_image_size_mb": 20.0,
"is_custom": true,
"description": "Google's Gemini 2.5 Pro via custom proxy API with vision"
}关键字段说明：
model_name: 与中转API中的模型名称完全一致aliases: 用户可以使用的简短别名is_custom: 必须设置为true，表示这是自定义端点模型context_window: 模型的上下文窗口大小supports_*: 根据实际模型能力设置
常见中转API配置示例
1. OneAPI/New API
# OneAPI示例
CUSTOM_API_URL=https://api.your-domain.com/v1
CUSTOM_API_KEY=sk-xxxxxxxxxxxxxx
CUSTOM_MODEL_NAME=gpt-4
DEFAULT_MODEL=gpt-42. 自建代理服务
bash
# 自建代理示例
CUSTOM_API_URL=https://your-proxy.com/v1
CUSTOM_API_KEY=your-secret-key
CUSTOM_MODEL_NAME=claude-3-opus-20240229
DEFAULT_MODEL=claude-3-opus-202402293. 本地模型服务 (Ollama/vLLM)
bash
# Ollama示例
CUSTOM_API_URL=http://localhost:11434/v1
CUSTOM_API_KEY=ollama
CUSTOM_MODEL_NAME=llama3.2
DEFAULT_MODEL=llama3.2使用方法
1. 通过模型名称调用
python
# 使用完整模型名称
response = client.chat("gemini-2.5-pro", "你好，世界！")
# 使用别名
response = client.chat("gemini-custom", "你好，世界！")2. 使用默认模型
python
# 使用环境变量中设置的默认模型
response = client.chat(None, "你好，世界！")故障排除
1. API响应格式错误
问题表现：
bash
Could not read JSON from response data due to JSONDecodeError
'content-type': 'text/html; charset=utf-8'解决方案：
- 检查
CUSTOM_API_URL是否正确，确保包含/v1路径 - 验证API密钥是否有效
- 确认中转服务是否正常运行
- 检查模型名称是否在中转API中可用
2. 模型不可用
问题表现：
bash
Custom API API error for model xxx after 1 attempt解决方案：
- 确认模型名称在中转API中正确配置
- 检查API配额是否充足
- 验证中转服务的模型映射配置
3. 配置冲突
问题表现：
- 系统使用了错误的API端点
- 模型调用失败
解决方案：
- 确保只启用一种API配置方式
- 注释掉其他API的环境变量
- 检查
DEFAULT_MODEL设置是否正确
测试配置
1. API连通性测试
bash
curl -X POST https://your-api-proxy.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your_api_key_here" \
-d '{
"model": "gemini-2.5-pro",
"messages": [{"role": "user", "content": "Hello"}],
"max_tokens": 10
}'2. 模型列表查询
bash
curl -X GET https://your-api-proxy.com/v1/models \
-H "Authorization: Bearer your_api_key_here"
-
-
-
-最佳实践
1. 安全配置
- 妥善保管API密钥，不要提交到版本控制系统
- 使用环境变量管理敏感信息
- 定期轮换API密钥
2. 性能优化
- 根据实际需求设置合适的
context_window和max_output_tokens - 合理配置超时时间
- 监控API调用频率和配额使用情况
3. 模型管理
- 为常用模型设置简短易记的别名
- 在
custom_models.json中详细描述模型能力 - 定期更新模型配置以反映最新能力
高级配置
1. 多模型支持
bash
可以在同一个中转API中配置多个模型：
{ "models": [ { "model_name": "gpt-4", "aliases": ["gpt4", "openai-gpt4"], "is_custom": true, "description": "GPT-4 via custom proxy" }, { "model_name": "claude-3-opus", "aliases": ["opus", "claude-opus"], "is_custom": true, "description": "Claude 3 Opus via custom proxy" } ] }
{
"models": [
{
"model_name": "gpt-4",
"aliases": ["gpt4", "openai-gpt4"],
"is_custom": true,
"description": "GPT-4 via custom proxy"
},
{
"model_name": "claude-3-opus",
"aliases": ["opus", "claude-opus"],
"is_custom": true,
"description": "Claude 3 Opus via custom proxy"
}
]
}2. 条件路由
某些中转API支持根据模型名称自动路由到不同的上游API，您可以配置相应的模型别名来简化使用。
通过以上配置，您就可以成功使用自定义中转API来访问各种AI模型了。记住根据您的具体中转服务提供商的要求调整配置参数。