João Henrique
b541f502ba
- Adicionado estrutura completa do projeto - Configurado MCP server para Premiere Pro - Adicionado documentação e skills - Configurado Gitignore para o projeto
114 lines
5.3 KiB
Markdown
114 lines
5.3 KiB
Markdown
# RAG deste projeto
|
|
|
|
Esta pasta é o **padrão Genial Sistemas** para dar a qualquer sistema (CRM,
|
|
Doza, contabilidade, o que vier depois) um banco de RAG próprio — usado só
|
|
para a IA indexar código/documentação e responder consultas gastando menos
|
|
tokens, sem precisar reler o repositório inteiro a cada tarefa.
|
|
|
|
**Não é o banco de dados do sistema.** É infraestrutura de apoio ao
|
|
desenvolvimento, mantida à parte da aplicação em si.
|
|
|
|
## Como funciona a infra
|
|
|
|
Existe **um único container Postgres + pgvector** compartilhado, rodando na
|
|
VPS da equipe (`rag-hub-db`, em `/docker/rag-hub/`). Cada sistema recebe o
|
|
seu **próprio banco de dados** dentro desse container — não um container
|
|
Docker novo por projeto. Isso é intencional: mais barato de manter (1
|
|
backup, 1 upgrade, 1 lugar pra olhar) do que uma stack isolada por sistema.
|
|
|
|
```
|
|
rag-hub-db (container único na VPS)
|
|
├── rag_doza ← banco deste projeto
|
|
├── rag_crm ← banco do CRM (quando existir)
|
|
├── rag_contabilidade ← banco da contabilidade (quando existir)
|
|
└── ... ← um banco por sistema novo
|
|
```
|
|
|
|
## Arquivos desta pasta
|
|
|
|
- `README.md` — este arquivo.
|
|
- `SETUP.md` — passo a passo para provisionar o banco deste projeto na
|
|
primeira vez (ou reprovisionar do zero).
|
|
- `schema.sql` / `schema-tigre.sql` — schema de cada sistema (extensões,
|
|
tabelas, índices). São o estado FINAL desejado: num banco novo basta
|
|
rodá-los. Num banco que já existe, use as migrations.
|
|
- `migrations/` — mudanças de schema numeradas e idempotentes, aplicadas com
|
|
`migrate_tigre.sh` (precisa de `rag_admin`; o usuário de indexação não tem
|
|
DDL). Cada arquivo abre com o motivo da mudança e o que fazer depois.
|
|
- `index_code.py` — indexador. `swift_chunker.py` faz o corte de arquivos
|
|
Swift por declaração.
|
|
- `search.py` — busca. `bench.py` mede recall e custo.
|
|
- `reindex_hook.sh` — hook de reindexação do arquivo recém-editado.
|
|
- `.env.example` — variáveis de ambiente que o código deste projeto precisa
|
|
para se conectar ao banco (sem valores reais — apenas o formato).
|
|
|
|
## Como a busca funciona
|
|
|
|
Três listas em paralelo, fundidas com RRF ponderado:
|
|
|
|
1. **densa** — embedding do trecho de código;
|
|
2. **lexical** — `pg_trgm` sobre os símbolos declarados, para consultas que
|
|
citam o nome exato de um tipo;
|
|
3. **resumo** — embedding só do doc-comment do arquivo, sem código para
|
|
diluir, que resgata arquivos pequenos e precisos.
|
|
|
|
Cada trecho guarda `start_line`/`end_line`, então o resultado aponta a janela
|
|
exata (`arquivo.swift:120-180`) em vez de mandar ler o arquivo inteiro.
|
|
|
|
Os números que justificam esse desenho estão em `bench.py` (18 consultas
|
|
douradas) e nos cabeçalhos das migrations. Antes: recall@5 de 33%. Depois:
|
|
94%, com 67% menos bytes por consulta. **Ao mexer nos parâmetros de fusão ou
|
|
no cortador, rode `bench.sh` antes e depois.**
|
|
|
|
### Modos de saída
|
|
|
|
| Comando | O que traz |
|
|
|---|---|
|
|
| `search_tigre.sh "consulta"` | caminho, faixa de linhas e uma linha de descrição (padrão) |
|
|
| `… --snippet` | + 300 chars do trecho |
|
|
| `… --full` | + o trecho inteiro |
|
|
| `… --json` | saída estruturada |
|
|
| `… --module X` / `--path Y` / `--ext .swift` | restringe o escopo |
|
|
| `… --map [termo]` | inventário de arquivos, sem nenhum código |
|
|
|
|
### Os dois bancos, lado a lado
|
|
|
|
O mesmo `search.py`/`index_code.py` atende `rag_tigre` (Swift) e `rag_doza`
|
|
(Python legado) — só muda o wrapper (`_tigre.sh` / `_doza.sh`) e o `.env`
|
|
carregado. `index_code.py` escolhe o cortador pela extensão:
|
|
`swift_chunker.py` para `.swift`, `python_chunker.py` para `.py`, janela de
|
|
linhas para o resto (`.md`, `.sql`, `.sh`).
|
|
|
|
O legado tem uma diferença estrutural real: não segue "uma classe por
|
|
arquivo" (`ai_analysis.py` e `app.py` passam de 5000 linhas, com dezenas de
|
|
funções soltas), então o `python_chunker` desce um nível dentro de blocos
|
|
grandes demais em vez de aceitar o arquivo inteiro como um só trecho.
|
|
|
|
Números do legado em `rag/bench_doza.sh`: recall@5 de 72% (18 consultas).
|
|
Mais baixo que os 94% do Tigre — a causa identificada não é bug do
|
|
pipeline, é o modelo de embedding (`nomic-embed-text`, majoritariamente
|
|
inglês) perdendo para conteúdo em português que soa tematicamente próximo:
|
|
"transcrever o áudio para texto" caiu atrás de markdown em português sobre
|
|
edição de voz, na frente do próprio `transcribe.py` (docstring em inglês).
|
|
Um modelo multilíngue deve fechar essa lacuna — ver README no que muda ao
|
|
trocar de modelo antes de decidir.
|
|
|
|
## Onde ficam as credenciais reais
|
|
|
|
Nunca neste diretório (ele é comitado no git). Credenciais reais —
|
|
host da VPS, senha do Postgres, chave SSH — ficam em `admin/VPS-ACCESS.md`
|
|
na raiz do projeto (nunca comitado, `chmod 600`).
|
|
|
|
## Convenção para um sistema novo
|
|
|
|
Ao começar um sistema novo (ou adicionar RAG a um já existente):
|
|
|
|
1. Copiar esta pasta `rag/` inteira para a raiz do novo projeto.
|
|
2. Trocar todas as referências de `doza`/`rag_doza` pelo nome do novo
|
|
sistema (ex: `crm` → banco `rag_crm`).
|
|
3. Seguir `SETUP.md` para criar o banco na VPS (usa a mesma `rag-hub-db`,
|
|
não sobe container novo).
|
|
4. Preencher `admin/VPS-ACCESS.md` do novo projeto com as credenciais reais
|
|
(copiando o padrão de acesso SSH/túnel já documentado nos projetos
|
|
existentes).
|