Qwen（阿里云）

Qwen 是阿里云的语言和多模态模型系列，通过百炼 Model Studio（又称 DashScope）提供服务。应用通过稳定的 AISIX 别名调用 Qwen，网关负责保管 DashScope 凭证。

本指南涵盖通过同一个 Model Studio 服务提供方密钥承载的 Qwen Chat Completions、原生 Responses 和 Wan 视频任务。

准备工作

开始前，请准备以下内容：

• 一套 AISIX 环境：
  • 对于 AISIX Enterprise 或 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 AISIX Enterprise，请按照 AISIX Enterprise 快速入门操作。如需申请 AISIX Cloud 访问权限，请联系 API7。
  • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
• 从 Model Studio 国际站控制台或中国大陆 Model Studio 控制台获取的、适用于计划使用区域的 DashScope API Key。
• curl 和 jq。

使用 AISIX Enterprise 或 AISIX Cloud 配置

导出控制面连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不含尾部斜杠
# 本地 AISIX Enterprise 快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

为由 Qwen 提供支持的 Chat Completions 和原生 Responses 创建服务提供方密钥、模型别名和调用方 API Key。示例使用新加坡区域端点。

由于阿里云百炼 Model Studio 提供 OpenAI 兼容端点，AISIX 通过 openai 适配器连接，并使用创建凭证所在区域的 DashScope API 根地址。

创建服务提供方密钥

DashScope API Key 和端点具有区域属性。AISIX 目录为国际站和中国大陆分别提供服务提供方 ID，默认 API 根地址如下：

服务提供方 ID	默认 API 根地址	范围
alibaba	https://dashscope-intl.aliyuncs.com/compatible-mode/v1	国际站，使用新加坡端点
alibaba-cn	https://dashscope.aliyuncs.com/compatible-mode/v1	中国大陆，使用北京端点

一个区域签发的 API Key 无法用于另一区域的端点。如果需要同时路由到两个区域，请为每个区域创建一个服务提供方密钥。国际流量使用 alibaba，中国大陆流量使用 alibaba-cn，使用量记录和成本报告归属到匹配的目录。

阿里云建议生产环境使用工作区专属域名。上述共享 DashScope 根地址仍可用于现有集成，但专属域名提供工作区隔离和更高并发。下方示例使用新加坡形式；请将 YOUR_WORKSPACE_ID 替换为签发 API Key 的工作区。其他区域请使用 Model Studio 控制台中的匹配域名。

创建用于存储 DashScope 凭证和 API 根地址的服务提供方密钥，并获取其 ID：

# 请替换为实际值
export DASHSCOPE_API_KEY="YOUR_PROVIDER_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "qwen-prod",
    "provider": "alibaba",
    "api_key": "'"${DASHSCOPE_API_KEY}"'",
    "api_base": "https://YOUR_WORKSPACE_ID.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
    "apis": {
      "responses": {}
    },
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

❶ provider 为 alibaba，即 Model Studio 国际区域的目录服务提供方 ID。中国大陆区域请使用 alibaba-cn。AISIX Cloud Admin API 会从目录服务提供方派生适配器；仅 BYO 服务提供方密钥接受适配器字段。

❷ api_key 存储 DashScope API Key。其行为遵循服务提供方密钥中的凭证处理方式。

❸ api_base 已包含 /compatible-mode/v1 路径。请使用签发 API Key 的工作区和区域。省略该字段时，AISIX Cloud Admin API 会为 alibaba 使用共享国际根地址，为 alibaba-cn 使用共享北京根地址；这些目录默认值不会选择工作区专属域名。

❹ apis.responses 声明 Model Studio 在同一区域根地址上提供 Responses API。随后 AISIX 会使用 Qwen 原生格式，而不是通过 Chat Completions 转换请求。

创建模型

创建调用方将在请求中发送的模型别名，并获取其 ID：

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "qwen-plus-prod",
    "model_name": "qwen3.7-plus",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

❶ display_name 是调用方在 model 中发送的别名。

❷ model_name 是 Qwen 模型 ID。此示例使用当前的 qwen3.7-plus 模型；创建别名前，请在 Model Studio 模型列表中检查该模型在目标区域的可用性。

