# 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)