LLM Preflight

LLM Preflight

最終レビュー日： 2026-10-19 · 対象バージョン： v2.22.2

モデル、プロンプト、スキーマ、プロバイダーを変更する前に、アプリケーションが依存する出力ルールに照らして LLM の応答をチェックします。

機能に必要な JSON の形式、ルーティングラベル、または厳密な出力を定義します。 応答がルールに適合するかをチェックし、プロバイダーへのリクエストと推定コストをプレビューして、変更レビュー用の証拠を残せます。

LLM 機能を保守するエンジニア向けに構築されています。CLI、GitHub Action、または MCP サーバーとしてローカルで実行できます。Python 3.10 以降に対応し、サードパーティの実行時依存関係はありません。

試してみる · 確認済みのモデル · 独自のコントラクトを使う · CI とエージェント

無効な応答が検出され、修正される様子をご覧ください（23 秒）。

billing は合格 → 応答を sales に変更 → チェック失敗 → billing に戻す → チェック合格。許可されるラベルは変わりません。

合成応答フィクスチャを使った実際の CLI 出力です。バリデーターをチェックするものであり、プロバイダーへのリクエストやアプリケーションのパーサーの実行は行いません。 MP4 を見る。

60 秒で試す

新しいディレクトリでツールをインストールし、ローカルモックを実行します。API キーもプロバイダーへのリクエストも不要です。

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install llm-preflight
llm-preflight init
llm-preflight benchmark.json --no-save --no-env-file

上記の有効化コマンドは POSIX シェル用です。PowerShell では .\.venv\Scripts\Activate.ps1 を使用します。

init は既存の設定ファイルを上書きしません。品質ゲートで PASS と表示された local-mock を確認してください。モックは ok と応答し、厳密な出力テストに合格しています。ローカルモックではライブプロバイダーの証拠が得られないため、総合判定は inconclusive（終了コード 3）です。デモは動作しましたが、モデルを承認するものではありません。 --no-save は JSON／Markdown 形式の結果アーティファクトの保存をスキップし、--no-env-file は認証情報ファイルの保存をスキップします。

対話型のデフォルトテンプレートを見る（30 秒）

モックとデフォルトの Reply with ok テストを選択し、プランを確認してローカル実行を確定します。このセッションでは、CLI JSON を通じて同じ判定も読み取ります。

ローカルテスト：合格。ライブプロバイダー：未テスト。API キーもプロバイダー呼び出しもありません。 MP4 を見る または、テキストによる手順 と対話型 CLI JSON の例から始めてください。

ベンチマークを実行する場合は、操作に移る前に判定を確認してください。

• pass、終了コード 0： 設定されたチェックに、必要な証拠を伴って合格しました。
• fail、終了コード 1： 設定されたチェックに失敗しました。原因を確認してください。
• inconclusive、終了コード 3： 証拠が不十分です。処理を妨げている警告を確認してください。

実行に合格した場合も、証拠となるのは設定されたワークロードに対してのみであり、本番環境での承認を意味するものではありません。

サポートルーティングの契約で観測された結果

失敗したチェックや拒否されたリクエストを含む、実際のプロバイダーで観測された結果の一部です。各モデルに16件のリクエストを送信しました。日付、ルート、リクエスト設定は異なります。これらの結果は1つのワークロードを示すものであり、一般的なランキングではありません。

レイテンシには契約違反を含む成功したAPI応答を含め、APIエラーは除外しています。—は利用不可を意味します。使用量が取得できない場合、合計コストは不明のままです。OpenRouterでの観測結果から、ネイティブプロバイダーの動作を判断することはできません。 結果をテキスト、リクエスト設定、失敗分析で読む。

最初のライブ実行

まず、アプリケーションですでに適用しているルールを1つ選びます。 プロジェクト統合ガイド では、受け入れ／拒否のフィクスチャと、費用の発生しないプルリクエストチェックを含む、完全なルーティング契約を紹介しています。デプロイ済みのプロンプトと応答パーサーに合わせてください。ローカルのフィクスチャチェックでは、アプリケーションコードは自動的に実行されません。

代わりに、最小限のプロバイダースターターを試すには：

llm-preflight init live.json --template provider \
  --provider openai --model gpt-6.1-sol --api-key-env OPENAI_API_KEY

スターターはokだけを厳密に要求します。バリデーターをローカルで確認するには、既存のフィールドを残したまま、このトップレベルフィールドをlive.jsonに追加します：

