Textextraktion aus Bildern in Node.js mit AWS Rekognition

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande · Bio anzeigen

Nutzen Sie die Operation DetectText von AWS Rekognition, um mit Node.js Text auf Schildern, Etiketten und anderen Bildern zu lesen. Diese Anleitung erstellt eine CLI, die eine lokale JPEG- oder PNG-Datei oder ein vorhandenes S3-Objekt akzeptiert und erkannte Zeilen mit Konfidenzwerten und Geometrie ausgibt.

Einführung in AWS Rekognition und die Texterkennung

DetectText liefert Erkennungen sowohl vom Typ LINE als auch vom Typ WORD. Werden beide ausgegeben, wiederholt sich derselbe Text. Unsere CLI gibt deshalb nur Zeilen zurück und zählt diese. Eine erkannte Zeile kann Teil eines Satzes sein; das Ergebnis bildet weder die Absatzstruktur eines Dokuments noch eine garantierte Lesereihenfolge ab. AWS dokumentiert maximal 100 erkannte Wörter pro Bild in seiner Anleitung zur Texterkennung⁠. Für die OCR von Formularen, Tabellen und mehrseitigen Dokumenten sollten Sie stattdessen Amazon Textract⁠ in Betracht ziehen.

AWS Rekognition einrichten

Sie benötigen ein AWS-Konto und ein authentifiziertes lokales Profil oder eine IAM-Rolle, die rekognition:DetectText erlaubt. Diese Aktion verwendet Resource: "*"; sie arbeitet nicht mit einer Rekognition-Sammlung. Eine administrierende Person kann die folgende Richtlinie zuweisen:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "rekognition:DetectText",
      "Resource": "*"
    }
  ]
}

Nutzen Sie die bestehende Authentifizierungsmethode Ihrer Organisation. Für ein lokales Profil führen Sie die Einrichtung der AWS-SDK-Authentifizierung⁠ durch und melden sich an, bevor Sie das Beispiel ausführen. Wir lassen credentials ungesetzt, damit die Standardkette der Zugangsdatenanbieter⁠ Ihr Profil oder Ihre Rolle ermitteln kann. Zugangsdaten aus Umgebungsvariablen werden ebenfalls unterstützt; temporäre Zugangsdaten benötigen neben dem Zugriffsschlüssel und dem geheimen Schlüssel auch AWS_SESSION_TOKEN. Halten Sie Zugangsdaten aus Quelldateien und Terminalausgaben heraus.

Wählen Sie eine unterstützte AWS-Region⁠. Die folgenden Befehle verwenden us-east-1; ersetzen Sie diesen Wert durch Ihre Region und MY_PROFILE durch Ihren Profilnamen. Bei einer bereitgestellten IAM-Rolle lassen Sie AWS_PROFILE weg. Wenn Sie ein Bild an Rekognition senden, wird sein Inhalt an AWS übertragen. Dabei können Gebühren anfallen.

AWS SDK für Node.js installieren

Installieren Sie Node.js 24 LTS mit npm⁠. Das Beispiel wurde mit Node.js 24.21.0 und dem Paket @aws-sdk/client-rekognition in Version 3.1148.0 aus dem AWS SDK v3 getestet. Die Node.js-Patchversion ist eine getestete Version, keine zwingende API-Anforderung; spätere gepflegte Versionen derselben Hauptversion sind geeignet. Die Shell-Befehle verwenden Bash und wurden unter Linux getestet. Nutzen Sie eine Shell ohne NODE_OPTIONS, damit eingeschleuste Loader die Modulauflösung des neuen Projekts nicht überschreiben.

Führen Sie dies in einem Verzeichnis aus, in dem Sie ein neues Projekt namens rekognition-text anlegen möchten. Die Subshell lässt Ihr aktuelles Verzeichnis unverändert, und mkdir verweigert die Ausführung bei einem bereits vorhandenen Projekt. Die Installation richtet sich explizit an das neue Projekt, auch innerhalb eines anderen npm- oder Yarn-Projekts:

