Node.js と AWS Rekognition による画像からのテキスト抽出
AWS Rekognition の DetectText 操作を使って、Node.js から看板やラベルなどの画像内のテキストを読み取ります。このチュートリアルでは、ローカルの JPEG または PNG、あるいは既存の S3 オブジェクトを受け取り、検出した行を信頼度スコアと位置・形状情報とともに出力する CLI を構築します。
AWS Rekognition とテキスト検出の概要
DetectText は、LINE と
WORD の両方の検出結果を返します。両方を出力すると同じテキストが重複するため、この CLI は行だけを返し、その行数を数えます。検出された行は文の一部である場合があります。結果は文書の段落構造を表すものではなく、読み順も保証されません。AWS のテキスト検出ガイドには、画像あたりの検出単語数の上限が 100 と記載されています。フォーム、表、複数ページの文書の OCR には、代わりに
Amazon Textract を検討してください。
AWS Rekognition のセットアップ
AWS アカウントと、rekognition:DetectText を許可する認証済みのローカルプロファイルまたは IAM ロールが必要です。このアクションは Resource: "*" を使用し、Rekognition コレクションには作用しません。管理者は次のポリシーを付与できます。
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "rekognition:DetectText",
"Resource": "*"
}
]
}
組織で既に使用している認証方法を利用してください。ローカルプロファイルの場合は、AWS SDK の認証設定を完了し、サンプルの実行前にサインインしてください。ここでは credentials を設定せず、デフォルトの認証情報プロバイダーチェーンでプロファイルまたはロールを解決します。環境変数による認証情報も使用できます。一時的な認証情報には、アクセスキーとシークレットに加えて
AWS_SESSION_TOKEN も必要です。認証情報の値をソースファイルやターミナル出力に含めないでください。
サポートされている AWS リージョンを選んでください。以下のコマンドでは us-east-1 を使用します。使用するリージョンに置き換え、MY_PROFILE はプロファイル名に置き換えてください。デプロイ先の IAM ロールを使う場合は、AWS_PROFILE を省略してください。Rekognition に画像を送信すると、その内容が AWS に送られ、料金が発生する場合があります。
Node.js 用 AWS SDK のインストール
npm を含む Node.js 24 LTS をインストールしてください。このサンプルは Node.js 24.21.0 と AWS SDK v3 の @aws-sdk/client-rekognition 3.1148.0 でテストしています。この Node.js パッチバージョンはテストに使用したものであり、API 自体の要件ではありません。同じメジャーバージョンの、より新しい保守対象リリースも使用できます。シェルコマンドは Bash を使用し、Linux でテストしています。挿入されたローダーが新規プロジェクトのモジュール解決を上書きしないように、NODE_OPTIONS が設定されていないシェルを使用してください。
新しい rekognition-text プロジェクトを作成したいディレクトリで、次を実行してください。サブシェルを使用するため、現在のディレクトリは変わりません。また、mkdir は既存のプロジェクトがある場合に処理を拒否します。別の npm または Yarn プロジェクト内で実行しても、インストール先には新規プロジェクトを明示します。
(
command -v node >/dev/null || { printf 'Install Node.js first.\n' >&2; exit 1; }
command -v npm >/dev/null || { printf 'Install npm first.\n' >&2; exit 1; }
[ -z "${NODE_OPTIONS:-}" ] || { printf 'Use a shell without NODE_OPTIONS.\n' >&2; exit 1; }
mkdir rekognition-text && cd rekognition-text &&
printf '{"private":true,"type":"module"}\n' > package.json &&
npm install --prefix "$PWD" --workspaces=false --ignore-scripts --save-exact \
@aws-sdk/client-rekognition@3.1148.0
)
作成後にインストールが失敗した場合は、ディレクトリを残し、その中で
npm install コマンドを再実行してください。mkdir を繰り返したり、作業内容が既にあるプロジェクトを上書きしたりしないでください。サンプルを共有する際は、生成された package-lock.json を保持してください。
Node.js アプリケーションへの AWS SDK の組み込み
まず、次のブロックを使って rekognition-text/detect-text.mjs を作成してください。.mjs 拡張子により、CommonJS プロジェクト内でもモジュール形式が明示されます。maxAttempts: 1 により、各呼び出しでは自動再試行を行わず、一度だけ解析を試みます。
import { DetectTextCommand, RekognitionClient } from '@aws-sdk/client-rekognition'
const client = new RekognitionClient({
region: process.env.AWS_REGION,
maxAttempts: 1,
})
AWS Rekognition によるテキスト検出の実行
同じファイルに、次のブロックを追記してください。ローカルパスは URL エスケープを解釈せず、拡張子にも依存せずに直接開きます。読み取りは 5 MiB と追加の 1 バイトまでに制限し、サイズ超過のファイルを解析前に拒否します。読み取り中に変更されない通常ファイルを使用してください。SDK は Buffer を直接受け取り、base64 エンコードを処理します。AWS は画像形式を検証し、内容をデコードします。ただし、レスポンスが成功しても、破損した画像が完全に復元されたことを証明するものではありません。
import { open } from 'node:fs/promises'
class InputError extends Error {}
async function localBytes(path) {
const file = await open(path, 'r')
try {
const info = await file.stat()
const limit = 5 * 1024 * 1024
if (!info.isFile() || info.size === 0 || info.size > limit) {
throw new InputError('Use a nonempty regular image file of at most 5 MiB.')
}
const buffer = Buffer.alloc(limit + 1)
let length = 0
while (length < buffer.length) {
const { bytesRead } = await file.read(buffer, length, buffer.length - length, null)
if (bytesRead === 0) break
length += bytesRead
}
if (length === 0 || length > limit) {
throw new InputError('Use a nonempty image file of at most 5 MiB.')
}
return buffer.subarray(0, length)
} finally {
await file.close()
}
}
async function main() {
const [mode, first, second, ...extra] = process.argv.slice(2)
if (!process.env.AWS_REGION) throw new InputError('Set AWS_REGION before running the CLI.')
let image
let source
if (mode === 'local' && first && second === undefined && extra.length === 0) {
image = { Bytes: await localBytes(first) }
source = { mode, path: first }
} else if (mode === 's3' && first && second && extra.length === 0) {
image = { S3Object: { Bucket: first, Name: second } }
source = { mode, bucket: first, key: second }
} else {
throw new InputError('Usage: node detect-text.mjs local PATH | s3 BUCKET KEY')
}
const response = await client.send(new DetectTextCommand({ Image: image }))
const lines = (response.TextDetections ?? [])
.filter((item) => item.Type === 'LINE')
.map((item) => ({
text: item.DetectedText,
confidence: item.Confidence,
boundingBox: item.Geometry?.BoundingBox,
polygon: item.Geometry?.Polygon,
}))
console.log(JSON.stringify({ source, lineCount: lines.length, lines }, null, 2))
}
main()
.catch((error) => {
const codes = [
'AccessDeniedException', 'CredentialsProviderError', 'InvalidImageFormatException',
'ImageTooLargeException', 'InvalidParameterException', 'InvalidS3ObjectException',
'ProvisionedThroughputExceededException', 'ThrottlingException', 'ENOENT', 'EACCES',
]
const name = error instanceof Error && 'code' in error ? error.code : error?.name
const code = codes.includes(name) ? name : 'RequestError'
console.error(error instanceof InputError ? error.message : `Text detection failed (${code}).`)
process.exitCode = 1
})
.finally(() => client.destroy())
S3 上の画像の解析
s3 モードは、バケットと正確なキーを Rekognition に送信します。オブジェクトを Node.js にダウンロードすることはありません。AWS_REGION と同じリージョンにある汎用 S3 バケット内の、既存の非公開オブジェクトを使用してください。呼び出し元の ID には、そのオブジェクトに対する s3:GetObject と、rekognition:DetectText の権限が必要です。この同期操作には、公開バケットもサービスロールも必要ありません。S3 入力の仕様と画像解析の手順を参照してください。
S3 URL や URL エンコード済みのキーではなく、images/sign %20.png のような未加工のキーを指定してください。このサンプルは現在のオブジェクトを読み取り、バージョンは指定しません。テストした S3 オブジェクトには SSE-S3 暗号化を使用しています。KMS で暗号化されたオブジェクトには、追加のキー権限が必要になる場合があります。この CLI は S3 オブジェクトの作成、変更、削除を行いません。
実行例とコードスニペット
画像を rekognition-text/photo.png に配置してください。親ディレクトリから次を実行します。
(
cd rekognition-text &&
AWS_PROFILE=MY_PROFILE AWS_REGION=us-east-1 node detect-text.mjs local './photo.png'
)
S3 にアップロード済みの画像の場合は、MY_BUCKET と
images/photo.png をバケット名とキーに置き換え、そのバケットと同じリージョンを使用してください。
(
cd rekognition-text &&
AWS_PROFILE=MY_PROFILE AWS_REGION=us-east-1 node detect-text.mjs s3 'MY_BUCKET' 'images/photo.png'
)
JSON は要求した入力元を示し、検出された行だけを含みます。一行のテキストがある鮮明な画像で、lineCount が一であり、lines[0].text が画像内の目に見えるテキストと一致することを確認してください。信頼度スコアは 0–100 の尺度であり、精度の保証ではありません。バウンディングボックスは画像に対する相対座標を使用します。正立した幅 1,000 ピクセルの画像では、Left の値が
0.1 なら、左端から 100 ピクセルの位置を意味します。ポリゴンは検出領域の各頂点を示します。AWS が省略した任意フィールドは、架空の値で埋めずに JSON からも省略します。
解析に成功しても行が見つからなかった場合は、lineCount: 0 と空の lines 配列を出力し、終了コードはゼロになります。これは空白の画像や、テキストを認識できなかった場合に起こり得ます。一方、ファイルが存在しない場合、不正な入力、認証情報の問題、AWS リクエストの失敗では、診断情報を標準エラー出力に書き込み、ゼロ以外の終了コードで終了します。成功時の JSON は出力しません。データ入力やアクセシビリティに利用する前に、テキストを元の画像と照合してください。
AWS Rekognition のサービス制限と料金
AWS のサービス制限ドキュメントには、入力形式が JPEG と PNG、画像の幅と高さがそれぞれ最小 80 ピクセル、検出単語数が最大 100 と記載されています。また、未加工バイト列の上限は 5 MB、S3 オブジェクトの上限は 15 MB です。この CLI は末尾の付加データも含めて、ローカル入力を正確に 5,242,880 バイトまでに制限します。SDK の base64 表現には追加のメモリーが必要です。S3 入力には、AWS がオブジェクトの上限を適用します。圧縮後のファイルが小さければすべての制約を満たすと思い込まず、呼び出し前に保存されたオブジェクトのサイズと画像の幅・高さを確認してください。
トラブルシューティングには API のエラーリファレンスを使用してください。InvalidS3ObjectException の場合は、正確なキー、リージョン、オブジェクトの読み取り権限を確認してください。画像のエラーでは、実際の形式、幅・高さ、バイト数を確認してください。アクセスや認証情報の失敗には、認証または権限の修正が必要です。スループットやスロットリングによる失敗は、使用状況を確認した後、バックオフを設けて再試行できます。このサンプルでは繰り返しの解析を隠れて行わず、再試行するかどうかの判断を利用者に委ねています。
AWS Rekognition の料金で、リージョン、API、使用量、アカウントの適用条件を確認してください。S3 のストレージとリクエストには別途料金がかかります。
まとめ
返された行は OCR の候補として使用し、画像内のテキストの位置を特定する必要がある場合は、位置・形状情報も保持してください。画像処理パイプラインも必要な場合は、マネージドの画像解析処理として Transloadit の Image Describe Robot を参照してください。この CLI とは API も出力も異なります。
