Qwen API は阿里雲の百錬（Model Studio）が提供し、DashScope がそのネイティブなインターフェース体系です。百錬は OpenAI 互換インターフェースと DashScope ネイティブインターフェースの両方を提供しています。ほとんどのチームにとって、まず OpenAI 互換インターフェースを使うのが最も簡単です。既存の SDK、Agent フレームワーク、ツールチェーンは通常 3 か所だけ変更すれば済みます。API キー、Base URL、モデル名です。
本当の落とし穴は「つながるかどうか」ではなく、Base URL の地域、モデル名が有効か、ストリーミング出力をどう解析するか、OpenAI から移行するときにどのパラメータを持ち込めないか、といった点にあります。本記事では最小リクエストで経路を通し、その後にツール呼び出し、エラー切り分け、移行チェックリストを補足します。
注記：Qwen、通義千問、阿里雲、百錬（Model Studio）、DashScope は阿里巴巴グループおよびその関連会社の商標または製品名です。本記事は技術的な説明のみを目的としており、阿里巴巴グループとは提携、代理、許諾の関係にありません。Base URL、モデル名、コンテキスト長、課金の基準は変更される場合があるため、阿里雲百錬の公式ドキュメントとサイト内のモデル価格を基準にしてください。
一、接続前の準備
開始前に次の 3 つを確認してください。
- 利用可能な API キーがあり、対象地域と一致している。
- 正しい Base URL があり、中国本土、国際サイト、ゲートウェイのアドレスを混ぜていない。
- 現在実際に利用できるモデル名があり、古い記事の例をそのまま写していない。
まず curl で認証とネットワークを確認してから SDK を接続することをおすすめします。そうすれば、エラー時にキー、アドレス、コードのどれが問題かを判断しやすくなります。
二、Base URL：まず地域、次にドメイン
OpenAI 互換インターフェースのパスは /compatible-mode/v1 で固定され、チャットはさらに /chat/completions を結合します。ドメインは地域ごとに分かれ、一般的な表記は次のとおりです。
| 場面 | OpenAI 互換 Base URL | 説明 |
|---|---|---|
| 中国本土（北京、旧共有ドメイン） | https://dashscope.aliyuncs.com/compatible-mode/v1 |
旧コードと互換。現在も利用可能 |
| シンガポール（国際サイト） | https://dashscope-intl.aliyuncs.com/compatible-mode/v1 |
国際サイトのアカウントとキー |
| 米国バージニア | https://dashscope-us.aliyuncs.com/compatible-mode/v1 |
IPv4 のみ。対応能力はドキュメントを基準 |
| 中国香港 | https://cn-hongkong.dashscope.aliyuncs.com/compatible-mode/v1 |
独立した地域とキー |
| 業務スペース専用 | https://{WorkspaceId}.{region}.maas.aliyuncs.com/compatible-mode/v1 |
本番推奨。スループットと分離がより良い |
| ZSQH AI Gateway | https://ai.zhongshangqihang.com/v1 |
複数モデルの統一入口 |
重要な点がいくつかあります。第一に、API キーは地域に紐づき、地域をまたぐ呼び出しは通常 401 と invalid_api_key を返します。これはキーとアドレスが一致していないことを示し、キー自体が無効という意味ではありません。第二に、中国本土のアカウントと国際サイトのアカウントは 2 つの体系で、キー、請求、モデル一覧は共通ではありません。第三に、業務スペース専用ドメインはそのスペース自身のキーだけを受け付けますが、スループットとトラフィックの分離がより良く、本番環境に向きます。旧共有ドメインはスペースをまたいだ利用や迅速なテストに便利です。
チームが複数社のモデルを併用し、地域、割当、複数セットのキーを自分で維持したくない場合は、ZSQH AI Gateway で統一キーを作成し、Base URL を表の最後の行のアドレスに変更できます。
三、モデル名の選び方
百錬のモデル一覧は更新が速いです。現在の公式モデルページを例にすると、テキスト生成の部分に qwen3.8-max、qwen3.7-plus、qwen3.8-flash が記載されています。命名からおおまかに理解すると、max は能力の上限、plus はバランス、flash は低遅延と低コストに寄っています。具体的な位置づけとコンテキスト長は公式モデルドキュメントを基準にし、価格は変更されるためモデル価格ページを基準にしてください。
選定では「最も強い」ものだけを見ないでください。カスタマーサポートの質問応答、バッチ分類、コンテンツ審査では、低遅延の階層のほうが割安なことがよくあります。長文書の分析や複雑な Agent では上位構成を使います。モデル名はコードに固定せず設定項目にすると、後の切り替えがはるかに楽になります。
見落としやすい点が 2 つあります。古いチュートリアルの qwen-max、qwen-plus などの表記は調整されている可能性があるため、接続前にコンソールのモデル一覧で確認してください。ベクトル能力が必要な場合は embedding 系列（たとえば qwen3.7-text-embedding）を使いますが、チャットインターフェースとはリクエストボディが異なります。Qwen-Audio は OpenAI 互換プロトコルに対応しておらず、DashScope ネイティブインターフェースを使う必要があります。
四、curl で最初の呼び出しを通す
まず環境変数を用意し、キーがコマンド履歴に残らないようにします。
export DASHSCOPE_API_KEY="your_key_here"
curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-max",
"messages": [
{"role": "system", "content": "あなたは簡潔な技術アシスタントです。"},
{"role": "user", "content": "API ゲートウェイとは何かを 3 文で説明してください。"}
],
"temperature": 0.7
}'
正常に返ったら、3 つのフィールドを重点的に確認します。choices[0].message.content が回答、usage が今回の使用量、finish_reason が終了理由です。401 が返る場合はキーと地域を、404 と ModelNotFound が返る場合はモデル名とその地域でモデルが開通しているかを先に確認してください。
五、Python SDK での呼び出しとストリーミング出力
OpenAI SDK は 1.0 以上が必要です。Base URL を百錬に向けると、呼び出し方は OpenAI とほぼ同じになります。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
stream = client.chat.completions.create(
model="qwen3.8-max",
messages=[{"role": "user", "content": "100 文字以内で製品紹介を書いてください。"}],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
ストリーミング出力では、最初の chunk が役割情報だけで content が空の場合があることに注意してください。すべての chunk にテキストがあると決めつけないでください。stream_options={"include_usage": True} を加えると、使用量が最後の chunk に現れます。HTTP で直接接続する場合、レスポンスは SSE 形式で、data: [DONE] で終わります。ユーザーがページを閉じた後、サーバーはできるだけ早く上流のリクエストをキャンセルし、生成と課金が続かないようにしてください。
六、ツール呼び出しとパラメータの差異
ツール呼び出しは OpenAI の tools と tool_choice の形式を踏襲します。モデルが message.tool_calls を返したら、各呼び出しの function.arguments を JSON として解析し、ローカル関数を実行して、結果を role: "tool" のメッセージとして返します。マルチターンの流れでは、各ターンのリクエストに tools を含めます。本番環境ではパラメータの検証、権限の検証、タイムアウト制御を行い、モデルが生成したパラメータをそのまま信頼しないでください。
公式の互換ドキュメントでは現在、ツールに関して 2 つの制限が示されています。対応するモデルが一部に限られること、tools と stream=True を同時に使えないことです。モデル一覧と能力は継続的に更新されるため、公開前に必ず対象モデルで実測してください。ストリーミングしながらツールを呼ぶ必要がある業務では、DashScope ネイティブインターフェースを使うか、ツール呼び出しを非ストリーミングの工程として設計することを検討してください。
OpenAI から移行する際は、次のパラメータ差異にも注意してください。
messages：system ロールにできるのはmessages[0]だけです。user と assistant は通常交互に並べ、最後は必ず user にします。temperature：範囲は [0, 2) で、公式は 0 を設定しないことを推奨しています。top_p：範囲は (0, 1.0) です。seed：符号なし 64 ビット整数を使います。stop：配列の要素で token ID と文字列を混在させないでください。system_fingerprint：現在は空文字列が返ります。enable_searchなどの拡張パラメータ：通常はextra_bodyで渡し、すべてのモデルが対応しているわけではありません。response_format、frequency_penaltyなどのフィールド：互換ドキュメントでは明示されていないため、OpenAI と同じ動作だと決めつけないでください。
七、よくあるエラー対応表
| 現象 | よくあるエラーコード | 考えられる原因 | 対処 |
|---|---|---|---|
| 401 | InvalidApiKey / invalid_api_key |
キーの誤り、地域の不一致、プラン用キーの混用 | キーと Base URL の地域・種類を確認 |
| 404 | ModelNotFound / model_not_found |
モデル名の誤記、地域にモデルがない、未開通 | コンソールのモデル一覧を確認 |
| 404 | model_not_supported |
モデルが OpenAI 互換モードに対応していない | DashScope ネイティブインターフェースに変更 |
| 403 | AccessDenied / Workspace.AccessDenied |
スペースまたはモデルの権限不足 | 業務スペースの権限を確認 |
| 403 | AllocationQuota.FreeTierOnly |
無料枠を使い切った | チャージまたはプランを調整 |
| 429 | Throttling 系 |
リクエスト頻度、Token、同時実行の超過 | 同時実行を下げ、バックオフ再試行、割当を申請 |
| 400 | Arrearage |
アカウントの未払い | チャージしてから再試行 |
| 400 | Range of input length... |
入力がコンテキスト上限を超過 | プロンプトを圧縮するか分割 |
| 400 | DataInspectionFailed |
入力または出力がコンテンツ安全基準で遮断された | 内容を調整して再試行 |
再試行が有効なのは 429、5xx、ネットワークタイムアウトだけです。401、403、404、パラメータエラーは再試行しても改善せず、時間と割当を浪費するだけです。調査時はレスポンスの Request ID を記録し、コンソールのログで照会すると、当てずっぽうよりはるかに速く特定できます。
八、OpenAI からの移行チェックリスト
- 既存のプロンプト、モデルパラメータ、評価セットをバックアップする。
- 対象地域に合った Qwen のキーを新規作成し、他社のキーを再利用しない。
- Base URL とモデル名を設定項目に変更する。
messagesのロール規則を確認し、先頭を system、末尾を user にする。- ストリーミングの解析と使用量の統計方法を確認する。
- 実際のツールでツール呼び出しの回帰テストを 1 回行う。
- 同じサンプル群で出力品質、遅延、使用量を比較する。
- 再試行、タイムアウト、同時実行を調整し、1 週間観察してから全量に切り替える。
- ログに Request ID を記録し、ロールバック用のスイッチを残す。
九、よくある質問（FAQ）
1. Qwen API は OpenAI と互換ですか？
よく使われるチャットインターフェースの大部分は互換ですが、地域への紐づき、ロールの順序、パラメータの範囲、ツール呼び出しの制限などの差異が残ります。公式の OpenAI 互換ドキュメントに沿って項目ごとに検証し、すべてのパラメータが同じ動作をすると決めつけないでください。
2. 中国本土と国際サイトで 1 つのキーを共用できますか？
できません。2 つのサイトのアカウント、キー、接続ドメイン、請求は互いに独立しています。地域やサイトをまたぐ呼び出しは通常 401 と invalid_api_key を返します。
3. Base URL は旧ドメインと業務スペース専用ドメインのどちらを使うべきですか？
迅速なテストには旧共有ドメインを使えます。本番環境では業務スペース専用ドメインを推奨します。スループットとトラフィックの分離がより良いためです。重要なのは、キーがドメインの地域と業務スペースに一致していることです。
4. モデル名が正しいのに model_not_found が返るのはなぜですか？
よくある原因は、その地域にモデルがない、モデルが未開通、名前の大文字と小文字が一致しない、すでに提供終了したバージョンにアクセスしている、などです。コンソールの現在のモデル一覧を基準にしてください。
5. tools と stream は同時に使えますか？
公式の互換ドキュメントでは現在、両者を同時に使えないこと、ツール呼び出しに対応するモデルが一部に限られることが示されています。能力と制限はモデルの更新に伴って変わるため、公開前に対象モデルで実測するか、DashScope ネイティブインターフェースに切り替えてください。
