User's blog

Como construir uma solução de sincronização automática para o Amazon Bedrock Knowledge Bases

Written by

Make.com Service User

in

O problema: sincronização manual não escala

O Amazon Bedrock Knowledge Bases permite que modelos de fundação (Foundation Models — FMs) e agentes de IA utilizem dados privados da organização para entregar respostas mais relevantes e precisas. Mas há um detalhe importante: sempre que documentos são adicionados, modificados ou excluídos no Amazon Simple Storage Service (Amazon S3), a base de conhecimento precisa ser ressincronizada — e, por padrão, esse processo é manual.

Em ambientes com atualizações frequentes, múltiplas equipes fazendo upload de arquivos ao longo do dia ou aplicações como sistemas de suporte ao cliente que exigem acesso imediato às informações mais recentes, depender de sincronização manual é um gargalo real. Sem automação, requests de sync se acumulam, exigem supervisão humana e ficam sujeitos a atrasos ou simplesmente serem esquecidos.

Para resolver isso, a AWS publicou um guia com uma solução automatizada que detecta eventos no S3 e dispara jobs de ingestão de forma inteligente, respeitando as cotas de serviço do Amazon Bedrock e oferecendo monitoramento abrangente.

Restrições que a solução precisa respeitar

Antes de entrar na arquitetura, é importante entender os limites impostos pelo Amazon Bedrock que qualquer solução de automação precisa considerar:

  • Máximo de 5 jobs de ingestão simultâneos por conta AWS
  • Máximo de 1 job por knowledge base
  • Máximo de 1 job por data source

Além disso, a API StartIngestionJob tem um rate limit de 0,1 requisições por segundo — ou seja, uma requisição a cada 10 segundos por Região. Esses limites valem por Região AWS e podem mudar; consulte as cotas de serviço do Amazon Bedrock para informações atualizadas.

Imagine um time de conteúdo atualizando vários arquivos durante uma release. Sem coordenação, os requests de sync se acumulam e ultrapassam os limites. Uma abordagem orquestrada resolve isso de forma transparente.

Visão geral da solução

A solução proposta é totalmente serverless, utiliza o AWS Serverless Application Model (AWS SAM) para deploy e não exige gerenciamento de infraestrutura. Ela é orientada a eventos e combina cinco serviços AWS para processar mudanças no S3 em tempo real enquanto gerencia os jobs de ingestão de forma inteligente:

As cinco fases da arquitetura

Fase 1: Detecção de mudanças nos documentos

Quando um documento é criado, modificado ou excluído no S3, o EventBridge captura o evento imediatamente. Uma função Lambda processa esses eventos sequencialmente: extrai metadados do arquivo (caminho, tipo de mudança, timestamp), cria uma entrada de rastreamento no DynamoDB para fins de auditoria e envia uma mensagem para a fila SQS.

# Event Processor Lambda extracts change information
def lambda_handler(event, context):
    for record in event.get('Records', []):
        # Extract S3 information
        bucket = record['s3']['bucket']['name']
        key = record['s3']['object']['key']
        event_name = record['eventName']

        # Determine change type
        change_type = get_change_type(event_name)

        # Create tracking entry in DynamoDB
        tracking_table.put_item(
            Item={
                'change_id': str(uuid.uuid4()),
                'knowledge_base_id': kb_id,
                'change_type': change_type,
                'key': key,
                'processed': False,
                'timestamp': datetime.utcnow().timestamp()
            }
        )

        # Send immediate notification to SQS
        sqs.send_message(
            QueueUrl=QUEUE_URL,
            MessageBody=json.dumps({
                'change_type': change_type,
                'bucket': bucket,
                'key': key,
                'knowledge_base_id': kb_id
            })
        )

Fase 2: Gerenciamento da fila

O SQS atua como buffer para garantir que o rate limit entre os jobs de sync seja respeitado. Uma segunda função Lambda consome uma mensagem por vez da fila e inicia uma execução no Step Functions com os detalhes da mudança e a configuração da knowledge base.

