阿里雲 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邊界