Webエンジニア向けプログラミング解説動画をYouTubeで配信中!
▶ チャンネル登録はこちら

【ITニュース解説】Why reasoning_effort behaves differently across providers

2026年10月19日に「Dev.to」が公開したITニュース「Why reasoning_effort behaves differently across providers」について初心者にもわかりやすく解説しています。

作成日: 更新日:

ITニュース概要

OpenAI互換API利用時、クラウド・vLLM・リレーで`reasoning_effort`設定の扱いやエラー応答が異なり、ツール機能が動かない問題が発生した。エラーメッセージを正確に解釈し、各エンドポイントの挙動に合わせて設定を調整する必要がある。設定名が似ていても動作は大きく異なる点に注意が必要だ。

ITニュース解説

システムエンジニアとして、AI(人工知能)を活用したアプリケーションを構築する際、異なるAIモデルや提供元(プロバイダー)を組み合わせることは多い。しかし、これらのAIプロバイダーは見た目が似ていても、内部の動作や設定の解釈が微妙に異なることがあり、これが予期せぬ問題を引き起こす。この記事では、AIモデルの「思考プロセス」を制御する「reasoning_effort」という設定が、プロバイダー間でどのように異なる振る舞いを見せ、それを解決するためにどのような工夫が必要だったかを解説する。

問題となったのは、AIモデルが応答を生成する前に、どれくらいの「思考」を行うかを指定する「reasoning_effort」という設定だった。例えば「'none'」に設定すれば思考プロセスを省略し、迅速な応答を期待できる。我々のアプリケーションは、OpenAI互換の/v1/chat/completionsというAPIエンドポイントを利用して、クラウドサービス、自社で構築したvLLM(大規模言語モデルを高速で実行するためのフレームワーク)、そしてこれらを中継するリレーサーバーといった複数の環境にアクセスしていた。

最初の問題は、クラウドプロバイダーの一種であるgpt-5.6-lunaモデルとの連携時に発生した。アプリケーションが、外部ツール(例えばブラウザ操作を行う機能)とreasoning_effort設定を同時にAPIリクエストで送信したところ、400エラーというステータスコード(「不正なリクエスト」を示す)が返された。エラーメッセージには「Function tools with reasoning_effort are not supported for gpt-5.6-luna in /v1/chat/completions. To use function tools, use /v1/responses or set reasoning_effort to 'none'.」と明確に記されていた。しかし、アプリケーションはこのメッセージの「tool」と「not supported」という部分だけを読み取り、「このモデルはツールをサポートしていない」と誤って判断してしまった。その結果、以降のAPIリクエストではツール機能を一切送らなくなり、ブラウザ操作が必要な場面でも何も実行されない状態に陥った。これは、モデルがツールを避けているように見えたが、実際にはツールが送られていなかっただけという、初歩的な誤解が原因だった。エラーメッセージには、解決策が明記されていたにもかかわらず、アプリケーションがこの後半部分を読み飛ばしてしまったことが問題の根源である。この誤りを修正し、エラーメッセージの指示通りreasoning_effort: 'none'を設定してツールを再送信するようにしたところ、無事にツールが利用できるようになった。この修正によって、入力から出力開始までのレイテンシ(遅延時間)が4〜5秒からわずか2秒に短縮されるという、パフォーマンス上の大きなメリットも得られた。

次に、自社で構築・運用しているvLLMインスタンスに同じ設定を適用した際に、別の問題が発生した。reasoning_effort: 'none'という設定を送ると、再び400エラーが返された。エラーメッセージは「Input should be 'low', 'medium' or 'high'」というもので、vLLMでは'none'という値が受け入れられず、代わりに'low'、'medium'、'high'のいずれかを指定する必要があることを示していた。この違いは、単に会話を行うだけのテストでは見過ごされがちだが、ツール呼び出しのパスをテストすることで明らかになった。vLLMに対しては、reasoning_effortの送信自体をやめ、代わりにchat_template_kwargs: { enable_thinking: false }という別の設定を送ることで、思考プロセスを無効化するように変更した。この変更後、思考を無効化する様々な方法を比較したところ、enable_thinking=falseが最も良好な応答時間を示すことがわかった。 さらに、AIモデルが生成した「思考」の内容を読み取る際にも問題が生じた。プロバイダーによって思考結果を出力するフィールド名が異なり、例えばreasoning、reasoning_content、thinkingといった複数の名前が使われていたが、アプリケーションの読み取り側はreasoningというフィールド名しか見ていなかったため、vLLMからの思考結果を認識できず、「空の応答」と誤って判断することがあった。これも、各プロバイダーの仕様に合わせて読み取り側を調整することで解決した。