{
  "validation_fixtures": [
    {"name": "accepted-label", "response": "ok", "expect": "pass"},
    {"name": "rejected-label", "response": "not ok", "expect": "fail"}
  ]
}

シェルまたはlive.jsonと同じ場所にある、コミット対象外の.env.productionにOPENAI_API_KEYを設定します。設定ファイルに保存されるのは変数名だけで、キーは保存されません。生成リクエストを送信せずにチェックをプレビューします：

llm-preflight live.json --contract-check
llm-preflight live.json --doctor
llm-preflight live.json --pricing-check
llm-preflight live.json --dry-run

スターターには、リクエスト数の上限が3件、推定コストの上限が$0.05に設定されています。警告を解消し、ルート、再試行を考慮したリクエスト上限、料金、保持設定を確認してください。スターターはデフォルトで失敗した応答を保存します。共有する前にアーティファクトを確認してください。

**有料リクエスト：**計画を確認して承認した場合に限り、次を実行します：

llm-preflight live.json

CLIを直接実行しても、別途承認を求めるプロンプトは表示されません。--no-saveを指定しない限り、結果はresults/の下にJSONとMarkdownで保存されます。CLIは設定ファイルと同じ場所にある.env.productionを読み込みますが、既存のシェル値は上書きしません。別のファイルを選択するには--env-file PATHを、読み込みをスキップするには--no-env-fileを指定します。

進め方を選ぶ

• 実際のプロジェクトをセットアップする。 プロジェクト統合ガイドを使って、アプリケーションのルールを1つ適用します。
• 変更を検証する。 モデル変更ガイドを使って、承認済みの設定と候補の設定を比較します。
• 確立済みの契約を自動化する。 CIとJSON出力またはGitHub Actionを使います。
• コーディングエージェントを設定する。 信頼できるリポジトリでllm-preflight-mcp --workspace "$PWD"から始め、MCP サーバーガイドに従います。

契約の変更が失敗する様子を確認する

レビュー用アーティファクトには、判定、契約の有効性、レイテンシ、使用量、 推定コスト、ブロック要因となる警告が保持されます。保存済みの schema-version-1 JSON を、 プロバイダーへの追加リクエストなしで単独のレポートとしてレンダリングします。実行時に出力された 保存済み JSON のパスを results/run.json に置き換えてください：

llm-preflight report results/run.json --output report.html

レンダラーはプロンプト、レスポンス、ローカルパス、実行を特定できるメタデータを省略します。 再現可能な例を試すには、ソースチェックアウトから次のコマンドを実行してください：

python3 -m llm_preflight report examples/reports/schema-baseline.json --format markdown
python3 -m llm_preflight report examples/reports/schema-break.json --format markdown

1 つ目の合成結果は合格し、2 つ目は contract_failure、契約の有効性 67％、 契約のみを原因とする失敗 1 件を報告します。 レポートギャラリー には、no_record によってゲートがブロックされる例（終了コード 1）もあります。これらのフィクスチャは プロバイダーへの呼び出しを行わず、証明済みの CI エビデンスとして使用できません。

CLI、CI、MCP

CLI、GitHub Action、ローカル MCP サーバーとして動作します。 Action はデフォルトで生成リクエストを行いません。ライブ MCP 実行には、有料実行の明示的な確認が必要です。 クライアントのツール承認は有効にしておいてください。確認フィールドは、支出を人が承認した証拠ではありません。

事前チェックなしではマージ不可。 必須チェックを設定すると、オフラインゲートは、現在の契約、ルート、 プロンプト、実行選択と一致する最新の合格済み CI レコードを要求します。生成側とゲートのワークフローを保護してください。 署名済みレコードも、ゲートの前に gh attestation verify で検証する必要があります。 設定方法については、事前チェックの証明 を参照してください。ローカルフィクスチャでの合格やパッケージのインストールだけでは、 マージポリシーは適用されません。

本番環境での動作を認証するものではありません。チェックが実施されたことを証明します。

コーディングエージェント向け MCP

インストール済みの stdio コマンドを MCP クライアントに設定してください：

{
  "mcpServers": {
    "llm-preflight": {
      "command": "llm-preflight-mcp",
      "args": ["--workspace", "/absolute/path/to/repository"]
    }
  }
}

