Local FAISS

Sobre o armazenamento de vetores Local FAISS como um servidor MCP – RAG local plug-and-play para Claude / Copilot / Agentes.

GitHub
33
Experimente este MCPPatrocinado

Documentação

Servidor MCP Local FAISS

License: MIT Python 3.10+ Tests PyPI version

Um servidor Model Context Protocol (MCP) que fornece funcionalidade de banco de dados vetorial local usando FAISS para aplicações de Geração Aumentada por Recuperação (RAG).

demo

Recursos

Capacidades Principais

  • Armazenamento Vetorial Local: Usa FAISS para busca eficiente de similaridade sem dependências externas
  • Ingestão de Documentos: Divide e incorpora documentos automaticamente para armazenamento
  • Busca Semântica: Consulte documentos usando linguagem natural com embeddings de frases
  • Armazenamento Persistente: Índices e metadados são salvos em disco
  • Compatível com MCP: Funciona com qualquer agente ou cliente de IA compatível com MCP

Destaques da v0.2.0

  • Ferramenta CLI: comando local-faiss para indexação e busca independentes
  • Formatos de Documento: Suporte nativo a PDF/TXT/MD, DOCX/HTML/EPUB com pandoc
  • Re-classificação: Recuperação e re-classificação em dois estágios para melhores resultados
  • Embeddings Personalizados: Escolha qualquer modelo de embedding da Hugging Face
  • Prompts MCP: Prompts integrados para extração de respostas e sumarização

Início Rápido

# Install
pip install local-faiss-mcp

# Index documents
local-faiss index document.pdf

# Search
local-faiss search "What is this document about?"

Ou use com Claude Code - configure o cliente MCP (veja Configuração) e tente:

Use the ingest_document tool with: ./path/to/document.pdf
Then use query_rag_store to search for: "How does FAISS perform similarity search?"

Claude recuperará trechos de documentos relevantes do seu armazenamento vetorial e os usará para responder à sua pergunta.

Instalação

⚡️ Atualizando? Execute pip install --upgrade local-faiss-mcp

Do PyPI (Recomendado)

pip install local-faiss-mcp

Opcional: Suporte a Formatos Estendidos

Para DOCX, HTML, EPUB e mais de 40 formatos adicionais, instale o pandoc:

# macOS
brew install pandoc

# Linux
sudo apt install pandoc

# Or download from: https://pandoc.org/installing.html

Nota: PDF, TXT e MD funcionam sem pandoc.

A partir do Código Fonte

git clone https://github.com/nonatofabio/local_faiss_mcp.git
cd local_faiss_mcp
pip install -e .

Uso

Executando o Servidor

Após a instalação, você pode executar o servidor de três maneiras:

1. Usando o comando instalado (mais fácil):

local-faiss-mcp --index-dir /path/to/index/directory

2. Como módulo Python:

python -m local_faiss_mcp --index-dir /path/to/index/directory

3. Para desenvolvimento/testes:

python local_faiss_mcp/server.py --index-dir /path/to/index/directory

Argumentos de Linha de Comando:

  • --index-dir: Diretório para armazenar arquivos de índice e metadados do FAISS (padrão: diretório atual)
  • --embed: Nome do modelo de embedding da Hugging Face (padrão: all-MiniLM-L6-v2)
  • --rerank: Ativar re-classificação com o modelo cross-encoder especificado (padrão: BAAI/bge-reranker-base)

Usando um Modelo de Embedding Personalizado:

# Use a larger, more accurate model
local-faiss-mcp --index-dir ./.vector_store --embed all-mpnet-base-v2

# Use a multilingual model
local-faiss-mcp --index-dir ./.vector_store --embed paraphrase-multilingual-MiniLM-L12-v2

# Use any Hugging Face sentence-transformers model
local-faiss-mcp --index-dir ./.vector_store --embed sentence-transformers/model-name

Usando Re-classificação para Melhores Resultados:

A re-classificação usa um modelo cross-encoder para reordenar os resultados do FAISS para melhorar a relevância. Essa abordagem de dois estágios "recuperar e re-classificar" é comum em sistemas de busca em produção.

# Enable re-ranking with default model (BAAI/bge-reranker-base)
local-faiss-mcp --index-dir ./.vector_store --rerank

# Use a specific re-ranking model
local-faiss-mcp --index-dir ./.vector_store --rerank cross-encoder/ms-marco-MiniLM-L-6-v2

# Combine custom embedding and re-ranking
local-faiss-mcp --index-dir ./.vector_store --embed all-mpnet-base-v2 --rerank BAAI/bge-reranker-base

