Introdução: a qualidade dos dados define a qualidade das respostas
Quando falamos de aplicações de Geração Aumentada por Recuperação (RAG), a qualidade das respostas depende diretamente dos dados que alimentam o sistema. O Amazon Bedrock Knowledge Bases é a capacidade totalmente gerenciada de RAG do Amazon Bedrock. Com o Amazon Bedrock Managed Knowledge Base, basta conectar as fontes de dados — a AWS cuida de toda a ingestão, armazenamento, indexação e recuperação. Não é preciso provisionar ou escalar um armazenamento vetorial, e os modelos de embedding e reranking já vêm configurados por padrão.
Para conteúdo web, o ponto de partida mais direto é o Amazon Bedrock Web Crawler, o conector de fonte de dados para knowledge bases gerenciadas. Basta informar as URLs semente ou sitemaps autorizados, e o crawler opera dentro do escopo e dos limites de taxa definidos. Sincronizações agendadas mantêm a base atualizada conforme as páginas mudam, e o conector consegue aguardar conteúdo carregado via JavaScript. Não há crawler para construir, hospedar ou operar — o que torna esse conector o ponto de partida para a maioria dos sites públicos.
Porém, algumas fontes exigem mais controle sobre o que chega à knowledge base. Pode ser necessário indexar apenas a região principal de conteúdo de cada página, remover navegação e outros elementos repetitivos, ou anexar metadados personalizados a cada documento. Para esse tipo de material, é possível estender o alcance da knowledge base com uma etapa de preparação usando o Crawl4AI, um crawler Python de código aberto. Essa etapa grava Markdown e um arquivo de metadados sidecar para cada página no Amazon S3, e a knowledge base ingere ambos por meio da fonte de dados S3.
O artigo original da AWS mostra como escolher o caminho de ingestão web adequado, implementar a preparação personalizada e validar a qualidade da recuperação. O repositório de exemplo aws-samples fornece o fluxo completo como implementação de referência. Vale destacar que se trata de ingestão em lote de propriedades web conhecidas, e não de acesso web em tempo real durante a inferência — para isso, existe o Web Grounding com Amazon Nova.
Visão geral da solução
A recomendação é começar pelo Amazon Bedrock Web Crawler quando ele consegue alcançar e indexar as páginas necessárias. Ele respeita o robots.txt e, após o primeiro crawl completo, cada sincronização captura apenas conteúdo adicionado, atualizado ou excluído.
O caminho via Crawl4AI entra em cena quando o material público precisa de um ou mais dos seguintes tratamentos antes da ingestão:
- Preparação estruturada em Markdown: Uso do
DefaultMarkdownGeneratorcom filtro de conteúdo por poda para reduzir navegação e boilerplate, preservando cabeçalhos, listas e tabelas. Como a poda é heurística, é importante revisar a saída representativa dos seus sites. - Extração direcionada e delimitada: Extração apenas da região da página que um seletor CSS opcional corresponde. Controle da travessia em largura por origem da semente, escopo de página/caminho/host, profundidade, limites de página e padrões de URL.
- Metadados personalizados: Anexar URLs de origem, timestamps de crawl, tipo de conteúdo e atributos próprios a cada documento, permitindo filtrar resultados de recuperação por eles.
Como tanto knowledge bases gerenciadas quanto gerenciadas pelo cliente suportam fontes de dados Amazon S3, o caminho via Crawl4AI funciona com ambos os tipos.
Como o fluxo de trabalho funciona
A aplicação AWS CDK empacota a implementação em uma imagem de contêiner durante o deploy. Quando o agendamento dispara, o contêiner executa scripts/container_entrypoint.py e realiza crawl, upload e ingestão em sequência. O fluxo segue estes passos:
- O Amazon EventBridge inicia a tarefa Amazon ECS no AWS Fargate conforme o agendamento configurado.
- A tarefa faz o crawl dos sites públicos configurados e prepara Markdown com um sidecar de metadados para cada página.
- A tarefa faz upload dos arquivos preparados para o bucket Amazon S3 que respalda a fonte de dados da knowledge base.
- A tarefa inicia um job de ingestão do Amazon Bedrock Knowledge Bases.
- O Amazon Bedrock Knowledge Bases lê os objetos novos e alterados, faz o parsing e aplica a estratégia de chunking selecionada. Cria embeddings e os indexa no armazenamento vetorial da knowledge base.
- A aplicação de IA generativa consulta a knowledge base para obter chunks relevantes ou uma resposta gerada com citações.
A tarefa lê sua configuração de pipeline (não secreta) do AWS Systems Manager Parameter Store na inicialização. O fluxo processa apenas páginas públicas e não implementa sessões autenticadas. Para sites que exigem login, a recomendação é avaliar primeiro as opções de autenticação do Amazon Bedrock Web Crawler, que incluem autenticação básica, baseada em formulário e SAML.
Etapa 1: Crawl e extração de conteúdo
A etapa de crawl realiza a varredura delimitada e grava um arquivo Markdown com um sidecar de metadados para cada página preparada com sucesso. Segue o trecho simplificado do código:
async def crawl_and_prepare(config: PipelineConfig, output_dir: str) -> list[str]:
written, seen = [], set()
pages_crawled = 0
browser_config = BrowserConfig(headless=True, java_script_enabled=True)
async with AsyncWebCrawler(config=browser_config) as crawler:
for seed in config.seed_urls:
remaining = config.crawl.max_pages - pages_crawled
if remaining <= 0:
break
strategy = BFSDeepCrawlStrategy(
max_depth=config.crawl.max_depth,
max_pages=remaining,
filter_chain=FilterChain([
SeedScopeFilter(seed, config.crawl.scope),
]),
)
run_config = CrawlerRunConfig(
deep_crawl_strategy=strategy,
markdown_generator=DefaultMarkdownGenerator(
content_filter=PruningContentFilter()
),
css_selector=config.crawl.css_selector,
check_robots_txt=config.crawl.check_robots_txt,
mean_delay=config.crawl.request_delay_seconds,
max_range=0,
semaphore_count=1,
)
results = await crawler.arun(url=seed, config=run_config)
for result in results:
if pages_crawled >= config.crawl.max_pages:
break
pages_crawled += 1
requested_url = result.url
source_url = getattr(result, "redirected_url", None) or requested_url
if not SeedScopeFilter(seed, config.crawl.scope).apply(source_url):
continue
canonical = _canonical_url(source_url)
if canonical in seen:
continue
seen.add(canonical)
if not result.success or not result.markdown:
continue
md_result = result.markdown
markdown = (
getattr(md_result, "fit_markdown", None)
or getattr(md_result, "raw_markdown", None)
or (md_result if isinstance(md_result, str) else "")
)
if not markdown:
continue
written.extend(
_write_document(
output_dir, _base_name(source_url),
markdown, {"source_url": source_url},
)
)
return writtenO Amazon Bedrock Knowledge Bases suporta diversos formatos de documento para fontes de dados S3, incluindo texto puro, HTML, Markdown, PDF e DOCX. O fluxo grava em Markdown porque esse formato preserva cabeçalhos, listas e tabelas sem carregar todo o HTML bruto para a ingestão.
Etapa 2: Upload para o Amazon S3
A etapa de upload envia cada documento Markdown preparado e seu sidecar de metadados correspondente para o bucket S3 configurado, sob o prefixo s3Prefix do fluxo. Para page.md, o sidecar deve ser nomeado page.md.metadata.json — o nome completo do arquivo de origem com .metadata.json anexado.
O Amazon Bedrock limita cada sidecar de metadados a 10 KB. Se um sidecar exceder esse limite, a execução para com erro antes de gravar qualquer arquivo. Veja um exemplo abreviado de sidecar:
{
"metadataAttributes": {
"source_url": {
"value": {"type": "STRING", "stringValue": "https://www.example.com/services/permits"}
},
"crawled_at_epoch": {
"value": {"type": "NUMBER", "numberValue": 1790640000}
},
"content_category": {
"value": {"type": "STRING", "stringValue": "web"}
}
}
}Etapa 3: Chunking, embedding e indexação pelo Amazon Bedrock
Com o conteúdo no S3, um job de ingestão entrega cada documento ao pipeline de ingestão da fonte de dados. Por padrão, uma knowledge base gerenciada faz o parsing de cada arquivo com seu parser gerenciado, que seleciona automaticamente a abordagem de parsing para o conteúdo.
A estratégia de chunking é selecionada ao conectar a fonte de dados e não pode ser alterada depois — por isso é importante avaliar as opções antes de criar uma fonte de dados de produção. As estratégias disponíveis em uma knowledge base gerenciada são:
- Chunking padrão: chunks de tamanho fixo de 300 tokens com 20% de sobreposição.
- Chunking de tamanho fixo: divisão por contagem máxima de tokens e percentual de sobreposição configuráveis.
- Sem chunking: trata cada arquivo como um único chunk, para conteúdo já dividido previamente.
Para mais informações, consulte Personalizar ingestão para uma fonte de dados. Uma knowledge base gerenciada pelo cliente também oferece chunking semântico e hierárquico, além de opções adicionais de parsing — veja Como o chunking de conteúdo funciona para knowledge bases.
O fluxo então inicia o job de ingestão com o seguinte código simplificado:
def start_ingestion_job(config: PipelineConfig) -> str:
client = boto3.client("bedrock-agent", region_name=config.region)
response = client.start_ingestion_job(
knowledgeBaseId=config.knowledge_base_id,
dataSourceId=config.data_source_id,
)
return response["ingestionJob"]["ingestionJobId"]Deploy da solução
Pré-requisitos
Antes de começar, é necessário ter:
- Uma conta AWS.
- Uma knowledge base gerenciada em uma região onde knowledge bases gerenciadas estão disponíveis, com o conector Amazon S3. Na fonte de dados, deixe o campo Metadata files prefix vazio, pois o fluxo grava cada sidecar de metadados junto ao seu documento. Ou uma knowledge base gerenciada pelo cliente existente — para adicionar uma fonte de dados S3, veja Conectar ao Amazon S3 para sua knowledge base.
- Uma fonte de dados Amazon S3 nessa knowledge base com status AVAILABLE.
- A knowledge base, o bucket S3 e a stack na mesma região.
- Autorização para fazer crawl dos sites públicos configurados.
- Uma estação de trabalho com Git, Python 3.10+, Node.js, AWS CLI v2, AWS CDK CLI v2 e um engine de contêiner compatível com Docker. O guia de deploy lista a versão mínima do CDK CLI.
- Credenciais AWS configuradas com permissão para bootstrap e deploy da stack CDK.
Deploy do fluxo agendado
Clone o repositório e instale as dependências de deploy:
git clone https://github.com/aws-samples/sample-crawl4ai-bedrock-knowledge-base.git
cd sample-crawl4ai-bedrock-knowledge-base/deploy
python -m venv .venv
source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -r requirements.txtMantenha o Docker em execução. Defina AWS_DEFAULT_REGION para a região da sua knowledge base. Faça o bootstrap da conta e região alvo uma vez, se necessário, e depois faça o deploy da stack:
export AWS_DEFAULT_REGION=REGION
cdk bootstrap aws://ACCOUNT_ID/REGION
cdk deploy \
-c knowledgeBaseId=ABCDEFGHIJ \
-c dataSourceId=KLMNOPQRST \
-c s3Bucket=amzn-s3-demo-bucket \
-c 'seedUrls=["https://www.example.com/services"]' \
-c maxDepth=1 \
-c maxPages=25Substitua todos os valores de exemplo pelos seus próprios. Os valores maxDepth e maxPages limitam o primeiro crawl a um nível de link e 25 páginas. Aumente-os após revisar a saída preparada. Para visualizar quais páginas um crawl prepara, é possível executar o pipeline localmente com --dry-run, conforme descrito no README.
Se o Docker na sua estação x86_64 não conseguir compilar imagens ARM64, adicione -c cpuArchitecture=X86_64 ao comando. Se a conta ativar VPC Block Public Access, a tarefa não consegue acessar a internet pela subnet pública padrão — nesse caso, faça o deploy com -c egressMode=nat, que adiciona um NAT gateway com cobranças por hora. O guia de deploy cobre as demais configurações.
Validação da qualidade de recuperação
Após a ingestão, a recomendação é testar perguntas representativas com a operação Retrieve antes de adicionar geração. Uma knowledge base gerenciada usa busca híbrida e, quando utiliza o modelo de embedding gerenciado padrão, também reordena resultados com seu reranker gerenciado. É possível filtrar resultados com os metadados dos sidecars.
O exemplo a seguir retorna até cinco chunks de páginas com content_category igual a web que foram indexadas nos últimos sete dias. Requer Boto3 1.43.32 ou posterior:
import time
import boto3
client = boto3.client("bedrock-agent-runtime", region_name="us-east-1")
week_ago = int(time.time()) - 7 * 24 * 60 * 60
response = client.retrieve(
knowledgeBaseId="ABCDEFGHIJ",
retrievalQuery={"text": "How do I apply for a building permit?"},
retrievalConfiguration={
"managedSearchConfiguration": {
"numberOfResults": 5,
"filter": {
"andAll": [
{"equals": {"key": "content_category", "value": "web"}},
{"greaterThan": {"key": "crawled_at_epoch", "value": week_ago}},
]
},
}
},
)
for result in response["retrievalResults"]:
print(result.get("metadata", {}).get("source_url"), result["content"]["text"][:200])Para uma knowledge base gerenciada pelo cliente, passe o mesmo filtro em vectorSearchConfiguration em vez de managedSearchConfiguration. A filtragem por metadados pode melhorar a precisão da recuperação, mas não é uma fronteira de autorização. Se diferentes usuários devem ver páginas diferentes, o conector Amazon S3 para knowledge bases gerenciadas suporta controle de acesso em nível de documento com arquivos de Lista de Controle de Acesso (ACL).
Para gerar respostas a partir de uma knowledge base gerenciada, use a recuperação agêntica. A operação AgenticRetrieveStream retorna os resultados recuperados e uma resposta gerada com citações. Para uma knowledge base gerenciada pelo cliente, use RetrieveAndGenerate. Avalie relevância de recuperação, cobertura de páginas-fonte e qualidade de citação sempre que alterar preparação de conteúdo, chunking ou configurações de recuperação — veja Configurar e personalizar consultas para knowledge bases gerenciadas.
Execuções recorrentes e custos
Cada evento agendado lança uma tarefa Fargate independente. A stack não impede execuções sobrepostas, então é importante escolher um intervalo maior que a duração esperada do crawl e ingestão. Uma execução com falha não é anunciada, pois o exemplo não adiciona política de retry, fila de mensagens mortas ou alarme.
Cada execução incorre em cobranças Fargate pelo tamanho configurado da tarefa (padrão: 2 vCPU e 4 GB). A tarefa continua em execução enquanto consulta o job de ingestão por até 30 minutos. A stack habilita Container Insights para o cluster e flow logs para a VPC, ambos adicionando cobranças do CloudWatch. Com egressMode=nat ou privateEndpoints=true, o NAT gateway e os endpoints de interface são cobrados por hora, mesmo sem tarefa em execução. Para detalhes, consulte preços do Amazon VPC e preços do Amazon Bedrock.
Os uploads são aditivos: remover uma URL ou perder uma página em um crawl posterior não exclui os objetos S3 existentes. Para remover conteúdo obsoleto, delete o documento e o sidecar correspondente sob o prefixo configurado e inicie a ingestão novamente. Para iniciar a ingestão automaticamente quando objetos no bucket mudam, veja Construir e implantar uma solução de sincronização automática para Amazon Bedrock Knowledge Bases.
Considerações de IA Responsável
As passagens recuperadas se tornam o contexto que um modelo foundation usa para gerar uma resposta. A AWS destaca os seguintes controles para aplicar antes de usar este fluxo em produção:
- Amazon Bedrock Guardrails: Anexe um guardrail às suas requisições de recuperação agêntica ou
RetrieveAndGeneratepara aplicar filtros de conteúdo, tópicos negados, filtros de palavras e filtros de informações sensíveis. - Verificações de grounding contextual: Ative a verificação de grounding contextual do Guardrails para pontuar cada resposta quanto ao grounding contra as passagens recuperadas e à relevância para a consulta.
- Trate conteúdo rastreado como entrada não confiável: Páginas web preparadas se tornam contexto do modelo, então texto em uma página pública pode tentar injeção de prompt via recuperação. Restrinja as URLs semente a sites confiáveis.
- Citações e revisão humana: Retorne citações com cada resposta gerada para que os usuários possam verificar afirmações contra a página-fonte.
Considerações de segurança e conformidade
- Use alvos de crawl públicos confiáveis: Configure apenas sites públicos autorizados. Não use este exemplo para rastrear endpoints privados ou internos.
- Respeite diretivas de crawl: O fluxo ativa a verificação de
robots.txtdo Crawl4AI por padrão, consistente com a Política de Uso Aceitável da AWS. - Limitação de taxa: Configure atrasos entre requisições para evitar sobrecarregar os sites de origem.
- Criptografia em repouso: A stack cria uma chave AWS KMS gerenciada pelo cliente com rotação automática e criptografa seus log groups do CloudWatch com ela.
- IAM de menor privilégio: A stack CDK concede à role da tarefa Fargate apenas
s3:PutObjectno prefixo do bucket configurado,bedrock:StartIngestionJobebedrock:GetIngestionJobna knowledge base alvo, além dessm:GetParameterpara seu parâmetro de configuração. - Segurança do pipeline de ingestão: Veja Protegendo o pipeline de ingestão RAG: Mecanismos de filtragem para padrões de filtragem e validação.
Limpeza de recursos
Para evitar cobranças contínuas, execute cdk destroy no diretório deploy/ do repositório, na mesma região e com os mesmos quatro valores -c obrigatórios usados no cdk deploy. Isso remove a regra do EventBridge, cluster ECS, task definition, log groups, roles IAM, parâmetro do Parameter Store e security groups. A chave AWS KMS é agendada para exclusão após 30 dias. Não são excluídos: a VPC importada, a knowledge base, o bucket S3 ou os objetos carregados pelo fluxo.
Para remover o conteúdo web ingerido, delete os objetos preparados sob s3://<bucket>/<prefix> e sincronize a fonte de dados novamente.
Conclusão
Este artigo da AWS demonstra como estender o Amazon Bedrock Knowledge Bases para conteúdo web público autorizado que precisa de preparação antes da ingestão. Uma tarefa Fargate agendada usa o Crawl4AI para crawl delimitado, prepara Markdown com sidecars page.md.metadata.json, faz upload para uma fonte de dados Amazon S3 e inicia a ingestão. A knowledge base então cuida de parsing, chunking, embeddings, indexação, recuperação e respostas fundamentadas com citações.
A recomendação é começar pelo Amazon Bedrock Web Crawler em uma knowledge base gerenciada para a maioria dos sites públicos. O caminho via Crawl4AI é indicado quando se precisa de controle sobre qual parte de cada página é indexada ou quais metadados acompanham o documento. Para começar, faça o deploy do fluxo Fargate agendado a partir do repositório sample-crawl4ai-bedrock-knowledge-base e valide a qualidade de recuperação e citações com conteúdo representativo antes de escalar.
Saiba mais
- Construir uma knowledge base gerenciada
- Amazon Bedrock Web Crawler para knowledge bases gerenciadas
- Conector Amazon S3 para knowledge bases gerenciadas
- Usar recuperação agêntica para consultar uma knowledge base
- Crawl4AI no GitHub
- Exemplos de Knowledge Bases no aws-samples/amazon-bedrock-samples
Fonte
Prepare web content for Amazon Bedrock Knowledge Bases with Crawl4AI (https://aws.amazon.com/blogs/machine-learning/prepare-web-content-for-amazon-bedrock-knowledge-bases-with-crawl4ai/)
Leave a Reply