Let's Build: Transloadit による AI 請求書解析
PDF 請求書から、発行元、請求書番号、通貨、金額を含むローカルの JSON ファイルを作成します。この例では、文書を Transloadit と AI プロバイダーにアップロードし、返されたフィールドの型を検証して、元の請求書と照合できるように結果を保存します。
作成するもの
サンプルスクリプトは、空でない、最大 20 MiB の PDF または DOCX ファイルを受け付けます。PDF は直接 🤖 /ai/chat に渡し、DOCX ファイルは先に 🤖 /document/convert で PDF に変換します。この例では、それ以外の拡張子の入力を拒否します。
このチュートリアルでは、スクリプトをローカルで実行し、抽出結果をローカルに保存します。Assembly が完了し、JSON がスキーマに準拠していても、金額が正しく読み取られたとは限りません。会計や支払いに使う前に出力を確認してください。このスキーマでは信頼度スコアは返されません。
スキーマを先に定義(zod)
ダウンロードできるプログラムは Zod スキーマをエクスポートします。以下のダウンロード時のファイル配置に従えば、フィールド一覧を別途管理する代わりに、自身の TypeScript コードにスキーマをインポートできます。
import { zodToJsonSchema } from 'zod-to-json-schema'
import { invoiceSchema } from './invoice-parser/run.ts'
const invoiceJsonSchema = zodToJsonSchema(invoiceSchema)
フィールドには、発行元の詳細、請求日と支払期限、通貨、小計、税額、合計、明細、支払条件、発注書が含まれます。不明な値をモデルが省略できるよう、すべて任意項目です。実行プログラムは、不正な JSON、無効なフィールド型、認識できるフィールドのないオブジェクトを拒否します。ただし、もっともらしくても誤った合計金額が、これらの検証を通過する場合があります。
パイプラインの概要
PDF → /ai/chat → JSON download → local validation → result.json
DOCX → /document/convert (PDF) → /ai/chat → JSON download → local validation → result.json
このプログラムは anthropic/claude-sonnet-4-6 を明示的に選択します。これは /ai/chat がサポートする、PDF 対応のモデルです。結果 URL から応答をダウンロードし、検証済みのデータをローカルに保存するため、一時 URL の有効期限が切れた後もファイルを確認できます。
Assembly のスニペット
エクスポートされる処理設定には、完全な Assembly Instructions が含まれます。このスニペットは、リクエストを送信せずに処理設定を組み立てます。
import { example } from './invoice-parser/run.ts'
const instructions = {
steps: example.steps({ test_credentials: true }),
}
抽出用の Step は、format: 'json'、シリアライズされた JSON Schema、result: true を使用します。CLI がアップロード、完了確認、結果のダウンロード、ローカルでの検証を処理します。test_credentials: true を選択すると、Transloadit 提供の AI 認証情報が使われ、課金されます。処理が無料になるわけではありません。
サンプルアプリの実行
既存の Node プロジェクトの外にある空のディレクトリを使ってください。Node.js と cURL をインストールし、Corepack は別途インストールしてください。動作確認済みのランタイムは Node.js 26.12.1 です。例を応用する際は、保守されている Node 26 リリースを使ってください。セットアップ手順では Yarn 4.12.0 を使い、@transloadit/node 4.14.0、Zod 3.25.76、zod-to-json-schema 3.25.2 をインストールします。これらのバージョン固定は、ダウンロードできる例の SDK とスキーマコンバーターの組み合わせを再現するためのもので、最新版であることを示すものでも、既存アプリのダウングレードを求めるものでもありません。
まず、その README のインストールとアクセス設定に従い、コマンドを一つずつ実行してください。invoice-parser/run.ts と shared/runtime.ts の両方を、相対的な配置を保ってダウンロードしてください。何かをアップロードする前に、記載されている --help の検証を実行してください。インストールやダウンロードに失敗した場合は、パーサーを実行せず、先に問題を解決してください。
同じシェルで、Workspace の Auth Key と Auth Secret をそれぞれ
TRANSLOADIT_AUTH_KEY と TRANSLOADIT_AUTH_SECRET としてエクスポートしてください。スクリプトはこれらの環境変数を読み取ります。環境ファイルの読み込みや認証情報の作成は行いません。シークレットをソース管理やブラウザーのコードに含めないでください。
TRANSLOADIT_AI_CREDENTIALS が未設定の状態で、アップロードする権限のある請求書を
invoice.pdf に配置してください。まだ存在しない出力先を選び、次を実行してください。
node invoice-parser/run.ts --input ./invoice.pdf --output ./result.json --test-credentials
このコマンドは、Transloadit の処理に加え、課金対象の AI テスト認証情報の使用を明示的に許可します。代わりに自身の Anthropic キーを使う場合は、Console で AI 認証情報を設定し、その既存の名前を TRANSLOADIT_AI_CREDENTIALS としてエクスポートして、--test-credentials を省略してください。プロバイダーの認証情報モードは、必ずいずれか一つだけを選択してください。複数の請求書を処理する前に、料金を確認してください。
実行プログラムは入力を変更せず、出力先が既に存在する場合は Assembly を送信する前に拒否します。再実行時は新しいファイル名を使ってください。このチュートリアルでの上限は、入力とダウンロードする出力がそれぞれ 20 MiB、処理時間が五分、結果のダウンロードが 30 秒です。これらは製品の上限ではありません。Assembly ID の表示後に失敗した場合は、再試行する前に Console でその Assembly を確認してください。タイムアウトや中断が発生しても、リモート側の処理が停止したとは限らず、実行が失敗しても課金される場合があります。実行プログラムは Assembly を自動で再試行しません。
入力例
まず、各フィールドを別途確認できる架空の請求書を使ってください。たとえば、Sample Workshop Ltd が発行した請求書番号 INV-2026-0042 の請求書に、一件 USD 100 の自転車修理が二件と USD 20 の税額が記載されている場合、少なくとも次の値が得られるはずです。
{
"vendor_name": "Sample Workshop Ltd",
"invoice_number": "INV-2026-0042",
"currency": "USD",
"subtotal": 200,
"tax": 20,
"total": 220
}
実行が成功したら、result.json をテキストエディターで開いてください。発行元、請求書番号、通貨、明細、金額を、実際に入力した請求書と照合してください。請求書が異なれば、出力データも異なるはずです。ファイルが正常に保存されても、欠落したフィールドがあれば確認が必要です。業務情報や個人情報を含む結果は非公開で扱ってください。
次のステップ
結果をデータベースに保存する前に、アプリケーションで必須とするフィールドを決め、値の欠落や不一致は人が確認するフローに回してください。通貨換算は抽出とは分けてください。返される通貨と金額は元の請求書を表すもので、正規化された会計仕訳ではありません。
