8.2 KiB
8.2 KiB
Guia de Adicao de Documentos ao Bedrock Knowledge Base
Este guia explica como adicionar documentos a uma Knowledge Base do Amazon Bedrock utilizando S3 como fonte de dados com armazenamento vetorial.
Indice
- Visao Geral
- Pre-requisitos
- Estrutura do S3
- Formatos de Documentos Suportados
- Adicionando Documentos
- Sincronizacao da Knowledge Base
- Validacao e Testes
- Boas Praticas
- Troubleshooting
Visao Geral
O Amazon Bedrock Knowledge Bases permite criar aplicacoes RAG (Retrieval-Augmented Generation) conectando modelos de fundacao a fontes de dados da sua organizacao. O fluxo basico e:
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Documentos S3 │────▶│ Processamento │────▶│ Vector Store │
└─────────────────┘ │ (Chunking + │ │ (Embeddings) │
│ Embedding) │ └─────────────────┘
└──────────────────┘ │
▼
┌─────────────────┐
│ Knowledge Base │
│ Retriever │
└─────────────────┘
Quando voce adiciona documentos ao bucket S3 e sincroniza a Knowledge Base:
- Os documentos sao divididos em chunks (pedacos menores)
- Cada chunk e convertido em um embedding vetorial
- Os vetores sao armazenados para busca semantica
Pre-requisitos
Recursos AWS Necessarios
- Bucket S3 - Para armazenar os documentos fonte
- Knowledge Base do Bedrock - Ja configurada com data source S3
- Permissoes IAM - Acesso ao S3 e Bedrock
Permissoes IAM Minimas
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::SEU-BUCKET-NAME",
"arn:aws:s3:::SEU-BUCKET-NAME/*"
]
},
{
"Effect": "Allow",
"Action": [
"bedrock:StartIngestionJob",
"bedrock:GetIngestionJob",
"bedrock:ListIngestionJobs"
],
"Resource": "*"
}
]
}
Estrutura do S3
Organizacao Recomendada
Organize os documentos de forma logica no bucket S3:
s3://seu-bucket-knowledge-base/
├── produtos/
│ ├── comm-pix/
│ │ ├── manual-usuario.pdf
│ │ ├── faq.md
│ │ └── especificacoes-tecnicas.docx
│ └── outros-produtos/
│ └── ...
├── suporte/
│ ├── troubleshooting.md
│ └── procedimentos-operacionais.pdf
└── regulatorio/
├── termos-de-uso.pdf
└── politica-privacidade.pdf
Metadados (Opcional)
Voce pode adicionar metadados aos documentos criando um arquivo .metadata.json no mesmo diretorio:
{
"metadataAttributes": {
"categoria": "produtos",
"produto": "comm-pix",
"versao": "2.0",
"data_atualizacao": "2024-01-15"
}
}
Formatos de Documentos Suportados
O Bedrock Knowledge Base suporta os seguintes formatos:
| Formato | Extensao | Observacoes |
|---|---|---|
.pdf |
Texto e imagens (OCR disponivel) | |
| Texto Plano | .txt |
Encoding UTF-8 recomendado |
| Markdown | .md |
Preserva estrutura de titulos |
| HTML | .html |
Tags sao processadas |
| Microsoft Word | .docx |
Versoes recentes |
| CSV | .csv |
Cada linha como chunk separado |
| Excel | .xlsx |
Planilhas convertidas para texto |
Limitacoes
- Tamanho maximo por arquivo: 50 MB
- Numero maximo de arquivos por data source: 10.000
- Caracteres maximos por documento: 20.000 (para chunking padrao)
Adicionando Documentos
Via AWS CLI
# Upload de um unico arquivo
aws s3 cp documento.pdf s3://seu-bucket-knowledge-base/produtos/
# Upload de um diretorio inteiro
aws s3 cp ./docs/ s3://seu-bucket-knowledge-base/produtos/ --recursive
# Upload com exclusao de arquivos desnecessarios
aws s3 sync ./docs/ s3://seu-bucket-knowledge-base/produtos/ \
--exclude "*.tmp" \
--exclude ".git/*"
Sincronizacao da Knowledge Base
Apos adicionar documentos ao S3, e necessario sincronizar (ingest) a Knowledge Base para processar os novos arquivos.
Via Console AWS
- Acesse o Amazon Bedrock no console AWS
- Navegue ate Knowledge bases no menu lateral
- Selecione sua Knowledge Base
- Na aba Data source, clique em Sync
- Aguarde o processamento completar
Via AWS CLI
# Iniciar sincronizacao
aws bedrock-agent start-ingestion-job \
--knowledge-base-id SEU_KB_ID \
--data-source-id SEU_DS_ID
# Verificar status do job
aws bedrock-agent get-ingestion-job \
--knowledge-base-id SEU_KB_ID \
--data-source-id SEU_DS_ID \
--ingestion-job-id JOB_ID
Boas Praticas
1. Organizacao de Documentos
# BOM - Estrutura clara e organizada
produtos/
├── comm-pix/
│ ├── v2.0/
│ │ └── manual.pdf
│ └── v1.0/
│ └── manual.pdf
# EVITAR - Arquivos soltos e desorganizados
manual_v1.pdf
manual_v2.pdf
manual_novo_final_v3.pdf
2. Nomenclatura de Arquivos
# BOM - Nomes descritivos
manual-usuario-comm-pix-v2.pdf
faq-integracao-api.md
troubleshooting-erros-comuns.pdf
# EVITAR - Nomes vagos
doc1.pdf
novo.pdf
final.pdf
3. Atualizacao de Documentos
Ao atualizar um documento existente:
# Sobrescrever o arquivo existente (mesmo nome/caminho)
# O Bedrock detecta a mudanca e reprocessa na proxima sincronizacao
aws s3 cp manual-atualizado.pdf s3://bucket/produtos/manual.pdf
# Sincronizar para aplicar mudancas
aws bedrock-agent start-ingestion-job ...
4. Remocao de Documentos
# Remover do S3
aws s3 rm s3://bucket/produtos/documento-obsoleto.pdf
# Sincronizar para remover do indice
aws bedrock-agent start-ingestion-job ...
5. Versionamento
Considere usar versionamento de bucket S3 para manter historico:
# Habilitar versionamento
aws s3api put-bucket-versioning \
--bucket seu-bucket-knowledge-base \
--versioning-configuration Status=Enabled
Troubleshooting
Erro: "Access Denied" no Upload
Causa: Permissoes IAM insuficientes.
Solucao: Verifique se a role/usuario tem permissoes s3:PutObject no bucket.
Documentos Nao Aparecem nas Buscas
Causas possiveis:
- Sincronizacao nao foi executada
- Formato do arquivo nao suportado
- Arquivo muito grande (>50MB)
Solucao:
# Verificar status do ultimo job
aws bedrock-agent list-ingestion-jobs \
--knowledge-base-id PETAZDUOFZ \
--data-source-id SEU_DS_ID
Conteudo Recuperado Incompleto
Causa: Chunking pode ter dividido informacoes importantes.
Solucao: Considere ajustar a estrategia de chunking na configuracao da Knowledge Base (via console ou API).
Latencia Alta nas Buscas
Possiveis solucoes:
- Reduzir numero de documentos desnecessarios
- Otimizar tamanho dos chunks
- Usar filtros de metadados para buscas mais direcionadas