282 lines
5.5 KiB
Markdown
282 lines
5.5 KiB
Markdown
# 阿里云 DashScope 配置指南
|
||
|
||
## 📋 概述
|
||
|
||
阿里云 DashScope 是阿里巴巴推出的大语言模型服务平台，提供通义千问等多个大模型。本文档介绍如何在 MCP Client Vue 中配置和使用 DashScope。
|
||
|
||
---
|
||
|
||
## 🚀 快速配置
|
||
|
||
### 1. 获取 API Key
|
||
|
||
1. 访问 [阿里云 DashScope 控制台](https://dashscope.console.aliyun.com/)
|
||
2. 登录阿里云账号
|
||
3. 进入"API-KEY管理"
|
||
4. 创建或获取现有的 API Key
|
||
|
||
### 2. 添加服务
|
||
|
||
在 MCP Client Vue 中：
|
||
|
||
```
|
||
服务名称: 阿里大模型
|
||
服务类型: 阿里云 DashScope
|
||
服务地址: https://dashscope.aliyuncs.com/compatible-mode/v1
|
||
API Key: sk-xxxxxxxxxxxxxxxxxxxx
|
||
```
|
||
|
||
**重要提示**:
|
||
- 服务地址必须使用 `/compatible-mode/v1` 端点（OpenAI 兼容模式）
|
||
- API Key 格式：`sk-` 开头的密钥
|
||
|
||
### 3. 测试连接
|
||
|
||
点击"连接"按钮，系统将：
|
||
- ✅ 验证 API Key
|
||
- ✅ 获取可用模型列表
|
||
- ✅ 显示连接状态
|
||
|
||
---
|
||
|
||
## 🎯 支持的模型
|
||
|
||
### 通义千问系列
|
||
|
||
DashScope 提供多个通义千问模型：
|
||
|
||
- **qwen-turbo** - 快速响应，适合日常对话
|
||
- **qwen-plus** - 平衡性能和效果
|
||
- **qwen-max** - 最强性能，适合复杂任务
|
||
- **qwen-max-longcontext** - 支持长文本（最大30K tokens）
|
||
|
||
### 其他模型
|
||
|
||
- **qwen-vl-plus** - 视觉理解模型
|
||
- **qwen-vl-max** - 高级视觉模型
|
||
- **qwen-audio-turbo** - 音频处理模型
|
||
|
||
---
|
||
|
||
## 🔧 API 端点说明
|
||
|
||
### 兼容模式端点
|
||
|
||
DashScope 提供 OpenAI 兼容的 API 端点：
|
||
|
||
```
|
||
基础 URL: https://dashscope.aliyuncs.com/compatible-mode/v1
|
||
```
|
||
|
||
#### 可用端点
|
||
|
||
1. **模型列表**
|
||
```
|
||
GET /compatible-mode/v1/models
|
||
Authorization: Bearer {api_key}
|
||
```
|
||
|
||
2. **聊天补全**
|
||
```
|
||
POST /compatible-mode/v1/chat/completions
|
||
Authorization: Bearer {api_key}
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"model": "qwen-turbo",
|
||
"messages": [...]
|
||
}
|
||
```
|
||
|
||
### 原生模式端点
|
||
|
||
如果需要使用 DashScope 原生 API（非兼容模式）：
|
||
|
||
```
|
||
基础 URL: https://dashscope.aliyuncs.com/api/v1
|
||
```
|
||
|
||
**注意**: 当前实现使用兼容模式，无需额外配置。
|
||
|
||
---
|
||
|
||
## 💡 配置示例
|
||
|
||
### 基础配置
|
||
|
||
```json
|
||
{
|
||
"name": "通义千问",
|
||
"type": "dashscope",
|
||
"url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
|
||
"apiKey": "sk-your-dashscope-api-key"
|
||
}
|
||
```
|
||
|
||
### 带自定义配置
|
||
|
||
如果需要自定义超时等参数：
|
||
|
||
```json
|
||
{
|
||
"name": "通义千问（自定义）",
|
||
"type": "dashscope",
|
||
"url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
|
||
"apiKey": "sk-your-dashscope-api-key",
|
||
"customConfig": "{\"timeout\": 60000}"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 故障排查
|
||
|
||
### 问题1: 401 未授权
|
||
|
||
**错误信息**:
|
||
```
|
||
HTTP 401: {"error":{"message":"You didn't provide an API key..."}}
|
||
```
|
||
|
||
**解决方案**:
|
||
1. ✅ 确认服务类型选择"阿里云 DashScope"
|
||
2. ✅ 检查 API Key 是否正确（以 `sk-` 开头）
|
||
3. ✅ 确认 API Key 未过期
|
||
4. ✅ 验证服务地址包含 `/compatible-mode/v1`
|
||
|
||
### 问题2: 模型列表为空
|
||
|
||
**可能原因**:
|
||
- API 端点格式错误
|
||
- 账户未开通相关服务
|
||
|
||
**解决方案**:
|
||
1. 确认使用兼容模式端点
|
||
2. 在阿里云控制台检查服务状态
|
||
3. 查看账户是否有可用额度
|
||
|
||
### 问题3: 请求超时
|
||
|
||
**解决方案**:
|
||
1. 检查网络连接
|
||
2. 尝试增加超时时间
|
||
3. 使用国内网络访问
|
||
|
||
---
|
||
|
||
## 📊 API 响应格式
|
||
|
||
### 模型列表响应
|
||
|
||
```json
|
||
{
|
||
"data": [
|
||
{
|
||
"id": "qwen-turbo",
|
||
"object": "model",
|
||
"created": 1234567890,
|
||
"owned_by": "dashscope"
|
||
},
|
||
{
|
||
"id": "qwen-plus",
|
||
"object": "model",
|
||
"created": 1234567890,
|
||
"owned_by": "dashscope"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 聊天响应
|
||
|
||
```json
|
||
{
|
||
"id": "chatcmpl-xxxxx",
|
||
"object": "chat.completion",
|
||
"created": 1234567890,
|
||
"model": "qwen-turbo",
|
||
"choices": [
|
||
{
|
||
"index": 0,
|
||
"message": {
|
||
"role": "assistant",
|
||
"content": "你好！我是通义千问..."
|
||
},
|
||
"finish_reason": "stop"
|
||
}
|
||
],
|
||
"usage": {
|
||
"prompt_tokens": 10,
|
||
"completion_tokens": 20,
|
||
"total_tokens": 30
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 安全建议
|
||
|
||
1. **保护 API Key**
|
||
- 不要在代码中硬编码
|
||
- 不要提交到版本控制
|
||
- 定期轮换密钥
|
||
|
||
2. **访问控制**
|
||
- 在阿里云控制台设置 IP 白名单
|
||
- 启用访问频率限制
|
||
- 监控异常使用
|
||
|
||
3. **费用控制**
|
||
- 设置每日调用上限
|
||
- 启用预算告警
|
||
- 定期检查账单
|
||
|
||
---
|
||
|
||
## 📚 参考文档
|
||
|
||
- [DashScope 官方文档](https://help.aliyun.com/zh/dashscope/)
|
||
- [OpenAI 兼容接口](https://help.aliyun.com/zh/dashscope/developer-reference/compatibility-of-openai-with-dashscope/)
|
||
- [模型列表](https://help.aliyun.com/zh/dashscope/developer-reference/model-square/)
|
||
- [计费说明](https://help.aliyun.com/zh/dashscope/developer-reference/tongyi-qianwen-metering-and-billing/)
|
||
|
||
---
|
||
|
||
## 🎯 最佳实践
|
||
|
||
### 1. 模型选择
|
||
|
||
- **日常对话**: qwen-turbo（速度快，成本低）
|
||
- **复杂任务**: qwen-max（效果好）
|
||
- **长文本**: qwen-max-longcontext（支持更长上下文）
|
||
|
||
### 2. 性能优化
|
||
|
||
- 使用流式输出提升响应速度
|
||
- 合理设置 max_tokens 控制成本
|
||
- 缓存常用响应
|
||
|
||
### 3. 错误处理
|
||
|
||
- 实现重试机制
|
||
- 处理速率限制
|
||
- 记录错误日志
|
||
|
||
---
|
||
|
||
## ✅ 验证清单
|
||
|
||
配置完成后，确认以下项目：
|
||
|
||
- [ ] API Key 已正确配置
|
||
- [ ] 服务类型选择"阿里云 DashScope"
|
||
- [ ] URL 使用兼容模式端点
|
||
- [ ] 连接测试成功
|
||
- [ ] 能够获取模型列表
|
||
- [ ] 模型数量大于 0
|
||
|
||
---
|
||
|
||
**享受使用阿里云 DashScope 大模型服务！** 🎉
|