GCP OCR と Node.js による文書 OCR ツールの作成
ひとつの Node.js コマンドラインプログラムで、ローカルの PNG、JPEG、PDF からテキストを抽出します。画像は Google Cloud Vision に直接送信します。PDF は非公開の Cloud Storage バケットにアップロードし、非同期で処理して、ページごとにテキストを格納した JSON として返します。PDF コマンドは、全ページが揃っているかとジョブの識別情報を確認してから JSON の結果を出力します。
前提条件
- ネイティブの TypeScript サポートを備えた Node.js 26.8.2 またはそれ以降の Node.js 26 リリース。Node.js から最新のセキュリティリリースをインストールします。
- 別途インストールした Corepack。プロジェクトで固定したパッケージマネージャーを通じて Yarn 4.12.0 を提供します。
- Google Cloud CLI
- Google Cloud に送信する権限のある PNG または JPEG。
ocr-projectと同じ場所のsample.pngに配置するか、画像コマンドのパスを変更します。 - 課金、Vision API、Cloud Storage が有効な Google Cloud プロジェクト。アカウントには、プロジェクトの割り当ての使用、サンプル用バケットの作成と削除、そのオブジェクトの作成、一覧表示、読み取り、削除の権限が必要です。必要に応じてプロジェクト管理者にアクセス権を依頼してください。
コマンドは macOS 上の Bash を使用します。この例は Node.js 26.8.2、Yarn 4.12.0、@google-cloud/vision 6.1.1、@google-cloud/storage 8.2.0 でテストしました。このチュートリアルはローカルで順番に実行することを前提としています。まずは合成文書を使用し、ジョブのプレフィックスを別のプロセスと共有しないでください。
Google Cloud Vision API の設定
Google Cloud Console でプロジェクトを選択し、課金が有効になっていることを確認してから Cloud Vision API を有効にします。プロジェクトの設定については、Google の
Vision セットアップガイドを参照してください。以下のコマンドでは、PROJECT_ID をすべて同じ値に置き換えます。
認証の設定
ローカル開発では、認可されたユーザーアカウントで Application Default Credentials(ADC)を使用します。CLI と ADC の両方がすでに目的のアカウントと割り当てプロジェクトを使用している場合は、次のログインコマンドを省略します。
gcloud auth login &&
gcloud auth application-default login &&
gcloud auth application-default set-quota-project PROJECT_ID
ADC は CLI の通常のログインとは別です。割り当てプロジェクトには serviceusage.services.use が必要です。Google の Vision 認証ガイドを参照してください。既存の GOOGLE_APPLICATION_CREDENTIALS 設定はローカルの ADC ファイルより優先されるため、意図した認証情報を選択しているか確認してください。このチュートリアルではサービスアカウントキーをダウンロードしないでください。後でデプロイする際は、アタッチされた ID または Workload Identity Federation を ADC と併用します。
Google Cloud Vision クライアントライブラリのインストール
サンプルを配置したいディレクトリで、次のブロックを貼り付けて実行します。書き込み前にツールを確認し、ocr-project がすでに存在する場合は処理を拒否します。シェルの作業ディレクトリは元のままです。
(
set -eu
node --version
corepack --version
gcloud --version
test ! -e ocr-project && test ! -L ocr-project
mkdir ocr-project
cd ocr-project
cat > package.json <<'JSON'
{
"name": "node-document-ocr",
"private": true,
"type": "module",
"packageManager": "yarn@4.12.0",
"dependencies": {
"@google-cloud/storage": "8.2.0",
"@google-cloud/vision": "6.1.1",
"pdf-lib": "1.17.1",
"zod": "4.3.6"
}
}
JSON
touch yarn.lock
printf 'nodeLinker: node-modules\n' > .yarnrc.yml
YARN_IGNORE_PATH=1 corepack yarn install
)
子ディレクトリのロックファイルとパッケージマネージャーの固定設定により、親の Yarn プロジェクトから独立してインストールします。ローカル設定では node_modules を選択します。プロジェクトの作成後にインストールが失敗した場合は、ディレクトリを残し、インストールだけを再試行してください。
(cd ocr-project && YARN_IGNORE_PATH=1 corepack yarn install)
プロジェクトの作成に失敗した場合は、別の親ディレクトリを選んでから設定をやり直します。以下の TypeScript ファイルふたつを ocr-project 内に保存します。以降のコマンドも親ディレクトリから実行します。
Node.js コードの作成
次のプログラム全体を ocr-project/ocr.ts として保存します。画像のパス、または PDF のパスとバケット名、ジョブ ID を受け取ります。PDF のアップロードもコマンドに含まれます。既存のジョブプレフィックスは拒否し、入力のアップロードでも世代の事前条件を使用して置き換えを拒否します。
import type { Bucket } from '@google-cloud/storage'
import { readFile } from 'node:fs/promises'
import { setTimeout as delay } from 'node:timers/promises'
import { Storage } from '@google-cloud/storage'
import { ImageAnnotatorClient, protos } from '@google-cloud/vision'
import { PDFDocument } from 'pdf-lib'
import { z } from 'zod'
const rpcOptions = { timeout: 30_000, retry: null }
const statusSchema = z.object({ code: z.number().optional() })
const pageSchema = z.object({
error: statusSchema.optional(),
context: z.object({ uri: z.string(), pageNumber: z.number().int() }),
fullTextAnnotation: z.object({ text: z.string().default('') }).optional(),
})
const fileSchema = z.object({
error: statusSchema.optional(),
inputConfig: z.object({ gcsSource: z.object({ uri: z.string() }) }),
responses: z.array(pageSchema),
})
const operationResultSchema = z.object({
responses: z.array(z.object({
outputConfig: z.object({ gcsDestination: z.object({ uri: z.string() }) }),
})).length(1),
})
class OcrError extends Error {}
function jobPrefix(job: string): string {
if (!/^[a-z0-9][a-z0-9-]{0,63}$/u.test(job)) {
throw new OcrError('Use a job ID containing lowercase letters, numbers, and hyphens')
}
return `node-ocr/${job}/`
}
async function removeJob(bucket: Bucket, prefix: string): Promise<void> {
const [files] = await bucket.getFiles({ prefix })
for (const file of files) await file.delete()
}
async function waitForOperation(
client: ImageAnnotatorClient,
name: string,
): Promise<protos.google.longrunning.IOperation> {
const deadline = Date.now() + 180_000
while (Date.now() < deadline) {
const [status] = await client.operationsClient.getOperation({ name }, rpcOptions)
if (status.done) return status
await delay(1000)
}
throw new OcrError('Wait expired; the cloud operation may still be running')
}
async function extractTextFromImage(
client: ImageAnnotatorClient,
bytes: Buffer,
): Promise<{ number: number; text: string }[]> {
const png = bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
const jpeg = bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255
if (!png && !jpeg) throw new OcrError('Image input must be a PNG or JPEG')
const [result] = await client.documentTextDetection({ image: { content: bytes } }, rpcOptions)
if (result.error?.code) {
throw Object.assign(new OcrError('Vision rejected the image', { cause: result.error }), {
code: result.error.code,
})
}
return [{ number: 1, text: (result.fullTextAnnotation?.text ?? '').trimEnd() }]
}
async function extractTextFromPDF(
client: ImageAnnotatorClient,
bucket: Bucket,
bytes: Buffer,
job: string,
project: string,
): Promise<{ number: number; text: string }[]> {
const pdf = await PDFDocument.load(bytes)
const pageCount = pdf.getPageCount()
if (pageCount < 1 || pageCount > 20) throw new OcrError('This example accepts 1–20 PDF pages')
const prefix = jobPrefix(job)
const outputPrefix = `${prefix}output/`
const source = `gs://${bucket.name}/${prefix}input.pdf`
const destination = `gs://${bucket.name}/${outputPrefix}`
const [existing] = await bucket.getFiles({ prefix })
if (existing.length > 0) throw new OcrError('Job prefix already exists; choose a new job ID')
let uploaded = false
let safeToClean = true
try {
await bucket.file(`${prefix}input.pdf`).save(bytes, {
resumable: false,
contentType: 'application/pdf',
preconditionOpts: { ifGenerationMatch: 0 },
})
uploaded = true
// A lost submission response can leave an operation running without a known name.
safeToClean = false
const [operation] = await client.asyncBatchAnnotateFiles({
parent: `projects/${project}/locations/eu`,
requests: [{
inputConfig: { mimeType: 'application/pdf', gcsSource: { uri: source } },
features: [{ type: 'DOCUMENT_TEXT_DETECTION' }],
outputConfig: { batchSize: 1, gcsDestination: { uri: destination } },
}],
}, rpcOptions)
if (!operation.name) throw new OcrError('Vision did not return an operation name')
console.error(`Operation: ${operation.name}`)
await bucket.file(`${prefix}operation.json`).save(`${JSON.stringify({ name: operation.name })}\n`, {
resumable: false,
contentType: 'application/json',
preconditionOpts: { ifGenerationMatch: 0 },
})
const status = await waitForOperation(client, operation.name)
safeToClean = true
if (status.error?.code) {
throw Object.assign(new OcrError('Vision operation failed', { cause: status.error }), {
code: status.error.code,
})
}
if (!(status.response?.value instanceof Uint8Array)) throw new OcrError('Operation has no result')
const decoded = protos.google.cloud.vision.v1.AsyncBatchAnnotateFilesResponse.decode(
status.response.value,
)
const result = operationResultSchema.parse(decoded)
if (result.responses[0].outputConfig.gcsDestination.uri !== destination) {
throw new OcrError('Operation returned a different output prefix')
}
const [files] = await bucket.getFiles({ prefix: outputPrefix })
const pages = new Map<number, string>()
for (const file of files) {
if (!file.name.startsWith(outputPrefix) || !file.name.endsWith('.json')) {
throw new OcrError('Unexpected output object')
}
const [contents] = await file.download()
const data = fileSchema.parse(JSON.parse(contents.toString('utf8')))
if (data.error?.code) throw new OcrError('Vision file failed')
if (data.inputConfig.gcsSource.uri !== source) throw new OcrError('Wrong input in result')
for (const page of data.responses) {
if (page.error?.code) throw new OcrError('Vision page failed')
const number = page.context.pageNumber
if (page.context.uri !== source || number < 1 || number > pageCount || pages.has(number)) {
throw new OcrError('Wrong source, duplicate page, or invalid page number')
}
pages.set(number, (page.fullTextAnnotation?.text ?? '').trimEnd())
}
}
if (pages.size !== pageCount) throw new OcrError('Incomplete PDF result')
return Array.from({ length: pageCount }, (_, index) => ({
number: index + 1,
text: pages.get(index + 1) ?? '',
}))
} finally {
if (uploaded && safeToClean) await removeJob(bucket, prefix)
if (uploaded && !safeToClean) {
console.error(`Retained pending job: gs://${bucket.name}/${prefix}`)
}
}
}
async function main(): Promise<void> {
const [mode, input, bucketName, job, ...extra] = process.argv.slice(2)
if (!input || extra.length > 0 ||
(mode !== 'image' && mode !== 'pdf' && mode !== 'cleanup') ||
(mode === 'image' && (bucketName !== undefined || job !== undefined))) {
throw new OcrError('Usage: image FILE | pdf FILE BUCKET JOB | cleanup OPERATION BUCKET JOB')
}
const project = z.string().min(1).parse(process.env.GOOGLE_CLOUD_PROJECT)
const client = new ImageAnnotatorClient({ projectId: project, apiEndpoint: 'eu-vision.googleapis.com' })
const storage = new Storage({ projectId: project, retryOptions: { autoRetry: false }, timeout: 30_000 })
let pages: { number: number; text: string }[] | undefined
try {
if (mode === 'image') {
pages = await extractTextFromImage(client, await readFile(input))
} else {
if (!bucketName || !job) throw new OcrError('PDF and cleanup modes require BUCKET and JOB')
if (mode === 'cleanup') {
if (!input.startsWith(`projects/${project}/locations/eu/operations/`)) {
throw new OcrError('Use the operation name printed by this project’s PDF command')
}
const prefix = jobPrefix(job)
const bucket = storage.bucket(bucketName)
const [receipt] = await bucket.file(`${prefix}operation.json`).download()
const record = z.object({ name: z.string() }).parse(JSON.parse(receipt.toString('utf8')))
if (record.name !== input) throw new OcrError('Operation does not belong to this job prefix')
await waitForOperation(client, input)
await removeJob(bucket, prefix)
console.error('Job objects removed')
} else {
pages = await extractTextFromPDF(client, storage.bucket(bucketName), await readFile(input), job, project)
}
}
} finally {
await client.close()
}
if (pages !== undefined) console.log(JSON.stringify({ pages }, null, 2))
}
main().catch((error: unknown) => {
const code = statusSchema.safeParse(error)
const hint = code.success && code.data.code === 7 ? 'Permission denied; check project and bucket access'
: code.success && code.data.code === 8 ? 'Quota exceeded; check Vision quota'
: error instanceof OcrError ? error.message : 'Check input, ADC, bucket access, and result format'
console.error(`OCR failed: ${hint}`)
process.exitCode = 1
})
Google Cloud に送信する権限のあるローカル画像を使って、画像モードを実行します。
GOOGLE_CLOUD_PROJECT=PROJECT_ID node ocr-project/ocr.ts image ./sample.png
認識したテキストを含むひとつのページを、末尾の空白なしで出力します。空白の画像では、text に空文字列を返します。ファイルが存在しない場合、画像が拒否された場合、リクエストが失敗した場合は、終了ステータス一で終了し、JSON の結果は出力しません。画像ヘッダーの確認で形式を選択しますが、Vision 側でも画像をデコードする必要があります。OCR テキストを正式な転記として使用する前に、原本と照合してください。
PDF ファイルの処理
次のテストデータ生成プログラムを ocr-project/make-pdf.ts として保存します。異なるテキストを持つふたつのページを作成し、既存の sample.pdf の上書きは拒否します。
import { writeFile } from 'node:fs/promises'
import { PDFDocument, StandardFonts } from 'pdf-lib'
const pdf = await PDFDocument.create()
const font = await pdf.embedFont(StandardFonts.Helvetica)
for (const text of ['DEVTIPS FIRST PAGE 2026', 'DEVTIPS SECOND PAGE 2026']) {
const page = pdf.addPage([1000, 400])
page.drawText(text, { x: 50, y: 250, size: 32, font })
}
await writeFile(new URL('./sample.pdf', import.meta.url), await pdf.save(), { flag: 'wx' })
テストデータを生成してから、新しい非公開バケットを作成します。YOUR_NEW_BUCKET を、自分が所有するグローバルに一意なバケット名に置き換えます。gcloud が使用するアカウントにも、このプロジェクトの認可が必要です。
node ocr-project/make-pdf.ts &&
gcloud storage buckets create gs://YOUR_NEW_BUCKET --project=PROJECT_ID --location=EU \
--uniform-bucket-level-access --public-access-prevention &&
GOOGLE_CLOUD_PROJECT=PROJECT_ID node ocr-project/ocr.ts pdf \
ocr-project/sample.pdf YOUR_NEW_BUCKET trial-1
CLI は node-ocr/trial-1/input.pdf をアップロードし、node-ocr/trial-1/output/ 配下に JSON を出力するようリクエストします。オペレーションの完了を待ち、返された出力先と各ページのソース URI を確認し、ページの欠落や重複を拒否したうえで、テキストをページ番号順に並べます。オブジェクトのアルファベット順の一覧表示だけでは、ページ順には並びません。非同期処理への引き渡しと JSON レスポンス形式については、Google の
PDF/TIFF OCR ガイドを参照してください。
このテストデータでは、次の JSON 結果になるはずです。
{
"pages": [
{ "number": 1, "text": "DEVTIPS FIRST PAGE 2026" },
{ "number": 2, "text": "DEVTIPS SECOND PAGE 2026" }
]
}
コマンドが成功すると、アップロードした入力と OCR オブジェクトを削除してから結果を出力します。オペレーションがエラーで終了した場合や結果が無効な場合も、このクリーンアップを実行します。クリーンアップに失敗した場合は、成功結果を出力せず、終了ステータス一を返します。ジョブを拒否した場合、既存のプレフィックス内の内容は保持します。他の人のオブジェクトを削除するのではなく、新しいジョブ ID を選んでください。
保留中のジョブの復旧とバケットの削除
CLI は最大三分間ポーリングします。処理中のステータスリクエストにより、さらに最大 30 秒かかることがあります。タイムアウトや接続の切断が発生しても、Vision の処理はキャンセルされません。完了したか不明な場合は、オペレーション名を出力し、ジョブのオブジェクトを保持します。復旧のために別の OCR リクエストを送信しないでください。同じバケットとジョブ ID を使い、出力されたオペレーション名を次のコマンドにコピーします。
GOOGLE_CLOUD_PROJECT=PROJECT_ID node ocr-project/ocr.ts cleanup \
'projects/PROJECT_ID/locations/eu/operations/OPERATION_ID' YOUR_NEW_BUCKET trial-1
クリーンアップは保存済みのオペレーション記録を確認し、終了状態になるまで待ってから、そのジョブのオブジェクトを削除します。オペレーションが失敗した場合も削除します。再びタイムアウトした場合は、オブジェクトを残し、後でクリーンアップを再実行してください。オペレーション名が届く前に送信レスポンスが失われた場合や、オペレーション記録の保存に失敗した場合は、プレフィックスを保持してください。そのオブジェクトを削除する前に、プロジェクト管理者にオペレーションの確認を依頼してください。クリーンアップは、自分が作成したプレフィックスに対してのみ使用してください。
自分のサンプル用バケットが空になったら、削除します。
gcloud storage buckets delete gs://YOUR_NEW_BUCKET --project=PROJECT_ID --quiet
テストデータの生成やバケットの作成に失敗した場合は、ファイルを残し、失敗した手順だけを再試行してください。生成プログラムは既存の PDF を拒否します。そのファイルを OCR に再利用するか、再生成する前に、生成したテストデータだけを意図的に削除してください。バケットの作成手順が成功していない限り、バケットの削除を実行しないでください。JSON が必要な場合は別途保存してください。この例ではアーカイブを維持しません。
API の制限と料金
Vision は最大 2,000 ページの PDF/TIFF ファイルを受け付けますが、この CLI では意図的に PDF のみを対象とし、ページ数を一から 20 ページに制限しています。TIFF の処理は実装していません。PDF は、リクエストした機能について各ページが画像として課金されるため、ふたつのページを持つテストデータは OCR を二単位使用します。最新の料金は Cloud Vision の料金を確認してください。Storage の料金は別途発生します。レスポンスが不確かな場合に、有料ジョブを知らないうちに再送信することを避けるため、リクエスト送信の自動再試行は行いません。
リージョン設定
この処理設定では、EU の Vision エンドポイント、EU のリクエスト親リソース、EU の Storage バケットを使用します。エンドポイントは Vision の処理場所を制御しますが、既存のバケットを移動するものではありません。ロケーションを変更する前に、Google のマルチリージョン OCR ドキュメントを参照してください。このチュートリアルは EU 設定で検証しました。
トラブルシューティング
- 認証または割り当てのエラー:目的の ADC アカウント、割り当てプロジェクト、API の有効化を確認します。
gcloudのログインが成功しても、SDK の認証ができている証拠にはなりません。 - バケットアクセスのエラー:入力の読み取りと、出力の作成、一覧表示、読み取り、削除の権限を確認します。ダウンロードの拒否を、空の OCR 結果として扱ってはいけません。
- PDF 出力の欠落や不一致:失敗を明示したままにします。部分的なテキストを出力するために、ページ数やソースの検証を緩めないでください。
- 中断またはタイムアウトしたジョブ:リソースの削除や新たな送信を検討する前に、上記の方法でオペレーションを復旧します。
まとめ
Transloadit で管理するアップロード処理ワークフローについては、Document OCR Robotを参照してください。その設定方法と結果の仕様は、この Google Cloud を直接利用する CLI とは別のものです。