Como Funciona a Re-classificação:

  1. O FAISS recupera os principais candidatos (10x mais do que o solicitado)
  2. O cross-encoder pontua cada candidato em relação à consulta
  3. Os resultados são reordenados pela pontuação de relevância
  4. Os k resultados mais relevantes são retornados

Modelos populares de re-classificação:

  • BAAI/bge-reranker-base - Bom equilíbrio (padrão)
  • cross-encoder/ms-marco-MiniLM-L-6-v2 - Rápido e eficiente
  • cross-encoder/ms-marco-TinyBERT-L-2-v2 - Muito rápido, modelo menor

O servidor irá:

  • Criar o diretório de índice se não existir
  • Carregar o índice FAISS existente de {index-dir}/faiss.index (ou criar um novo)
  • Carregar metadados de documentos de {index-dir}/metadata.json (ou criar novos)
  • Ouvir chamadas de ferramentas MCP via stdin/stdout

Ferramentas Disponíveis

O servidor fornece duas ferramentas para gerenciamento de documentos:

1. ingest_document

Ingira um documento no armazenamento vetorial.

Parâmetros:

  • document (obrigatório): Conteúdo de texto OU caminho de arquivo para ingerir
  • source (opcional): Identificador para a fonte do documento (padrão: "unknown")

Detecção automática: Se document parecer um caminho de arquivo, ele será analisado automaticamente.

Formatos suportados:

  • Nativo: TXT, MD, PDF
  • Com pandoc: DOCX, ODT, HTML, RTF, EPUB e mais de 40 formatos

Exemplos:

{
  "document": "FAISS is a library for efficient similarity search...",
  "source": "faiss_docs.txt"
}

{
  "document": "./documents/research_paper.pdf"
}

2. query_rag_store

Consulte o armazenamento vetorial para obter trechos de documentos relevantes.

Parâmetros:

  • query (obrigatório): O texto da consulta de busca
  • top_k (opcional): Número de resultados a retornar (padrão: 3)

Exemplo:

{
  "query": "How does FAISS perform similarity search?",
  "top_k": 5
}

Prompts Disponíveis

O servidor fornece prompts MCP para ajudar a extrair respostas e resumir informações de documentos recuperados:

1. extract-answer

Extraia a resposta mais relevante dos trechos de documentos recuperados com citações adequadas.

Argumentos:

  • query (obrigatório): A consulta ou pergunta original do usuário
  • chunks (obrigatório): Trechos de documentos recuperados como array JSON com campos: text, source, distance

Caso de Uso: Após consultar o armazenamento RAG, use este prompt para obter uma resposta bem formatada que cite fontes e explique a relevância.

Exemplo de fluxo de trabalho no Claude:

  1. Use a ferramenta query_rag_store para recuperar trechos relevantes
  2. Use o prompt extract-answer com a consulta e os resultados
  3. Obtenha uma resposta abrangente com citações

2. summarize-documents

Crie um resumo focado a partir de vários trechos de documentos.

Argumentos:

  • topic (obrigatório): O tópico ou tema a resumir
  • chunks (obrigatório): Trechos de documentos a resumir como array JSON
  • max_length (opcional): Comprimento máximo do resumo em palavras (padrão: 200)

Caso de Uso: Sintetize informações de vários documentos recuperados em um resumo conciso.

Exemplo de Uso:

No Claude Code, após recuperar documentos com query_rag_store, você pode usar os prompts como:

Use the extract-answer prompt with:
- query: "What is FAISS?"
- chunks: [the JSON results from query_rag_store]

Os prompts guiarão o LLM a fornecer respostas estruturadas e com citações com base nos dados do seu armazenamento vetorial.

Interface de Linha de Comando

A CLI local-faiss fornece recursos independentes de indexação e busca de documentos.

Comando de Indexação

Indexe documentos a partir da linha de comando:

# Index single file
local-faiss index document.pdf

# Index multiple files
local-faiss index doc1.pdf doc2.txt doc3.md

# Index all files in folder
local-faiss index documents/

# Index recursively
local-faiss index -r documents/

# Index with glob pattern
local-faiss index "docs/**/*.pdf"

Configuração: A CLI usa automaticamente a configuração MCP de:

  1. ./.mcp.json (local/específico do projeto)
  2. ~/.claude/.mcp.json (configuração do Claude Code)
  3. ~/.mcp.json (fallback)

Se não existir configuração, cria ./.mcp.json com configurações padrão (./.vector_store).

Formatos suportados:

  • Nativo: TXT, MD, PDF (sempre disponível)
  • Com pandoc: DOCX, ODT, HTML, RTF, EPUB, etc.
    • Instale: brew install pandoc (macOS) ou apt install pandoc (Linux)

