296 lines
8.2 KiB
Markdown
296 lines
8.2 KiB
Markdown
# 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](#visao-geral)
|
|
- [Pre-requisitos](#pre-requisitos)
|
|
- [Estrutura do S3](#estrutura-do-s3)
|
|
- [Formatos de Documentos Suportados](#formatos-de-documentos-suportados)
|
|
- [Adicionando Documentos](#adicionando-documentos)
|
|
- [Sincronizacao da Knowledge Base](#sincronizacao-da-knowledge-base)
|
|
- [Validacao e Testes](#validacao-e-testes)
|
|
- [Boas Praticas](#boas-praticas)
|
|
- [Troubleshooting](#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:
|
|
|
|
1. Os documentos sao divididos em chunks (pedacos menores)
|
|
2. Cada chunk e convertido em um embedding vetorial
|
|
3. Os vetores sao armazenados para busca semantica
|
|
|
|
## Pre-requisitos
|
|
|
|
### Recursos AWS Necessarios
|
|
|
|
1. **Bucket S3** - Para armazenar os documentos fonte
|
|
2. **Knowledge Base do Bedrock** - Ja configurada com data source S3
|
|
3. **Permissoes IAM** - Acesso ao S3 e Bedrock
|
|
|
|
### Permissoes IAM Minimas
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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 | `.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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
1. Acesse o **Amazon Bedrock** no console AWS
|
|
2. Navegue ate **Knowledge bases** no menu lateral
|
|
3. Selecione sua Knowledge Base
|
|
4. Na aba **Data source**, clique em **Sync**
|
|
5. Aguarde o processamento completar
|
|
|
|
### Via AWS CLI
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```python
|
|
# 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
|
|
|
|
```python
|
|
# 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:
|
|
|
|
```bash
|
|
# 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**:
|
|
|
|
1. Sincronizacao nao foi executada
|
|
2. Formato do arquivo nao suportado
|
|
3. Arquivo muito grande (>50MB)
|
|
|
|
**Solucao**:
|
|
|
|
```python
|
|
# 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**:
|
|
|
|
1. Reduzir numero de documentos desnecessarios
|
|
2. Otimizar tamanho dos chunks
|
|
3. Usar filtros de metadados para buscas mais direcionadas
|
|
|
|
## Referencias
|
|
|
|
- [Documentacao Amazon Bedrock Knowledge Bases](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html)
|
|
- [API Reference - bedrock-agent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Agents_for_Amazon_Bedrock.html)
|
|
- [Boto3 Bedrock Agent](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock-agent.html)
|