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:
- Amazon EventBridge — captura eventos do S3 em tempo real
- AWS Lambda — processa eventos e gerencia a sincronização
- Amazon Simple Queue Service (Amazon SQS) — faz buffer das requisições para respeitar as cotas
- AWS Step Functions — orquestra o fluxo de sincronização
- Amazon DynamoDB — rastreia mudanças de documentos e metadados dos jobs
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 timePré-requisitos para o deploy
Antes de implantar a solução, é necessário ter:
- Uma conta AWS com permissões para criar e gerenciar: Amazon Bedrock, Lambda, EventBridge, SQS, Step Functions, DynamoDB, S3 e AWS Identity and Access Management (IAM)
- Uma knowledge base do Amazon Bedrock já configurada com ao menos uma data source conectada ao S3
- AWS Command Line Interface (AWS CLI) versão 2.x ou superior — veja como instalar em Instalando ou atualizando a AWS CLI
- AWS SAM CLI versão 1.x ou superior — instruções em Instalar o AWS SAM CLI
- Python 3.12 ou superior — disponível em Python Downloads
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-basesEm seguida, faça o build e o deploy guiado:
sam build
sam deploy --guidedDurante 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]: YConsideraçõ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:
- AWS Lambda — cobrança por requisição e tempo de computação (~$0,20)
- Amazon EventBridge — cobrança por evento (~$1,00)
- Amazon SQS — cobrança por requisição
- AWS Step Functions — cobrança por transição de estado
- Amazon DynamoDB — cobrança por armazenamento e throughput
- Amazon CloudWatch — cobrança por dashboards, alarmes e armazenamento de logs
- Amazon SNS — cobrança por requisições mensais de API
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-promptsVia 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:
- Amazon Bedrock Workshop
- Boas práticas para arquiteturas orientadas a eventos
- Sincronização automática de dados no Amazon Bedrock
- Guia do usuário do Amazon Bedrock
- Documentação do Amazon Bedrock Knowledge Bases
- Sincronizando seus dados com a knowledge base do Amazon Bedrock
- Introdução à arquitetura orientada a eventos
- Exemplos do Amazon Bedrock no GitHub
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/)
