> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/quickstart/dashscope · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# 接入 DashScope 上游

DashScope 是阿里云的 AI 服务，涵盖文本生成、多模态、文本向量、重排序、ASR 等多种模型。本章教你建一个 `dashscope` 上游 + `qwen-turbo` 模型，用 OpenAI SDK 调用，并简单覆盖其他 `kind` 变体。

## 前置

- 网关已运行（`http://localhost:7890`），能登录控制台
- 已设 `ENCRYPTION_KEY`——下面要保存的上游 API key 与访问密钥都落库前加密，没设会在保存时报 `encryption_key not set in config`。见 [Docker 单机跑通 → 前置](/zh-CN/quickstart/docker-single-node.md#prereq)
- 一个阿里云 DashScope API key

## 1. 建 dashscope 上游

控制台 → **上游服务** → **新建**：

| 字段 | 值 | 说明 |
|------|-----|------|
| 名称 | `dashscope` | 上游唯一标识 |
| 协议 | `dashscope` | 决定执行器与请求 schema |
| 基础 URL | `https://dashscope.aliyuncs.com` | 上游真实地址，结尾不带 `/` |
| API Key | 阿里云 key | 点「添加」可加多把，按权重分布 |
| 启用 | ✓ | |

保存。

## 2. 建 qwen-turbo 模型

在上游 `dashscope` 行点 **展开** → 模型子表 → **新建模型**：

| 字段 | 值 | 说明 |
|------|-----|------|
| 名称 | `qwen-turbo` | 对外暴露给客户端的模型名 |
| 上游 | `dashscope` | 选刚建的上游 |
| 上游模型 ID | `qwen-turbo` | DashScope 真实模型名 |
| 协议 | `dashscope`（继承上游） | 也可在模型层覆盖 |
| 启用 | ✓ | |

保存。

> DashScope 不同类型模型有不同端点，由 `kind` 字段选择。文本生成（如 `qwen-turbo`、`qwen-plus`、`qwen-max`）走默认端点 `/api/v1/services/aigc/text-generation/generation`，不需要指定 `kind`。其他变体见下表。

## 3. 配密钥组放行

控制台 → **访问密钥** → **密钥组** 页签 → **新建**：

| 字段 | 值 | 说明 |
|------|-----|------|
| 名称 | `default` | 分组名 |
| 模型 | 选 `qwen-turbo`，或 `*`（全部） | 决定该组密钥能调哪些模型 |
| 启用 | ✓ | |

## 4. 签发访问密钥

控制台 → **访问密钥** → **新建**：

| 字段 | 值 | 说明 |
|------|-----|------|
| 名称 | `my-app-key` | 密钥的标识，用于管理与审计 |
| API 密钥 | 点「生成」 | 自动生成一串，客户端调用时带的凭证 |
| 分组 | `default` | 决定这把密钥能访问哪些模型 |
| 启用 | ✓ | |

## 5. 用 OpenAI SDK 调用

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:7890/v1",
    api_key="<你的访问密钥>",
)

resp = client.chat.completions.create(
    model="qwen-turbo",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)
```

网关自动把 OpenAI 请求格式翻译成 DashScope 格式，发给 `https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation`，响应翻译回 OpenAI 格式。

## 6. 或用 curl

```bash
curl http://localhost:7890/v1/chat/completions \
  -H "Authorization: Bearer <你的访问密钥>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-turbo",
    "messages": [{"role":"user","content":"你好"}]
  }'
```

收到回复即跑通。

## 其他 kind 变体

DashScope 文本生成走默认端点，其他类型模型用 `kind` 字段切换端点。下表概览，完整字段说明见 [上游与模型字段](/zh-CN/reference/upstreams-models-fields.md)。

| kind | 端点 | 适用模型 |
|------|------|---------|
| （默认） | `/api/v1/services/aigc/text-generation/generation` | qwen-turbo、qwen-plus、qwen-max |
| `dashscope-multimodal` | `/api/v1/services/aigc/multimodal-generation/generation` | qwen-vl-chat-v1、qwen-vl-plus、qwen-audio、fun-asr-flash |
| `dashscope-text-embedding` | `/api/v1/services/embeddings/text-embedding/text-embedding` | text-embedding-v4 |
| `dashscope-rerank` | `/api/v1/services/rerank/text-rerank/text-rerank` | gte-rerank |
| `dashscope-audio-asr` | `/api/v1/services/audio/asr/transcription`（异步） | fun-asr |

> 后三行（embedding / rerank / ASR）的端点挂在**百炼 MaaS 域名**（`https://<workspace-id>.cn-beijing.maas.aliyuncs.com`）下，与文本生成的 `https://dashscope.aliyuncs.com` 不同域，需单独建一个 upstream——见下方[文本向量（独立 upstream）](#text-embedding)。

