# 阿里云 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 大模型服务！** 🎉