AWS Rekognition と Node.js による画像の代替テキストの下書き
AWS Rekognition の DetectLabels 操作を使い、編集者が代替テキストを書く際の参考にできる物体やシーンの候補を取得します。このチュートリアルでは、画像ごとのラベル候補を
reviewRequired フラグとともに出力し、ローカルファイルのキャッシュと小規模な逐次バッチ処理を追加します。
なぜ代替テキストを自動化するのか?
ラベルは説明を書き始める手がかりになりますが、ページ内での画像の目的は判断できません。W3C の alt 判断ツリーに従い、画像を説明するか、リンクやボタンとしての機能を説明するか、装飾画像として空の代替テキストを使うかを判断します。文脈の中で画像を人が確認するまでは、候補を
alt 属性に入れないでください。
AWS Rekognition と Node.js の連携
DetectLabels
は、文脈に沿ったキャプションではなく、ラベルと信頼度スコアを返します。ラベルは英語で返され、特定の物体とその上位カテゴリなど、ひとつの物体に複数の名前が含まれることがあります。この例では、指定した信頼度のしきい値で最大五つの名前を残します。画像内の文字を読むには、Rekognition の別の操作である
DetectText を使います。
環境のセットアップ
Bash、Node.js 24 LTS、npm、および rekognition:DetectLabels の呼び出しが許可された認証済みの
AWS プロファイルまたは IAM ロールが必要です。例は Node.js 24.21.0 と 26.8.1、および AWS SDK v3 の
@aws-sdk/client-rekognition 3.1148.0 でテストしています。これらはテスト済みのバージョンであり、API 自体の最小要件ではありません。メンテナンス中の Node.js リリースを使ってください。AWS に画像を送信すると料金が発生する場合があります。
組織で既に使用している認証方法と、SDK のデフォルトの認証情報プロバイダーチェーンを使います。ローカルプロファイルを使う場合は、先にサインインし、以下のコマンドで
AWS_PROFILE を設定します。IAM ロールの場合は、この変数を省略します。一時的な環境認証情報には、アクセスキーとシークレットに加えて
AWS_SESSION_TOKEN が必要です。これらの値をソースファイルやターミナル出力に含めないでください。
新しい image-labels プロジェクトを作成するディレクトリで、次を実行します。サブシェルにより現在のディレクトリは維持され、mkdir は既存プロジェクトの上書きを拒否します。npm の対象を明示することで、親ディレクトリが別のパッケージマネージャーを使っていても、新しいプロジェクト内にインストールされます。
(
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 image-labels && cd image-labels &&
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
)
以下のファイルを image-labels に保存します。ディレクトリ作成後にインストールが失敗した場合は、報告された問題を修正し、そのディレクトリ内で npm install コマンドを再実行します。既存のファイルは残してください。作成ブロック全体を再実行すると、意図した動作としてそのディレクトリの使用が拒否されます。
画像の要件
JPEG または PNG 画像を使います。AWS のドキュメントでは、直接送信するバイト列は最大 5 MB、S3 オブジェクトは最大 15 MB とされています。DetectLabels では、縦と横がそれぞれ
80~10,000 ピクセルである必要があります。現在の制限は
Rekognition のクォータを参照してください。コードは、サイズ変更、デコード、カラープロファイルの変更を行わず、元のバイト列を送信します。リクエストが成功しても、画像に破損がないことやラベルが正確であることを検証したわけではありません。
ラベル候補の実装
次を image-labels/labels.mjs として保存します。SDK はファイルのバッファーを直接受け取るため、手動で Base64 エンコードしないでください。credentials を未設定にすると、プロファイルとロールによる認証が維持されます。maxAttempts: 1 を設定すると自動再試行が無効になり、分析が失敗した呼び出しは失敗のままになります。
import { DetectLabelsCommand, RekognitionClient } from '@aws-sdk/client-rekognition'
import fs from 'node:fs'
const client = new RekognitionClient({ region: process.env.AWS_REGION, maxAttempts: 1 })
async function detectImageLabels(image, minConfidence = 75) {
if (!Number.isFinite(minConfidence) || minConfidence < 0 || minConfidence > 100) {
throw new Error('Confidence must be a number between 0 and 100.')
}
const response = await client.send(new DetectLabelsCommand({
Image: image,
Features: ['GENERAL_LABELS'],
MaxLabels: 5,
MinConfidence: minConfidence,
}))
return (response.Labels ?? [])
.map((label) => label.Name)
.filter((name) => typeof name === 'string' && name.trim().length > 0)
}
async function suggestImageLabels(imagePath, minConfidence = 75) {
const imageBytes = fs.readFileSync(imagePath)
return detectImageLabels({ Bytes: imageBytes }, minConfidence)
}
function reviewRecord(source, labelSuggestions, minConfidence = 75) {
return { source, minConfidence, reviewRequired: true, labelSuggestions }
}
export { client, detectImageLabels, reviewRecord, suggestImageLabels }
エントリーポイントを image-labels/review.mjs として保存します。
import { client, reviewRecord, suggestImageLabels } from './labels.mjs'
try {
const [imagePath, confidence = '75', ...extra] = process.argv.slice(2)
if (!imagePath || extra.length > 0 || !process.env.AWS_REGION) {
throw new Error('Supply AWS_REGION and an image path, with optional confidence.')
}
const minConfidence = Number(confidence)
const labels = await suggestImageLabels(imagePath, minConfidence)
console.log(JSON.stringify(reviewRecord(imagePath, labels, minConfidence)))
} catch {
console.error('Unable to retrieve image label suggestions. Check the path, region, credentials, and image.')
process.exitCode = 1
} finally {
client.destroy()
}
リージョンを選び、MY_PROFILE と
./example.jpg を置き換えます。パスは Node.js を実行するディレクトリからの相対パスです。スペースを含むファイル名は引用符で囲んでください。
AWS_REGION=us-east-1 AWS_PROFILE=MY_PROFILE node image-labels/review.mjs './example.jpg'
JSON には、選択された source、しきい値、reviewRequired: true、labelSuggestions が含まれます。実際の画像と照らし合わせて名前を確認してください。空のリストは、分析には成功したものの使えるラベルがないことを示すため、やはりレビューが必要です。ファイル、認証情報、プロバイダーの障害が発生すると、診断情報を stderr に出力し、成功レコードを生成せず、非ゼロで終了します。完成した代替テキストを含むフィールドはありません。
S3 の画像の処理
既存の S3 画像を使う場合、バケットと Rekognition クライアントのリージョンが一致している必要があり、呼び出し元の ID には対象オブジェクトへの
s3:GetObject が必要です。AWS の
S3 画像ガイドと
IAM ガイダンスを参照してください。この例ではキーにある現在のオブジェクトを読み取り、過去のバージョンは選択しません。
次を image-labels/labels.mjs に追記します。
async function suggestImageLabelsFromS3(bucket, key, minConfidence = 75) {
return detectImageLabels({ S3Object: { Bucket: bucket, Name: key } }, minConfidence)
}
export { suggestImageLabelsFromS3 }
image-labels/review-s3.mjs を保存します。
import { client, reviewRecord, suggestImageLabelsFromS3 } from './labels.mjs'
try {
const [bucket, key, confidence = '75', ...extra] = process.argv.slice(2)
if (!bucket || !key || extra.length > 0 || !process.env.AWS_REGION) {
throw new Error('Supply AWS_REGION, a bucket, and an object key, with optional confidence.')
}
const minConfidence = Number(confidence)
const labels = await suggestImageLabelsFromS3(bucket, key, minConfidence)
console.log(JSON.stringify(reviewRecord({ bucket, key }, labels, minConfidence)))
} catch {
console.error('Unable to retrieve S3 image label suggestions. Check the key, region, credentials, and permissions.')
process.exitCode = 1
} finally {
client.destroy()
}
バケットとキーを、自分の既存画像のものに置き換えます。キーはスペースやパーセント文字も含めてそのまま渡し、URL エンコードしないでください。この S3 の処理経路ではキャッシュを使わないため、呼び出すたびに現在のオブジェクトを分析します。
AWS_REGION=us-east-1 AWS_PROFILE=MY_PROFILE node image-labels/review-s3.mjs my-bucket 'images/example.jpg'
エッジケースとエラーへの対応
リクエストの失敗と空のラベルリストは異なります。ヘルパーは失敗時に reject し、エントリーポイントは AWS の生のレスポンスや認証情報を公開せずに失敗を報告します。トラブルシューティングでは、まずローカルパスを確認し、次に認証とリージョンを確認します。S3 の場合は、正確なキーとオブジェクトの読み取り権限も確認してください。AWS の DetectLabels のエラーでは、未対応の形式、無効なパラメーター、アクセスできない S3 オブジェクト、サービスやクォータに関する障害が説明されています。原因を修正してからコマンドを再実行してください。再試行のたびに、再度分析が行われる可能性があります。
機能の拡張
キャッシュの実装
ローカル画像では、内容とリクエスト設定をキーに、正常に取得した名前をキャッシュします。この任意のセクションでは、稼働中の Redis サーバーとその接続 URL があることを前提とします。Redis 7.4.11 と、現行の redis クライアント
6.3.0 でテストしています。既存プロジェクトにクライアントをインストールします。
test -f image-labels/package.json &&
npm install --prefix "$PWD/image-labels" --workspaces=false --ignore-scripts --save-exact redis@6.3.0
image-labels/cache.mjs を保存します。識別情報には、リージョン、コンテンツハッシュ、信頼度のしきい値、固定のラベル設定が含まれます。同じバッファーを読み取って分析することで、変更されたファイルが以前のバージョンのラベルを再利用しないようにします。プロバイダーから成功レスポンスを受け取った後にのみ保存します。形式が不正なキャッシュレコードや一致しないレコードは、ラベルとして扱わず、明示的なエラーにします。
import { createHash } from 'node:crypto'
import fs from 'node:fs'
import { createClient } from 'redis'
import { detectImageLabels } from './labels.mjs'
const redisClient = createClient({
url: process.env.REDIS_URL,
socket: { connectTimeout: 5000, reconnectStrategy: false },
})
redisClient.on('error', () => console.error('Redis connection error.'))
async function getCachedOrSuggestImageLabels(imagePath, minConfidence = 75) {
if (!Number.isFinite(minConfidence) || minConfidence < 0 || minConfidence > 100) {
throw new Error('Confidence must be a number between 0 and 100.')
}
const imageBytes = fs.readFileSync(imagePath)
const imageHash = createHash('sha256').update(imageBytes).digest('hex')
const identity = JSON.stringify({
region: process.env.AWS_REGION, imageHash, minConfidence,
features: ['GENERAL_LABELS'], maxLabels: 5,
})
const cacheKey = `image_labels:v2:${createHash('sha256').update(identity).digest('hex')}`
const cached = await redisClient.get(cacheKey)
if (cached !== null) {
const record = JSON.parse(cached)
if (record.identity !== identity || !Array.isArray(record.labels) ||
!record.labels.every((name) => typeof name === 'string' && name.trim().length > 0)) {
throw new Error('Invalid image-label cache record.')
}
return record.labels
}
const labels = await detectImageLabels({ Bytes: imageBytes }, minConfidence)
await redisClient.set(cacheKey, JSON.stringify({ identity, labels }), { EX: 60 * 60 * 24 })
return labels
}
export { getCachedOrSuggestImageLabels, redisClient }
image-labels/review-cached.mjs を保存します。
import { client, reviewRecord } from './labels.mjs'
let redisClient
try {
const [imagePath, confidence = '75', ...extra] = process.argv.slice(2)
if (!imagePath || extra.length > 0 || !process.env.AWS_REGION || !process.env.REDIS_URL) {
throw new Error('Supply AWS_REGION, REDIS_URL, and an image path, with optional confidence.')
}
const cache = await import('./cache.mjs')
redisClient = cache.redisClient
await redisClient.connect()
const minConfidence = Number(confidence)
const labels = await cache.getCachedOrSuggestImageLabels(imagePath, minConfidence)
console.log(JSON.stringify(reviewRecord(imagePath, labels, minConfidence)))
} catch {
console.error('Unable to retrieve cached image label suggestions. Check Redis and the image prerequisites.')
process.exitCode = 1
} finally {
if (redisClient?.isOpen) await redisClient.close()
client.destroy()
}
Redis URL を指定し、同じコマンドを二度実行します。二度目は Rekognition で再分析せず、保存済みの結果を読み取るはずです。24 時間の TTL は再利用を制限しますが、AWS のモデルのバージョンは固定しません。結果の抽出方法や固定設定を変更する際は、キャッシュの名前空間を更新してください。この例は Redis が利用できなければ失敗し、キャッシュを使わない課金対象のリクエストへ暗黙に切り替わることはありません。
AWS_REGION=us-east-1 AWS_PROFILE=MY_PROFILE REDIS_URL=redis://127.0.0.1:6379 node image-labels/review-cached.mjs './example.jpg'
バッチ処理
小さなリストでは、ファイルをひとつずつ処理し、各ファイルの結果を保持します。あるファイルが失敗しても後続のファイルは分析されますが、コマンド全体は非ゼロで終了します。この実行処理はキャッシュを使わず、読み取れる画像ごとに一度の分析を送信します。image-labels/review-batch.mjs を保存します。
import { client, reviewRecord, suggestImageLabels } from './labels.mjs'
async function batchProcessImages(imagePaths) {
const results = []
for (const imagePath of imagePaths) {
try {
const labels = await suggestImageLabels(imagePath)
results.push(reviewRecord(imagePath, labels))
} catch {
results.push({ source: imagePath, reviewRequired: true, status: 'failed' })
}
}
return results
}
try {
const imagePaths = process.argv.slice(2)
if (imagePaths.length === 0 || !process.env.AWS_REGION) {
throw new Error('Supply AWS_REGION and at least one image path.')
}
const results = await batchProcessImages(imagePaths)
console.log(JSON.stringify(results))
if (results.some((result) => result.status === 'failed')) process.exitCode = 1
} catch {
console.error('Unable to run the image-label batch. Check the region and arguments.')
process.exitCode = 1
} finally {
client.destroy()
}
候補を使う前に、各レコードの source を確認します。失敗したレコードにはラベルデータがありません。
AWS_REGION=us-east-1 AWS_PROFILE=MY_PROFILE node image-labels/review-batch.mjs './image1.jpg' './image2.jpg' './image3.jpg'
信頼度のしきい値の調整
単一画像のコマンドの最後の引数に、0~100 のしきい値を渡します。たとえば、最小信頼度 90% を指定します。
AWS_REGION=us-east-1 AWS_PROFILE=MY_PROFILE node image-labels/review.mjs './example.jpg' 90
しきい値を高くすると、不確かなラベルだけでなく、有用なラベルも除外されることがあります。信頼度が高い予測でも間違うことがあります。キャッシュヘルパーはこの値を識別情報に含めるため、90% のリクエストで 75% を指定して取得した結果を再利用することはできません。
まとめ
候補は、画像とその周辺コンテンツを確認できる編集者のための手がかりとして使います。信頼度はモデルの予測に関する指標であり、アクセシビリティの品質を示すものではありません。アプリケーションでほかの画像分析操作も必要な場合は、当社の 🤖 人工知能サービスをご覧ください。
