BroadRouter
始める

オープンモデルのツール呼び出し:スキーマ、並列呼び出し、リトライ

BroadNet Inference チーム · 約 4 分で読めます · 公開日 · 更新日

OpenAI 互換 API のオープンモデルは、OpenAI と同じ tools と tool_calls の形式を使います。スキーマは小さくフラットにし、引数は JSON 文字列としてパースし、実行前に検証し、エラーはツールの結果としてモデルに返してリトライさせます。ステップ数には上限を設けます。BroadNet では GLM 5.3 と Qwen3.8 27B にツール対応の記載があります。

ツール呼び出しは、モデルをエージェントに変えるものです。OpenAI 互換 API でオープンモデルを使う場合も、リクエストの形式は OpenAI と同じです。違うのは、どれくらいの頻度で失敗するかと、それを防ぐためにサーバーが何をしているかです。この記事では、形式、オープンモデルが扱いやすいスキーマの書き方、並列呼び出し、実際に遭遇する 5 つの失敗、そしてそれらを乗り越える Python ループを解説します。

OpenAI 互換 API でツール呼び出しはどう動きますか?

  1. messages と tools のリストを送ります。各ツールには名前、説明、引数の JSON Schema があります。
  2. モデルは finish_reason: "tool_calls" と tool_calls のリストで返答します。各エントリには id、関数名、そして JSON 文字列の arguments があります。
  3. コード側で各呼び出しを実行し、呼び出しごとに対応する tool_call_id を付けた role: "tool" メッセージを 1 つ追加します。
  4. もう一度 API を呼びます。モデルは回答するか、さらにツールを求めます。

モデル自身は何も実行しません。何を実行するかはコードが決めます。

ツールのスキーマはどう書くべきですか?

オープンモデルは、シンプルなスキーマほど確実に従います。次のルールは OpenAI のガイドと、壊れやすいポイントの経験から来ています。

  • ツールは動作で名付けます。read_file や search_code のようにし、説明にはいつ使うかを書きます。
  • **リストは短くします。**OpenAI のガイドは、ターン開始時に関数を 20 個未満にすることをソフトな目安としています。しかも、すべてのスキーマが毎回の呼び出しで送られます。エージェントのトークン予算を参照してください。
  • **引数はフラットにします。**文字列、数値、真偽値、enum を使い、深いネストや自由形式のオブジェクトは避けます。
  • **選択肢が決まっているなら enum を使います。**モデルが値をでっち上げられなくなります。JSON スキーマジェネレーターを使えば、引数のサンプルオブジェクトから、parameters に貼り付けられるフラットなスキーマを作れます。
  • **必須フィールドを明示します。**OpenAI の strict モードでは、additionalProperties: false と、すべてのフィールドを required に入れること、省略可能なフィールドの型に null を加えることが必要です。プロバイダーが strict を強制するかはまちまちなので、いずれにしても検証してください。

並列ツール呼び出しはどう扱いますか?

モデルは 1 ターンで tool_calls に複数のエントリを返すことがあります。たとえば 3 つのファイルの読み込みです。互いに独立した呼び出しは並行して実行し、tool_call_id ごとに結果を 1 つ、順不同で返します。ツールに互いに依存する副作用がある場合は、parallel_tool_calls: false を設定します。OpenAI のガイドによると、これでモデルの呼び出しは 1 ターンあたり 0 回か 1 回に制限されます。プロバイダーがこれに従うかテストしてください。

ツール呼び出しが失敗するのはなぜですか?

失敗 見えるもの 対処
不正な形式の引数 json.loads が例外を出す パースエラーをツールの結果として返し、リトライ
スキーマとの不一致 フィールドの欠落、型の誤り、でっち上げた enum 検証し、検証エラーを返す
未知のツール 定義していない名前 「unknown tool, available: …」を返す
必要なのに呼び出さない テキストで回答してしまう tool_choice: "required" か関数を指定
途中で切れた呼び出し finish_reason: "length" max_tokens を上げる。推論も同じ上限を使う

最初の 2 つはまれではなく、想定しておくべきものです。vLLM のツール呼び出しのドキュメントによると、auto モードでは、ツールが strict: true を設定している(またはサーバーが最低限の厳密さを強制している)うえで、モデルのパーサーが制約に対応している場合を除き、“vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.”(訳:vLLM は生のテキストからツール呼び出しを抽出するため、引数がまれに不正な形式になったり、関数のパラメータースキーマに違反したりすることがある。)関数を指定した場合は、vLLM の構造化出力バックエンドが使われます。プロバイダーのモデルの提供方法は違うかもしれないので、検証は必須と考えてください。

最後の行は、推論モデルを使う人がよくはまるところです。GLM 5.3 と Qwen3.8 27B は回答前に考え、その思考は max_tokens に含まれます。どれだけ余裕を残すべきかは、返答が空になる、または途中で切れる理由で説明しています。

検証してリトライするツールループ

import json, os
from openai import OpenAI
from jsonschema import validate, ValidationError

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
MODEL = "broadnet/glm-5.3"

