Skip to content

DOUBAO_CONFIG.md

Latest commit

 

History

History
222 lines (155 loc) · 4.36 KB

DOUBAO_CONFIG.md

File metadata and controls

222 lines (155 loc) · 4.36 KB

Doubao (豆包) API 配置指南

📝 概述

Jazz 设计师 Agent 现在使用 OpenAI SDK 来调用 Doubao 模型，这样可以获得更好的兼容性和稳定性。

🔑 获取 API Key

1. 访问火山引擎控制台

访问：https://console.volcengine.com/ark

2. 创建推理接入点

  1. 登录后，进入「火山方舟」
  2. 选择「推理」→「在线推理」
  3. 创建一个接入点（Endpoint）
  4. 选择豆包模型（如：doubao-pro-32k）
  5. 获取 API Key 和 Endpoint ID

⚙️ 配置 .env 文件

在项目根目录的 .env 文件中配置：

# Doubao API Configuration
DOUBAO_API_KEY=你的API密钥
DOUBAO_ENDPOINT=https://ark.cn-beijing.volces.com/api/v3
DOUBAO_MODEL=ep-20241004xxxxxx-xxxxx  # 你的 Endpoint ID

重要说明

  1. DOUBAO_API_KEY:

    • 在火山引擎控制台获取
    • 格式类似：ak-xxxxxxxxxxxxx

  2. DOUBAO_ENDPOINT:

    • 使用火山方舟的 API 端点
    • 固定为：https://ark.cn-beijing.volces.com/api/v3
    • 不需要添加 /chat/completions（SDK 会自动添加）

  3. DOUBAO_MODEL:

    • 这是你创建的推理接入点的 Endpoint ID
    • 格式类似：ep-20241004xxxxxx-xxxxx
    • 不是模型名称（如 doubao-pro）

🔍 配置示例

示例 1: 使用火山方舟推理服务

DOUBAO_API_KEY=ak-1234567890abcdef
DOUBAO_ENDPOINT=https://ark.cn-beijing.volces.com/api/v3
DOUBAO_MODEL=ep-20241004123456-abcde

示例 2: 使用豆包开放平台（如果可用）

DOUBAO_API_KEY=your_api_key
DOUBAO_ENDPOINT=https://open.bigmodel.cn/api/paas/v4
DOUBAO_MODEL=doubao-pro

✅ 验证配置

方法 1: 使用健康检查 API

curl http://localhost:8000/api/v1/health

期望返回：

{
  "status": "healthy",
  "version": "0.1.0",
  "services": {
    "doubao": true,    ← 应该是 true
    "seeddream": true,
    "memory": true
  }
}

方法 2: 查看后端日志

启动后端时，应该看到：

✓ Doubao adapter registered
Calling Doubao model: ep-20241004xxxxxx
Doubao response received: XX characters

🐛 常见问题

问题 1: 401 Unauthorized

原因: API Key 错误或过期

解决:

  1. 检查 API Key 是否正确
  2. 确认 API Key 没有过期
  3. 在火山引擎控制台重新生成 API Key

问题 2: 404 Not Found

原因: Endpoint 配置错误或 Model ID 错误

解决:

  1. 确认 DOUBAO_ENDPOINT 是 https://ark.cn-beijing.volces.com/api/v3
  2. 确认 DOUBAO_MODEL 是推理接入点的 Endpoint ID（不是模型名称）
  3. 确认推理接入点已创建并启用

问题 3: 429 Rate Limit

原因: 请求频率过高

解决:

  1. 降低请求频率
  2. 联系火山引擎升级配额

问题 4: Connection Timeout

原因: 网络问题或服务不可用

解决:

  1. 检查网络连接
  2. 尝试 ping ark.cn-beijing.volces.com
  3. 检查防火墙设置

🔧 使用 OpenAI SDK 的优势

1. 标准接口

  • 使用 OpenAI 标准的 Chat Completions API
  • 兼容性强，易于维护

2. 自动重试

  • SDK 内置了重试机制
  • 自动处理临时性错误

3. 流式支持

  • 支持 streaming 模式（未来可用）
  • 实时获取生成结果

4. 类型安全

  • 完整的类型提示
  • 减少运行时错误

📚 参考文档

💡 最佳实践

1. API Key 安全

# 不要将 API Key 提交到 Git
echo ".env" >> .gitignore

2. 环境隔离

# 开发环境
DOUBAO_API_KEY=dev_key

# 生产环境
DOUBAO_API_KEY=prod_key

3. 错误处理

代码已内置完整的错误处理和日志记录，出现问题时查看日志即可。

🚀 测试连接

配置完成后，重启后端服务：

# 停止旧服务
pkill -f "uvicorn app.main"

# 启动新服务
cd backend
source venv/bin/activate
python -m uvicorn app.main:app --reload --port 8000

然后测试生成：

curl -X POST http://localhost:8000/api/v1/design/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "设计一个科技感的海报",
    "model": "seeddream"
  }'

配置成功后，你就可以使用完整的 AI 推理能力了！ 🎉