Transformersコミュニティがツール構造の変換不具合を報告、複合型でパラメーター制約が失われる可能性

9月26日、Hugging Face Transformersコミュニティで、ツール呼び出しに関する不具合が報告された。`get_json_schema()`がユニオン型を処理する際、配列要素や列挙値の制約を失う可能性があるという。報告者によると、リリース版5.17.0と開発版の両方で再現できる。確認時点でissueは未解決のままで、修正PRにもリンクされていない。[コミュニティの報告](https://github.com/huggingface/transformers/issues/49122)

この変換は、モデルがツールの説明を受け取る入口にあたる。公式ドキュメントによると、開発者はPython関数を`apply_chat_template()`の`tools`引数に渡すことができ、システムは型ヒントと説明文を読み取って、ツール用のJSON Schemaを生成する。エージェントを開発する際、パラメーターの誤りを調査するには、プロンプトやモデルの出力だけでなく、テンプレートに渡した構造が関数シグネチャを正しく反映しているかも確認するとよい。変換段階で情報が失われたことを、モデルの能力の問題と誤認するのを避けられる。[公式のツールドキュメント](https://huggingface.co/docs/transformers/main/en/chat_extras)

報告の例では、文字列または文字列配列を受け取る`str | list[str]`を変換すると、文字列と配列という大まかな型だけが残り、配列要素が文字列でなければならないことを指定する`items`が欠落する。別の例では、`Literal`と整数を組み合わせたパラメーターから、許可される文字列の選択肢を制限する`enum`が失われる。これらの事例はツール記述の生成に関するもので、下流でモデルが誤ってツールを呼び出す割合のデータは示されていない。[再現例](https://github.com/huggingface/transformers/issues/49122)

5.17.0のソースコードを確認すると、ユニオン型の分岐では、すべての子スキーマの`type`が文字列であれば、それらを型のリストにまとめている。配列や列挙型もこの条件に該当するため、ほかの制約が破棄される。コードには、子スキーマ全体を保持する`anyOf`分岐がすでにある。報告者が提案している修正の方向性は、先行する条件をより厳しくすることだ。[リリース版のソースコード](https://github.com/huggingface/transformers/blob/v5.17.0/src/transformers/utils/chat_template_utils.py)

影響を受ける条件には境界もある。型が1つだけで、それに`None`が加わる場合は別の分岐に進むため、すべてのオプショナルパラメーターが影響を受けるわけではない。コードの動作から推測すると、アプリケーションが制約の弱まったスキーマを検証に使う場合、本来許可されないパラメーターを受け入れる可能性がある。実際の結果は、チャットテンプレート、モデル、ツール実行側の検証に左右される。

エンジニアリングチームは、自動生成されたスキーマを確認し、不正な配列要素や許可されていない列挙値を使ったテストを追加できる。公式には手書きのJSON Schemaを直接渡す方法もあり、自動変換を回避できる。今後はメンテナーの確認、回帰テスト、修正版のリリースを追う必要がある。現時点で影響を受けるバージョンの全リストはなく、コミュニティが提案した変更をリリース済みの修正として扱うことはできない。[ツールの定義方法](https://huggingface.co/docs/transformers/main/en/chat_extras)