Llm integration

LLM機能のプロダクト組み込み

目的

LLMをプロダクトに組み込む際の判断と実装を体系化する。「とりあえずAPIを叩く」段階から、eval・信頼性・コスト・セキュリティまでを設計の一部として扱えるチームを支援する。

使うタイミング

• 新機能にLLMを使うか判断したいとき
• プロンプトを本番に投入する前のレビュー・品質担保
• 既存LLM機能のコスト・品質・安全性を改善したいとき
• LLM機能の設計ドキュメントをレビュー・作成するとき

進め方

1. ユースケース適合性を判断する — LLMが向く処理かどうかを先に問う。普通のコードで書けるならLLMを使わない
2. LLM機能設計シートを書く — 下記テンプレートを埋める。曖昧なまま実装に入らない
3. プロンプトを設計・バージョン管理する — 役割・入力・制約・出力形式を明示し、Gitで管理してテスト対象にする([[git-workflow]])
4. evalデータセットを作る — 最低20件の代表的な入力と期待出力を用意する。これが品質の基準線になる
5. 信頼性設計を実装する — バリデーション・リトライ・タイムアウト・フォールバックをコードに組み込む
6. コストを試算・モニタリングする — 本番投入前にリクエスト数×トークン×単価を見積もり、監視とアラートを設定する([[monitoring-operations]])
7. セキュリティレビューを行う — プロンプトインジェクション・PII送信・出力の無検証実行を確認する([[security]])
8. UXに不確実性を反映する — 下書き提示・編集可能・フィードバック収集を設計に含める

設計の要点

ユースケース適合性

LLMが向く処理と向かない処理を最初に区別する。

向く処理	向かない処理
非構造データの構造化・抽出	厳密な計算・集計
要約・分類・ラベリング	決定的であるべき処理(金額計算など)
自然言語UI・対話	低レイテンシ必須(100ms以下)
文書生成・変換	ルールが完全に明文化できる処理

判断基準: 「正規表現やテンプレートで実装できるか?」「失敗時のコストは?」「人間が見てもバラつく判断か?」の3問に答えてからLLMを選択する。

プロンプト設計

• 4要素を明示する: 役割(あなたは〜)・入力(ユーザーデータの形式)・制約(禁止事項・長さ・言語)・出力形式(JSONスキーマを明示)
• 構造化出力を使う: JSON Schemaを指定してパース失敗を減らす。フリーテキスト出力は検証が困難
• few-shot例を入れる: 2〜5件の入出力例で品質が大きく変わる。境界ケースを例に含める
• プロンプトはコードとして管理する: ファイルに外出しし、変更をGitでトラッキングしてevalを通す。インラインの文字列リテラルにしない

# プロンプトファイルの構成例
prompts/
  classify_feedback/
    system.txt       # システムプロンプト
    examples.json    # few-shot例
    schema.json      # 出力JSONスキーマ
    eval_dataset.jsonl  # evalデータセット

評価(eval)

「触ってみて良さそう」は評価ではない。変更のたびに数値で回帰を検知する。

• evalデータセット: 代表的な入力20件以上+正解ラベル。境界ケース・失敗しやすいケースを意図的に含める
• 合格基準を先に決める: 「精度90%以上」「拒否率5%以下」など定量的に設定する
• LLM-as-judge: 完全一致で採点できないタスクは別のLLMに採点させる。採点プロンプト自体もバージョン管理する
• 定期的な人間の抜き取り検査: LLM-as-judgeの採点精度自体を週次・月次で確認する
• CI/CDに組み込む: プロンプト変更のPRでevalが自動実行され、合格基準を下回ればマージ不可にする

信頼性

• スキーマバリデーション: LLMの出力をJSONスキーマで検証。失敗したら即リトライ(最大2〜3回)
• タイムアウト: LLMコールには必ずタイムアウトを設定する。デフォルト30秒を目安に
• フォールバック: LLM失敗時の代替動作を設計する(エラー表示・ルールベース処理・人間への引き継ぎ)
• レートリミット対応: 指数バックオフ付きリトライ。同期処理ではなくキュー経由にすることも検討
• ストリーミング: レイテンシが体感上問題になるなら最初のトークンから表示する。生成中のUIを設計する

コスト

• タスク難易度に応じて最小モデルを選ぶ: [[orchestration]] のモデル委譲と同じ思想。全タスクに最上位モデルを使わない。分類・抽出など定型タスクは軽量モデルで十分なことが多い
• プロンプトキャッシュを使う: システムプロンプトや固定のfew-shot例をキャッシュし、繰り返し課金を減らす
• トークン使用量の監視: リクエストごとの入出力トークン数をログに記録し、異常なスパイクにアラートを出す([[monitoring-operations]])
• ユーザーあたりの利用上限: 1日・1ヶ月のトークン上限をユーザーごとに設け、過剰利用を防ぐ
• 本番投入前に試算する: 月次リクエスト数 × 平均トークン数 × 単価 を必ず計算してから設計を確定する

セキュリティ

