Vibe Search API: Motor de Busca Semântica para Turismo

Uma API de busca inteligente projetada para melhorar a forma como usuários fazem buscas, usando como contexto experiências turísticas na Bahia. Em vez de depender de filtros rígidos e palavras-chaves, o sistema compreende a intenção em linguagem natural do usuário (ex: "quero relaxar na água quente sem fazer esforço") e retorna os roteiros mais coerentes.

Arquitetura de Produção: Two-Stage Retrieval

Para garantir latência baixa e precisão absoluta na recuperação de informações (evitando o fenômeno de alucinação comum em LLMs generativos), este projeto utiliza o padrão Two-Stage Retrieval com modelos Open-Source rodando 100% localmente.

1. Estágio 1 (Recuperação Densa / Bi-Encoder): A query do usuário é vetorizada pelo modelo intfloat/multilingual-e5-large. O sistema implementa buscas assimétricas avançadas (utilizando os prefixos instrucionais query: e passage:) para mapear intenções curtas contra descrições longas. O banco vetorial Qdrant realiza uma busca ultra-rápida via Cosine Similarity para recuperar as top opções.

2. Estágio 2 (Re-Ranking Cirúrgico / Cross-Encoder): Os resultados pré-selecionados passam por uma lupa neural profunda (cross-encoder/mmarco-mMiniLMv2-L12-H384-v1). A IA lê a pergunta e a resposta simultaneamente, calculando a coerência exata e reordenando os resultados do melhor para o pior, eliminando falsos positivos.

3. Otimização de Hardware (MLOps): O modelo de Re-Ranking foi submetido a Quantização Dinâmica (INT8) via PyTorch, comprimindo os tensores de 32-bits para 8-bits. Isso permite que a inferência pesada do Transformer rode nativamente em CPU com altíssima performance e baixo custo de nuvem.

Tecnologias Utilizadas

• Backend Framework: FastAPI (Python)

• Vector Database: Qdrant (Containerizado via Docker)

• Machine Learning: PyTorch, Hugging Face (sentence-transformers)

• Modelos de IA (Otimizados para PT-BR):

  • Embeddings (Asymmetric Search): intfloat/multilingual-e5-large

  • Cross-Encoder (Reranker): cross-encoder/mmarco-mMiniLMv2-L12-H384-v1

Roadmap e Próximos Passos

• Busca Híbrida (Hybrid Search): Integração do algoritmo vetorial esparso (BM25) ao Qdrant. Isso permitirá que o sistema processe tanto intenções semânticas profundas ("vibe") quanto buscas exatas por palavras-chave ("Cachoeira da Fumaça") simultaneamente, somando os scores para entregar o resultado perfeito sem o usuário precisar escolher o tipo de busca.

• Autocomplete Leve: Criação de um endpoint dedicado para busca rápida de prefixos por título, garantindo uma UX responsiva enquanto o usuário digita na interface, acionando o motor semântico pesado apenas na busca final (no "Enter").

• Threshold de Relevância Matemático: Implementação de uma nota de corte (Score Threshold) na saída do Cross-Encoder para interceptar buscas fora de contexto (ex: "comprar notebook gamer") e devolver mensagens amigáveis de fallback, garantindo a consistência do produto.

Como Rodar o Projeto

Pré-requisitos

• Python 3.10+

• Docker (para rodar o Qdrant localmente)

Passos para Instalação

1. Suba o container do banco de dados vetorial:

docker run -p 6333:6333 -p 6334:6334 \
    -v $(pwd)/qdrant_storage:/qdrant/storage:z \
    qdrant/qdrant

2. Instale as dependências do projeto:

pip install -r requirements.txt

3. Execute a API com Uvicorn:

uvicorn main:app --reload

A API estará disponível em http://localhost:8000 e a documentação interativa (Swagger) em http://localhost:8000/docs.