GLM API の接続コストは、多くの人が想像するより低いものです。OpenAI 互換インターフェースを提供しているため、既存の OpenAI SDK は通常 3 か所だけ変更すれば済みます。API キー、Base URL、モデル名です。本当の落とし穴は「つながるかどうか」ではなく、モデル名が有効か、ストリーミング出力をどう処理するか、ツール呼び出しがどんな形式を返すか、OpenAI から移行するときにどのパラメータを持ち込めないか、といった点にあります。
本記事では 1 つの最小リクエストで経路を通し、その後にストリーミング、ツール呼び出し、エラー切り分け、移行チェックリストを補足します。すべての例はキーを置き換えればそのまま実行できます。
注記：智譜、GLM、BigModel は関連する権利者の商標です。本記事は技術的な説明のみを目的としており、智譜とは提携、代理、許諾の関係にありません。Base URL、モデル名、コンテキスト長、課金の基準は変更される場合があるため、智譜のオープンプラットフォームの公式ドキュメントとサイト内のモデル価格を基準にしてください。
一、接続前の準備
開始前に次の 3 つを確認してください。
- 利用可能な API キーがあり、種類が呼び出すインターフェースと一致している。
- 正しい Base URL があり、公式への直結とゲートウェイのアドレスを混ぜていない。
- 現在実際に利用できるモデル名があり、古い記事の例をそのまま写していない。
新規プロジェクトの場合は、まず curl で認証とネットワークを確認してから SDK を接続することをおすすめします。そうすれば、エラー時にキー、アドレス、コードのどれが問題かを判断しやすくなります。
二、Base URL の書き方
智譜の公式 OpenAI 互換インターフェースの Base URL は、通常次のように書きます。
https://open.bigmodel.cn/api/paas/v4
ZSQH AI Gateway の OpenAI 互換アドレスは次のとおりです。
https://ai.zhongshangqihang.com/v1
どちらも OpenAI の /chat/completions パスを結合して使います。コード内でバージョン部分や /chat/completions を重複して結合しないでください。末尾のスラッシュを適当に足したり削ったりして混在させないでください。
| 接続方式 | Base URL の例 | 向く場面 | 注意事項 |
|---|---|---|---|
| 智譜公式 | https://open.bigmodel.cn/api/paas/v4 |
GLM のみを使い、最新機能が必要 | 公式アカウントと残高が必要 |
| ZSQH ゲートウェイ | https://ai.zhongshangqihang.com/v1 |
複数モデルの統一入口、統一請求 | ゲートウェイでキーを作成する必要がある |
三、モデル名の選び方
GLM 系列は能力別にテキスト、視覚、音声、ベクトルなどのカテゴリに分かれます。テキストモデルにも階層があり、汎用対話と Agent に向くもの、低遅延と高並列に向くもの、より長いコンテキストに対応するものがあります。公式ドキュメントに現在記載されている GLM-5 系列を例にすると、glm-5.3、glm-5.3-flash、glm-5.2 などの表記が一般的ですが、モデルは継続的に更新されます。実際に利用できる名前はコンソールとモデル価格ページを基準にしてください。
選定では「最も強い」ものだけを見ないでください。カスタマーサポートの質問応答やバッチ分類では、低遅延の階層のほうが割安なことがよくあります。長文書の分析や複雑な Agent では上位構成を使います。モデル名はコードに固定せず設定項目にすると、後の切り替えがはるかに楽になります。
タスクが画像理解を含む場合は、視覚入力に対応するモデルを選びます。ベクトル検索を含む場合は embedding 系列を使います。テキスト、視覚、ベクトルのモデルはインターフェースのパスとパラメータが完全には同じではないため、同じリクエストボディを無理に使い回さないでください。公開前に候補モデルを同じ評価セットに入れ、精度、遅延、使用量を比較してから主力と予備を決めます。
四、curl で最初の呼び出しを通す
まず環境変数を用意し、キーがコマンド履歴に残らないようにします。
export GLM_API_KEY="your_key_here"
curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
-H "Authorization: Bearer $GLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.3",
"messages": [
{"role": "system", "content": "あなたは簡潔な技術アシスタントです。"},
{"role": "user", "content": "API ゲートウェイとは何かを 3 文で説明してください。"}
],
"temperature": 0.6
}'
正常に返ったら、3 つのフィールドを重点的に確認します。choices[0].message.content が回答、usage が今回の使用量、finish_reason が終了理由です。401 が返る場合はキーとリクエストヘッダーを、1211 が返る場合はモデル名を先に確認してください。
五、Python SDK での呼び出しとストリーミング出力
OpenAI SDK は 1.0 以上が必要です。Base URL を GLM に向けると、呼び出し方は OpenAI とほぼ同じになります。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("GLM_API_KEY"),
base_url="https://open.bigmodel.cn/api/paas/v4",
)
stream = client.chat.completions.create(
model="glm-5.3",
messages=[{"role": "user", "content": "100 文字以内で製品紹介を書いてください。"}],
stream=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 にテキストがあると決めつけないでください。思考モードを有効にすると、推論内容が reasoning_content フィールドに現れ、最終回答は引き続き content に入ります。両者は分けて処理し、推論過程をそのままエンドユーザーに表示しないようにしてください。
六、ツール呼び出しとパラメータの差異
ツール呼び出しは OpenAI の tools と tool_choice の形式を踏襲します。モデルが message.tool_calls を返したら、各呼び出しの function.arguments を JSON として解析し、ローカル関数を実行して、結果を tool ロールのメッセージとして返します。本番環境ではパラメータの検証とタイムアウト制御を行い、モデルが生成したパラメータをそのまま信頼しないでください。
OpenAI から移行する際は、いくつかの差異に注意してください。temperature の範囲は通常 0 から 1 の間で、0 を渡しても効かない場合があります。既定値は約 0.6 です。一部の新しい機能は extra_body でパラメータを渡す必要があります。具体的なパラメータは公式の OpenAI 互換ドキュメントを基準にしてください。
ストリーミングではクライアントの切断も処理してください。ユーザーがページを閉じた後、サーバーはできるだけ早く上流のリクエストをキャンセルし、生成と課金が続かないようにします。業務上どうしても完全な生成が必要な場合は、タスクをバックグラウンドのキューに移し、フロントエンドの接続に依存しないようにしてください。
七、よくあるエラー対応表
| 現象 | 考えられる原因 | 対処 |
|---|---|---|
| 401 / 1000 | キーの誤り、種類の不一致 | キーの種類とリクエストヘッダーを確認 |
| 1211 | モデル名が存在しない、または未開通 | コンソールで利用可能なモデルを確認 |
| 1261 | 入力がコンテキスト上限を超過 | プロンプトを圧縮するか分割 |
| 1302 / 1305 | アカウントのレート制限、またはプラットフォームの混雑 | 同時実行を下げ、バックオフ再試行 |
| 1113 | アカウントの未払い | チャージしてから再試行 |
| 接続タイムアウト | DNS、プロキシ、ネットワーク経路 | まず curl でネットワーク層を特定 |
再試行が有効なのは 429、5xx、ネットワークタイムアウトだけです。401、1211、1261 のようなエラーは再試行しても改善せず、時間と割当を浪費するだけです。
八、OpenAI からの移行チェックリスト
- 既存のプロンプト、モデルパラメータ、評価セットをバックアップする。
- GLM 専用のキーを新規作成し、他社のキーを再利用しない。
- Base URL とモデル名を設定項目に変更する。
- 同じサンプル群で出力品質、遅延、使用量を比較する。
- ストリーミングの解析、ツール呼び出し、JSON 出力の互換性を確認する。
- 再試行、タイムアウト、同時実行を調整し、1 週間観察してから全量に切り替える。
九、よくある質問（FAQ）
1. GLM API は OpenAI と完全に互換ですか？
よく使われるインターフェースの大部分は互換ですが、パラメータの範囲、思考フィールド、一部の高度な機能には差異が残ります。公式の OpenAI 互換ドキュメントに沿って項目ごとに検証し、すべてのパラメータが同じ動作をすると決めつけないでください。
2. Base URL の末尾にスラッシュは必要ですか？
公式ドキュメントではスラッシュありとなしの両方の表記が見られます。SDK は通常自動で処理します。重要なのはパスを重複して結合しないことで、どちらか一方の表記を選び、プロジェクト内で統一してください。
3. ストリーミング出力で推論過程を取得できますか？
一部のモデルは思考モードで reasoning_content を返します。表示するかどうかは製品設計によります。エンドユーザー向けには通常、最終回答だけを表示します。
4. ツール呼び出しは OpenAI と同じ形式ですか？
ツール定義と返却構造は基本的に OpenAI の形式を踏襲しますが、パラメータの細部はモデルによって変わる場合があります。公開前に実際のツールで回帰テストを行ってください。
5. 公式とゲートウェイのモデル名は同じですか？
多くの場合は同じモデル名を使いますが、ゲートウェイが特定のモデルを開通しているか、特定のパラメータに対応しているかは、ゲートウェイのコンソールとモデル価格ページを基準にしてください。