Comando de Busca

Busque nos documentos indexados:

# Basic search
local-faiss search "What is FAISS?"

# Get more results
local-faiss search -k 5 "similarity search algorithms"

Os resultados mostram:

  • Caminho do arquivo de origem
  • Pontuação de distância do FAISS
  • Pontuação de re-classificação (se ativada na configuração MCP)
  • Pré-visualização do texto (primeiros 300 caracteres)

Recursos da CLI

  • ✅ Indexação incremental: Adiciona ao índice existente, não sobrescreve
  • ✅ Saída de progresso: Mostra o progresso da indexação para cada arquivo
  • ✅ Configuração compartilhada: Usa as mesmas configurações do servidor MCP
  • ✅ Detecção automática: Suporta padrões glob e pastas recursivas
  • ✅ Suporte a formatos: Lida com PDF, TXT, MD nativamente; DOCX+ com pandoc

Configuração com Clientes MCP

Claude Code

Adicione este servidor à sua configuração MCP do Claude Code (.mcp.json):

Configuração para todos os usuários (~/.claude/.mcp.json):

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp"
    }
  }
}

Com diretório de índice personalizado:

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "/home/user/vector_indexes/my_project"
      ]
    }
  }
}

Com modelo de embedding personalizado:

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "./.vector_store",
        "--embed",
        "all-mpnet-base-v2"
      ]
    }
  }
}

Com re-classificação ativada:

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "./.vector_store",
        "--rerank"
      ]
    }
  }
}

Configuração completa com embedding e re-classificação:

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "./.vector_store",
        "--embed",
        "all-mpnet-base-v2",
        "--rerank",
        "BAAI/bge-reranker-base"
      ]
    }
  }
}

Configuração específica do projeto (./.mcp.json no seu projeto):

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": [
        "--index-dir",
        "./.vector_store"
      ]
    }
  }
}

Alternativa: Usando módulo Python (se o comando não estiver no PATH):

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "python",
      "args": ["-m", "local_faiss_mcp", "--index-dir", "./.vector_store"]
    }
  }
}

Claude Desktop

Adicione este servidor à sua configuração do Claude Desktop:

{
  "mcpServers": {
    "local-faiss-mcp": {
      "command": "local-faiss-mcp",
      "args": ["--index-dir", "/path/to/index/directory"]
    }
  }
}

Arquitetura

  • Modelo de Embedding: Configurável via flag --embed (padrão: all-MiniLM-L6-v2 com 384 dimensões)
    • Suporta qualquer modelo sentence-transformers da Hugging Face
    • Detecta automaticamente as dimensões do embedding
    • A escolha do modelo é persistida com o índice
  • Tipo de Índice: FAISS IndexFlatL2 para busca exata por distância L2
  • Divisão em trechos: Documentos são divididos em trechos de ~500 palavras com sobreposição de 50 palavras
  • Armazenamento: Índice salvo como faiss.index, metadados salvos como metadata.json

Escolhendo um Modelo de Embedding

Diferentes modelos oferecem diferentes compensações:

ModeloDimensõesVelocidadeQualidadeCaso de Uso
all-MiniLM-L6-v2384RápidoBomPadrão, desempenho equilibrado
all-mpnet-base-v2768MédioMelhorEmbeddings de maior qualidade
paraphrase-multilingual-MiniLM-L12-v2384RápidoBomSuporte multilíngue
all-MiniLM-L12-v2384MédioMelhorMelhor qualidade no mesmo tamanho

Importante: Depois de criar um índice com um modelo específico, você deve usar o mesmo modelo nas execuções subsequentes. O servidor detectará incompatibilidades de dimensão e avisará você.

Desenvolvimento

Teste Independente

Teste a funcionalidade do armazenamento vetorial FAISS sem a infraestrutura MCP:

source venv/bin/activate
python test_standalone.py

Este teste:

  • Inicializa o armazenamento vetorial
  • Ingere documentos de exemplo
  • Realiza consultas de busca semântica
  • Testa persistência e recarregamento
  • Limpa arquivos de teste

Testes Unitários

Execute a suíte de testes completa:

pytest tests/ -v

Execute arquivos de teste específicos:

# Test embedding model functionality
pytest tests/test_embedding_models.py -v

# Run standalone integration test
python tests/test_standalone.py

A suíte de testes inclui:

  • test_embedding_models.py: Testes abrangentes para modelos de embedding personalizados, detecção de dimensões e compatibilidade
  • test_standalone.py: Teste de integração de ponta a ponta sem infraestrutura MCP

Licença

MIT