def lambda_handler(event, context):
    for record in event.get('Records', []):
        message = json.loads(record['body'])
        kb_id = message['knowledge_base_id']

        # Get or discover data source ID
        data_source_id = get_data_source_id(kb_id)

        # Start Step Functions workflow
        sfn_input = {
            'knowledge_base_id': kb_id,
            'data_source_id': data_source_id,
            'message': message
        }

        response = sfn.start_execution(
            stateMachineArn=STEP_FUNCTION_ARN,
            name=f"sync-{kb_id}-{int(datetime.utcnow().timestamp())}",
            input=json.dumps(sfn_input)
        )

Fase 3: Sincronização orquestrada

O Step Functions coordena o processo de sincronização com lógica de decisão para gerenciar as cotas. O fluxo verifica se há jobs ativos, inicia o sync imediatamente se as cotas permitirem ou aguarda 5 minutos antes de tentar novamente. Inclui também monitoramento do progresso e tratamento de falhas com retry automático.

{
  "Comment": "Workflow for syncing documents to Amazon Bedrock Knowledge Base",
  "StartAt": "CheckServiceQuota",
  "States": {
    "CheckServiceQuota": {
      "Type": "Task",
      "Resource": "${CheckQuotaFunctionArn}",
      "Next": "EvaluateQuotaCheck"
    },
    "EvaluateQuotaCheck": {
      "Type": "Choice",
      "Choices": [
        {
          "Variable": "$.quota_check.all_quotas_ok",
          "BooleanEquals": true,
          "Next": "StartSyncJob"
        },
        {
          "Variable": "$.quota_check.all_quotas_ok",
          "BooleanEquals": false,
          "Next": "QuotaExceeded"
        }
      ]
    },
    "QuotaExceeded": {
      "Type": "Wait",
      "Seconds": 300,
      "Next": "CheckServiceQuota"
    },
    "StartSyncJob": {
      "Type": "Task",
      "Resource": "${StartSyncFunctionArn}",
      "Next": "MonitorSyncJob"
    }
  }
}

Fase 4: Processamento pela knowledge base

Nesta fase, o Amazon Bedrock processa o conteúdo sincronizado: escaneia os documentos alterados, divide-os em chunks, converte cada trecho em embeddings vetoriais usando o modelo configurado e atualiza o índice vetorial — removendo embeddings desatualizados e inserindo os novos. O conteúdo atualizado fica imediatamente disponível para busca semântica.

Fase 5: Monitoramento e alertas

A solução inclui monitoramento completo: o DynamoDB registra o status de cada mudança de documento, o Amazon CloudWatch rastreia duração dos jobs, taxas de sucesso e utilização de cotas, alarmes são disparados quando a taxa de erros ultrapassa limites definidos, e notificações de sucesso ou falha são enviadas via Amazon SNS para os endereços configurados.

Recursos-chave da solução

Processamento de eventos em tempo real

A integração com o EventBridge garante que mudanças no S3 sejam capturadas imediatamente, sem depender de processos agendados. A resposta é praticamente instantânea.

Gerenciamento completo de cotas

A solução valida os limites do serviço antes de disparar qualquer job:

# Service quotas validation
MAX_CONCURRENT_JOBS_PER_ACCOUNT = 5
MAX_CONCURRENT_JOBS_PER_DATA_SOURCE = 1
MAX_CONCURRENT_JOBS_PER_KB = 1
MAX_FILE_SIZE_BYTES = 50 * 1024 * 1024 * 1024  # 50 GB
MAX_TOTAL_SIZE_BYTES = 100 * 1024 * 1024 * 1024  # 100 GB

def check_quotas(kb_id, data_source_id):
    # Get current active jobs
    response = bedrock.list_ingestion_jobs(
        knowledgeBaseId=kb_id,
        dataSourceId=data_source_id
    )
    active_jobs = [job for job in response['ingestionJobSummaries']
                   if job['status'] in ['STARTING', 'IN_PROGRESS']]
    return {
        'all_quotas_ok': len(active_jobs) == 0,
        'kb_quota_ok': len(active_jobs) < MAX_CONCURRENT_JOBS_PER_KB
    }

Rate limiting inteligente via SQS

A fila SQS é configurada para processar uma mensagem por vez, com retenção de 14 dias e dead letter queue para mensagens que falharem após 5 tentativas:

