Extrair texto de imagens no Node.js com AWS Rekognition

Kevin van Zonneveld

Cofundador · Amsterdã, Países Baixos ·

Use a operação DetectText do AWS Rekognition para ler texto em placas, rótulos e outras imagens no Node.js. Este tutorial cria uma CLI que aceita um JPEG ou PNG local, ou um objeto existente no S3, e imprime as linhas detectadas com pontuações de confiança e geometria.

Introdução ao AWS Rekognition e à detecção de texto

DetectText retorna detecções de LINE e WORD. Imprimir ambas repete o mesmo texto, por isso nossa CLI retorna apenas linhas e conta essas linhas. Uma linha detectada pode ser parte de uma frase; o resultado não representa a estrutura de parágrafos de um documento nem garante uma ordem de leitura. A AWS documenta um máximo de 100 palavras detectadas por imagem em seu guia de detecção de texto. Para OCR de formulários, tabelas e documentos com várias páginas, avalie Amazon Textract como alternativa.

Configurar o AWS Rekognition

Você precisa de uma conta AWS e de um perfil local autenticado ou de uma função IAM que permita rekognition:DetectText. Essa ação usa Resource: "*"; ela não opera sobre uma coleção do Rekognition. Um administrador pode conceder a seguinte política:

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

Use o método de autenticação existente na sua organização. Para um perfil local, conclua a configuração de autenticação do AWS SDK e faça login antes de executar o exemplo. Deixamos credentials sem definição para que a cadeia padrão de provedores de credenciais possa resolver seu perfil ou sua função. Credenciais de ambiente também são aceitas; credenciais temporárias precisam de AWS_SESSION_TOKEN, além da chave de acesso e do segredo. Mantenha os valores das credenciais fora dos arquivos de código-fonte e da saída do terminal.

Escolha uma região AWS compatível. Os comandos abaixo usam us-east-1; substitua esse valor pela sua região e MY_PROFILE pelo nome do seu perfil. Para uma função IAM em um ambiente implantado, omita AWS_PROFILE. Enviar uma imagem ao Rekognition envia seu conteúdo à AWS e pode gerar uma cobrança.

Instalar o AWS SDK para Node.js

Instale o Node.js 24 LTS com npm. O exemplo foi testado com Node.js 24.21.0 e @aws-sdk/client-rekognition 3.1148.0 do AWS SDK v3. A versão de patch do Node.js foi testada, mas não é um requisito intrínseco da API; versões posteriores da mesma versão principal que continuam recebendo manutenção são adequadas. Os comandos de shell usam Bash e foram testados no Linux. Use um shell sem NODE_OPTIONS para que carregadores injetados não substituam a resolução de módulos do novo projeto.

Execute isto em um diretório onde você queira criar um projeto rekognition-text. O subshell mantém seu diretório atual inalterado, e mkdir não aceita um projeto existente. A instalação aponta explicitamente para o novo projeto, mesmo dentro de outro projeto npm ou 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
)

Se a instalação falhar após a criação, mantenha o diretório e tente novamente o comando npm install dentro dele. Não repita mkdir nem sobrescreva um projeto que já contenha seu trabalho. Preserve o package-lock.json resultante ao compartilhar o exemplo.

Integrar o AWS SDK a uma aplicação Node.js

Crie rekognition-text/detect-text.mjs com este primeiro bloco. A extensão .mjs torna o formato do módulo explícito, inclusive dentro de um projeto CommonJS. maxAttempts: 1 faz com que cada chamada tente realizar uma análise, sem novas tentativas automáticas:

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

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

Detectar texto com AWS Rekognition

Acrescente o bloco a seguir ao mesmo arquivo. O caminho local é aberto diretamente, sem interpretar sequências de escape de URL nem depender da extensão. A leitura é limitada a 5 MiB mais um byte, para que arquivos grandes demais sejam rejeitados antes de uma análise. Use um arquivo regular que não esteja sendo alterado durante a leitura. O SDK aceita o Buffer diretamente e cuida da codificação base64. A AWS valida o formato da imagem e decodifica seu conteúdo; uma resposta bem-sucedida não comprova que uma imagem danificada foi recuperada por completo.

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

