LLMプロバイダーごとの制約を解決する「Transcript Hygiene」の仕組み

LLMを使ったアプリケーションを開発していると、特定のプロバイダーだけで「メッセージの順番が違う」とか「IDの形式が正しくない」といった理由でエラーが返ってくることがありますよね。プロバイダーごとに異なる細かいルールをすべて手動で管理するのは、開発者にとって大きな負担になります。

こうした「プロバイダーごとのこだわり」を吸収し、コンテキストを構築する直前にデータを整えてくれるのが Transcript Hygiene（プロバイダー修正）という仕組みです。これがあるおかげで、私たちは個別のAPI仕様に振り回されることなく、共通のロジックで対話を管理できるようになります。

必要なもの

この機能を利用・理解するために必要なコンポーネントは以下の通りです。

• Embedded runner: 修正ロジックが組み込まれている実行環境
• Transcript policy: プロバイダーやモデルに応じた適用ルール（src/agents/transcript-policy.ts）
• Session repair logic: 読み込み時にファイルを修復する仕組み

クイックスタート

Transcript Hygieneは、モデルにコンテキストを渡す直前に インメモリ で実行されます。ディスク上のJSONLファイルを直接書き換えるのではなく、送信直前のデータを「衛生的に」整えるイメージです。

1. グローバルルールの適用

すべてのプロバイダーで共通して適用されるルールが2つあります。

• 画像データのサニタイズ: 送信エラーを防ぐため、サイズ制限を超えるベース64画像は自動でリサイズや再圧縮が行われます。
• 不完全なTool callの除去: input や arguments が欠落しているAssistantのTool callブロックは、エラー防止のために削除されます。

2. プロバイダー別の修正

利用するプロバイダー（provider, modelApi, modelId）に応じて、以下の調整が自動で行われます。

• Google (Gemini系): Tool call IDを厳格な英数字のみに制限し、ユーザーとアシスタントのターンが交互に並ぶよう調整します。
• Anthropic / Minimax: 連続したユーザーターンを統合し、厳格なターンの交代ルールを守るようにします。
• Mistral: Tool call IDを英数字9文字の形式に変換します。
• OpenAI: 基本的に画像サニタイズのみを行い、保存されたデータに極力手を加えない「no-touch」ポリシーを採用しています。

3. セッションファイルの修復

インメモリの修正とは別に、セッションファイルの読み込み時に不正な行を削除する修復パスも存在します。修復が行われる際は、元のファイルのバックアップが自動で作成されます。

トラブルシューティング

よくある問題と、システム内での解決策をまとめました。

• 画像サイズによるリジェクト: sanitizeSessionMessagesImages が自動でダウンスケールを行い、プロバイダーの制限内に収めます。
• Tool call IDの形式エラー: sanitizeToolCallInputs がプロバイダーの期待する形式（例：Mistralなら英数字9文字）に変換します。
• ターンの順序不正: Googleモデルなどで履歴がAssistantから始まる場合、小さなUserターンのブートストラップを先頭に挿入してエラーを回避します。
• 不正な思考プロセスのデータ: OpenRouter Geminiなどで、base64形式ではない thought_signature が含まれる場合は自動で削除されます。

AI Setup Assistant

次のステップ

• /reference/session-management-compaction
• src/agents/transcript-policy.ts の実装詳細を確認する