SyncQueue:
  Type: AWS::SQS::Queue
  Properties:
    VisibilityTimeout: 300
    MessageRetentionPeriod: 1209600  # 14 days
    RedrivePolicy:
      deadLetterTargetArn: !GetAtt SyncQueueDLQ.Arn
      maxReceiveCount: 5

SyncProcessorFunction:
  Events:
    SQSEvent:
      Type: SQS
      Properties:
        Queue: !GetAtt SyncQueue.Arn
        BatchSize: 1  # Process one message at a time

Pré-requisitos para o deploy

Antes de implantar a solução, é necessário ter:

O tempo estimado para o deploy da infraestrutura é de 5 a 10 minutos.

Passo a passo do deploy

Para implantar a solução, clone o repositório no GitHub e execute os comandos abaixo:

git clone https://github.com/aws-samples/sample-automatic-sync-for-bedrock-knowledge-bases
cd sample-automatic-sync-for-bedrock-knowledge-bases

Em seguida, faça o build e o deploy guiado:

sam build
sam deploy --guided

Durante o deploy, você será solicitado a informar os seguintes parâmetros:

  • Stack Name — nome para sua stack do CloudFormation (padrão: kb-auto-sync)
  • AWS Region — Região onde sua knowledge base existe (padrão: us-west-2)
  • KnowledgeBaseId — identificador da sua knowledge base no Amazon Bedrock
  • S3BucketName — nome do bucket S3 com seus documentos
  • S3KeyPrefix (opcional) — prefixo de pasta específico para sincronizar (ex: documents/)
  • NotificationsEmail (opcional) — e-mail para receber notificações dos jobs
  • MaxConcurrentJobs — número máximo de jobs simultâneos (padrão: 5)

Exemplo de entrada durante o deploy:

Setting default arguments for sam deploy
===============================
Stack Name [kb-auto-sync]: my-kb-sync
AWS Region [us-west-2]: us-east-1
Parameter KnowledgeBaseId: kb-1234567890
Parameter S3BucketName: my-document-bucket
Parameter S3KeyPrefix: documents/
Parameter NotificationsEmail: user@example.com
Allow SAM CLI IAM role creation [Y/n]: Y
Save arguments to configuration file [Y/n]: Y

Considerações de custo

A solução usa múltiplos serviços AWS com modelos de cobrança distintos. Para uma estimativa de uso típico com 10.000 documentos por mês:

Os outros serviços têm custos mínimos para esse volume. No geral, a solução é bastante econômica para organizações que precisam de sincronização em tempo real.

Troubleshooting: problemas mais comuns

Falha no job de sincronização

Pode ocorrer quando as permissões do IAM estão mal configuradas ou quando o tamanho dos documentos ultrapassa os limites permitidos. Para resolver: verifique o histórico de sincronização da data source no console do Amazon Bedrock, confirme que as permissões IAM estão corretas e valide que os documentos estão dentro dos tamanhos permitidos.

Rate limiting

Acontece quando muitas requisições de sync são processadas simultaneamente ou as cotas de serviço são atingidas. Para resolver: monitore as métricas no CloudWatch para identificar gargalos e ajuste as configurações de concorrência conforme necessário.

Limpeza dos recursos

Para evitar cobranças contínuas, remova a stack criada com um dos métodos abaixo.

Via AWS SAM:

# Deleção interativa (recomendada)
sam delete \
  --stack-name kb-auto-sync \
  --region YOUR_REGION

# Ou deleção não-interativa
sam delete \
  --stack-name kb-auto-sync \
  --region YOUR_REGION \
  --no-prompts

Via console do AWS CloudFormation: selecione a stack kb-auto-sync, clique em Delete e confirme. Aguarde a conclusão sem erros.

Após a deleção, permanecerão: os documentos originais no S3, a knowledge base do Amazon Bedrock, os logs do CloudWatch (até o período de retenção expirar) e quaisquer recursos criados manualmente fora da stack.

Recursos adicionais

Para aprofundar o conhecimento sobre os temas abordados, a AWS disponibiliza os seguintes recursos:

Fonte

Build and deploy an automatic sync solution for Amazon Bedrock Knowledge Bases (https://aws.amazon.com/blogs/machine-learning/build-and-deploy-an-automatic-sync-solution-for-amazon-bedrock-knowledge-bases/)

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

More posts