目的: AI機能をプロダクション品質で統合するための思想メモ。
再利用可能な設計原則を整理してみる。
1. AIは「賢いが信用できない外部システム」
まず重要な前提です。
AIは普通のAPIやライブラリとは違います！
| 特性 | 通常のAPI | AI（LLM/OCR） |
|---|---|---|
| 同じ入力で同じ出力 | ほぼ保証 | ✕保証されない |
| 型が保証される | ◎ | ✕壊れる |
| JSON schemaが守られる | ◎ | ✕守られないことがある |
| 存在しない値 | なし | あり |
➡ AIは「信頼できない外部センサー」として扱った方がいい！
2. AI境界層アーキテクチャ
2.1 全体構造
[ External AI ]
↓
↓ そのままでは使わない
↓
[ AI Sanitizer / Normalizer Layer ] ← 重要
↓
↓ アプリで使える形に変換する
↓
[ Domain / Business Logic ]
↓
↓
↓
[ DB / API / UI ]
➡ AIの出力をそのままアプリに入れないようにする。変換層を挟んだ方が良い！
3. AIレスポンスは基本的に信頼しない
3.1 よくある事故
- 数字なのに
"1,000円"と文字列 - フィールドが欠ける
- null / 空文字 / 全角混入
- JSON構造が崩れる
3.2 対策パターン（ensure_* パターン）
def ensure_int(value):
try:
return int(value)
except:
return 0
def ensure_str(value):
return str(value) if value is not None else ""
➡ AI出力は必ずアプリ側で型保証する！
4. Domain Model に直接流し込まない
4.1 悪い例（アンチパターン）
# ❌ やらない方がいい
orm.insert(ai_response)
4.2 正しい例のイメージ
raw = ai_response
canonical = sanitize(raw) # ensure_* を通す
domain = map_to_domain(canonical)
repository.save(domain)
➡ AI出力 = 外部入力。DB直結は無し！
5. Flag（AIのON/OFF切替）
5.1 なぜ必要か？
- AI APIが落ちることがある
- 精度が急に悪化することがある
- コストが爆増することがある
5.2 実装イメージ
if AI_ENABLED:
ai_pipeline()
else:
legacy_pipeline()
➡ AIはいつでも切れるようにする！
6. リトライ / タイムアウト は必須
6.1 なぜ必須なのか？
- AI APIは不安定な時がある
- 画像などの元データが大きいとtimeoutすることがある
- Rate Limitあり
6.2 実装イメージ
for retry in range(RETRY_COUNT):
try:
call_ai()
break
except Exception:
sleep(backoff_time)
backoff_time *= 2
➡ AI呼び出しは失敗する前提で書くと良い！
7. 業務ロジックはAIに任せない(例：OCR処理)
7.1 AIに任せていいこと
- 分類（レシートか請求書か）
- OCR抽出
- 要約
7.2 AIに任せてはいけないこと
- 会計ロジック
- 権限判定
- 金額計算
➡ AIは「認識担当」、業務判断はアプリの担当！
8. 段階抽出設計(例：OCR処理)
8.1 推奨分割
| Step | 内容 | 例 |
|---|---|---|
| Step1 | 種別分類 | レシート or 通帳 ,,, |
| Step2 | メタ情報 | 会社名、期間 |
| Step3 | 明細 | 勘定科目、金額 |
➡ AIは粗い判断→詳細抽出の順で使うと安定する！
9. AI出力は必ず保存する
9.1 なぜ保存するのか？
- モデル更新時に再解析
- 不具合調査
- 法務・監査対応
9.2 保存するもの例
- 元画像 / テキスト
- AIの生レスポンス
- 正規化後データ
➡ AIは再現性がないためログ保存は必須！
10. 監視
10.1 取った方が良いメトリクス
- AI成功率
- fallback率
- レイテンシ
- 月額コスト
10.2 ログに残した方が良いもの
- prompt version
- model version
- raw output
- sanitized output
11. セキュリティ注意点
- 個人情報を外部AIに送らない
- マスキング処理
- プロンプトインジェクション対策
ユーザー入力がプロンプトの「命令」を上書きしてしまうリスクがある
→入力データのデリミタ利用やシステムプロンプトによる支持の固定化を行う - 出力のバリデーション
12. まとめ
意識する5原則
- AIは基本的には信用しない
- AI出力は必ず正規化する
- DBに直接入れない
- AIはON/OFFできるようにする
- ロジックの責務は分離する
- 生レスポンスを保存する
Appendix: AI 実装 チェックリスト例
- AI出力を直接Domainに流していないか
- ensure_* で型補正しているか
- ON/OFF Flagがあるか
- Fallback pathがあるか
- リトライ設計があるか
- 生データを保存しているか
- モデル・プロンプトのバージョン管理があるか