Claude Haiku 5.5へのAPI移行｜設定変更と動作確認のポイント

分類結果が業務へ渡るところまでを移行対象にする

想定するのは、届いた問い合わせを「請求・解約・障害・その他」に分類し、担当部署へ振り分ける処理です。短いラベルを返すだけでも、入力の組み立て、応答の取り出し、ラベルの確認、保存がつながっています。APIが応答したことだけで移行完了にすると、空の分類や想定外の値が後続処理へ流れる可能性があります。

まず現在のモデル名、SDKの版、送信直前の設定、応答を読む関数を確認します。設定ファイルに値がなくても、共通の呼び出し関数がtemperatureなどを追加している場合があります。改修箇所はモデルを指定する一行ではなく、最終的な要求と結果の保存条件から探します。

以下はこの用途に絞った作業案です。コンピューター操作や保存済み会話の再利用には別の変更点があるため、該当する場合は公式移行ガイドも確認してください。

旧設定を外してからeffortを調整する

Claude APIのモデルIDはclaude-haiku-5-5です。旧来のthinking.typeをenabledとしbudget_tokensを渡す設定は400エラーになるため、adaptiveへ変更します。Haiku 5.5ではadaptive thinkingが既定で有効なので、thinkingの指定を省略する構成も選べます。

公式移行ガイドはtemperature、top_p、top_kを省くよう案内しています。厳密にはtemperatureは1、top_pは0.99のみ指定可能で、それ以外の値は400です。top_kはどの値でも、temperatureとtop_pは両方を送っても400になります。既存の共通設定をそのまま引き継がないようにします。

JSONの書き出しを促すため、messagesの末尾にassistantの「{」などを置くprefillも、thinkingの有無にかかわらず400になります。要求をuserのターンで終え、分類の出力形式は構造化出力などで定義し直します。

検証時はoutput_config.effortをmediumに固定して基準を作り、次にlowでも必要な分類を保てるか比べる進め方が考えられます。公式の既定値はmediumです。effortは厳密なトークン予算ではないため、budget_tokensの数値を機械的に置き換える対応表は作らず、用途ごとに選びます。

contentは位置ではなくtypeを見て読む

応答のcontentは複数のブロックを持ち、Haiku 5.5では先頭にthinkingが来る場合があります。「contentの0番目にあるtextを分類結果にする」という読み方を見直し、typeがtextのブロックを取り出す処理にします。

この分類例では、取り出した文字列を所定の形式として解析し、categoryが四つの許可値のいずれかかを確認します。空文字、必須項目の欠落、未定義のラベルは保存せず、確認待ちへ送る設計にします。「その他」は内容に対する分類なので、応答の解析失敗を自動的に「その他」へ変換すると、障害を見落としやすくなります。

ツールを使う処理なら、tool_useを通常の文章として扱わない分岐も必要です。表示するtextの抽出と、次の要求へ渡す会話データの保持は別の処理にし、表示用に抜き出した文章で応答全体を上書きしないようにします。

stop_reasonと内容の両方で保存を判断する

公式資料では、stop_reasonは応答の生成が止まった理由を示します。HTTPが成功でも、必要な分類が完成したとは限りません。この例では、終了理由の確認と、ラベルの形式・内容の確認を通過したものだけを保存する方針を先に決めます。

• end_turn：生成が自然に終了した状態。分類ラベルが存在し、許可値を満たすかを続けて確認する。
• max_tokens：出力上限に到達した状態。途中のJSONを補って保存せず、上限やeffortを見直す対象にする。
• tool_use：ツール呼び出しの要求。必要な処理と結果の返却を行い、分類完了とは数えない。
• refusal：応答を拒否した状態。「その他」へ押し込まず、別の結果として記録して担当者へ渡す。

同じ入力でトークンを数え直し、出力の余裕も確かめる

Haiku 5.5は新しいトークナイザーを使い、同じ入力でもHaiku 4.5より約30%多くのトークンになると公式資料は説明しています。増加幅は内容で変わるため、日本語の問い合わせを一律1.3倍で見積もらず、利用予定のモデルIDで数え直します。

検証用に、短い単独質問、長い経緯の説明、複数の相談が混ざった文章を用意します。本文だけでなく実際に添える分類ルールや例も含め、旧モデルと新モデルへ渡す同じ入力を計数します。Token countingの値は入力の見積もりであり、最終的な利用量は応答のusageと照合します。

出力側は、短い分類ラベルに必要な量だけで上限を決めないことが重要です。thinkingもmax_tokensを消費するため、推論だけで上限に達してtextがない応答も起こり得ます。空の結果を保存しない確認と併せて、長い問い合わせでも必要な出力が残る設定を探します。

入力の修正と分類品質の比較を分けて切り替える

移行確認は二段階に分けると原因を追いやすくなります。まず、旧設定が残らず要求を送れるか、thinkingや空の応答を正しく扱えるかを調べます。その後、業務担当者が正解を付けた問い合わせで、分類先が妥当かを比較します。形式が正しいまま違う部署へ振り分ける問題は、前半の確認だけでは見つかりません。

比較表にはモデルと設定の版、入力ケース、分類結果、終了理由、所要時間、利用トークンを残します。たとえば「請求書の宛名変更」と「請求が止まらないので解約したい」を別のケースにすると、単語が似ていて判断が違う場面を確認できます。匿名化した同じ入力を使い、モデル以外の変更を増やしすぎないようにします。

切り替え条件は、主要な分類を維持できること、解析失敗を分類結果として保存しないこと、許容する待ち時間に収まることを、担当者と合意して決めます。旧モデル用の設定を復旧用に保存し、新設定は一部の処理で試します。条件を外れたら戻せる単位で進め、仕様の把握を、自社の処理を置き換えられるかの判断へつなげます。