15 分で読了
このページの目次

本番環境向けチェックリスト

これまでの全章を「評価セットの作成」から「グレープリリース」、そして「オンラインでの失敗ごとに回帰テストを追加」というリリースライフサイクルへと結びつけます。これはAIセクションの最終ページであり、いつでも参照できるチェックリストです。

概要

これまでの10数章では、モデル、コンテキスト、エージェント、アプリケーションパターンを個別に解説しました。本章ではその逆で、LLM/エージェントアプリケーションのリリース順序に従ってそれらを結びつけ⁠、総括的なまとめとして、かつチェック可能なチェックリストとして機能させます。

一貫して貫かれる2つの核心的な信念があります。

  • 評価なしに改善はあり得ない。 プロンプトを変更し、モデルを交換し、ツールを追加したとして、なぜ「良くなった」と言えるのか？——それは勘ではなく、評価（eval）によるものです（評価と観測可能性参照）。
  • リリースするかどうかをまず確認し、次に方法について議論する。 ワークフロー で記述できるものはエージェントにせず、単一エージェント で対応できるものはマルチエージェントにしない——最も安定したシステムは、最もシンプルなものです。

リリースライフサイクル

flowchart TD
    A["① レベルの選択<br/>ワークフロー？エージェント？マルチエージェント？"] --> B["② 評価セットの構築<br/>小さく現実的、境界ケースを含む"]
    B --> C["③ プロンプト/モデル/イフェルトの調整<br/>評価セットに対して調整"]
    C --> D["④ 保護の導入<br/>サンドボックス/権限/インジェクション/シークレット"]
    D --> E["⑤ 観測可能性の接続<br/>トレース + 使用量 + 停止理由"]
    E --> F["⑥ グレープリリース<br/>少量トラフィック、ロールバック可能"]
    F --> G["⑦ オンラインでの失敗<br/>回帰評価として固定"]
    G --> C

以下、各段階ごとのチェック項目を示します。各項目は、詳細な解説がある該当章へのリンクを指しています。

① レベルの選択：安易にエージェントを使わない

エージェントを導入する前に、4つの関門 を通過してください（いずれかでも「No」であれば、よりシンプルなレベルに戻ってください）。

  • 複雑さ⁠: タスクが複数ステップに分かれており、事前に完全に規定できないか？（フローをハードコードできる場合 → ワークフローを使用）
  • 価値⁠: その結果は、より高いコストとレイテンシに見合うか？
  • 実現可能性⁠: モデルは本当にこの種の仕事が得意か？
  • エラーのコスト⁠: 失敗した場合に検知およびロールバックできるか？（テスト/監査/フォールバックがあるか）

マルチエージェントの場合、さらに1つ質問を追加します。⁠単一エージェント＋良いツールでは解決できない場合にのみ、マルチエージェントを採用する⁠（マルチエージェント オーケストレーション参照）——マルチエージェントは調整オーバーヘッド、コンテキスト同期、デバッグの複雑さを導入します。

② まず評価セットを作り、調整を始める

最も重要なプラクティス：手を動かす前に、小さく現実的な評価セットを持つこと。 20件程度の代表性のあるタスク（既知の失敗ケースや境界ケースを含み、ハッピーパスだけでなく）でも、単一の勘に頼るよりもはるかに優れています（評価と観測可能性参照）。

  • 評価セットには、順調なシナリオだけでなく失敗/境界ケースが含まれている。
  • 採点は信頼性の高い順：⁠プログラム可能な検証 > LLM-as-judge > 結果スコアリング。assert で検証できる場合は審判を呼ばない——構造化出力 を用いることで、この種の検証を安定して実行可能にする。
  • LLM 審判はテスト対象から分離する⁠（自己採点を避ける）、⁠独立して判定可能なルーブリックを与える。

③ 勘ではなく評価セットに対して調整する

  • プロンプト⁠: 「必須」を羅列するのではなく、「いつ/境界」を記述する。正例は反例よりも優れている（プロンプトエンジニアリング参照）。
  • イフェルト (effort): 最初は high で始め、評価セット上で medium/high/xhigh をスキャンして決定する——関係性は単調ではない（推論と思考参照）。
  • サンプリングパラメータ⁠: 新モデルでは既に削除されている。旧コードの temperature は削除し、プロンプトとイフェルトに置き換える。
  • 出力形状⁠: 下流に渡す場合は output_config.format / strict を使用する。「JSONを返してください」という頼みに頼らないこと。
  • 知識⁠: 私有/リアルタイム知識は RAG を通じて処理し、生成を調整する前にまず recall@k を最大化する。
  • コンテキスト予算⁠: 安定するまでプレフィックスを固定してキャッシュを確保し、動的なコンテンツは後続に配置する。長文の会話には圧縮 (compaction) やコンテキスト編集を使用する。

④ 保護の導入：モデルの出力は信頼できないものとする

リリース前に、セキュリティと保護 のゲートをすべて設置する。

  • bash/ツール⁠: 隔離された環境 + 許可リスト + タイムアウト + ログ；コマンドは信頼できない出力として扱う。
  • パス⁠: 正規化 + 境界検証、../シンボリックリンク/URLエンコードされたトラバーサルを拒否する。
  • 危険な操作⁠: 不可逆的な操作はヒューマン・イン・ザ・ループとし、可逆性に基づいて階層化し、最小権限を適用する。
  • インジェクション⁠: ツールの出力はデータとして扱い、指示として扱わない。オペレータの指示は role:system の信頼できるチャネル経由で渡す。
  • シークレット/PII: コンテキスト/メモリ/プロンプトに決して含めない。資格情報はプロキシ経由で注入し、マルチテナントを分離する。
  • 出力側⁠: content を読み取る前に stop_reason を確認する（拒否処理を行う）。SQL/HTML/shell に出力する前に、パラメータ化されたエスケープを適用する。

