BroadRouter
始める

BroadNet Inference で Instructor を使って構造化出力を得る

更新日

base_url を https://inference.broadnet.ai/v1 にし、BroadNet のキーを設定した OpenAI クライアントを instructor.from_openai でラップします。次に、response_model に Pydantic クラス、model に broadnet/glm-5.3 か broadnet/qwen3.8-27b を指定して chat.completions.create を呼びます。BroadNet がツールと構造化出力を掲載しているのはこの 2 モデルです。デフォルトは Mode.TOOLS で、Mode.JSON_SCHEMA も使えます。

Instructor は、LLM の返答を検証済みの Pydantic オブジェクトに変換し、検証に失敗したときは再試行もできる Python ライブラリです。OpenAI クライアントにパッチを当てる仕組みで、ドキュメントでは base_url による OpenAI 互換サーバーへの接続も説明されています。BroadNet Inference は https://inference.broadnet.ai/v1 で chat completions を提供し、GLM 5.3 と Qwen3.8 27B にツールと構造化出力を掲載しています。BroadRouter は BroadNet 自身のサイトです。この記事はバージョン 1.17.0 時点の Instructor のドキュメントに従っています。

インストール

pip install instructor
export BROADNET_API_KEY='your-broadnet-key'

オブジェクトを抽出する

import os
import instructor
from openai import OpenAI
from pydantic import BaseModel

class Invoice(BaseModel):
    vendor: str
    total: float
    currency: str

client = instructor.from_openai(
    OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"]),
    mode=instructor.Mode.TOOLS,
)

invoice = client.chat.completions.create(
    model="broadnet/glm-5.3",
    response_model=Invoice,
    max_tokens=4000,
    messages=[{"role": "user", "content": "Acme Trading invoice, total 1,250.00 SAR"}],
)
print(invoice)

Instructor は Invoice をツールのスキーマに変換し、tool_choice でモデルにそのツールを強制的に呼ばせて、引数を検証します。オブジェクトが検証を通らないと、検証エラーを添えて再度リクエストします。その回数は max_retries で制御します。

from_provider を使う場合

pclient = instructor.from_provider(
    "openai/broadnet/glm-5.3",
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
)
invoice = pclient.create(response_model=Invoice, max_tokens=4000,
                         messages=[{"role": "user", "content": "Acme Trading, 1,250.00 SAR"}])

openai/ の部分でクライアントが決まります。残りの broadnet/glm-5.3 がモデル ID として送られます。

どのモードを使うか

Mode 送られる内容 BroadNet での利用
Mode.TOOLS(デフォルト) スキーマを使った強制的なツール呼び出し 可。GLM 5.3 か Qwen3.8 27B で
Mode.JSON_SCHEMA タイプ json_schema の response_format 可。GLM 5.3 か Qwen3.8 27B で
Mode.MD_JSON 通常のリクエスト。テキストから JSON をパース ほかのモデル用の代替手段。先にテストを
Mode.RESPONSES_TOOLS Responses API 不可:BroadNet が提供するのは chat completions

画像

Qwen3.8 27B はツールに加えて画像も受け付けるので、写真やスキャンを直接モデルのオブジェクトに読み込めます。

import base64
img = base64.b64encode(open("invoice.jpg", "rb").read()).decode()
invoice = client.chat.completions.create(
    model="broadnet/qwen3.8-27b",
    response_model=Invoice,
    max_tokens=4000,
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Extract the invoice fields."},
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64," + img}},
    ]}],
)

従量課金のキーでは、画像は入力トークンとして数えられます。ビジョンでアラビア語の請求書を読むを参照してください。

テスト方法

2026-11-15 に、クリーンな仮想環境に instructor 1.17.0 と openai 3.3.0 をインストールし、上記の例を、BroadNet の chat completions の形式で応答するローカルのモックサーバーに対して実行しました。記録されたリクエストを確認したところ、Mode.TOOLS はスキーマをツールとして強制の tool_choice 付きで送り、Mode.JSON_SCHEMA は json_schema の response format を送り、どちらも有効な Invoice を返しました。from_provider はモデル ID をそのまま送りました。モックは自由形式のテキストで JSON を書かないため Mode.MD_JSON はテストしておらず、画像の例も送っていません。BroadNet のキーは持っていなかったため、実際のモデル出力はテストしていません。

トラブルシューティング

  • 検証の再試行がいつまでも成功しない。 GLM 5.3 と Qwen3.8 27B では、推論が max_tokens に含まれます。上限が低いとツールの引数が途中で切れることがあります。上げてください。回答が空で返ってくる理由。
  • リクエストが 400 になる。 GLM 5.3 か Qwen3.8 27B を使っているか確認してください。強制の tool_choice が拒否される場合は、Mode.JSON_SCHEMA を試してください。
  • 401。 キーが間違っている、期限切れ、または利用枠を使い切っています。
  • 404。 base_url は /v1 で終わっている必要があります。GLM 5.3 と Qwen3.8 27B にはチャージが必要で、$5 のクレジットでは使えません。
  • バッチ抽出で 429 になる。 従量課金のキーでは 1 分あたり 30 リクエスト、処理中のリクエストは同時に 4 個までです。検証の再試行も 1 回ごとに別のリクエストになります。エラーとリトライを参照してください。

よくある質問

BroadNet では Instructor のどのモードを使えばいいですか?

デフォルトの Mode.TOOLS を、BroadNet がツールと構造化出力を掲載している GLM 5.3 か Qwen3.8 27B で使ってください。Mode.JSON_SCHEMA は代わりに json_schema の response_format を送ります。私たちのモックサーバーでのテストでは、どちらも有効なオブジェクトが得られました。

Mode.RESPONSES_TOOLS は使えますか?

いいえ。Instructor のドキュメントは、サーバーが Responses API を実装していない限りこのモードを選ばないよう書いています。BroadNet が提供しているのは chat completions だけです。

Instructor は BroadNet の DeepSeek V4.1 Flash や Gemma でも使えますか?

BroadNet はこれらのモデルにツールや構造化出力を掲載していません。Mode.MD_JSON はプレーンテキストで JSON を求めてパースするので動く可能性はありますが、頼る前に自分のデータでテストしてください。

from_provider のモデル文字列はどう書けばいいですか?

openai/broadnet/glm-5.3 と書きます。Instructor は最初のセグメントをプロバイダーとして切り出します。私たちのテストでは、broadnet/glm-5.3 がそのままサーバーに送られました。

Markdown で読むChatGPT に聞くClaude に聞くPerplexity に聞く