阿里云 Model Studio API 接入指南

先确定地区、工作空间和实际模型

本指南使用阿里云国际站Model Studio的OpenAI兼容文本聊天接口。前提是已有获授权的账号、已开通服务、可用工作空间和相应模型权限。先记录访问地区、工作空间、服务部署范围、真实模型ID、计费方式与调用限额；不要把模型目录里的名称直接当成该工作空间可调用的ID。

地区决定接入和存储安排，服务部署范围决定推理位置，两者需要分别核对。某个国际站模型、全球推理或套餐的可用性不能从“兼容OpenAI”推断。本文不为你创建工作空间、申请配额或启用付费服务。

端点与密钥必须匹配

优先在工作空间管理中复制API Host，再按所选协议组合路径。OpenAI兼容路径为 /compatible-mode/v1，原生DashScope的 /api/v1 不是同一个接口。下例仅展示新加坡工作空间专属域名形状，必须替换占位工作空间；其他地区使用相应控制台Host，不通过猜域名切换地区。

密钥须对应地区、目标工作空间和计费计划。按量付费的Key不能与Coding Plan或Token Plan专属端点混用；当前后两类计划面向交互式编码工具，不能当作后端模型服务套餐。官方端点列表若与旧教程不同，先核对当前Base URL页和控制台。不要把国际站和中国站的账号、配额、价格自动合并。

安装并设置占位配置

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade openai

由授权服务端环境安全注入 DASHSCOPE_API_KEY；以下只设置公开结构占位值，不能直接运行成功。确认模型支持文本聊天、流式输出与 max_tokens 后再替换 MODEL_STUDIO_MODEL。某些模型仅支持流式，不能先用非流式请求判断其是否可用。

export MODEL_STUDIO_BASE_URL='https://YOUR-WORKSPACE.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1'
export MODEL_STUDIO_MODEL='YOUR-ACTUAL-TEXT-MODEL-ID'

最小流式调用与用量解析

保存为 model_studio_chat.py，确认费用和测试权限后再运行 python model_studio_chat.py。例中的128输出上限、30秒客户端超时是本地测试控制，SDK重试暂为0；它们不代表服务配额、最大等待时间或支持承诺。

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["MODEL_STUDIO_BASE_URL"],
    api_key=os.environ["DASHSCOPE_API_KEY"],
    timeout=30.0,
    max_retries=0,
)
usage = None
finish_reason = None
with client.chat.completions.create(
    model=os.environ["MODEL_STUDIO_MODEL"],
    messages=[{"role": "user", "content": "Reply with one short greeting."}],
    max_tokens=128,
    stream=True,
    stream_options={"include_usage": True},
) as events:
    for part in events:
        if part.usage is not None:
            usage = part.usage
        if not part.choices:
            continue
        choice = part.choices[0]
        if choice.delta.content:
            print(choice.delta.content, end="", flush=True)
        if choice.finish_reason is not None:
            finish_reason = choice.finish_reason
print()
print("finish_reason:", finish_reason)
print(usage.model_dump() if usage else "usage unavailable")

include_usage要求返回用量信息。最终usage块可能是空 choices，因此先读usage、再检查列表。文本来自 delta.content，不能按非流式 message.content解析；也不要在收到finish reason时提前退出，遗漏后续用量块。流中断而未收到usage时，记录为“用量未取得”，不是零用量或免费。此例处理普通文本；工具调用、推理内容、图像与音频需另外实现对应结构。

按问题类型排查

• 401/403：核对Key的地区、工作空间、计划和授权；不要把完整认证信息粘贴到工单。
• 404或模型不存在：核对Host、兼容路径、真实模型ID与工作空间可用列表，避免使用其他地区旧后缀。
• 400：确认该模型接受的输入、输出上限与可选参数；先用普通短文本缩小范围。
• 429：同时检查请求数、Token与并发相关限制，按返回错误和限流文档做有限退避。
• 超时/5xx：保留脱敏请求编号与时间，控制重试次数；部分输出不当作完整任务成功。

上线前核对费用、安全与验收

以实际模型、地区和部署范围计量，对照控制台与账单；流式展示不会免除生成费用，断开连接也不证明服务端立即停止。将输出限制、并发、总任务时限及工具循环上限分开设置，预算通知不能代替调用限制。本文不提供单价、折扣或套餐保证。

按当前数据保留政策，推理输入输出默认保留不超过30天，但存在法律/安全例外；ZDR需获准启用且仅覆盖特定模型和路径，计量、安全记录及状态型功能另有边界。使用敏感数据前复核实际工作空间与合同，并控制应用侧日志。

验收应覆盖正常完成、截断、空choices用量块、流中断、限流与权限失败，并记录模型ID、路径、finish reason和计量。示例只完成离线语法检查，未读取密钥、调用真实模型或证明你账号中的供应状态。

官方依据

核验日期：2026-10-17。配置以当前工作空间与官方文档为准。

• Base URL与计划匹配
• 地区和服务部署范围
• 流式输出与usage
• 限流规则
• 数据保留政策与ZDR边界