私はポケモンのファンサイト「ポケフォリオ」というサイトを運営しています。
機能の一つとして、AIを活用した分析機能があります。
この記事では、そのハーネス設計についてまとめます。
前提:ハーネスエンジニアリング
言葉の定義には揺れがあると思いますが、本記事では以下のように扱います。
AIや外部処理を安全かつ安定して動作させるために、
入力・出力・再試行・例外処理・検証などを統合的に管理する設計手法。
システム全体の信頼性と再現性を担保する仕組み。
前提:ポケフォリオのAI機能
ポケモンのランクバトルにおいて、上位プレイヤーが公開しているパーティ構築記事を分析し、
トレーナーの実績として整理・管理する機能を提供しています。
平均4000文字程度のブログ記事から、約120項目の構造化データへ変換するAIエージェントを実装しています。
技術構成は LangChain + Gemini。
すでに140記事以上を分析済みで、ユーザーはログインして自分の実績を管理できます(ユーザー数は約200人)。
ポケフォリオAIにおけるハーネスエンジニアリング
このAI機能を設計する上で、特に重視したのは以下の2点です。
- ハルシネーション(誤生成)
- 実行制御の不安定さ
これらに対処するため、ハーネス設計を最優先で設計しました。
2024年8月頃に設計したものなので、現在のベストプラクティスとは異なる部分もあると思います。
改善点などあれば、Xで指摘いただけると嬉しいです。
以下では、設計時に意識した7つのポイントを
「入力・処理・出力」の3つに分けて説明します。
入力(URLの取得・実行制御)
WebアプリとAI処理の非同期実行
防げる問題
- 処理の失敗に対して復旧、再トライができない
- 大量に入力され、LLMコストがかかってしまう
- Webアプリの脆弱性を利用されLLMに直接問い合わせてしまう
ユーザーによる記事登録とAI分析は、完全に独立したプロセスとして設計しています。
記事は「処理待ち」としてキューに溜め、任意のタイミングでにAIに処理するように指示します。
登録をトリガーに即時実行するとUXは向上しますが、障害時、大量リクエストによる攻撃時に対処が難しくなるため採用していません。
「登録が失敗しても、登録データは保持しているので、原因の切り分けがしやすい」
「そのままLLM分析はしないので、悪意のある大量リクエストが来てもLLMコストに影響がない」
「WebアプリにLLMへリクエストする機能がないため、脆弱性を突かれてもLLMコストに影響がない」
※最低限のWAF等入れています。
Webアプリ側での分析ステータス管理およびデータ提供の制限
防げる問題
- 再処理のしやすさ
- 失敗対象の無限再実行
各記事の分析状態はWebアプリ側で管理しています。
具体的には、WebアプリにAIへは「分析待ち」のデータしか取れないようにしています。
AI側では、成功すれば「分析完了」、失敗すれば「エラー」をか必ず更新するようにします。
「再度分析したい場合はステータスを手動で"分析待ち"に変えるだけ」
「失敗しているブログに何度もリトライして、LLMコストが増えることを防げる」
AI起動は手動トリガー
防げる問題
- バグの全件拡散
- 本番データ汚染
- コスト暴走
- ブラックボックス化
AI処理の起動は手動で行っています。
(自分のラップトップから実際には、Langchain製のPythonスクリプトを実行しています。)
完全自動化すると、異常時の制御が困難になるためです。
また、実行前に件数を確認することで、悪意ある大量登録にも対応できます。
処理(AIによるデータ構造化)
ユーザー情報はAIに処理させない
防げる問題
- ユーザー誤識別
ユーザー情報はLLMを通さず、確定ロジックで処理しています。
「ユーザーAのデータをユーザーBのものだと登録した」ということは絶対に避けるべきと思っています。
信頼性が要求される領域は、AIに任せない設計です。
処理順序の固定化
防げる問題
- 前提条件が揃っていない場合のAIの誤動作
処理フローは固定し、AIに順序判断をさせていません。
依存関係がある処理は、確定ロジックで順序制御します。
「ポケモンをパーティ作成より先に分析した後、パーティのレコードがないため、無関係なパーティを更新する」ことを防ぎます。
例:
- パーティ登録
- → ポケモン6体を紐付け
無関係なサイトの場合は処理を中断
防げる問題
- 不正入力の解析
- 無意味なデータ生成
- リソース浪費
LLMで記事の種類を判定し、対象外の場合は処理を停止します。
また、有害サイトへの誘導リスクもここで防いでいます。
出力(APIによるデータ登録)
失敗は必ず「失敗」として記録
防げる問題
- 無限リトライ
失敗は明示的に状態として記録し、次回以降の処理対象から除外します。
これにより無限ループを防ぎます。
バリテーションの厳格化と失敗時は最大3回リトライする機構
防げる問題
- 想定外のデータの登録を防ぐ
- 一時的エラーの取りこぼし
最終的なデータ検証はWebアプリ側で行います。
AI側の検証には依存せず、「受け側で防ぐ」設計にしています。
バリテーションを厳格にすることで、想定外のデータの登録を防ぎます。
ただし、エラーで止まってしまうので、リトライする機構を入れることで想定通りのデータを投入できるようにします。
また、通信エラーや一時的な生成失敗にも対応できます。
すべての処理にリトライ(最大3回)を実装しています。
まとめ
本記事では、ポケフォリオにおけるAI機能のハーネス設計について紹介しました。
実際には、精度向上(コンテキストエンジニアリング)を追求する中で、
結果的にハーネス設計として機能している部分も多くあります。
ハーネスエンジニアリングとコンテキストエンジニアリングは、
密接に関係している設計領域なのかもしれません。