❸ provider_key_id 将别名关联到 Qwen 服务提供方密钥。

创建调用方 API Key

创建可访问模型别名的调用方 API Key 资源。明文密钥由服务器生成，并仅在响应中返回一次：

AISIX_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "qwen-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

allowed_models 值必须引用已获取的模型 ID。请妥善保存明文密钥；之后无法再次获取。

新资源会自动投射到已关联的网关，因此该路由几乎可以立即调用。

使用开源 AISIX 网关配置

导出上游凭证，并选择应用将发送给网关的调用方 API Key：

export DASHSCOPE_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

对于新网关，请使用此完整资源文件。对于现有网关，请将这些条目合并到其当前文件中，并保留其他资源：

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: "qwen-prod"
    provider: "alibaba"
    adapter: "openai"
    api_key: ${DASHSCOPE_API_KEY}
    api_base: "https://YOUR_WORKSPACE_ID.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
    apis:
      responses: {}

models:
  - display_name: "qwen-plus-prod"
    provider: "alibaba"
    model_name: "qwen3.7-plus"
    provider_key: "qwen-prod"

api_keys:
  - display_name: "qwen-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "qwen-plus-prod"

如果 AISIX 安装在本地，请在加载文件前进行验证：

aisix validate --resources resources.yaml

验证后，在网关进程环境中提供文件引用的环境变量，再启动网关。仅当这些变量已经可供进程使用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两条命令中使用 -e 传入它引用的每个环境变量。资源加载后，准备下文共用的验证请求：

export AISIX_API_KEY="$CALLER_API_KEY"

验证服务提供方连接

导出 AISIX 网关 Origin：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

通过 AISIX 代理发送 Responses 请求：

curl -sS -X POST "$AISIX_PROXY/v1/responses" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-plus-prod",
    "input": "Say hello from Qwen."
  }'

AISIX 会把请求发送到 Qwen 原生 Responses 端点，在上游请求中将别名替换为 Model Studio 模型 ID，并在响应中恢复该别名。请在 Model Studio 用量页面中确认该请求。如果请求因上游身份认证错误而失败，请检查服务提供方密钥凭证，并确认密钥与基础 URL 使用同一区域。

原生 Responses 路径支持流式传输、previous_response_id、推理强度和服务提供方托管工具，但具体可用性因模型和区域而异。

通过透传使用原生 Messages

Model Studio 还在另一个区域 /apps/anthropic Base 下提供 Anthropic 兼容 Messages API。该 API 接受 Bearer 或 x-api-key 身份认证，但仅提供 /v1/messages 文档，没有 /v1/messages/count_tokens。服务提供方密钥应省略 apis.messages，因为 AISIX 中的该声明覆盖两条路由。

应用需要 Qwen 原生 Messages 格式时，请配置专用透传路由，不要复用通用服务提供方前缀。将路由绑定到同一区域的 Qwen 服务提供方密钥，使 AISIX 能够注入其凭证。国际站示例使用 /passthrough/alibaba-messages 前缀，目标为 https://YOUR_WORKSPACE_ID.ap-southeast-1.maas.aliyuncs.com/apps/anthropic；中国大陆示例使用 /passthrough/alibaba-cn-messages 前缀，目标为 https://YOUR_WORKSPACE_ID.cn-beijing.maas.aliyuncs.com/apps/anthropic。中国区域端点参考列出了共享和工作区专属 Base。

调用 /passthrough/alibaba-messages/v1/messages 或 /passthrough/alibaba-cn-messages/v1/messages，并发送 qwen3.7-plus 等上游模型 ID，因为透传不会重写 AISIX 别名。Count Tokens 仍不可用。

使用 Wan 和 HappyHorse 生成视频

同一个服务提供方密钥即可驱动网关建模的视频路由。创建第二个别名，指向 Model Studio 的文生视频模型——可以是 Wan 2.7 模型，也可以是 HappyHorse 文生视频模型，例如 happyhorse-1.1-t2v。两个系列使用同一组 DashScope 异步端点，因此下面的流程完全相同，区别只在上游模型名称：

