1. Dados e indexação
- [ ] Fonte de verdade definida (wiki, PDFs, tickets) e dono por conjunto
- [ ] Pipeline de ingestão reproduzível (chunk size, overlap, limpeza)
- [ ] Metadados em todo chunk: tenant, origem, data, versão do doc
- [ ] Modelo de embedding versionado; reindex planejado se trocar o modelo
- [ ] Documentos sensíveis classificados (não indexar o que não pode sair)
- [ ] Job de atualização/remoção quando o doc original muda ou expira
2. Retrieval
- [ ] Hybrid search (keyword + vetor) ou justificativa documentada para só vetor
- [ ] Filtro obrigatório por tenant / workspace em toda query
- [ ] k e thresholds definidos; timeout na busca
- [ ] Conjunto de avaliação (perguntas + docs relevantes) e baseline de recall@k / MRR
- [ ] Teste de regressão quando mudar chunking, pesos ou modelo
tip · Veja o artigo de hybrid search e o de RAG com pgvector para o caminho técnico.
3. Geração e prompts
- [ ] System prompt força uso das fontes e admite “não sei” quando não houver evidência
- [ ] Citações (id do doc / trecho) na resposta quando possível
- [ ] Temperatura baixa para respostas factuais
- [ ] Limite de tokens de contexto e de saída
- [ ] Prompt e parâmetros versionados (como código)
4. Segurança e privacidade
- [ ] API keys só em secret manager; nunca no front-end
- [ ] Isolamento multi-tenant verificado com testes automatizados
- [ ] Prompt injection: entrada do usuário não sobrescreve regras do sistema
- [ ] PII minimizada nos logs; retenção definida
- [ ] Tools/agents (se houver) com allowlist e sem shell irrestrito
- [ ] Política clara: o que pode ser enviado a provedores externos de LLM
5. Custo e limites
- [ ] Budget por usuário / tenant / feature
- [ ] Rate limit e quota; mensagem amigável quando estourar
- [ ] Modelo barato para triagem + modelo forte só quando necessário (se fizer sentido)
- [ ] Alertas de billing e de pico de tokens
- [ ] Cache de embeddings de queries repetidas (com TTL)
6. Observabilidade
- [ ] Trace por request: retrieval ids, scores, modelo, tokens in/out, latência
- [ ] Métricas: taxa de “não encontrado”, feedback do usuário, erros 4xx/5xx do LLM
- [ ] Amostragem de respostas para revisão humana periódica
- [ ] Dashboard mínimo (latência p95, custo/dia, recall em eval set)
7. Operação e rollback
- [ ] Feature flag para desligar o assistente sem deploy de emergência
- [ ] Fallback: mensagem estática ou busca keyword se o LLM/vector store cair
- [ ] Runbook: o que fazer se embedding API, Postgres ou provedor LLM falhar
- [ ] Backup do índice / tabela de chunks alinhado ao RPO da empresa
- [ ] Dono on-call e canal de escalação definidos
Se a maior parte dos itens ainda estiver aberta, o sistema é um protótipo útil — não um produto. Feche segurança e isolamento de tenant antes de escala de usuários.
8. Como verificar cada área
Marcar o item na lista não basta: o que vale é a evidência. Uma sugestão de teste para cada área:
| Área | Como verificar | Evidência |
|---|---|---|
| Dados e indexação | rodar a ingestão duas vezes e comparar os resultados; abrir uma amostra de chunks e conferir os metadados | log da ingestão e amostra dos chunks |
| Retrieval | rodar o conjunto de avaliação e registrar Recall@k e MRR como baseline | relatório versionado |
| Geração | fazer perguntas fora do escopo: o sistema deve dizer que não sabe | casos de teste salvos |
| Segurança | um usuário do tenant A pergunta algo que só existe no tenant B e não deve receber nada | teste automatizado no CI |
| Custo e limites | simular um pico de uso e conferir se o limite e o alerta disparam | painel de custos |
| Observabilidade | escolher uma requisição e reconstruir o caminho completo pelo trace | trace com ids, scores, tokens e latência |
| Operação e rollback | desligar a feature flag em homologação e ver o fallback funcionando | registro do teste |
9. Por onde começar
| Prioridade | Itens | Por quê |
|---|---|---|
| Antes de liberar para usuários | isolamento entre tenants, chaves no secret manager, dados sensíveis classificados, defesa contra prompt injection | falhas aqui expõem dados e não se corrigem depois do fato |
| Nas primeiras semanas | avaliação com baseline, limites de custo, trace por requisição, feature flag e fallback | dão controle para operar e para desligar em caso de problema |
| Evolução contínua | cache de embeddings, roteamento entre modelos, revisão por amostragem | melhoram custo e qualidade depois que o básico está estável |
Se a maior parte dos itens ainda estiver aberta, o sistema é um protótipo. Fechar segurança e isolamento primeiro é o que o separa de um produto.