GuidesOneMux

JSON Schema検証で信頼性の高いn8nデータ抽出ワークフローを構築する

構造化されたモデル出力を検証し、一時的なエラーには再試行を行い、不確実または無効なレコードを人による確認へ回すn8n抽出パイプラインの設計方法を解説します。

AI

要約 · TL;DR

堅牢な抽出ワークフローでは、モデルの出力を信頼できない入力として扱います。必要な項目に絞ったJSONの契約を定め、保存前に解析結果を検証し、一時的なエラーだけを再試行します。解決できないケースや影響の大きいケースは担当者に確認を依頼します。

要点

  • 予測可能なJSONオブジェクトを1つ出力するよう指示し、モデルとは独立して検証する。
  • 一時的なAPI障害と、不正な形式や不足のある抽出結果を区別する。
  • 再試行回数に上限を設け、再実行時に重複が発生しないよう元のレコードを保持する。
  • 重大な影響を伴う処理の前には、特に人による確認が重要。n8nでは選択したAI Agentツールの承認を設定できる。
  • 元データ、抽出結果、検証エラー、再試行回数、確認担当者の判断を監査記録として残す。
目次 (7)

設計上の要点:処理を実行する前に検証する

モデルが一見正しいJSONを返しても、データが完全で、型が正しく、安全に使えるとは限りません。n8nでは抽出を、明確な契約に基づくパイプラインとして扱います。元レコードを取得し、構造化された結果を要求し、解析・検証したうえで、後続処理へ進むか、再試行するか、人による確認に回すかを判断します。モデルの出力をデータベースの更新や外部メッセージに直接つないではいけません。

この記事では、請求書に似たレコードを説明用の例として使います。スキーマとノード設定は例示であり、動作検証済みのものでも、特定バージョン向けのn8nエクスポートでもありません。お使いのn8nバージョンで利用できるノードオプションと、選択したモデルのエンドポイントがサポートする出力形式を確認してください。

1. まず出力の契約を定義する

次の処理で実際に必要となるフィールドだけをスキーマに含めます。必須フィールドを明示し、安定した型を使い、情報が欠けている場合の表現方法を決めます。たとえば請求日が不明な場合は、日付を捏造したり自由記述の説明を入れたりせず、nullにします。

{
  "type": "object",
  "additionalProperties": false,
  "required": ["invoice_number", "invoice_date", "currency", "total"],
  "properties": {
    "invoice_number": { "type": "string", "minLength": 1 },
    "invoice_date": { "type": ["string", "null"] },
    "currency": { "type": "string", "minLength": 3, "maxLength": 3 },
    "total": { "type": "number", "minimum": 0 }
  }
}

スキーマで定義できるのは構造上のルールです。抽出された合計金額が元の書類と一致するかどうかまでは確認できません。日付を解析できるか、通貨コードが許可リストに含まれているかなど、業務ルールに基づく検査は別途追加します。想定外の値を黙って型変換するのは避けてください。テキストの金額を数値に変換するのが有用な場合でも、変換を記録し、曖昧な形式は拒否します。

2. n8nワークフローを段階ごとに組み立てる

実用的なキャンバス構成は次のとおりです。

  1. トリガーと元データの取得: ファイル、レコード、またはWebhookのペイロードを受け取ります。一意で安定したソースIDを割り当て、元のテキスト、またはその参照情報を保持します。
  2. 抽出リクエスト: テキストと簡潔な指示を選択したモデルに送信します。定義済みのオブジェクトだけを返すよう求め、不確かな値や存在しない値は契約で定めた方法で表すよう伝えます。
  3. 解析と検証: 応答をJSONとして解析し、必須キー、型、許可値、業務ルールを確認します。環境で利用できる場合はスキーマ検証ノードを使うか、意図的に導入してテストしたバリデーターをCodeノードで使います。すべてのn8n環境に特定の検証パッケージがあるとは限らないため、利用できると決めつけないでください。
  4. 結果に応じた振り分け: 有効なレコードは保存先へ進めます。再試行可能な失敗は回数に上限のある再試行経路へ送り、検証に繰り返し失敗するケースや曖昧なケースは確認に回します。
  5. 結果の記録: ソースID、ステータス、抽出したオブジェクト、検証エラー、試行回数、最終判断を保存します。

検証ステップはモデルへのリクエストとは分けてください。プロンプトの指示で応答を改善することはできますが、検証の代わりにはなりません。

3. 適切なエラーだけを再試行する

再試行は、一時的な通信エラー、レート制限、サービス側の障害には有効です。一方、請求書番号の欠落や、スキーマ違反を繰り返す応答は再試行しても解決しません。再試行回数は少なく設定し、ノードが対応していれば試行間に待ち時間を設けます。n8nのバージョンによって設定や動作が異なる場合があるため、利用中のバージョンで実際の再試行制御を確認してください。

