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 回ごとに別のリクエストになります。エラーとリトライを参照してください。