在 AISIX Enterprise 和 AISIX Cloud 中创建视频别名和仅限该别名的调用方 Key：

VIDEO_MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "wan-video-prod",
    "model_name": "wan2.7-t2v",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$VIDEO_MODEL_ID"

VIDEO_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "qwen-video-caller",
    "allowed_models": ["'"${VIDEO_MODEL_ID}"'"]
  }' | jq -r '.plaintext')

对于开源 AISIX 网关，请将 wan-video-prod 添加到现有 models 集合。将现有 qwen-caller 条目替换为下面更新后的条目，使其允许两个模型别名。保留无关条目和集合：

resources.yaml（视频模型访问）

models:
  - display_name: "wan-video-prod"
    provider: "alibaba"
    model_name: "wan2.7-t2v"
    provider_key: "qwen-prod"

api_keys:
  - display_name: "qwen-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "qwen-plus-prod"
      - "wan-video-prod"

按上文所述验证并重载或重启声明式资源文件，然后使用现有调用方 Key 发起视频请求：

export VIDEO_API_KEY="$CALLER_API_KEY"

提交任务：

curl -sS -X POST "$AISIX_PROXY/v1/videos" \
  -H "Authorization: Bearer ${VIDEO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan-video-prod",
    "prompt": "A paper boat drifts down a rain-soaked street at dusk.",
    "seconds": 5
  }'

在为此路由编写脚本前，需要了解以下六项服务提供方特定行为：

• 只有 alibaba 这个 provider 值会被分发。 alibaba-cn 不在视频路由的允许列表内，因此中国内地区域的别名在提交时会返回未实现错误。如需访问中国内地区域的视频 API，请配置一条 target_url 指向该区域原生 Model Studio 地址的透传路由。
• Chat 的 api_base 会原样复用。 AISIX 会去掉一个 /compatible-mode/v1、/api/v1 或 /v1 后缀，从中派生服务商根地址，并在其下组成 DashScope 的原生任务路径。已经为 Qwen Chat 流量配置的服务提供方密钥无需更改即可用于视频路由，异步提交所需的请求头也由网关自动补上。
• size 对应的是较早的 Wan 协议。 seconds 会作为整数 parameters.duration 转发，size 则会以服务提供方使用的 WIDTH*HEIGHT 写法作为 parameters.size 转发。该参数属于 Wan 2.6 及更早版本；Wan 2.7 模型已改用 resolution 和 ratio 档位，而 AISIX 不会判断别名指向哪个系列，只会原样转发你发送的值。因此 Wan 2.7 别名请像上面的示例一样自行省略 size，由服务提供方使用默认值。
• HappyHorse 文生视频走同一条路由。 happyhorse-1.1-t2v 和 happyhorse-1.0-t2v 与 Wan 使用相同的提交端点、轮询端点和任务状态，输出尺寸同样用 resolution 和 ratio 档位表达——因此与 Wan 2.7 一样，请省略 size，由服务提供方使用默认值。图生视频（happyhorse-1.1-i2v）、参考生视频和视频编辑属于 Model Studio 的另外几个 API，其参考素材输入不在建模路由的承载范围内，请像下面的其他原生字段一样通过透传路由访问。Runway 平台上也托管了 HappyHorse 模型，那条集成路径参见 RunwayML。
• 服务提供方原生视频字段需要透传路由。 标准化请求只建模 prompt、seconds 和 size；其他字段会被忽略。若要发送 negative_prompt、seed，或 Wan 2.7 的 resolution 和 ratio 等原生字段，请使用一条指向 DashScope 原生根地址的透传路由，该根地址与本页 /passthrough/alibaba 示例假定的 OpenAI 兼容根地址不同。若一条透传路由认领 /passthrough/alibaba-video 前缀、并将 target_url 设为 https://dashscope-intl.aliyuncs.com/api/v1，则提交路径为 /passthrough/alibaba-video/services/aigc/video-generation/video-synthesis，轮询路径为 /passthrough/alibaba-video/tasks/{id}。请发送原生正文和准确的上游模型 ID，并自行设置服务提供方要求的异步提交请求头。透传不会返回统一的 AISIX 视频对象或网关编码的任务 ID。
• 已完成的视频通过重定向交付。 GET /v1/videos/{id}/content 返回 302，并在 Location 响应头中提供指向服务提供方签名下载 URL 的地址。字节数据会从 Model Studio 存储直接传输到客户端，不会经过网关，因此下载时请跟随重定向，例如使用 curl 的 -L 参数。