結果ごとに経路を分けます。

  • 一時的なリクエストエラー: 上限の範囲内で再試行し、それでも失敗したら、後で調査できるようレコードに失敗ステータスを付けます。
  • 無効なJSON: 役立つ場合は、同じフィールドと契約を指定して、制御された修正を1回だけ試します。新しい応答を再検証し、修正が成功したと決めつけないでください。
  • スキーマまたは業務ルールの違反: 無期限にループさせず、確認に回します。
  • 有効な結果: ソースIDを使って、ワークフロー再実行時の重複書き込みを防ぎながら保存先へ進めます。

再試行によって、取り消せない後続処理を繰り返さないようにしてください。モデルによる抽出とデータ書き込みを別の段階に分け、可能な範囲で書き込みを冪等にします。

4. リスク低減につながる場面で人による確認を加える

値が曖昧な場合、検証ルールに違反した場合、または次の処理が大きな影響を伴う場合は、人による確認が有効です。担当者には元データ、提案されたフィールド、具体的な検証エラーを提示し、承認、編集、却下を明確に選べるようにします。担当者の判断と修正内容も保持してください。

n8nのドキュメントでは、AI Agentに接続された一部のツールに対する人の承認が説明されています。ワークフローは一時停止し、確認担当者が提案されたツール呼び出しを承認または拒否できます。ツールが実行されるのは承認された場合だけです。承認はSlack、Telegram、n8n Chatなど、サポートされるチャネルを通じて行えます。また、提案されたツールとパラメーターを確認担当者に表示するために、$tool.nameと$tool.parametersを使う方法も説明されています。これはAI Agentのツール呼び出しに対する承認であり、それだけであらゆる抽出レコードを確認できる汎用インターフェースになるわけではありません。レコード単位の確認には、利用環境に合った人手によるタスクと再開経路を構築してください。

出典:n8n documentation: Human-in-the-loop for tools

5. 根拠を確認してトラブルシューティングする

有効なレコードが繰り返し拒否される場合は、スキーマを変更する前に、生の応答とバリデーターのエラーを確認します。応答にMarkdownのコードフェンスや余分な説明文が含まれていないか、nullableなフィールドが欠けていないか、数値が文字列として返されていないかを調べてください。再試行によって重複レコードが作成される場合は、検証後に書き込みを行うよう変更し、安定したソース識別子を使います。確認担当者がすばやく判断できない場合は、JSONオブジェクトだけでなく、問題のある各フィールドを裏付ける元データの該当箇所も提示します。

合格率を上げるためだけにスキーマを緩めないでください。契約の変更は、実際の下流要件を反映する必要があります。必須フィールドの欠落、不正な形式の書類、矛盾する値などを含む代表的な入力で、変更の影響をテストしてください。

再利用できるリリース前チェックリスト

  • 必須フィールド、nullの扱い、型、追加フィールドの扱いを定義している。
  • 下流への書き込み前に、解析、スキーマ検証、業務ルールの検証を行っている。
  • 再試行回数に上限を設け、回復が見込める失敗だけを対象にしている。
  • 再処理によって、重大な処理が誤って重複しない。
  • 確認担当者が元データ、提案値、確認が必要な理由を確認できる。
  • 拒否された出力を隠すことなく調査できるよう、十分な情報をログに残している。

信頼性を高めるパターンはシンプルです。抽出し、検証し、振り分けてから処理を実行します。スキーマは構造上の問題を検出し、上限付きの再試行は一時的な障害に対処します。曖昧さやリスクがある場合は、自動化で黙って解決せず、人による確認に回します。

よくある質問

モデルにJSONを要求すれば、スキーマに適合した出力が保証されますか?

いいえ。応答は信頼できない入力として扱い、利用する前にワークフロー内で解析し、必須フィールド、型、業務ルールを検証してください。

抽出したJSONが検証に失敗したら、n8nで再試行すべきですか?

上限を設けずに自動再試行するべきではありません。修正を1回試すのは有効な場合がありますが、スキーマ違反が繰り返されるなら、無期限に再試行せず、通常は確認に回すか調査対象として記録してください。

n8nの人による承認機能で、抽出レコードを確認できますか?

ここで紹介したn8nの機能は、AI Agentが呼び出すツールを承認または拒否するものです。それ自体は汎用的なレコード確認インターフェースではありません。抽出ケースに適した人手によるタスクと再開経路を実装してください。

確認担当者には何を提示すべきですか?

元データまたは関連箇所、提案された構造化フィールド、検証エラーや不確実性を示し、承認、編集、却下を明確に選べるようにしてください。

関連記事