Alibaba Cloud Model Studio API 接続ガイド

リージョン、ワークスペース、モデルを決める

Alibaba Cloud International の Model Studio で、OpenAI 互換のテキストチャット API を利用する手順です。権限を持つアカウント、有効なサービス、利用できるワークスペース、モデル権限が必要です。接続リージョン、ワークスペース、サービスのデプロイ範囲、実際のモデル ID、課金プラン、呼び出し制限を記録します。一般のカタログ名がそのまま利用可能な ID とは限りません。

接続・保存の場所と、推論が行われるデプロイ範囲は別に確認してください。OpenAI 互換というだけでは、モデル、グローバル推論、契約プランの利用可否は分かりません。本手順はワークスペース作成、クォータ申請、有料サービスの有効化を代行するものではありません。

エンドポイントとキーを一致させる

Workspace Management から API Host を取得し、使用するプロトコルの経路を組み合わせます。OpenAI 互換は /compatible-mode/v1、ネイティブ DashScope の /api/v1 は別の API です。例はシンガポールのワークスペース専用ホストの形式です。仮のワークスペースを置き換え、他の地域ではコンソールの Host を使ってください。ドメインを推測して切り替えないでください。

キーはリージョン、対象ワークスペース、課金プランと一致する必要があります。従量課金キーを Coding Plan や Token Plan の専用 URL と混用しないでください。現在これらのプランは対話型コーディングツール用で、バックエンドのモデルサービス用ではありません。旧手順と異なる場合は、現在の Base URL 資料とコンソールを優先します。International と中国サイトのアカウント、クォータ、料金も同一とは限りません。

インストールと仮設定

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秒のタイムアウト、自動再試行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：キーの地域、ワークスペース、プラン、権限を確認する。認証情報全体を問い合わせに貼らない。
• 404・モデル不明：Host、互換経路、実際の ID、ワークスペースのモデル一覧を確認する。別地域の旧サフィックスを流用しない。
• 400：入力、出力上限、任意パラメーターを確認し、短い通常テキストで原因を絞る。
• 429：リクエスト数、トークン、同時実行の制限を確認し、応答と公式資料に沿って有限のバックオフを行う。
• タイムアウト/5xx：機密情報を除いたリクエスト番号と時刻を残し、再試行を制限する。途中出力を完了扱いにしない。

費用、安全、受入確認

実際のモデル、地域、デプロイ範囲を使用量と請求に照合します。ストリーミングでも生成費用は発生し、クライアントの切断はサーバーの即時停止を証明しません。出力、同時実行、業務全体の期限、ツールのループを個別に制限します。予算通知は呼び出しの強制停止ではありません。本稿は単価、割引、プラン保証を示しません。

現在のポリシーでは推論の入出力は原則30日以内の保存ですが、法律・安全上の例外があります。ZDR は承認と対応モデル・経路の条件があり、計量、安全記録、状態を保持する機能には別の境界があります。機密データを使う前にワークスペースと契約を確認し、アプリのログも管理してください。

通常完了、打ち切り、空 choices の使用量チャンク、切断、制限、権限エラーを検証し、モデル ID、経路、finish reason、使用量を記録します。本例は構文のオフライン確認のみで、キーの読み取り、モデル呼び出し、アカウント固有の利用可否確認は行っていません。

公式資料

確認日：2026-10-17。現在のワークスペースと公式資料で確認してください。

• Base URL とプラン
• 地域とデプロイ範囲
• ストリーミングと使用量
• 呼び出し制限
• 保存ポリシーと ZDR