完整的提交、轮询和下载工作流（包括状态语义和轮询时的限流行为）请参阅视频生成。

端点覆盖

Qwen 服务提供方密钥使用 openai 适配器，但路由支持还取决于 AISIX 服务提供方规则，以及配置的 Model Studio 基础地址上可用的 API：

路由	使用 Qwen 模型别名时的行为
/v1/chat/completions	支持缓冲和流式传输。
/v1/messages	通过转换为 Chat Completions 支持。原生格式请使用上文所述的区域 Messages 透传路由。由于 Model Studio 未提供该路由的文档，请将 /v1/messages/count_tokens 视为不可用。
/v1/responses	由于本指南声明了 apis.responses，请求会发送到阿里云原生 Responses API。如果没有此声明，AISIX 会使用 Responses 桥接。
/v1/embeddings	别名指向同一区域可用的文本嵌入模型（例如 text-embedding-v4）时支持。AISIX 会将 /embeddings 追加到配置的 OpenAI 兼容基础地址。
/v1/videos 及其状态和内容路由	仅当模型服务提供方值恰好为 alibaba 时支持；alibaba-cn 不在视频路由允许列表中。AISIX 会将请求映射到 DashScope 异步文生视频 API，该 API 同时服务 Wan 和 HappyHorse 文生视频模型。对于当前 Wan 2.7 和 HappyHorse 模型，请省略 size，因为 AISIX 的 size 映射面向较早的 Wan API。参见使用 Wan 和 HappyHorse 生成视频。需要原生 resolution、ratio 或多模态字段时请使用透传路由；对于 alibaba-cn，这要求一条以 Model Studio 原生基础地址为目标的路由。
/v1/audio/*	本页配置的 OpenAI 兼容基础地址不支持。Model Studio 音频 API 使用服务提供方原生路由和请求结构。
/v1/images/generations	不支持。该路由只接受配置的服务提供方为 openai 的模型；Model Studio 图片 API 需要透传路由。
/v1/rerank	不支持。该路由只接受 openai、cohere 和 jina 服务提供方值；Model Studio 重排模型使用服务提供方原生 API。
/passthrough/alibaba/*rest 和 /passthrough/alibaba-cn/*rest	通过已配置的透传路由可用于 OpenAI 兼容根地址下 AISIX 尚未建模的原生 Model Studio API。透传路由不会重写请求体中面向调用方的别名，并会增量中继上游 SSE。哪些请求形态会记录 Token 用量，参见信封识别与用量。原生 DashScope API（例如原生 rerank 和多模态向量）使用 /api/v1 根地址，参见阿里云原生 rerank 示例。原生 Messages 和视频 API 使用不同根地址，因此使用单独前缀。

/passthrough/alibaba 和 /passthrough/alibaba-cn 前缀假定目标为对应的 OpenAI 兼容 Model Studio 根地址；/passthrough/alibaba-messages 和 /passthrough/alibaba-cn-messages 前缀假定目标为对应区域的 /apps/anthropic 根地址，而 /passthrough/alibaba-video 假定目标为上文所述的 DashScope 视频根地址。请分别配置每条路由，并在调用方 Key 的 allowed_routes 上授予其名称。

完整端点和服务提供方矩阵请参阅服务提供方兼容性。

后续步骤

你已将 AISIX 连接到 Qwen，并验证了模型别名。接下来可阅读以下指南：

• 模型别名：为此别名配置路由、重试行为或成本元数据。
• 路由与故障转移：在 Qwen 区域之间，或在 Qwen 与其他服务提供方之间进行故障转移。
• 视频生成：按照提交、轮询和下载工作流使用受支持的 Wan 文本生成视频模型。
• 服务提供方专属覆盖项：当上游 API 与其适配器不同时，调整请求和响应形态。
• 服务提供方兼容性：查看受支持的代理端点和服务提供方专属边界。