Analisar imagens do S3

O modo s3 envia o bucket e a chave exata ao Rekognition; ele não baixa o objeto para o Node.js. Use um objeto privado existente em um bucket S3 de uso geral na mesma região que AWS_REGION. A identidade que faz a chamada precisa de s3:GetObject para esse objeto, além de rekognition:DetectText. Nenhum bucket público ou função de serviço é necessário para essa operação síncrona. Consulte o contrato de entrada do S3 e o procedimento de análise de imagens.

Forneça a chave sem codificação, como images/sign %20.png, em vez de uma URL do S3 ou uma chave codificada para URL. Este exemplo lê o objeto atual e não especifica uma versão. Os objetos do S3 que testamos usam criptografia SSE-S3; objetos criptografados com KMS podem exigir permissões adicionais para a chave. A CLI não cria, altera nem exclui objetos do S3.

Exemplo prático e trechos de código

Coloque sua imagem em rekognition-text/photo.png. No diretório pai, execute:

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

Para uma imagem cujo upload para o S3 já foi realizado, substitua MY_BUCKET e images/photo.png pelo seu bucket e pela chave, e use a mesma região desse bucket:

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

O JSON identifica a origem solicitada e contém apenas linhas detectadas. Para uma imagem nítida com uma linha, verifique se lineCount é um e se lines[0].text corresponde ao texto visível na imagem. Uma pontuação de confiança usa uma escala de 0–100; ela não é uma garantia de precisão. A caixa delimitadora usa coordenadas relativas à imagem. Em uma imagem na orientação correta com 1.000 pixels de largura, um valor de Left igual a 0.1 significa 100 pixels a partir da borda esquerda. O polígono indica os cantos da região detectada. Campos opcionais que a AWS omite também são omitidos do JSON, em vez de preenchidos com valores inventados.

Uma análise bem-sucedida que não encontra linhas imprime lineCount: 0 e um array lines vazio e termina com status zero. Isso pode acontecer em uma imagem em branco ou quando o texto não é reconhecido. Já um arquivo ausente, uma entrada inválida, um problema de credenciais ou uma requisição à AWS que falha faz com que a CLI escreva um diagnóstico em stderr e termine com status diferente de zero; ela não imprime JSON de sucesso. Compare o texto com a imagem de origem antes de usá-lo para entrada de dados ou acessibilidade.

Limites e preços do serviço AWS Rekognition

A documentação de limites do serviço da AWS lista entradas JPEG e PNG, um mínimo de 80 pixels para ambas as dimensões da imagem e um máximo de 100 palavras detectadas. Ela lista um limite de 5 MB para bytes brutos e de 15 MB para objetos do S3. Esta CLI limita a entrada local a exatamente 5.242.880 bytes, incluindo quaisquer dados adicionais no final; a representação em base64 do SDK aumenta o uso de memória. Para entradas do S3, a AWS aplica seu limite de objeto. Verifique o tamanho e as dimensões do objeto armazenado antes de fazer a chamada, em vez de presumir que um arquivo comprimido pequeno atende a todas as restrições.

Use a referência de erros da API ao investigar problemas. Para InvalidS3ObjectException, verifique a chave exata, a região e as permissões de leitura do objeto. Para erros de imagem, verifique o formato real, as dimensões e o tamanho em bytes. Uma falha de acesso ou de credenciais exige uma correção na autenticação ou nas permissões. Falhas de vazão e de limitação de requisições podem ser tratadas com novas tentativas com espera progressiva após verificar seu uso; este exemplo deixa essa decisão a seu critério, em vez de ocultar análises repetidas.

Consulte os preços do AWS Rekognition para sua região, API, volume e elegibilidade da conta. O armazenamento e as requisições do S3 têm cobranças separadas.

Conclusão

Use as linhas retornadas como candidatas a resultados de OCR e preserve a geometria quando precisar localizar texto em uma imagem. Se também precisar de um pipeline de processamento de imagens, consulte o Image Describe Robot da Transloadit para um Step gerenciado de análise de imagens; sua API e sua saída diferem das desta CLI.