ModelScope
ModelScope 是面向开放权重模型的模型社区和托管推理平台。AISIX 为应用提供用于这些模型的统一兼容 OpenAI API,同时管理凭证、调用方访问权限、速率限制和用量核算。
前提条件
开始前,请准备以下内容:
- 一套 AISIX 环境:
- 对于 AISIX Enterprise 或 AISIX Cloud,需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 AISIX Enterprise,请按照 AISIX Enterprise 快速入门操作。如需申请 AISIX Cloud 访问权限,请联系 API7。
- 对于开源 AISIX 网关,请准备本地 AISIX 安装,或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
- 从 ModelScope 账户获取的 ModelScope API Token。ModelScope API-Inference 文档说明了 Token 可用于推理请求前适用的账户激活和配额规则。
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"
为 ModelScope 支持的 chat-completions 路由创建模型服务提供方密钥、模型别名和调用方 API Key。
ModelScope 是提供兼容 OpenAI API-Inference 服务的社区目录模型服务提供方。AISIX 通过 openai 适配器连接,使用 Bearer Token 认证上游请求,并将 ModelScope API 根地址用作 api_base。发送生产流量前,请阅读提供 AISIX 未策划的传输细节。
创建模型服务提供方密钥
创建用于存储 ModelScope 凭证和 API 根地址的模型服务提供方密钥:
# 请替换为实际值
export MODELSCOPE_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": "modelscope-prod",
"provider": "modelscope",
"api_key": "'"${MODELSCOPE_API_KEY}"'",
"api_base": "https://api-inference.modelscope.cn/v1",
"allowed_environments": ["'"${ENV_ID}"'"]
}' | jq -r '.provider_key.id')
echo "$PROVIDER_KEY_ID"
❶ provider 为 modelscope。由于该 ID 存在于缓存的 models.dev 目录中,AISIX Cloud Admin API 会接受此值,并应用目录的默认规则:使用 openai 适配器和 HTTP Bearer 认证。不要设置 adapter 字段,AISIX Cloud Admin API 仅接受在 BYO 模型服务提供方密钥上设置该字段。
❷ api_key 存储 ModelScope API Token。openai 适配器会在 Authorization: Bearer 请求头中发送该 Token。该值遵循模型服务提供方密钥中的凭证处理行为。
❸ api_base 为 https://api-inference.modelscope.cn/v1,这是 ModelScope 兼容 OpenAI 的 chat-completions 端点 https://api-inference.modelscope.cn/v1/chat/completions 所在的 API 根地址。AISIX 会将 /chat/completions 等端点路径追加到存储的值。对于 modelscope,此字段可选,因为省略时控制面会从目录填入相同的根地址。示例显式设置该字段,以便配置中清楚显示每个密钥所指向的根地址。
请存储 API 根地址,而不是完整端点 URL,也不是不带路径的主机地址。如果粘贴的值末尾带有 /chat/completions,AISIX 会将其移除,但不会为非 OpenAI 主机合成 /v1 路径。将 api_base 设置为 https://api-inference.modelscope.cn 会生成指向 https://api-inference.modelscope.cn/chat/completions 的上游请求,而 ModelScope 不提供该路径。
这些示例面向 ModelScope 中国 站。ModelScope 国际站使用 https://api-inference.modelscope.ai/v1;如果 Token 和模型来自 modelscope.ai,请显式设置该根地址。目录默认值仍为 .cn 根地址,因此省略 api_base 不会自动选择国际站。
该命令将返回的模型服务提供方密钥 ID 保存到 PROVIDER_KEY_ID。
创建模型
ModelScope 模型 ID 带有组织命名空间。每个 ID 都复用了 ModelScope 模型页面的 organization/model 路径,包括大小写。AISIX 模型服务提供方目录中的当前 ID 包括:
| 模型 ID | 上下文窗口 | 说明 |
|---|---|---|
Qwen/Qwen3-235B-A22B-Instruct-2507 | 262,144 Token | 指令模型,不输出推理内容。 |
Qwen/Qwen3-235B-A22B-Thinking-2507 | 262,144 Token | 相同权重的推理变体。 |
Qwen/Qwen3-Coder-30B-A3B-Instruct | 262,144 Token | 编程和软件 Agent 模型。 |
ZhipuAI/GLM-4.6 | 202,752 Token | 在 ZhipuAI 组织下提供的 GLM 旗舰模型。 |
创建别名前,请在模型的 ModelScope 页面上确认 ID,因为 API-Inference 提供的模型集合会随时间变化。
创建调用方将在请求中发送的模型别名:
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": "modelscope-qwen-prod",
"model_name": "Qwen/Qwen3-235B-A22B-Instruct-2507",
"provider_key_id": "'"${PROVIDER_KEY_ID}"'"
}' | jq -r '.model.id')
echo "$MODEL_ID"
❶ display_name 是调用方在 model 中发送的别名。
❷ model_name 是完整的 ModelScope 模型 ID,包括组织前缀。省略该前缀,或复用同一权重在其他托管平台上的无前缀 ID(例如 qwen3-235b-a22b-instruct-2507),都会导致上游返回找不到模型的错误。
❸ provider_key_id 将别名关联到 ModelScope 模型服务提供方密钥。
创建调用方 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": "modelscope-caller",
"allowed_models": ["'"${MODEL_ID}"'"]
}' | jq -r '.plaintext')
echo "$AISIX_API_KEY"
allowed_models 的值必须引用上一步保存的模型 ID。写入后,配置会自动投射到已关联的网关。
使用开源 AISIX 网关配置
导出上游凭证,并选择应用将发送到网关的调用方 API Key:
export MODELSCOPE_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"
对于新网关,请使用此完整资源文件。对于现有网关,请将这些条目合并到其当前文件中,并保留其他资源:
_format_version: "1"
provider_keys:
- display_name: "modelscope-prod"
provider: "modelscope"
adapter: "openai"
api_key: ${MODELSCOPE_API_KEY}
api_base: "https://api-inference.modelscope.cn/v1"
models:
- display_name: "modelscope-qwen-prod"
provider: "modelscope"
model_name: "Qwen/Qwen3-235B-A22B-Instruct-2507"
provider_key: "modelscope-prod"
api_keys:
- display_name: "modelscope-caller"
key_env: CALLER_API_KEY
allowed_models:
- "modelscope-qwen-prod"
如果 AISIX 安装在本地,请在加载前验证该文件:
aisix validate --resources resources.yaml
验证后,在网关进程环境中设置所引用的环境变量并启动网关。仅当这些变量已在进程中可用时,才重新加载现有网关;否则,请使用更新后的环境重启网关。
如果使用 Docker,请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件,并在两个命令中使用 -e 传入它引用的每个环境变量。资源加载后,为下方的通用验证请求做好准备:
export AISIX_API_KEY="$CALLER_API_KEY"
验证模型服务提供方连接
导出 AISIX 网关源地址:
# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
通过 AISIX 代理发送 chat-completions 请求:
curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
-H "Authorization: Bearer ${AISIX_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "modelscope-qwen-prod",
"messages": [
{
"role": "user",
"content": "Say hello from ModelScope."
}
]
}'
网关返回兼容 OpenAI 的响应,其中会回显面向调用方的别名 modelscope-qwen-prod。如果请求失败,请检查模型服务提供方密钥的 api_key、api_base 根地址,以及 model_name 中带组织前缀的模型 ID。
在 ModelScope 与阿里云百炼之间选择
ModelScope 和阿里云百炼都提供 Qwen 模型,但它们是独立的上游,在 AISIX 中使用不同的模型服务提供方 ID。选择错误的上游会导致上游认证或找不到模型错误,而不是在创建时返回配置错误,因此请先确认凭证由哪项服务签发。
| ModelScope | 阿里云百炼 | |
|---|---|---|
| 模型服务提供方 ID | modelscope | alibaba |
| 目录层级 | 社区 | 精选 |
| 设置指南 | 本页 | Qwen(阿里云) |
| API 根地址 | https://api-inference.modelscope.cn/v1 | 特定于地域的 DashScope 兼容 OpenAI 根地址 |
| 凭证 | ModelScope API Token | 按地域签发的 DashScope API Key |
| 模型 ID 格式 | 带组织命名空间的仓库路径,例如 Qwen/Qwen3-235B-A22B-Instruct-2507 | 百炼模型名称,例如 qwen-plus |
已建模的 /v1/videos 路由 | 拒绝 | 支持 |
相同区别也适用于 GLM。ModelScope 在 ZhipuAI 组织下提供 GLM 权重,但由 modelscope 模型服务提供方支持的 GLM 别名,并不等同于由 Zhipu AI(GLM)中介绍的精选 zhipuai 模型服务提供方支持的别名。按模型服务提供方标签分派的网关接口(例如已建模的视频生成路由)依据模型上记录的模型服务提供方,而不是依据上游恰好提供的权重来决定行为。
提供 AISIX 未策划的传输细节
对于具有 AISIX 精选适配器映射的模型服务提供方,目录会记录适配器、认证方案、默认 API 根地址以及请求或响应的特殊规则。ModelScope 没有此类映射。它通过目录的默认规则解析:获得 openai 适配器和 Bearer 认证,并被标记为来源于社区;除非操作人员按密钥覆盖,否则其传输兼容性会被假定为 OpenAI 格式。超出该假设的所有设置都需要由你配置。
实际使用中:
- 未注册参数重命名规则。 AISIX 会按照调用方发送的形式原样转发顶层 chat-completions 参数。某些精选模型服务提供方会为
max_completion_tokens等字段设置重命名规则;ModelScope 没有此类规则,因此适用于已重命名模型服务提供方的请求体并不会自动适用于此处,反之亦然。 - 未注册响应字段重新映射。 AISIX 已经会将到达
message.reasoning_content、delta.reasoning_content或message.reasoning的推理内容规范化到标准reasoning_content字段。除非进行映射,否则不会重新映射从其他流式delta路径传递的推理内容。 - 不适用模型服务提供方范围的推理控制。 ModelScope 没有发布跨越其所提供模型的通用推理开关、推理强度级别或思考 Token 预算,因此推理行为取决于各个模型。请按模型 ID 进行验证:
Qwen/Qwen3-235B-A22B-Thinking-2507的设计会进行推理,而Qwen/Qwen3-235B-A22B-Instruct-2507则不会。
这两类调整都是模型服务提供方密钥字段。将它们添加到创建模型服务提供方密钥的请求中,或声明式资源文件中的模型服务提供方密钥条目中:
{
"request": {
"param_renames": {
"max_completion_tokens": "max_tokens"
}
},
"response": {
"reasoning_field": "delta.thinking"
}
}
仅当 ModelScope 提供的特定模型拒绝客户端已发送的参数名称时,才使用 request.param_renames