(
  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
)

Falls die Installation nach dem Anlegen fehlschlägt, behalten Sie das Verzeichnis und führen Sie den Befehl npm install darin erneut aus. Wiederholen Sie mkdir nicht und überschreiben Sie kein Projekt, das bereits Ihre Arbeit enthält. Behalten Sie die entstandene Datei package-lock.json bei, wenn Sie das Beispiel teilen.

AWS SDK in eine Node.js-Anwendung integrieren

Erstellen Sie rekognition-text/detect-text.mjs mit diesem ersten Block. Die Dateiendung .mjs legt das Modulformat explizit fest, auch innerhalb eines CommonJS-Projekts. maxAttempts: 1 sorgt dafür, dass jeder Aufruf eine Analyse versucht, ohne automatische Wiederholungsversuche:

import { DetectTextCommand, RekognitionClient } from '@aws-sdk/client-rekognition'

const client = new RekognitionClient({
  region: process.env.AWS_REGION,
  maxAttempts: 1,
})

Texterkennung mit AWS Rekognition durchführen

Fügen Sie den folgenden Block am Ende derselben Datei hinzu. Der lokale Pfad wird direkt geöffnet, ohne URL-Escape-Sequenzen auszuwerten oder sich auf die Dateiendung zu verlassen. Der Leseumfang ist auf 5 MiB plus ein Byte begrenzt, sodass zu große Dateien vor einer Analyse abgelehnt werden. Verwenden Sie eine reguläre Datei, die während des Lesens nicht verändert wird. Das SDK akzeptiert Buffer direkt und übernimmt die Base64-Kodierung⁠. AWS validiert das Bildformat und decodiert den Inhalt; eine erfolgreiche Antwort beweist nicht, dass ein beschädigtes Bild vollständig wiederhergestellt wurde.

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())

Bilder aus S3 analysieren

Der Modus s3 sendet den Bucket und den exakten Schlüssel an Rekognition; er lädt das Objekt nicht in Node.js herunter. Verwenden Sie ein vorhandenes privates Objekt in einem S3-Bucket für allgemeine Zwecke in derselben Region wie AWS_REGION. Die aufrufende Identität benötigt s3:GetObject für dieses Objekt sowie rekognition:DetectText. Für diese synchrone Operation sind weder ein öffentlicher Bucket noch eine Servicerolle nötig. Siehe die Vorgaben für S3-Eingaben⁠ und das Verfahren zur Bildanalyse⁠.

Geben Sie den unveränderten Schlüssel an, etwa images/sign %20.png, statt einer S3-URL oder eines URL-kodierten Schlüssels. Dieses Beispiel liest das aktuelle Objekt und gibt keine Version an. Unsere getesteten S3-Objekte verwenden SSE-S3-Verschlüsselung; bei KMS-verschlüsselten Objekten können zusätzliche Schlüsselberechtigungen erforderlich sein. Die CLI erstellt, verändert und löscht keine S3-Objekte.

Praxisbeispiel und Codeausschnitte

Speichern Sie Ihr Bild unter rekognition-text/photo.png. Führen Sie aus dem übergeordneten Verzeichnis Folgendes aus:

(
  cd rekognition-text &&
    AWS_PROFILE=MY_PROFILE AWS_REGION=us-east-1 node detect-text.mjs local './photo.png'
)

Für ein bereits nach S3 hochgeladenes Bild ersetzen Sie MY_BUCKET und images/photo.png durch Ihren Bucket und Schlüssel und verwenden dieselbe Region wie der Bucket:

(
  cd rekognition-text &&
    AWS_PROFILE=MY_PROFILE AWS_REGION=us-east-1 node detect-text.mjs s3 'MY_BUCKET' 'images/photo.png'
)

