# 火山引擎大模型配置指南

## 快速配置

### 基本信息
- **服务类型**: 火山引擎
- **API 端点**: `https://ark.cn-beijing.volces.com/api/v3`
- **认证方式**: Bearer Token（API Key）

### 配置步骤

1. **获取 API Key**
   - 访问 [火山引擎控制台](https://console.volcengine.com/ark)
   - 进入「方舟」产品页面
   - 创建或查看 API Key

2. **添加服务**
   - 服务名称: 填写自定义名称（如：字节豆包）
   - 服务类型: 选择「火山引擎」
   - 服务地址: `https://ark.cn-beijing.volces.com/api/v3`
   - API 密钥: 粘贴从控制台获取的 API Key

3. **测试连接**
   - 点击「测试连接」按钮
   - 系统会自动加载可用模型列表

## 可用模型

### 豆包系列模型

#### Pro 系列（高性能）
- `doubao-pro-4k`: 4K 上下文，高质量对话
- `doubao-pro-32k`: 32K 上下文，长文本处理
- `doubao-pro-128k`: 128K 超长上下文

#### Lite 系列（快速响应）
- `doubao-lite-4k`: 4K 上下文，快速响应
- `doubao-lite-32k`: 32K 上下文，平衡性能
- `doubao-lite-128k`: 128K 超长上下文

#### 专业能力
- `doubao-character-8k`: 角色扮演模型
- `doubao-embedding`: 文本向量化
- `doubao-vision`: 视觉理解模型

## API 端点说明

### 聊天对话
```
POST https://ark.cn-beijing.volces.com/api/v3/chat/completions
```

**请求格式**:
```json
{
  "model": "doubao-pro-4k",
  "messages": [
    {
      "role": "user",
      "content": "你好"
    }
  ]
}
```

**认证头**:
```
Authorization: Bearer YOUR_API_KEY
```

**注意**: 火山引擎不提供公开的 `/models` 端点，系统使用预定义的模型列表。连接测试时会发送一个简单的聊天请求来验证 API Key 的有效性。

### 响应格式
```json
{
  "id": "chatcmpl-xxxxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "doubao-pro-4k",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！有什么我可以帮助你的吗？"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 15,
    "total_tokens": 20
  }
}
```

## 常见问题

### 1. 连接失败 - 401 Unauthorized
**原因**: API Key 无效或已过期

**解决方案**:
- 检查 API Key 是否正确复制
- 确认 API Key 在火山引擎控制台是否有效
- 重新生成 API Key

### 2. 模型不可用
**原因**: 模型未在您的账号中开通

**解决方案**:
- 登录火山引擎控制台
- 在方舟产品中申请开通对应模型
- 部分模型需要企业认证

### 3. 请求超时
**原因**: 网络问题或模型响应慢

**解决方案**:
- 检查网络连接
- 尝试使用不同的区域端点
- 使用 Lite 系列模型以获得更快响应

### 4. 限流错误
**原因**: 请求频率超过限制

**解决方案**:
- 降低请求频率
- 联系火山引擎升级配额
- 实现请求队列机制

## 区域端点

火山引擎提供多个区域端点，选择最近的区域可获得更好性能：

- **华北（北京）**: `https://ark.cn-beijing.volces.com/api/v3`（推荐）
- **华东（上海）**: `https://ark.cn-shanghai.volces.com/api/v3`
- **华南（广州）**: `https://ark.cn-guangzhou.volces.com/api/v3`

## 模型选择建议

### 日常对话
推荐: `doubao-pro-4k` 或 `doubao-lite-4k`
- 响应速度快
- 成本较低
- 适合大多数场景

### 长文本处理
推荐: `doubao-pro-32k` 或 `doubao-pro-128k`
- 支持长文档分析
- 代码审查
- 学术论文阅读

### 专业场景
- **角色扮演**: `doubao-character-8k`
- **文档检索**: `doubao-embedding`
- **图像理解**: `doubao-vision`

## 最佳实践

### 1. API Key 安全
- ✅ 定期轮换 API Key
- ✅ 不要在代码中硬编码 API Key
- ✅ 使用环境变量或配置文件
- ❌ 不要将 API Key 提交到版本控制

### 2. 错误处理
```typescript
try {
  const response = await modelService.sendChatRequest(service, model, messages)
  // 处理响应
} catch (error) {
  if (error.message.includes('401')) {
    // API Key 无效
  } else if (error.message.includes('429')) {
    // 请求限流
  } else {
    // 其他错误
  }
}
```

### 3. 性能优化
- 根据任务选择合适的模型规格
- Lite 系列适合简单任务
- Pro 系列适合复杂推理
- 使用流式响应改善用户体验

### 4. 成本控制
- 监控 token 使用量
- 对用户输入进行长度限制
- 缓存常见问题的回答
- 使用较小的上下文窗口模型

## 参考资源

- [火山引擎方舟文档](https://www.volcengine.com/docs/82379)
- [API 参考文档](https://www.volcengine.com/docs/82379/1099455)
- [定价说明](https://www.volcengine.com/docs/82379/1099320)
- [控制台](https://console.volcengine.com/ark)

## 技术支持

如遇到问题，可以通过以下方式获取帮助：
- 火山引擎工单系统
- 技术支持邮箱: support@volcengine.com
- 开发者社区: https://developer.volcengine.com/

---

*最后更新: 2025-10-14*