146 lines
3.7 KiB
Markdown
146 lines
3.7 KiB
Markdown
# AI 服务配置说明
|
||
|
||
## 环境变量配置
|
||
|
||
AI 服务需要通过环境变量进行配置，支持阿里云 DashScope API。
|
||
|
||
### 必需的环境变量
|
||
|
||
在 `.env` 文件或系统环境变量中配置以下参数：
|
||
|
||
```bash
|
||
# AI API 密钥（阿里云 DashScope API Key）
|
||
AI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxx
|
||
|
||
# AI API 基础 URL（阿里云 DashScope 兼容 OpenAI 格式接口）
|
||
AI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
|
||
|
||
# AI 模型名称
|
||
# 可选值：
|
||
# - qwen-turbo（快速，推荐日常使用）
|
||
# - qwen-plus（增强，平衡性能和成本）
|
||
# - qwen-max（最强，高质量输出）
|
||
# - qwen-long（长文本，支持超长上下文）
|
||
AI_MODEL=qwen-turbo
|
||
```
|
||
|
||
### 配置示例
|
||
|
||
#### 1. 开发环境配置 (.env)
|
||
|
||
```bash
|
||
# 阿里云 DashScope 配置
|
||
AI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||
AI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
|
||
AI_MODEL=qwen-turbo
|
||
```
|
||
|
||
#### 2. 生产环境配置 (.env.production)
|
||
|
||
```bash
|
||
# 阿里云 DashScope 配置（生产环境使用增强版）
|
||
AI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||
AI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
|
||
AI_MODEL=qwen-plus
|
||
```
|
||
|
||
### 阿里云模型对比
|
||
|
||
| 模型 | 速度 | 质量 | 成本 | 适用场景 |
|
||
|------|------|------|------|----------|
|
||
| qwen-turbo | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 日常对话、简单分析 |
|
||
| qwen-plus | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 复杂分析、专业任务 |
|
||
| qwen-max | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | 高质量输出、关键任务 |
|
||
| qwen-long | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | 长文本处理、文档分析 |
|
||
|
||
### 代码中使用
|
||
|
||
```javascript
|
||
// 使用默认配置（从环境变量读取）
|
||
const AIService = require('./services/ai_service.js');
|
||
const aiService = AIService.getInstance();
|
||
|
||
// 使用自定义配置
|
||
const aiService = AIService.createInstance({
|
||
apiKey: 'sk-custom-key',
|
||
baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
|
||
model: 'qwen-plus',
|
||
timeout: 60000
|
||
});
|
||
```
|
||
|
||
### API 认证格式
|
||
|
||
阿里云 DashScope API 使用标准的 Bearer Token 认证：
|
||
|
||
```
|
||
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxx
|
||
```
|
||
|
||
### 注意事项
|
||
|
||
1. **API Key 安全**：
|
||
- 不要将 API Key 硬编码在代码中
|
||
- 不要将 `.env` 文件提交到版本控制
|
||
- 生产环境使用独立的 API Key
|
||
|
||
2. **模型选择建议**：
|
||
- 开发/测试：使用 `qwen-turbo`（成本低）
|
||
- 生产环境：使用 `qwen-plus`（性能平衡）
|
||
- 关键业务：使用 `qwen-max`（质量最高）
|
||
|
||
3. **速率限制**：
|
||
- 注意 API 的 QPM（每分钟请求数）限制
|
||
- 根据套餐调整并发数量
|
||
- 实现重试和错误处理机制
|
||
|
||
4. **成本控制**：
|
||
- 监控 Token 使用量
|
||
- 设置合理的 `max_tokens` 限制
|
||
- 定期查看账单和用量统计
|
||
|
||
### 获取 API Key
|
||
|
||
1. 访问阿里云控制台：https://dashscope.console.aliyun.com/
|
||
2. 进入 API-KEY 管理
|
||
3. 创建新的 API Key
|
||
4. 复制 API Key 并保存到环境变量
|
||
|
||
### 故障排查
|
||
|
||
#### 问题 1：Authentication Fails
|
||
```
|
||
错误：auth header format should be Bearer sk-...
|
||
解决：检查 AI_API_KEY 是否正确配置
|
||
```
|
||
|
||
#### 问题 2：连接超时
|
||
```
|
||
错误：timeout of 30000ms exceeded
|
||
解决：
|
||
1. 检查网络连接
|
||
2. 增加 timeout 配置
|
||
3. 检查 AI_BASE_URL 是否正确
|
||
```
|
||
|
||
#### 问题 3：模型不存在
|
||
```
|
||
错误：model not found
|
||
解决：检查 AI_MODEL 配置，确保使用支持的模型名称
|
||
```
|
||
|
||
### 迁移指南
|
||
|
||
如果之前使用其他 AI 服务（如 DeepSeek），迁移步骤：
|
||
|
||
1. 更新环境变量配置
|
||
2. 修改 API_BASE_URL
|
||
3. 更新模型名称
|
||
4. 测试 AI 调用功能
|
||
5. 验证响应格式
|
||
|
||
---
|
||
|
||
**配置更新时间**: 2025-12-27
|
||
**维护者**: 系统管理员
|