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，且不含尾部斜杠
# 本地私有化部署快速入门使用 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 不提供该路径。

这些示例面向 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"

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

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 网关源地址：

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

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

核算成本和共享配额

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

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

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

端点覆盖范围

ModelScope API-Inference 提供多个 OpenAI 和 Anthropic 格式端点，但只有部分规范化 AISIX 代理接口适用于 ModelScope 支持的别名。下表所称“支持”说明 AISIX 如何处理请求，并不表示 AISIX 会调用 ModelScope 同名原生端点。

路由	ModelScope 别名的行为
/v1/chat/completions	支持，包括 stream: true。
/v1/completions	不支持。ModelScope API-Inference 不提供旧版 Completions 路径。
/v1/responses	通过 Chat 适配器路径上的 Responses 桥接支持。它不会调用 ModelScope 原生 /v1/responses 端点，且没有 Chat 等价项的 Responses 字段会被忽略。需要原生 Responses 语义时请使用透传路由。
/v1/messages	通过转换为 Chat Completions 支持 Anthropic 格式调用方，并不调用 ModelScope 原生 /v1/messages 端点。
/v1/messages/count_tokens	此指南中的 modelscope 配置会被拒绝，因为规范化计数器要求 Anthropic 后端模型。可通过透传路由访问 ModelScope 原生计数器。
/v1/embeddings	通过 openai 适配器分派，因此仅当配置的模型由上游 /v1/embeddings 路径提供时才有效。AISIX 模型服务提供方目录中的 ModelScope 条目是文本聊天模型。请参阅嵌入。
/v1/audio/*、/v1/files、/v1/batches 和 /v1/fine_tuning/jobs	此服务提供方不可用。ModelScope API-Inference 不在配置的 API 根地址下提供兼容路径。
/v1/images/generations	返回 400 错误而被拒绝。该路由仅接受模型服务提供方为 openai 的模型。可通过透传路由访问 ModelScope 原生异步图片生成工作流。
/v1/rerank	返回 400 错误而被拒绝。该路由仅接受 openai、cohere 和 jina 模型服务提供方值。
/v1/videos	返回 501 not_implemented 而被拒绝。该路由按模型服务提供方标签分派，modelscope 不在其接受的标签中，即使是 zhipuai 模型服务提供方可在此路由上驱动的 GLM 权重也不例外。
/passthrough/modelscope/*	通过已配置的透传路由可用于模型服务提供方原生路由，包括 /responses、/messages、/messages/count_tokens、/images/generations 和 /tasks/{task_id}。

ModelScope 原生 API 接口不同于规范化 AISIX 接口。例如，ModelScope 图片生成会在 /v1/images/generations 启动异步作业并返回任务 ID，应用随后轮询 /v1/tasks/{task_id}。使用以本指南 API 根地址为目标的透传路由时，请通过 /passthrough/modelscope/images/generations 和 /passthrough/modelscope/tasks/{task_id} 调用这些路由。启动作业时发送 X-ModelScope-Async-Mode: true，轮询时发送 X-ModelScope-Task-Type: image_generation，并在原生请求体中使用确切的 ModelScope 图片模型 ID。

这些路径假定一条透传路由认领 /passthrough/modelscope 前缀，target_url 设为 https://api-inference.modelscope.cn/v1 并用 ModelScope 服务提供方密钥做凭证注入；在调用方 Key 的 allowed_routes 上授予路由名称。前导 /v1 与目标末尾路径段重复时会被移除，因此在 /passthrough/modelscope 后添加它会到达相同上游 URL。网关不会重写请求体中的 AISIX 别名，原生 model 字段也不会选择凭证——路由绑定一个目标和服务提供方密钥，不同的 ModelScope 账号或根地址请使用独立路由。AISIX 会检测 Chat、Completions 和 Responses 信封，并记录受支持的用量字段。没有可识别载体字段的请求保持不透明：缓冲响应记录零 Token，而不透明 SSE 仍可记录顶层受支持的 usage 字段。AISIX 会增量中继服务提供方 SSE，而不是缓冲事件。

后续步骤

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

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