Let's Build: Transloadit の文書解析パイプライン
PDF または DOCX 文書から、タイトル、要約、任意の分析情報を含むローカル JSON ファイルを作成します。このサンプルでは、文書変換とスキーマに基づく AI 抽出を組み合わせます。保存した結果は、ほかの用途に使う前に原文と照合します。
ダウンロード可能な TypeScript アプリケーションは、このリポジトリーの外で実行します。ローカル文書を 1 件受け取り、Transloadit と AI プロバイダーに送信して、応答を新しい出力ファイルに保存します。初回の実行には、アップロードする権限がある、合成文書または機密情報を含まない文書を使用してください。Transloadit 提供の AI テスト用認証情報を明示的に選択した場合も含め、処理には料金が発生します。
ドキュメントインテリジェンスとは
文書ワークフローでは、テキストの解析、ページの分割、構造化フィールドの抽出を行えます。これらはそれぞれ別の処理です。このアプリケーションは PDF を /ai/chatに直接送信し、DOCX ファイルは先に PDF に変換します。OCR や文書のチャンク分割は行いません。
結果はレビューやインデックス作成の出発点であり、すべての事実が正しく抽出された証拠ではありません。スキーマが記述するのは文書の分析情報であり、請求書の合計、明細項目、信頼度スコアではありません。
TypeScript プロジェクトのセットアップ
既存の Node.js プロジェクトや Yarn ワークスペースの外にある、空の独立したディレクトリーで、アプリケーションのインストールとアクセスの手順に従ってください。非公開リポジトリーのチェックアウトやフィクスチャーのダウンロードは不要です。PDF または DOCX は自分で用意します。シェルの例では Bash を使用します。
テスト済みの組み合わせは、Node.js 26.12.1、Corepack 経由の Yarn
4.12.0、@transloadit/node 4.14.0、zod 3.25.76、zod-to-json-schema 3.25.2 です。これらは再現用に固定したバージョンであり、最新リリースであるという意味ではありません。Node 26 は保守対象のリリース系列です。サンプルを調整する際は、セキュリティ更新にも注意してください。Node 26 では Corepack を別途用意する必要があります。corepack が利用できない場合は、インストール手順に従ってください。ダウンロードには cURL も必要です。
README の手順では、固定バージョンのパッケージをインストールし、document-intelligence-pipeline/run.ts と shared/runtime.ts の両方をダウンロードします。プログラムが ../shared/runtime.ts をインポートするため、これらのディレクトリーは同じ親ディレクトリー内に置いてください。認証情報を指定する前に、最後の --help コマンドが動作するはずです。セットアップに失敗した場合は、再試行する前に作成途中のディレクトリーを確認してください。最初の package.json 作成処理は、既存ファイルの上書きを拒否します。既存のアプリケーションに対して繰り返し実行しないでください。
README に従い、アプリケーションを実行するシェルで
TRANSLOADIT_AUTH_KEY と TRANSLOADIT_AUTH_SECRET を設定してください。これらは Transloadit Workspace の認証に使用します。ソース管理やブラウザー側のコードに含めないでください。プログラムはプロセスの環境変数を読み取り、環境変数ファイルは読み込みません。
AI へのアクセス方法は別途選択します。TRANSLOADIT_AI_CREDENTIALS に、Anthropic キーを格納した既存の AI Credential の名前を設定するか、--test-credentials を明示的に渡して、Transloadit 提供の課金対象テストキーを使用します。どちらかのモードを選択してください。プログラムは認証情報を作成、変更しません。プロバイダーへのアクセスと課金については、/ai/chat のドキュメントを参照してください。
ステップ 1:OCR による文書解析(任意)
/document/ocr の
Robot は、別のワークフローで PDF から認識済みテキストやレイアウト情報が必要な場合に役立ちます。このアプリケーションでは代わりに、抽出 Step で明示的に選択した anthropic/claude-sonnet-4-6 の PDF 入力対応機能を使用します。
DOCX 入力の場合、/document/convert の Robot が、モデルに送信する PDF を生成します。変換と OCR は目的が異なります。OCR Step を追加するには、その出力を独自の抽出ワークフローにどう渡すかを決める必要があります。
ステップ 2:文書の分割
/document/split の Robot を使うと、別のワークフロー用にページを選択できます。以下のサンプルでは、ファイル全体を 1 件として処理します。契約書を独立したリクエストに分割すると、ほかのページにある定義や条項が失われる場合があります。ページごとの回答を結合すれば文書全体の意味を再現できるとは考えないでください。
ステップ 3:AI によるスキーマ駆動のデータ抽出
アプリケーションは example と documentInsightsSchema をエクスポートします。内容を確認、調整する際は、処理設定やスキーマのコピーを別途管理せず、これらを再利用してください。抽出 Step は format: 'json'、シリアライズした JSON Schema、result: true を使い、回答ファイルを公開します。
title と summary は必須の文字列です。任意のフィールドは author、publication_date、document_type、key_topics、key_points です。文書の種類が含まれる場合、その値は whitepaper、report、contract、invoice、receipt、statement、manual のいずれかです。任意のフィールドは省略される場合があります。必須の文字列でも、空だったり事実と異なったりする場合があります。スキーマ検証で確認するのは構造であり、真偽ではありません。
完全なパイプラインの構築
作業ディレクトリーの document.pdf に文書を配置するか、--input を実際のパスに変更してください。出力先には、書き込み可能で、まだ存在しないパスを選択します。Workspace の認証が設定済みで、TRANSLOADIT_AI_CREDENTIALS が未設定の場合、次のコマンドはテストキーを使った課金対象の処理を許可します。
node document-intelligence-pipeline/run.ts --input ./document.pdf --output ./result.json --test-credentials
既存の Anthropic AI Credential を使う場合は、前述のとおり
TRANSLOADIT_AI_CREDENTIALS を設定し、--test-credentials を省略してください。ランナーは空ではない最大 20 MiB の入力を受け付け、最大 20 MiB の出力をダウンロードします。これらはチュートリアル上の制限です。Assembly の制限時間は 5 分で、結果のダウンロードには別途 30 秒の制限時間を設けています。ローカルのサイズ制限内でも、プロバイダーの制限によりファイルが拒否される場合があります。
成功すると、ターミナルに Saved と出力パスが順に表示されます。入力は変更されず、result.json は一時的な結果 URL ではなくローカルファイルです。出力先がすでに存在する場合は、Assembly の送信前に処理を拒否します。順次再実行する際は別の出力先を使用し、コマンドを繰り返すためだけに前の結果を削除しないでください。
次の確認スクリプトを、package.json と同じディレクトリーに
inspect.ts として保存してください。同じエクスポート済みスキーマを使って保存済みの出力を読み取り、必須テキストが空白なら拒否し、レビューすべき 2 つのフィールドを表示します。
import { readFile } from 'node:fs/promises'
import { documentInsightsSchema } from './document-intelligence-pipeline/run.ts'
const saved = JSON.parse(await readFile('./result.json', 'utf8'))
const insights = documentInsightsSchema.parse(saved)
if (!insights.title.trim() || !insights.summary.trim()) {
throw new Error('The title or summary is blank. Review the source and Assembly before retrying.')
}
console.log(insights.title)
console.log(insights.summary)
node inspect.ts
名前、日付、数量、要約の主な主張を原文と照合してください。$240 の予備部品で自転車 12 台を修理した報告が、自転車の販売や $24 の支出についての要約に変わっていてはいけません。確認スクリプトは、その事実判断を代わりに行うことはできません。JSON の任意フィールドもレビューし、機密情報を含む結果は非公開にしてください。
Assembly ID の表示後に実行が失敗した場合は、再試行する前に Console でその Assembly を確認してください。タイムアウトや中断が起きても、リモート処理が停止したとは限らず、失敗した実行にも料金が発生する場合があります。ランナーは SDK の再試行を無効にし、失敗を捕捉した後に未完成のローカル出力を削除しますが、強制終了後のクリーンアップは保証できません。新しい出力先を選ぶ前に、残ったファイルを確認してください。
複数の文書形式の処理
ランナーは .pdf と .docx のファイル名を受け付け、大文字の拡張子にも対応しています。/file/filter の
Robot は、MIME タイプが PDF のファイルを抽出処理へ直接送り、もう一方の分岐では先に PDF に変換します。だからといって、PDF 以外のすべての形式をこの CLI の入力として受け付けるわけではありません。破損ファイルの名前を変更しても内容は修復されず、変換が成功しても要約が正確だとは限りません。
ローカルサンプルに追加する機能の検討
結果とコストを評価する間は、出力ファイル名をそれぞれ変えて文書を順次処理してください。この CLI には、バッチスケジューラー、レビューキュー、クラウドストレージへのエクスポート機能はありません。文書群を処理する前に、現在の料金と Robot のドキュメントを確認してください。
Template を使うと、調整した Assembly Instructions を再利用できます。今回のローカル実行には必要ありません。処理設定を Template に保存したり、ストレージを追加したりするだけでは、人によるレビュー、アプリケーションのアクセス制御、信頼性の高い抽出ポリシーは実現しません。
このアプローチが適している場面
このアプローチは、ファイルワークフロー内の変換 Step と抽出 Step を制御したい場合で、その周囲のアプリケーションを用意できるときに役立ちます。パッケージ化されたレビュー機能や、測定済みの抽出品質が必要なら、手元の文書を使って専用の文書 AI 製品と比較してください。この小規模なサンプルは、機能が同等であることや本番運用への対応を示すものではありません。
構築を始めるには?
アプリケーションの READMEと、内容を把握している機密情報を含まない文書 1 件から始めてください。保存した JSON と原文を一緒に保管してレビューし、その後 AI Robot のドキュメントを使って抽出ワークフローの変更を計画してください。
