Busca inteligente com IA

O CloudTasks usa busca semântica baseada em embeddings vetoriais para encontrar issues por significado, não apenas por palavras-chave.

Como funciona

Pipeline de embedding

Quando uma issue é criada ou atualizada, o sistema envia o texto {título} — {descrição} para o modelo de embedding. O modelo converte esse texto em um vetor de alta dimensão (ex: 768 dimensões para o bge-m3) que captura o significado semântico do conteúdo.

Esse vetor é armazenado na coluna embedding da tabela de issues no PostgreSQL, usando a extensão pgvector.

O processo é assíncrono — a issue é criada imediatamente e o embedding é gerado em background por uma goroutine. Isso significa que issues muito novas (menos de alguns segundos) podem não aparecer na busca semântica ainda.

Modelo de embedding

O modelo padrão é o nomic-embed-text ou bge-m3, rodando localmente via Ollama. Isso significa:

• Nenhuma chamada a APIs externas (OpenAI, Cohere, etc.)
• Dados do seu workspace nunca saem da sua infra
• Latência de embedding depende do hardware onde o Ollama roda

Busca híbrida

Quando você faz uma busca, o sistema executa dois tipos de busca em paralelo:

1. Full-text search (PostgreSQL tsvector): encontra issues com correspondência exata de palavras, incluindo stemming e stop words
2. Busca semântica (pgvector <=> cosine distance): encontra issues semanticamente similares, mesmo sem palavras em comum

Os dois conjuntos de resultados são mesclados com Reciprocal Rank Fusion (RRF), um algoritmo que combina rankings sem precisar normalizar scores diferentes.

Reranker

Após o RRF, os top-N resultados passam por um reranker — um modelo cross-encoder que avalia a relevância de cada resultado em relação à query com mais precisão do que o embedding individual. O reranker reordena os resultados finais para máxima precisão.

O que é indexado

• Título da issue (peso maior)
• Descrição em Markdown (texto extraído, sem formatação)

Campos como status, prioridade, responsável e etiquetas não são indexados semanticamente — para filtrar por esses campos, use os filtros da barra de filtros.

Disponibilidade

A busca semântica está disponível nos planos Profissional e Empresarial. No plano Gratuito e em instâncias self-hosted sem Ollama configurado, a busca usa apenas full-text.

Você pode verificar se a busca semântica está ativa em Configurações da organização → Integrações → Busca IA.

Configuração em self-hosting

Para ativar a busca semântica em uma instância self-hosted:

1. Instale o Ollama: curl -fsSL https://ollama.com/install.sh | sh
2. Baixe o modelo: ollama pull nomic-embed-text
3. Configure a variável de ambiente: OLLAMA_URL=http://localhost:11434
4. Reinicie o backend

O backend verifica a conexão com o Ollama na inicialização e loga um aviso se não conseguir conectar. A aplicação inicia normalmente — apenas a busca semântica fica degradada para full-text.

Performance

Em produção com hardware típico (CPU):

• Latência de embedding por issue: ~50–200ms (CPU), ~5–20ms (GPU)
• Latência de busca: <100ms para full-text, <300ms para busca híbrida com até 10.000 issues
• O reranker adiciona ~50–100ms para os top-10 resultados

Para workspaces com mais de 50.000 issues, considere adicionar um índice HNSW no pgvector:

CREATE INDEX ON issues USING hnsw (embedding vector_cosine_ops);