Das JSON benennt die angeforderte Quelle und enthält nur erkannte Zeilen. Prüfen Sie bei einem klaren Bild mit einer Zeile, ob lineCount den Wert eins hat und lines[0].text dem sichtbaren Text im Bild entspricht. Ein Konfidenzwert⁠ liegt auf einer Skala von 0 bis 100; er garantiert keine Genauigkeit. Der Begrenzungsrahmen⁠ verwendet bildrelative Koordinaten. Bei einem aufrecht ausgerichteten Bild mit 1.000 Pixeln Breite bedeutet ein Wert für Left von 0.1 einen Abstand von 100 Pixeln zum linken Rand. Das Polygon gibt die Eckpunkte des erkannten Bereichs an. Optionale Felder, die AWS auslässt, werden auch im JSON ausgelassen, statt mit erfundenen Werten gefüllt zu werden.

Eine erfolgreiche Analyse, die keine Zeilen findet, gibt lineCount: 0 und ein leeres Array für lines aus und beendet sich mit dem Exit-Code null. Das kann bei einem leeren Bild passieren oder wenn Text nicht erkannt wird. Bei einer fehlenden Datei, ungültigen Eingabe, einem Problem mit den Zugangsdaten oder einer fehlgeschlagenen AWS-Anfrage wird stattdessen eine Diagnose auf stderr ausgegeben und das Programm mit einem Exit-Code ungleich null beendet; es gibt kein Erfolgs-JSON aus. Vergleichen Sie den Text mit dem Quellbild, bevor Sie ihn zur Dateneingabe oder für Barrierefreiheit verwenden.

Dienstlimits und Preise von AWS Rekognition

Die Dokumentation zu den Dienstlimits⁠ von AWS nennt JPEG und PNG als Eingabeformate, eine Mindestgröße von 80 Pixeln für beide Bilddimensionen und maximal 100 erkannte Wörter. Sie nennt ein Limit von 5 MB für rohe Bytes und 15 MB für S3-Objekte. Diese CLI begrenzt lokale Eingaben auf exakt 5.242.880 Bytes, einschließlich aller angehängten Daten; die Base64-Darstellung des SDK verursacht zusätzlichen Speicherbedarf. Bei S3-Eingaben wendet AWS sein Objektlimit an. Prüfen Sie vor dem Aufruf die Größe und Dimensionen des gespeicherten Objekts, statt anzunehmen, dass eine kleine komprimierte Datei alle Vorgaben erfüllt.

Nutzen Sie bei der Fehlersuche die Fehlerreferenz⁠ der API. Prüfen Sie bei InvalidS3ObjectException den exakten Schlüssel, die Region und die Leseberechtigungen für das Objekt. Prüfen Sie bei Bildfehlern das tatsächliche Format, die Dimensionen und die Größe in Bytes. Ein Zugriffs- oder Zugangsdatenfehler erfordert eine Korrektur der Authentifizierung oder Berechtigungen. Bei Durchsatz- und Drosselungsfehlern können Sie die Anfrage nach Prüfung Ihrer Nutzung mit Backoff erneut versuchen; dieses Beispiel überlässt Ihnen diese Entscheidung, statt wiederholte Analysen zu verbergen.

Prüfen Sie die Preise für AWS Rekognition⁠ für Ihre Region, API, Ihr Volumen und die Anspruchsberechtigung Ihres Kontos. Für Speicherung und Anfragen in S3 fallen separate Gebühren an.

Fazit

Verwenden Sie die zurückgegebenen Zeilen als OCR-Kandidaten und behalten Sie die Geometrie bei, wenn Sie Text in einem Bild lokalisieren müssen. Wenn Sie zusätzlich eine Pipeline zur Bildverarbeitung benötigen, bietet der Image Describe Robot von Transloadit einen verwalteten Schritt zur Bildanalyse; seine API und Ausgabe unterscheiden sich von dieser CLI.