Local FAISS

Acerca del almacén de vectores Local FAISS como servidor MCP – RAG local plug-and-play para Claude / Copilot / Agentes.

GitHub
33
Prueba este MCPPatrocinado

Documentación

Servidor MCP Local FAISS

License: MIT Python 3.10+ Tests PyPI version

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona funcionalidad de base de datos vectorial local utilizando FAISS para aplicaciones de Generación Aumentada por Recuperación (RAG).

demo

Características

Capacidades Principales

  • Almacenamiento Vectorial Local: Utiliza FAISS para búsqueda de similitud eficiente sin dependencias externas
  • Ingesta de Documentos: Divide y embebe documentos automáticamente para su almacenamiento
  • Búsqueda Semántica: Consulta documentos usando lenguaje natural con embeddings de oraciones
  • Almacenamiento Persistente: Los índices y metadatos se guardan en disco
  • Compatible con MCP: Funciona con cualquier agente o cliente de IA compatible con MCP

Novedades de v0.2.0

  • Herramienta CLI: Comando local-faiss para indexación y búsqueda independiente
  • Formatos de Documentos: Soporte nativo para PDF/TXT/MD, DOCX/HTML/EPUB con pandoc
  • Re-clasificación: Recuperación y re-clasificación en dos etapas para mejores resultados
  • Embeddings Personalizados: Elige cualquier modelo de embeddings de Hugging Face
  • Prompts MCP: Prompts integrados para extracción de respuestas y resúmenes

Inicio Rápido

# Install
pip install local-faiss-mcp

# Index documents
local-faiss index document.pdf

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

O úsalo con Claude Code: configura el cliente MCP (ver Configuración) y prueba:

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á los fragmentos de documentos relevantes de tu almacén vectorial y los usará para responder tu pregunta.

Instalación

⚡️ ¿Actualizando? Ejecuta pip install --upgrade local-faiss-mcp

Desde PyPI (Recomendado)

pip install local-faiss-mcp

Opcional: Soporte de Formatos Extendidos

Para DOCX, HTML, EPUB y más de 40 formatos adicionales, instala pandoc:

# macOS
brew install pandoc

# Linux
sudo apt install pandoc

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

Nota: PDF, TXT y MD funcionan sin pandoc.

Desde el Código Fuente

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

Uso

Ejecutando el Servidor

Después de la instalación, puedes ejecutar el servidor de tres maneras:

1. Usando el comando instalado (más fácil):

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

2. Como módulo de Python:

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

3. Para desarrollo/pruebas:

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

Argumentos de línea de comandos:

  • --index-dir: Directorio para almacenar el índice FAISS y archivos de metadatos (predeterminado: directorio actual)
  • --embed: Nombre del modelo de embeddings de Hugging Face (predeterminado: all-MiniLM-L6-v2)
  • --rerank: Habilita la re-clasificación con el modelo cross-encoder especificado (predeterminado: BAAI/bge-reranker-base)

Usando un Modelo de Embeddings 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-clasificación para Mejores Resultados:

La re-clasificación usa un modelo cross-encoder para reordenar los resultados de FAISS y mejorar la relevancia. Este enfoque de "recuperar y re-clasificar" en dos etapas es común en sistemas de búsqueda de producción.

# 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

Cómo Funciona la Re-clasificación:

  1. FAISS recupera los mejores candidatos (10 veces más de lo solicitado)
  2. El cross-encoder puntúa cada candidato contra la consulta
  3. Los resultados se reordenan por puntuación de relevancia
  4. Se devuelven los top-k resultados más relevantes

Modelos de re-clasificación populares:

  • BAAI/bge-reranker-base - Buen equilibrio (predeterminado)
  • cross-encoder/ms-marco-MiniLM-L-6-v2 - Rápido y eficiente
  • cross-encoder/ms-marco-TinyBERT-L-2-v2 - Muy rápido, modelo más pequeño

El servidor:

  • Creará el directorio de índice si no existe
  • Cargará el índice FAISS existente desde {index-dir}/faiss.index (o creará uno nuevo)
  • Cargará los metadatos de documentos desde {index-dir}/metadata.json (o creará nuevos)
  • Escuchará llamadas de herramientas MCP a través de stdin/stdout

Herramientas Disponibles

El servidor proporciona dos herramientas para la gestión de documentos:

1. ingest_document

Ingesta un documento en el almacén vectorial.

Parámetros:

  • document (obligatorio): Contenido de texto O ruta de archivo a ingestar
  • source (opcional): Identificador para la fuente del documento (predeterminado: "desconocido")

Detección automática: Si document parece una ruta de archivo, se analizará automáticamente.

Formatos soportados:

  • Nativos: TXT, MD, PDF
  • Con pandoc: DOCX, ODT, HTML, RTF, EPUB y más de 40 formatos

Ejemplos:

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

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

2. query_rag_store

Consulta el almacén vectorial para obtener fragmentos de documentos relevantes.

Parámetros:

  • query (obligatorio): El texto de la consulta de búsqueda
  • top_k (opcional): Número de resultados a devolver (predeterminado: 3)

Ejemplo:

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

Prompts Disponibles

El servidor proporciona prompts MCP para ayudar a extraer respuestas y resumir información de los documentos recuperados:

1. extract-answer

Extrae la respuesta más relevante de los fragmentos de documentos recuperados con citas adecuadas.

Argumentos:

  • query (obligatorio): La consulta o pregunta original del usuario
  • chunks (obligatorio): Fragmentos de documentos recuperados como matriz JSON con campos: text, source, distance