7 つのツールで、モデル ID のリテラルを監査し、設定を検証し、計画をプレビューし、事前チェックを実行し、 保存済みベースラインを比較し、レコードを検証し、CI エビデンスをゲートできます。 既存の契約がある場合は、validate_config と dry_run_plan から始めてください。 エージェントは構造化された判定を読み取り、不足しているエビデンスを報告する必要があります。 リクエストと結果の例、およびワークスペースの境界については、 MCP ガイド を参照してください。

agent-smoke スイートを --smoke とともに実行すると、設定済みの再試行の前にモデルごとに 6 件のリクエストを行います。 CLI コマンドについては、 コーディングエージェントのワークフロー を使用してください。エージェントは合格を得るためにバリデーターを弱めたり、 ゲートの結果から有料作業の許可を推測したりしてはいけません。

よくある作業

• 既存のモデル ID を監査する： llm-preflight --audit-source . は、同梱のスナップショットで廃止済みまたは廃止予定とマークされた リテラル ID を報告します。設定もキーも必要ありません。廃止判定を終了コードに反映するには --ci を追加してください。 指定しない場合、検出結果があっても通常は終了コード 0 になります。Git では、スキャン対象は追跡対象かつ無視されていないファイルです。 モデルの廃止を参照してください。

• 料金を確認する： --doctor は料金に関する参考情報を提供し、 --pricing-check はフェイルクローズ方式のカバレッジゲートです。実行をプレビューするには llm-preflight benchmark.json --dry-run を実行してください。

• Git の変更をレビューする： llm-preflight benchmark.json --change-plan は静的なシグナルに基づいて チェックを提案しますが、実行を許可するものではありません。

• 候補を見つける： メタデータを更新し、計画を準備してプレビューします：

  llm-preflight catalog refresh benchmarks/watch.json
  llm-preflight catalog prepare benchmarks/watch.json \
    --against benchmarks/approved.json --output benchmarks/candidates.json
  llm-preflight benchmarks/candidates.json --migration-check --dry-run
  

  まず、モデルカタログガイド に従って watch ファイルと approved ファイルを作成してください。カタログのプローブは別途実施する手順であり、 料金が発生する可能性があります。

モデルを安全に変更する

承認済みモデルと候補モデルをレビュー済みの設定に記述し、組み込みの互換性パックをプレビューします。

llm-preflight benchmark.json --migration-check --dry-run

この計画を承認すると、llm-preflight benchmark.json --migration-check は、設定された再試行の前に、モデルごとに組み込みのケースを3つ送信します。首都を答える質問、要約、書き換えです。これらは基本的な互換性を確認します。変更が機能のルールを満たすかどうかを確かめるには、独自のアプリケーション契約テストを使用してください。

安全性の境界

結果は、ある時点における設定済みのアカウント、ルート、プロンプト、バリデーターに適用されます。モデルの応答には引き続き確率的なばらつきがあります。決定論的なバリデーションで確認できるのは、宣言したルールです。意味的な正確性や本番環境での安全性を保証するものではありません。ライブリクエストの前に制限をプレビューし、有料実行の権限はインテグレーションに責任を持つ人が保持してください。

比較

インテグレーションを変更する前に、範囲を限定した契約チェックとレビュー可能なエビデンスが必要な場合は、このプロジェクトを使用してください。評価フレームワークもアサーションやCIをサポートしています。すでにニーズを満たしているものがあれば、引き続き使用してください。より広範な評価スイートは意味的なスコアリングや統計的な比較に適しており、可観測性ツールは本番環境のトレースやインシデント調査に適しています。使用する場面をご覧ください。

サポートを受ける、またはプロジェクトで試す

セットアップのサポートや契約の例をリクエストしてください。 バージョン、確認したい内容、機密情報を除去した出力を含めてください。キー、非公開のプロンプト、プロバイダーの応答は絶対に共有しないでください。脆弱性についてはセキュリティポリシーをご利用ください。

ドキュメント

ドキュメントのホームページでは、タスク別に案内しています。正確な動作については、CLI リファレンス、設定、結果の JSONをご覧ください。ネイティブルートと日付入りの料金情報は、現在のスナップショットに記載されています。AI 実装テストガイドでは、想定されるワークフローと対象範囲を説明しています。

すべてのバージョンのリリースノートは変更履歴にあります。

貢献とライセンス

開発およびドキュメントの基準については、貢献ガイドをご覧ください。MIT ライセンスの下で公開されています。