• プロンプトインジェクション対策:
  • ユーザー入力をシステムプロンプトに直接結合しない
  • システム指示とユーザーデータを構造的に分離する(XMLタグやJSONラッパーで囲む)
  • LLMに与えるツール・権限を最小化する(必要なツールだけを公開)
• PII送信ポリシー: 氏名・メールアドレス・健康情報など個人情報を外部APIに送ってよいか、法務・プライバシーポリシーと照合する。必要なら匿名化・マスキングを挟む
• 出力の無検証実行禁止: LLMが生成したSQL・シェルコマンド・コードを直接実行しない。ホワイトリスト検証またはサンドボックスを必ず挟む
• ログのマスキング: LLMへのリクエスト・レスポンスをログに記録する際、PII・機密情報をマスクする

成果物テンプレート

# LLM機能設計シート

## 基本情報
feature_name: ""
author: ""
date: ""

## ユースケースと適合性判断
use_case: ""  # 何をLLMにやらせるか
why_llm: ""   # なぜ通常のコードではなくLLMか
failure_cost: ""  # 失敗時の影響範囲

## モデル選定と根拠
model: ""           # 選定モデル
reason: ""          # 選定理由(コスト・品質・レイテンシのトレードオフ)
fallback_model: ""  # フォールバック時のモデル(コスト削減版など)

## プロンプト管理
prompt_path: ""          # リポジトリ内のパス
version_control: git     # Git管理前提
output_schema_path: ""   # JSONスキーマのパス

## evalデータセットと合格基準
dataset_path: ""         # .jsonlファイルのパス
dataset_size: 0          # 件数(最低20件)
acceptance_criteria: ""  # 例: 精度 >= 90%、拒否率 <= 5%
judge_method: ""         # exact_match / llm-as-judge / human

## 信頼性設計
timeout_sec: 30
retry_max: 3
fallback_behavior: ""    # LLM失敗時の代替動作

## コスト試算
monthly_requests: 0
avg_input_tokens: 0
avg_output_tokens: 0
unit_price_per_1k_tokens: 0.0
monthly_cost_estimate: 0.0  # 上記から計算
token_limit_per_user: ""

## セキュリティ
user_input_isolation: ""   # ユーザー入力の分離方法
pii_policy: ""             # PII送信の可否と根拠
output_validation: ""      # 出力検証の方法(DBに保存する前・実行する前)

チェックリスト

設計フェーズ

• 普通のコードで実現できないか検討した
• LLM機能設計シートを記入した
• evalデータセット(20件以上)を用意した
• 合格基準を数値で定義した
• フォールバック動作を設計した
• コスト試算を行った

実装フェーズ

• プロンプトをファイルに外出ししGit管理している
• 出力をJSONスキーマでバリデーションしている
• タイムアウトとリトライを実装した
• ユーザー入力をシステムプロンプトと分離している
• PII送信ポリシーを確認した
• LLM出力を無検証で実行・保存していない

リリース前

• CIでevalが自動実行される
• トークン使用量の監視・アラートを設定した
• ユーザーあたりの利用上限を実装した
• UXに不確実性が反映されている(下書き提示など)
• フィードバック収集の仕組みを実装した([[analytics-kpi]])

アンチパターン

アンチパターン	なぜ問題か	代替
evalなしでプロンプトを「雰囲気で」改善	ある入力で改善しても別の入力で劣化に気づかない	evalデータセットで定量的に回帰検知
全タスクに最上位モデルを使う	コストが数倍〜数十倍に膨らむ	タスク難易度に応じたモデル選択
ユーザー入力をシステムプロンプトに直結合	プロンプトインジェクションの温床	構造的分離+入力サニタイズ
LLM出力を無検証でDB保存・実行	不正データ挿入・任意コード実行のリスク	バリデーション・サンドボックスを必ず挟む
レイテンシとコストを見積もらずに本番投入	ユーザー体験の悪化・予算オーバー	設計シートで事前試算
エラー時に「AI機能が使えません」のみ表示	ユーザーが何もできなくなる	フォールバック動作で基本機能は継続

モデル委譲ガイド

共通原則は [[orchestration]] を参照。

役割	担当タスク
司令塔(メインモデル)	ユースケース適合性の判断、モデル選定の意思決定、設計シートのレビュー指示
Opus相当	プロンプト設計のレビュー、evalデータセット品質の判定、LLM-as-judgeプロンプトの設計レビュー
Sonnet相当	プロンプトの実装・改善、evalデータセットの作成、パイプライン実装、コードレビュー
Haiku相当	出力サンプルの大量収集、一次分類・タグ付け、evalデータの前処理

関連スキル

• [[orchestration]] — マルチエージェントとモデル委譲の共通原則
• [[security]] — プロンプトインジェクション・PII・出力検証の詳細
• [[monitoring-operations]] — トークン使用量監視・アラート設計
• [[analytics-kpi]] — フィードバック収集・改善指標の設計
• [[git-workflow]] — プロンプトのバージョン管理
• [[api-design]] — LLMをAPIとして公開する場合の設計
• [[testing]] — evalをCIに組み込む
• [[performance-optimization]] — レイテンシ改善・ストリーミング最適化
• [[architecture-design]] — LLM機能をシステム全体に組み込むアーキテクチャ設計