Caso de uso: Después de consultar el almacén RAG, usa este prompt para obtener una respuesta bien formateada que cite fuentes y explique la relevancia.

Flujo de trabajo de ejemplo en Claude:

  1. Usa la herramienta query_rag_store para recuperar fragmentos relevantes
  2. Usa el prompt extract-answer con la consulta y los resultados
  3. Obtén una respuesta completa con citas

2. summarize-documents

Crea un resumen enfocado a partir de múltiples fragmentos de documentos.

Argumentos:

  • topic (obligatorio): El tema o tema a resumir
  • chunks (obligatorio): Fragmentos de documentos a resumir como matriz JSON
  • max_length (opcional): Longitud máxima del resumen en palabras (predeterminado: 200)

Caso de uso: Sintetiza información de múltiples documentos recuperados en un resumen conciso.

Ejemplo de uso:

En Claude Code, después de recuperar documentos con query_rag_store, puedes usar los prompts así:

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

Los prompts guiarán al LLM para proporcionar respuestas estructuradas y respaldadas por citas basadas en los datos de tu almacén vectorial.

Interfaz de Línea de Comandos

El CLI local-faiss proporciona capacidades independientes de indexación y búsqueda de documentos.

Comando de Indexación

Indexa documentos desde la línea de comandos:

# 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"

Configuración: El CLI usa automáticamente la configuración de MCP desde:

  1. ./.mcp.json (local/específico del proyecto)
  2. ~/.claude/.mcp.json (configuración de Claude Code)
  3. ~/.mcp.json (respaldo)

Si no existe configuración, crea ./.mcp.json con la configuración predeterminada (./.vector_store).

Formatos soportados:

  • Nativos: TXT, MD, PDF (siempre disponibles)
  • Con pandoc: DOCX, ODT, HTML, RTF, EPUB, etc.
    • Instalación: brew install pandoc (macOS) o apt install pandoc (Linux)

Comando de Búsqueda

Busca en los documentos indexados:

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

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

Los resultados muestran:

  • Ruta del archivo fuente
  • Puntuación de distancia FAISS
  • Puntuación de re-clasificación (si está habilitada en la configuración de MCP)
  • Vista previa del texto (primeros 300 caracteres)

Características del CLI

  • ✅ Indexación incremental: Añade al índice existente, no sobrescribe
  • ✅ Salida de progreso: Muestra el progreso de indexación para cada archivo
  • ✅ Configuración compartida: Usa la misma configuración que el servidor MCP
  • ✅ Detección automática: Soporta patrones glob y carpetas recursivas
  • ✅ Soporte de formatos: Maneja PDF, TXT, MD nativamente; DOCX+ con pandoc

Configuración con Clientes MCP

Claude Code

Añade este servidor a tu configuración MCP de Claude Code (.mcp.json):

Configuración para todos los usuarios (~/.claude/.mcp.json):

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

Con directorio de índice personalizado:

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

Con modelo de embeddings personalizado:

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

Con re-clasificación habilitada:

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

Configuración completa con embeddings y re-clasificación:

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

Configuración específica del proyecto (./.mcp.json en tu proyecto):

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

Alternativa: Usando el módulo de Python (si el comando no está en PATH):

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

Claude Desktop

Añade este servidor a tu configuración de Claude Desktop:

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

Arquitectura

  • Modelo de Embeddings: Configurable mediante la bandera --embed (predeterminado: all-MiniLM-L6-v2 con 384 dimensiones)
    • Soporta cualquier modelo de sentence-transformers de Hugging Face
    • Detecta automáticamente las dimensiones de los embeddings
    • La elección del modelo se persiste con el índice
  • Tipo de Índice: FAISS IndexFlatL2 para búsqueda exacta de distancia L2
  • División en Fragmentos: Los documentos se dividen en fragmentos de ~500 palabras con superposición de 50 palabras
  • Almacenamiento: El índice se guarda como faiss.index, los metadatos se guardan como metadata.json

Elegir un Modelo de Embeddings

Diferentes modelos ofrecen diferentes compensaciones:

ModeloDimensionesVelocidadCalidadCaso de Uso
all-MiniLM-L6-v2384RápidoBuenaPredeterminado, rendimiento equilibrado
all-mpnet-base-v2768MediaMejorEmbeddings de mayor calidad
paraphrase-multilingual-MiniLM-L12-v2384RápidoBuenaSoporte multilingüe
all-MiniLM-L12-v2384MediaMejorMejor calidad al mismo tamaño

Importante: Una vez que creas un índice con un modelo específico, debes usar el mismo modelo para ejecuciones posteriores. El servidor detectará discrepancias de dimensiones y te advertirá.

Desarrollo

Prueba Independiente

Prueba la funcionalidad del almacén vectorial FAISS sin infraestructura MCP:

source venv/bin/activate
python test_standalone.py

Esta prueba:

  • Inicializa el almacén vectorial
  • Ingiesta documentos de muestra
  • Realiza consultas de búsqueda semántica
  • Prueba la persistencia y recarga
  • Limpia los archivos de prueba

Pruebas Unitarias

Ejecuta el conjunto completo de pruebas:

pytest tests/ -v

Ejecuta archivos de prueba específicos:

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

# Run standalone integration test
python tests/test_standalone.py

El conjunto de pruebas incluye:

  • test_embedding_models.py: Pruebas completas para modelos de embeddings personalizados, detección de dimensiones y compatibilidad
  • test_standalone.py: Prueba de integración de extremo a extremo sin infraestructura MCP

Licencia

MIT