Adds final version of documentation
This commit is contained in:
295
docs/bedrock-knowledge-base-guide.md
Normal file
295
docs/bedrock-knowledge-base-guide.md
Normal file
@@ -0,0 +1,295 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user