⑤ 観測可能性の接続：「どのステップで問題が発生したか」に答えられるようにする

観測可能性なしでのリリース＝大惨事。評価と観測可能性 を接続する。

  • トレース/スパン⁠: 各 tool_use/tool_result/モデル呼び出しごとにスパンを作成し、レイテンシとコストを段階的に帰属させる（本サイトでは構築時にOTelを初期化している）。
  • 使用量⁠: input/output_tokens、cache_read_input_tokens（長期間0の場合＝キャッシュが静かに無効化されている）、cache_creation_input_tokens を監視する——合計はこれら3つの和であり、1つのフィールドだけを見てはいけない。
  • stop_reason の分布⁠: max_tokens が高い＝出力が切り捨てられている；refusal が異常に高い＝プロンプトが拒否をトリガーしている；pause_turn が多い＝サーバー側のツールループが継続している。
  • コスト/レートリミット⁠: キャッシュヒット率、429 の頻度をダッシュボードに表示する（コスト、パフォーマンス、信頼性参照）。

⑥ グレープリリース：制御可能、ロールバック可能

  • ストリーミング⁠: 長入力/長出力はすべてストリーミングとし、非ストリーミングHTTPタイムアウトを回避する。
  • リトライ/冪等性⁠: 429/5xx のみリトライする。副作用のあるアクションには冪等キーと人間の確認を付与する。
  • 帰属⁠: 並列/Batches の結果は custom_id/トレースIDで対応させ、順序に頼らない。
  • 少量トラフィックから開始⁠: 新しいプロンプト/モデルはまず少量のトラフィックでグレープリリースし、評価セットとオンライン指標を比較してから拡大する。ロールバック経路を残す。
  • モデル変更時のキャッシュ注意⁠: モデルを変更すると、該当セグメントのキャッシュは無効化され、トークンのベースラインを再計算する必要がある。メインループ内で中途半端に切り替えない（マルチエージェント オーケストレーション参照）。

⑦ 回帰：失敗ごとに防御線を追加する

  • オンラインで失敗を発見するたびに、⁠それを1つの評価ケースとして固定する⁠——これこそが、時間が経つにつれて評価セットを強化する方法である（評価と観測可能性参照）。
  • ③に戻って再調整し、完全な評価を実行して劣化がないことを確認してから、再度リリースする。

ベストプラクティス（全セクションの凝縮）

  • まず評価し、その後改善する。 小さく現実的な評価セットは、すべての変更の審判である。それなしでは、すべての「最適化」は賭け事である。
  • シンプルさを保つ。 ワークフロー > 単一エージェント > マルチエージェント；レベルを上げるごとに発生する調整コストが、リターンに見合う必要がある。
  • ウィンドウを予算として管理する。 キャッシュのプレフィックス固定、検索による無理な埋め込みの回避、イフェルトによる深さの調整——これら3つがコストと品質を管理する。
  • モデルの出力はすべて信頼できないものとする。 セキュリティの境界はホスト側の実行環境に設ける：サンドボックス、パス検証、危険な操作の承認、シークレットをコンテキストに入れない。
  • 各ステップを定量化する。 トレース + 使用量 + stop_reason により「どのステップが間違っていたか」が見える化する。観測可能性が欠如していれば、それは闇雲な変更である。
  • 作成とレビューは別のレーンで行う。 実行するエージェント自身を検証しない。別のレビュアー/検証者を独立したコンテキストで評価させる（マルチエージェント オーケストレーション参照）。
  • オンラインでの失敗 → オフラインでの回帰。 各事故が1つの評価ケースとなり、防御線は増えるだけで減らない。

トレードオフと失敗パターン

  • 評価なしでの調整⁠: 勘で変更し、「良くなった」のか「別の間違い方に変えただけ」なのか区別できない → まず20件の現実的な評価セットを構築する。
  • 反射的なエージェント/マルチエージェントの導入⁠: 調整オーバーヘッド > リターン、かつデバッグがさらに困難になる → 4つの関門を通過し、ワークフローで済むならエージェントにしない。
  • 観測可能性なしでのリリース⁠: 問題が発生した際にどのステップで起きたか、トークンをどれくらい消費したかがわからない → トレース + 使用量 + stop_reason をまず接続する。
  • キャッシュヒット率の監視漏れ⁠: コストが気づかないうちに数倍になってから発見する → cache_read_input_tokens をダッシュボードに追加する。
  • ハッピーパスのみのテスト⁠: オンラインで境界ケースに遭遇するとすぐに崩壊する → 評価セットに境界を含め、事故の発生とともに成長させる。
  • 実行エージェントの自己評価⁠: 自己認証となる → レビューは別の独立したレーンで行う。
  • プロンプト/モデルの全量一括リリース⁠: 回帰での比較ができず、事故発生時にロールバックが困難 → グレープリリース + ロールバック経路の確保 + 完全な評価の実行。

参考

Keywords: 本番化, production checklist, リリースライフサイクル, eval-first, workflow vs agent, グレープリリース, canary, ロールバック, rollback, regression, 回帰, observability, trace, span, OTel, usage, stop_reason 分布, プロンプトキャッシュ, RAG, 構造化出力, 保護, サンドボックス, secret, human-in-the-loop, 冪等性, authoring vs review lane, チェックリスト

関連ページ

© 2026 liz's doc