Adds final version of documentation
This commit is contained in:
@@ -127,5 +127,6 @@ A funcao `agent_call` foi projetada para ser usada como handler de AWS Lambda.
|
|||||||
## Documentacao Adicional
|
## Documentacao Adicional
|
||||||
|
|
||||||
- [Guia de Integracao Langfuse](./langfuse-guide.md) - Como usar Langfuse para scoring e observabilidade
|
- [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
|
- [Referencia da API](./api-reference.md) - Documentacao detalhada da API
|
||||||
- [Melhorias de Codigo](./code-improvements.md) - Sugestoes de melhorias para o codigo
|
- [Melhorias de Codigo](./code-improvements.md) - Sugestoes de melhorias para o codigo
|
||||||
|
|||||||
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)
|
||||||
@@ -7,8 +7,7 @@ Este documento descreve a aplicação web Streamlit localizada na pasta `front/a
|
|||||||
```
|
```
|
||||||
front/app/
|
front/app/
|
||||||
├── front.py # Aplicação principal Streamlit (74 linhas)
|
├── front.py # Aplicação principal Streamlit (74 linhas)
|
||||||
├── st_auth.py # Módulo de autenticação AWS Secrets Manager (28 linhas)
|
└── st_auth.py # Módulo de autenticação AWS Secrets Manager (28 linhas)
|
||||||
└── __pycache__/ # Bytecode Python compilado
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Visão Geral da Arquitetura
|
## 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_answer_history` | `List[str]` | Lista de respostas da IA |
|
||||||
| `chat_history` | `List[dict]` | Histórico completo da conversa com papéis |
|
| `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:
|
##### 4. Fluxo Principal do Chat
|
||||||
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
|
|
||||||
|
|
||||||
Quando um usuário envia uma mensagem, a seguinte sequência ocorre:
|
Quando um usuário envia uma mensagem, a seguinte sequência ocorre:
|
||||||
|
|
||||||
@@ -244,7 +228,7 @@ x-api-key: <Chave API do AWS Secrets Manager>
|
|||||||
|
|
||||||
| Cenário | Comportamento |
|
| 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 |
|
| Erros gerais da API | Resposta pode não ser exibida corretamente |
|
||||||
|
|
||||||
## Comportamento da Sessão
|
## 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.
|
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
|
|
||||||
|
|||||||
Reference in New Issue
Block a user