gavin/map-client-vue
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 3 Wiki Activity
Files
7ce2366639f3d97322274c2685f0c859f14dbc37
map-client-vue/DASHSCOPE_CONFIG.md
douboer 4f5eea604e update at 2025-10-14 21:52:11
2025-10-14 21:52:11 +08:00

5.5 KiB
Raw Blame History

阿里云 DashScope 配置指南

📋 概述

阿里云 DashScope 是阿里巴巴推出的大语言模型服务平台，提供通义千问等多个大模型。本文档介绍如何在 MCP Client Vue 中配置和使用 DashScope。

🚀 快速配置

1. 获取 API Key

  1. 访问 阿里云 DashScope 控制台
  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

注意: 当前实现使用兼容模式，无需额外配置。

💡 配置示例

基础配置

{
  "name": "通义千问",
  "type": "dashscope",
  "url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "apiKey": "sk-your-dashscope-api-key"
}

带自定义配置

如果需要自定义超时等参数：

{
  "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 响应格式

模型列表响应

{
  "data": [
    {
      "id": "qwen-turbo",
      "object": "model",
      "created": 1234567890,
      "owned_by": "dashscope"
    },
    {
      "id": "qwen-plus",
      "object": "model",
      "created": 1234567890,
      "owned_by": "dashscope"
    }
  ]
}

聊天响应

{
  "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. 费用控制

    • 设置每日调用上限
    • 启用预算告警
    • 定期检查账单

📚 参考文档

🎯 最佳实践

1. 模型选择

  • 日常对话: qwen-turbo（速度快，成本低）
  • 复杂任务: qwen-max（效果好）
  • 长文本: qwen-max-longcontext（支持更长上下文）

2. 性能优化

  • 使用流式输出提升响应速度
  • 合理设置 max_tokens 控制成本
  • 缓存常用响应

3. 错误处理

  • 实现重试机制
  • 处理速率限制
  • 记录错误日志

✅ 验证清单

配置完成后，确认以下项目：

  • API Key 已正确配置
  • 服务类型选择"阿里云 DashScope"
  • URL 使用兼容模式端点
  • 连接测试成功
  • 能够获取模型列表
  • 模型数量大于 0

享受使用阿里云 DashScope 大模型服务！ 🎉