ModelScope

ModelScope 是面向开放权重模型的模型社区和托管推理平台。AISIX 为应用提供用于这些模型的统一兼容 OpenAI API，同时管理凭证、调用方访问权限、速率限制和用量核算。

前提条件

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

一套 AISIX 环境：
- 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
- 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
从 ModelScope 账户获取的 ModelScope API Token。ModelScope API-Inference 文档说明了 Token 可用于推理请求前适用的账户激活和配额规则。
curl 和 jq。

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 的基础 URL；应包含 /api，且末尾不要带斜杠
# 本地 On-Premises 快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_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 不提供该路径。

该命令将返回的模型服务提供方密钥 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"

为此模型服务提供方创建完整的声明式资源文件：

resources.yaml
_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 网关源地址：

# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

通过 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；仅当流式响应从 delta.reasoning_content 以外的路径携带推理内容时，才使用 response.reasoning_field。有关字段目录以及每个覆盖设置适用的适配器，请参阅模型服务提供方特定的覆盖设置。

模型服务提供方密钥上的覆盖设置会应用于引用它的每个模型，因此请先使用非生产别名验证变更。出于同样原因，如果所提供模型的行为不同，可以考虑为每个组织命名空间使用一个模型服务提供方密钥：Qwen/* 和 ZhipuAI/* 共享一个端点，但属于不同的模型系列。通过每个新别名发送缓冲和流式请求，并在将流量路由到该别名前，确认客户端读取的字段均存在。

核算成本和共享配额

托管控制平面使用确切的 (provider, model name) 对解析每个请求的成本；没有匹配的组织覆盖设置时，会回退到 models.dev 目录的默认值。ModelScope 目录条目发布的输入和输出价格均为零，因此 modelscope 模型的用量事件会记录 Token 数量，但解析出的支出为 $0.00。根据该支出评估的预算永远不会增长，least_cost 路由组也会将该别名视为免费。

如果成本报告或预算必须反映组织使用 ModelScope 流量的实际成本，请为模型服务提供方 modelscope 和配置时使用的确切模型名称添加组织定价覆盖设置，其中包括组织前缀。请参阅模型定价。

网关后的所有调用方共享同一个上游 ModelScope 账户，因此上游配额拒绝会同时影响所有调用方。请设置网关侧限制，避免单个调用方耗尽共享账户：将速率限制关联到模型别名、调用方 API Key，或同时关联到两者。请参阅速率限制。

端点覆盖范围

ModelScope API-Inference 是仅用于推理的上游，因此只有部分代理接口适用于 ModelScope 支持的别名。

路由	ModelScope 别名的行为
`/v1/chat/completions`	支持，包括 `stream: true`。
`/v1/responses`	支持通过聊天适配器路径上的 Responses 桥接。
`/v1/messages`	支持使用 Anthropic 格式的调用方请求，并进行格式转换。`/v1/messages/count_tokens` 上的 Token 计数需要由 Anthropic 支持的模型。
`/v1/embeddings`	通过 `openai` 适配器分派，因此仅当配置的模型由上游 `/v1/embeddings` 路径提供时才有效。AISIX 模型服务提供方目录中的 ModelScope 条目是文本聊天模型。请参阅嵌入。
`/v1/images/generations`	返回 400 错误而被拒绝。该路由仅接受模型服务提供方为 `openai` 的模型。
`/v1/rerank`	返回 400 错误而被拒绝。该路由仅接受 `openai`、`cohere` 和 `jina` 模型服务提供方值。
`/v1/videos`	返回 `501 not_implemented` 而被拒绝。该路由按模型服务提供方标签分派，`modelscope` 不在其接受的标签中，即使是 `zhipuai` 模型服务提供方可在此路由上驱动的 GLM 权重也不例外。
`/passthrough/modelscope/*`	支持模型服务提供方原生路由，并提供有限的网关规范化。请参阅模型服务提供方透传。

后续步骤

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

模型服务提供方特定的覆盖设置：当此上游与 openai 适配器的假设不同时，调整请求和响应格式。
模型别名：为此别名配置路由、重试行为或成本元数据。
路由和故障转移：从 ModelScope 故障转移到提供相似权重的第二个模型服务提供方。
Qwen（阿里云）：当凭证来自百炼时，改为配置精选阿里云百炼上游。
模型服务提供方兼容性：查看支持的代理端点和模型服务提供方特定的限制。

前提条件​

使用 AISIX Cloud 配置​

创建模型服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证模型服务提供方连接​

在 ModelScope 与阿里云百炼之间选择​

提供 AISIX 未策划的传输细节​

核算成本和共享配额​

端点覆盖范围​

后续步骤​