### 视频生成（direct_path） {#video-generation}

视频生成等异步模型需要 `direct_path = true` + 完整端点 URL：

```json
{
  "name": "wanx2.1-t2v",
  "upstream": ["dashscope"],
  "upstream_model_id": "wanx2.1-t2v",
  "protocol": "dashscope",
  "direct_path": true,
  "base_url": "https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis"
}
```

异步模型还需在 `extra_config` 设置：`{"dashscope": {"async_mode": true}}`

### 文本向量（独立 upstream） {#text-embedding}

文本向量 / rerank / ASR 模型走百炼 MaaS 域名，与文本生成的 `https://dashscope.aliyuncs.com` 不同域，所以要先建一个独立 upstream，再在它下面建模型。

**1）建 upstream `dashscope-maas`**（控制台 → 上游服务 → 新建）：

| 字段 | 值 | 说明 |
|------|-----|------|
| 名称 | `dashscope-maas` | 上游唯一标识，下面模型的 `upstream` 就引用它 |
| 协议 | `dashscope` | 与文本生成相同 |
| 基础 URL | `https://<workspace-id>.cn-beijing.maas.aliyuncs.com` | 百炼 MaaS 域名，把 `<workspace-id>` 换成你的百炼工作空间 ID |
| API Key | 阿里云 key | 与文本生成同一把即可 |
| 启用 | ✓ | |

**2）在该 upstream 下建文本向量模型**：

```json
{
  "name": "text-embedding-v4",
  "upstream": ["dashscope-maas"],
  "upstream_model_id": "text-embedding-v4",
  "protocol": "dashscope",
  "kind": "dashscope-text-embedding"
}
```

客户端用标准 OpenAI `/v1/embeddings` 协议发请求，网关自动翻译为 DashScope 格式。rerank / ASR 同理挂在 `dashscope-maas` 下，`kind` 分别填 `dashscope-rerank` / `dashscope-audio-asr`。

## 透传 vs 翻译

DashScope 客户端可走两路：

- **透传**：`POST /v1/services/{*rest}`，请求体原样发给 DashScope 上游
- **翻译**：`POST /v1/chat/completions`，网关把 OpenAI 格式翻译成 DashScope 格式

透传适合 DashScope 原生 SDK 或想完全绕过翻译的场景；翻译适合 OpenAI SDK 直接接入。

## 常见问题

**Q：客户端报 400 unsupported_feature？**
该「客户端协议 → 上游协议」组合没有翻译器。检查 [协议互通矩阵](/zh-CN/reference/protocol-matrix.md)。OpenAI → dashscope 是支持的。

**Q：客户端报 401 / 403 / 404？**
- 401：访问密钥没带对
- 403 model_access_denied：密钥组「模型」列表没包含 `qwen-turbo`
- 404 model_not_found：模型名拼错，或被设了 `hide_name`

**Q：客户端报 502 bad_gateway？**
上游不通。检查 DashScope 的 `base_url`（`https://dashscope.aliyuncs.com`，结尾不带 `/`）、API key 是否正确、是否在阿里云白名单里。

**Q：调视频/图像生成模型报 404？**
异步模型需要 `direct_path = true` + 完整端点 URL + `extra_config.dashscope.async_mode = true`。详见 [上游与模型字段](/zh-CN/reference/upstreams-models-fields.md)。

**下一步**：[上游与模型字段](/zh-CN/reference/upstreams-models-fields.md) 看上游/模型完整字段与所有 `kind` 变体；[端点 · 认证 · 协议互通](/zh-CN/reference/endpoints.md) 看完整端点；[客户端接入与网关差异](/zh-CN/reference/clients-and-gateway-diffs.md) 看各 SDK 接法。