TOOLS = [{"type": "function", "function": {
    "name": "get_order_status",
    "description": "Look up one order by its ID. Use when the user asks where an order is.",
    "parameters": {"type": "object",
                   "properties": {"order_id": {"type": "string"}},
                   "required": ["order_id"], "additionalProperties": False}}}]
SCHEMAS = {t["function"]["name"]: t["function"]["parameters"] for t in TOOLS}
IMPL = {"get_order_status": lambda order_id: f"Order {order_id}: shipped"}

def run_call(call):
    name = call.function.name
    if name not in IMPL:
        return f"Error: unknown tool {name}. Available: {', '.join(IMPL)}"
    try:
        args = json.loads(call.function.arguments or "{}")
        validate(args, SCHEMAS[name])
    except (json.JSONDecodeError, ValidationError) as e:
        return f"Error: invalid arguments ({e}). Send the call again with valid JSON."
    return str(IMPL[name](**args))

def agent(messages, max_steps=8):
    for _ in range(max_steps):
        r = client.chat.completions.create(model=MODEL, messages=messages,
                                           tools=TOOLS, max_tokens=4000)
        msg = r.choices[0].message
        if r.choices[0].finish_reason == "length":
            raise RuntimeError("Output limit reached; raise max_tokens")
        messages.append(msg.model_dump(exclude_none=True))
        if not msg.tool_calls:
            return msg.content
        for call in msg.tool_calls:
            messages.append({"role": "tool", "tool_call_id": call.id,
                             "content": run_call(call)})
    raise RuntimeError("Step limit reached")

ここで重要な設計上の選択は 3 つです。

  1. **エラーはツールの結果としてモデルに返します。**モデルは何が間違っていたかを見て、たいてい次のターンで直します。例外を投げると、その機会を捨てることになります。
  2. ループには上限があります。max_steps は、進展のないままツールを呼び続けるモデルを止めます。
  3. **通信のリトライは別に扱います。**クライアントの max_retries は 429 と 5xx を扱います。不正な引数はループの中で扱います。この 2 つを混ぜないでください。エラーとリトライを参照してください。

メール送信のような副作用のあるツールでは、冪等キーを付けて、リトライしたステップが 2 回実行されないようにします。これは長時間動くエージェントの記事で扱っています。

BroadNet のどのモデルがツール呼び出しに対応していますか?

モデル ツールの記載 コンテキスト 備考
GLM 5.3 あり 1,048,576 構造化出力にも対応
Qwen3.8 27B あり 262,144 画像入力にも対応
DeepSeek V4.1 Flash 記載なし 1,048,576 画像入力に対応。ツールに頼る前にテストを
Gemma 4 VL 26B 記載なし 32,768 ツールループには不向き

ツール対応の 2 モデルから選ぶには、GLM 5.3 と Qwen3.8 27B の比較をご覧ください。最終的な回答を決まった形にしたいだけで、関数を実行する必要がないなら、ツールより構造化出力のほうがシンプルです。

BroadNet Inference が向いている場面

BroadNet Inference は、ツール呼び出しの記載がある GLM 5.3 と Qwen3.8 27B を標準の chat completions 形式で提供しているので、上のループは OpenAI Python SDK でそのまま動きます。トークンあたりの料金は料金ページにあります。Web 検索やコード実行のようなサーバー側のツールはホストしておらず、無制限プランのモデルである DeepSeek V4.1 Flash については、ドキュメントにツール呼び出しの記載がありません。ツールを多用するエージェントには、トークン課金で GLM 5.3 か Qwen3.8 27B を使ってください。それでも定額プランを使いたいなら、1 か月分を買う前に、$1 の Meteor 1 時間で DeepSeek V4.1 Flash がツールを確実に呼び出せるか確認してください。

よくある質問

オープンモデルは Function Calling に対応していますか?

多くは対応していますが、モデルとプロバイダーの提供方法によります。BroadNet Inference のドキュメントでツール呼び出しが記載されているのは GLM 5.3 と Qwen3.8 27B です。DeepSeek V4.1 Flash と Gemma 4 VL 26B には記載がありません。

ツール呼び出しの引数が不正な JSON になるのはなぜですか?

サーバーがデコードを制約しない限り、引数はテキストとして生成され、後からパースされます。vLLM のドキュメントは、生のテキストから抽出した引数がまれに不正な形式になると述べています。パースエラーを捕まえ、ツールの結果として返せば、モデルが自分で直せます。

並列ツール呼び出しを無効にするには?

OpenAI の形式では parallel_tool_calls を false にします。これで、モデルが 1 ターンに行うツール呼び出しは 0 回か 1 回に制限されます。プロバイダーがこのフィールドに従うか確認してください。

モデルがツールを呼ばずにテキストで答えてしまうのはなぜですか?

tool_choice が auto の場合、判断するのはモデルです。呼び出しが必須なら、tool_choice を required か特定の関数にしてください。ツールの説明に、いつ使うかが書かれているかも確認してください。

ツール呼び出しが途中で切れるのはなぜですか?

推論モデルは思考を max_tokens に含めます。上限が小さいと、引数の途中で返答が終わることがあります。finish_reason を確認し、max_tokens を上げてください。

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