212 lines
4.9 KiB
Markdown
212 lines
4.9 KiB
Markdown
# 火山引擎大模型配置指南
|
||
|
||
## 快速配置
|
||
|
||
### 基本信息
|
||
- **服务类型**: 火山引擎
|
||
- **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*
|