update at 2025-10-14 21:52:11
This commit is contained in:
douboer
281
DASHSCOPE_CONFIG.md
Normal file
281
DASHSCOPE_CONFIG.md
Normal file
@@ -0,0 +1,281 @@
|
||||
# 阿里云 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 大模型服务！** 🎉
|
||||
Reference in New Issue
Block a user