三つ目の問題は、リレーサーバーとの連携時に発生した。アプリケーションはAPIからの応答をストリーミング形式(データが少しずつ送られてくる形式)で受け取ることを想定し、stream: trueというフラグを送信していた。しかし、一部のリレーサーバーエンドポイントは、このフラグを無視して標準的なJSON形式の応答を一度に返してきた。アプリケーションはdata:で始まる行だけを処理するように実装されていたため、標準JSONの応答からは何もデータを受け取ることができなかった。response.ok(応答が成功したかを示す)はtrueだったため、エラーも発生せず、画面には何も表示されないという非常に分かりにくい状況に陥った。この問題は、Content-Typeヘッダをチェックして、応答がストリーミングか標準JSONかを判別するように変更することで解決した。 さらに別のリレーサーバーエンドポイントでは、ストリーミングを有効にした場合にのみ200 OK(「成功」を示す)を返すが、応答ボディが完全に空という現象が発生した。非ストリーミング呼び出しでは400エラーを返す。空の応答ではエラーメッセージすらなく、原因を特定するのが困難だった。このような場合、アプリケーションは空の応答を例外として扱い、まず「思考」に関する設定を無効にして一度リトライするように設定した。それでも問題が解決しない場合は、そのエンドポイントへのリクエストを停止するようにした。この修正により、設定なしでリトライした際に正しいJSON応答が返されるようになった。

これらの経験から、プロバイダーごとに以下のような対応が必要であることが明らかになった。標準的なOpenAI互換のエンドポイントでは、reasoning_effort: 'none'を送信する。vLLMのように'none'が許容されないエンドポイントでは、chat_template_kwargs: { enable_thinking: false }を使用する。ストリーミング時に空の応答を返すリレーサーバーには、reasoningに関する設定自体を送信しない。これらの判断は、すべて実際の測定結果に基づいて行われた。ユーザーに尋ねるのではなく、アプリケーションがエンドポイントからの応答に基づいて学習し、適切な設定を選択するようにしたのだ。

しかし、プロバイダー間の違いに対応するための修正を行った後、私自身がいくつかの新たな問題(退行)を引き起こしてしまった。 一つ目の退行は、400エラーボディの処理が広すぎたことである。以前のロジックでは、400エラーメッセージの中に「invalid」という単語が含まれていれば、すべてのエラーを同じように「値が拒否された」と判断していた。その結果、gpt-5.6-lunaモデルで必須だったreasoning_effort: 'none'という設定が、誤って「reasoning_effortフィールドが存在しない」と判断され、リクエストから除外されてしまった。これにより、ブラウザ操作全体が再び機能しなくなった。この問題の根本原因は、テスト用に作成したカスタムエラーメッセージが実際のAPIのエラーメッセージと微妙に異なっていたことだった。テスト内容を、実際のAPIから記録されたエラーボディを直接使用するように調整することで、この問題を修正した。 二つ目の退行は、ローカル環境用の設定をクラウド環境にも適用してしまったことである。音声会話機能でAIの思考内容を自動的に短縮する設定を有効にしていたが、これが意図せず公式のクラウドエンドポイントにも適用されてしまい、OpenAIに対してreasoning_effortの設定がnoneとして送信される事態となった。これにより、すべての応答生成リクエストが60秒後にタイムアウトし、500エラー(サーバー内部エラーを示す)が発生した。OpenAIのシステム状況は正常だったにもかかわらず、連続してエラーが発生したため、原因究明に時間を要した。この設定は、エンドポイント固有の意味合いを考慮せず、全体に適用してしまったのが誤りだった。この問題は、設定をローカルプロバイダーに限定することで解決した。 さらに、拒否されたフィールドのリトライメカニズムにも欠陥があった。以前のロジックでは、一つの発話に対して一度しかリトライが許されなかった。そのため、複数のフィールドが拒否された場合、最初の拒否でリトライは終了し、残りの問題はサイレントに失敗していた。このロジックを改善し、拒否されたフィールドを検出するたびに、最大8回までリトライを試みるようにした。ただし、エラーで失敗する前に少なくとも1文字の応答が受信できた場合は、リトライは行わないようにした。

これらの経験から得られた重要な教訓は以下の通りである。

  • 400エラーを受け取った際は、エラーメッセージ全体を詳細に読み込み、正確にエラーの種類を分類する必要がある。
  • reasoning_effortのようなAIモデルの動作を制御する設定は、各プロバイダーやエンドポイントの実際の振る舞いを観察し、それに基づいて個別に対応する必要がある。
  • vLLMのように特定の値が拒否される場合は、プロバイダー固有の代替設定(例:chat_template_kwargs: { enable_thinking: false })を使用する。
  • リレーサーバーがストリーミング時に空の応答を返す場合、reasoning設定なしでリトライし、そのエンドポイントには設定を送信しないようにする。
  • テストでは、実際のAPIから記録された応答データを使用し、プロバイダー固有の設定をしっかりと行うことが重要である。 異なるAIサービスを連携させる際には、一見互換性があるように見えても、それぞれの実装の詳細やエラーハンドリング、設定の解釈に違いがあることを常に意識する必要がある。APIドキュメントを丁寧に読み込み、実際の挙動をテストで確認し、プロバイダーごとの差異を吸収する柔軟な設計を心がけることが、安定したAIアプリケーションを構築するための鍵となるだろう。

関連コンテンツ

関連IT用語