OmniRoute/Tuto_Qdrant.md

Tutorial Qdrant no OmniRoute (Guia para vídeo)

⚠️ Status (v3.8.0): Integração Qdrant está dormente no pipeline. As funções de upsert/search/delete existem em src/lib/memory/qdrant.ts e a UI de configuração está pronta (MemorySkillsTab.tsx + endpoint /api/settings/qdrant/embedding-models), mas:

• upsertSemanticMemoryPoint, searchSemanticMemory e deleteSemanticMemoryPoint não são chamadas pelo pipeline de chat — busca semântica corrente usa apenas o store local em SQLite (ver docs/frameworks/MEMORY.md).
• As rotas /api/settings/qdrant/health, /api/settings/qdrant/search e /api/settings/qdrant/cleanup mencionadas neste tutorial ainda não foram implementadas.
• Os botões "Testar conexão" e "Teste de busca" no painel exigem que essas rotas existam; até lá, são placeholders.

Este documento descreve a UX/configuração planejada. Para o sistema de memória ativo hoje, consulte docs/frameworks/MEMORY.md. Acompanhe o status da ativação em issues marcadas com area:qdrant.

1) O que é o Qdrant no OmniRoute

O Qdrant é o banco vetorial usado para memória semântica.

No OmniRoute, ele ajuda a:

• Encontrar contexto por significado (não só palavra exata).
• Reaproveitar memórias antigas com mais precisão.
• Melhorar respostas com base em histórico relevante.
• Escalar melhor quando a base de memória cresce.

---

2) Quando o OmniRoute envia dados para o Qdrant

Com Qdrant habilitado e modelo de embedding configurado, o sistema envia vetores quando:

• Memórias são salvas (upsert de memória).
• Fluxos de chat recuperam contexto semântico/híbrido.
• Testes de busca no painel geram embedding e consultam a coleção.

Resumo prático:

• Sem Qdrant: busca mais limitada (texto/chave).
• Com Qdrant: busca por similaridade semântica (mais inteligente).

---

3) Pré-requisitos

Você precisa de:

• Instância Qdrant acessível (porta 6333).
• Coleção criada (ex.: omniroute_memory).
• Modelo de embedding válido (ex.: OpenRouter).
• Credencial do provider do embedding configurada no OmniRoute.

Exemplo de modelo OpenRouter:

• openrouter/nvidia/llama-nemotron-embed-v1-1b-v2:free

Importante:

• O texto do modelo deve estar em formato provider/model.
• Se usar modelo com dimensão diferente da coleção, a busca falha.

---

4) Como configurar no painel do OmniRoute

No menu:

• Admin > Settings > Qdrant (Memória vetorial)

Preencha:

• Ativar Qdrant: ligado.
• Host: IP ou URL do servidor Qdrant (sem porta no campo Host).
• Porta: 6333.
• Collection: omniroute_memory (ou nome que você criou).
• Modelo de embedding: selecione da lista ou digite manualmente.
• API Key: opcional (preencha se seu Qdrant exigir).

Depois:

1. Clique em Salvar.
2. Clique em Testar conexão.
3. No Teste de busca, digite um texto e clique em Buscar.

---

5) Como criar a coleção no Dashboard do Qdrant (sem comando)

No Qdrant Dashboard:

1. Clique em Create collection.
2. Escolha Global search.
3. Em tipo de busca, use Custom.
4. Configure vetor:
   • Vector name: omniao (padrão esperado pelo OmniRoute atualmente).
   • Size: dimensão do seu modelo de embedding (ex.: 2048 em alguns modelos NVIDIA).
   • Distance: Cosine.
5. Salve a coleção com nome omniroute_memory.

Se já tinha coleção com dimensão errada:

• Recrie a coleção com dimensão correta.

---

6) Como validar se está funcionando

Checklist rápido:

1. Testar conexão no OmniRoute retorna OK.
2. Busca no painel retorna resultados (não “Sem resultados”).
3. No Qdrant Dashboard, aparecem pontos na coleção (payload + vector).
4. Resultados de chat passam a recuperar contexto mais relevante.

Sinal clássico de problema:

• Dados entram no Qdrant, mas busca do painel não retorna nada.

Causas comuns:

• Dimensão do vetor incompatível.
• Nome do vetor diferente do esperado (omniao).
• Modelo inválido/incompleto no campo de embedding.
• Provider sem credencial ativa.

---

7) O que melhorou com esta atualização

Nesta melhoria do OmniRoute:

• Suporte a embeddings de qualquer provider compatível (não só OpenAI fixo).
• Endpoint para carregar modelos de embedding na tela de configurações.
• Campo manual para modelo custom quando não aparecer na lista.
• Ajuda visual (?) com passo rápido de configuração Qdrant + OpenRouter.

---

8) Roteiro curto para seu vídeo

Sugestão de demo (3-5 minutos):

1. Mostrar problema sem Qdrant (busca simples).
2. Abrir Settings e habilitar Qdrant.
3. Configurar host/porta/collection/modelo.
4. Salvar + testar conexão.
5. Fazer Teste de busca no painel.
6. Abrir Qdrant Dashboard e mostrar ponto salvo + vetor.
7. Rodar um chat e mostrar melhoria de recuperação semântica.

Mensagem final para a galera:

• "Qdrant no OmniRoute transforma memória de palavra-chave em memória por significado."

---

9) Referências de código (para equipe técnica)

Implementado:

• UI de configuração Qdrant: src/app/(dashboard)/dashboard/settings/components/MemorySkillsTab.tsx
• Endpoint de modelos de embedding: src/app/api/settings/qdrant/embedding-models/route.ts
• Funções backend (definidas mas dormentes): src/lib/memory/qdrant.ts exporta upsertSemanticMemoryPoint, searchSemanticMemory, deleteSemanticMemoryPoint

Pendente para ativar a integração:

• Rotas API: /api/settings/qdrant/health, /api/settings/qdrant/search, /api/settings/qdrant/cleanup
• Wire-up no fluxo de chat: src/lib/memory/retrieval.ts e open-sse/handlers/chatCore.ts precisam chamar searchSemanticMemory quando Qdrant estiver habilitado nas settings
• Wire-up no save de memória: src/lib/memory/extraction.ts (ou camada equivalente) precisa chamar upsertSemanticMemoryPoint após persistir cada memória

Para o sistema de memória ativo hoje (SQLite-only), ver docs/frameworks/MEMORY.md.

---

10) Observação importante de segurança

Nunca exponha em vídeo:

• API key completa do OpenRouter.
• Tokens reais de produção.
• Endpoints internos sem proteção.

Use chaves mascaradas e ambiente de demonstração.