From 442acd7d1df862112b93ae1606e002b73b6219ed Mon Sep 17 00:00:00 2001 From: DNXBrasil Date: Wed, 28 Jan 2026 14:09:59 -0300 Subject: [PATCH] Adds final version of documentation --- docs/README.md | 1 + docs/bedrock-knowledge-base-guide.md | 295 +++++++++++++++++++++++++++ docs/frontend-app.md | 28 +-- 3 files changed, 299 insertions(+), 25 deletions(-) create mode 100644 docs/bedrock-knowledge-base-guide.md diff --git a/docs/README.md b/docs/README.md index 531450f..ab0bcf0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -127,5 +127,6 @@ A funcao `agent_call` foi projetada para ser usada como handler de AWS Lambda. ## Documentacao Adicional - [Guia de Integracao Langfuse](./langfuse-guide.md) - Como usar Langfuse para scoring e observabilidade +- [Guia do Bedrock Knowledge Base](./bedrock-knowledge-base-guide.md) - Como adicionar documentos a Knowledge Base - [Referencia da API](./api-reference.md) - Documentacao detalhada da API - [Melhorias de Codigo](./code-improvements.md) - Sugestoes de melhorias para o codigo diff --git a/docs/bedrock-knowledge-base-guide.md b/docs/bedrock-knowledge-base-guide.md new file mode 100644 index 0000000..28d1229 --- /dev/null +++ b/docs/bedrock-knowledge-base-guide.md @@ -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) diff --git a/docs/frontend-app.md b/docs/frontend-app.md index 71ce587..069f08a 100644 --- a/docs/frontend-app.md +++ b/docs/frontend-app.md @@ -7,8 +7,7 @@ Este documento descreve a aplicação web Streamlit localizada na pasta `front/a ``` front/app/ ├── front.py # Aplicação principal Streamlit (74 linhas) -├── st_auth.py # Módulo de autenticação AWS Secrets Manager (28 linhas) -└── __pycache__/ # Bytecode Python compilado +└── st_auth.py # Módulo de autenticação AWS Secrets Manager (28 linhas) ``` ## Visão Geral da Arquitetura @@ -118,24 +117,9 @@ A aplicação mantém três variáveis de estado de sessão: | `chat_answer_history` | `List[str]` | Lista de respostas da IA | | `chat_history` | `List[dict]` | Histórico completo da conversa com papéis | -##### 4. Função Utilitária: `create_sources_string()` -```python -def create_sources_string(source_urls: Set[str]) -> str: - """ - Formata fontes de citação para exibição. - Args: - source_urls: Conjunto de URLs de fontes únicas para formatar. - - Retorna: - str: Lista numerada de fontes para exibição. - """ -``` - -*Nota: Atualmente definida mas não utilizada ativamente no código.* - -##### 5. Fluxo Principal do Chat +##### 4. Fluxo Principal do Chat Quando um usuário envia uma mensagem, a seguinte sequência ocorre: @@ -244,7 +228,7 @@ x-api-key: | Cenário | Comportamento | |---------|---------------| -| Timeout da API | Exibe: "Desculpe, a busca pode ter demorado mais que o esperado. Por favor tente novamente." | +| Timeout da API | Exibe: Mensagem padrão definada anteriormente para enviar a equipe | | Erros gerais da API | Resposta pode não ser exibida corretamente | ## Comportamento da Sessão @@ -261,9 +245,3 @@ A aplicação foi projetada para executar atrás de um AWS Application Load Bala A aplicação executa em um container Docker (veja `front/Dockerfile`) e expõe a porta 8501. -## Considerações Conhecidas - -1. **Endpoint de API Hardcoded:** A URL do AWS API Gateway está hardcoded no código fonte -2. **Funcionalidades Não Utilizadas:** Dependências `streamlit-authenticator` e `sseclient` são importadas mas não utilizadas -3. **Sem Validação de Entrada:** Perguntas dos usuários e respostas da API não são validadas antes do uso -4. **Persistência Apenas na Sessão:** Conversas não persistem entre sessões