金大哥 - local_faiss

article

README

🚀 本地FAISS MCP服务器

本地FAISS MCP服务器是一个基于Model Context Protocol（MCP）的服务器，它使用FAISS提供本地向量数据库功能，适用于检索增强生成（RAG）应用程序。该服务器可以独立运行，也可以与任何MCP兼容的AI代理或客户端集成，为用户提供高效的文档索引和搜索服务。

🚀 快速开始

# 安装
pip install local-faiss-mcp

# 索引文档
local-faiss index document.pdf

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

或者与Claude Code一起使用 - 配置MCP客户端（请参阅与MCP客户端的配置）并尝试：

使用ingest_document工具处理：./path/to/document.pdf
然后使用query_rag_store搜索："How does FAISS perform similarity search?"

Claude将从你的向量存储中检索相关的文档块，并使用它们来回答你的问题。

✨ 主要特性

核心功能

本地向量存储：使用FAISS进行高效的相似性搜索，无需外部依赖。
文档摄取：自动对文档进行分块和嵌入，以便存储。
语义搜索：使用自然语言和句子嵌入进行文档查询。
持久存储：将索引和元数据保存到磁盘。
MCP兼容性：可与任何MCP兼容的AI代理或客户端配合使用。

v0.2.0亮点

CLI工具：提供local-faiss命令，用于独立的索引和搜索。
文档格式：原生支持PDF/TXT/MD格式，通过pandoc支持DOCX/HTML/EPUB等格式。
重新排序：采用两阶段的检索和重新排序，以获得更好的结果。
自定义嵌入：可选择任何Hugging Face嵌入模型。
MCP提示：内置用于答案提取和摘要的提示。

📦 安装指南

⚡️ 升级？ 运行 pip install --upgrade local-faiss-mcp

从PyPI安装（推荐）

pip install local-faiss-mcp

可选：扩展格式支持

对于DOCX、HTML、EPUB等40多种格式，需要安装pandoc：

# macOS
brew install pandoc

# Linux
sudo apt install pandoc

# 或者从以下网址下载：https://pandoc.org/installing.html

注意：PDF、TXT和MD格式无需pandoc即可使用。

从源代码安装

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

💻 使用示例

运行服务器

安装完成后，你可以通过以下三种方式运行服务器：

1. 使用已安装的命令（最简单）：

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

2. 作为Python模块运行：

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

3. 用于开发/测试：

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

命令行参数：

--index-dir：存储FAISS索引和元数据文件的目录（默认：当前目录）
--embed：Hugging Face嵌入模型名称（默认：all-MiniLM-L6-v2）
--rerank：启用使用指定交叉编码器模型的重新排序（默认：BAAI/bge-reranker-base）

使用自定义嵌入模型：

# 使用更大、更准确的模型
local-faiss-mcp --index-dir ./.vector_store --embed all-mpnet-base-v2

# 使用多语言模型
local-faiss-mcp --index-dir ./.vector_store --embed paraphrase-multilingual-MiniLM-L12-v2

# 使用任何Hugging Face句子转换器模型
local-faiss-mcp --index-dir ./.vector_store --embed sentence-transformers/model-name

使用重新排序以获得更好的结果：

重新排序使用交叉编码器模型对FAISS结果进行重新排序，以提高相关性。这种两阶段的“检索和重新排序”方法在生产搜索系统中很常见。

# 使用默认模型（BAAI/bge-reranker-base）启用重新排序
local-faiss-mcp --index-dir ./.vector_store --rerank

# 使用特定的重新排序模型
local-faiss-mcp --index-dir ./.vector_store --rerank cross-encoder/ms-marco-MiniLM-L-6-v2

# 结合自定义嵌入和重新排序
local-faiss-mcp --index-dir ./.vector_store --embed all-mpnet-base-v2 --rerank BAAI/bge-reranker-base

重新排序的工作原理：

FAISS检索出比请求数量多10倍的顶级候选者。
交叉编码器对每个候选者与查询进行评分。
根据相关性得分对结果进行重新排序。
返回前k个最相关的结果。

流行的重新排序模型：

BAAI/bge-reranker-base - 平衡性能（默认）
cross-encoder/ms-marco-MiniLM-L-6-v2 - 快速高效
cross-encoder/ms-marco-TinyBERT-L-2-v2 - 非常快，模型较小

服务器将：

如果索引目录不存在，则创建该目录。
从{index-dir}/faiss.index加载现有的FAISS索引（或创建一个新的）。
从{index-dir}/metadata.json加载文档元数据（或创建新的）。
通过stdin/stdout监听MCP工具调用。

可用工具

服务器提供两个用于文档管理的工具：

1. ingest_document

将文档摄取到向量存储中。

参数：

document（必需）：要摄取的文本内容或文件路径。
source（可选）：文档来源的标识符（默认："unknown"）。

自动检测：如果document看起来像文件路径，将自动解析。

支持的格式：

原生：TXT、MD、PDF
使用pandoc：DOCX、ODT、HTML、RTF、EPUB等40多种格式

示例：

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

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

2. query_rag_store

查询向量存储以获取相关的文档块。

参数：

query（必需）：搜索查询文本。
top_k（可选）：返回的结果数量（默认：3）。

示例：

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

可用提示

服务器提供MCP提示，帮助从检索到的文档中提取答案和总结信息：

1. extract-answer

从检索到的文档块中提取最相关的答案，并提供适当的引用。

参数：

query（必需）：原始用户查询或问题。
chunks（必需）：检索到的文档块，作为JSON数组，包含字段：text、source、distance。

用例：查询RAG存储后，使用此提示获取格式良好的答案，引用来源并解释相关性。

在Claude中的示例工作流程：

使用query_rag_store工具检索相关块。
使用extract-answer提示处理查询和结果。
获取带有引用和解释的全面答案。

2. summarize-documents

从多个文档块中创建聚焦的摘要。

参数：

topic（必需）：要总结的主题或主题。
chunks（必需）：要总结的文档块，作为JSON数组。
max_length（可选）：摘要的最大长度（默认：200）。

用例：将从多个检索到的文档中合成信息，形成简洁的摘要。

示例用法：

在Claude Code中，使用query_rag_store检索文档后，可以使用以下提示：

使用extract-answer提示处理：
- query: "What is FAISS?"
- chunks: [query_rag_store的JSON结果]

这些提示将引导大语言模型根据你的向量存储数据提供结构化、有引用支持的答案。

命令行界面

local-faiss CLI提供独立的文档索引和搜索功能。

索引命令

从命令行索引文档：

# 索引单个文件
local-faiss index document.pdf

# 索引多个文件
local-faiss index doc1.pdf doc2.txt doc3.md

# 索引文件夹中的所有文件
local-faiss index documents/

# 递归索引
local-faiss index -r documents/

# 使用通配符模式索引
local-faiss index "docs/**/*.pdf"

配置：CLI自动使用以下位置的MCP配置：

./.mcp.json（本地/项目特定）
~/.claude/.mcp.json（Claude Code配置）
~/.mcp.json（备用）

如果没有配置文件，将创建./.mcp.json，使用默认设置（./.vector_store）。

支持的格式：

原生：TXT、MD、PDF（始终可用）
使用pandoc：DOCX、ODT、HTML、RTF、EPUB等。
- 安装：brew install pandoc（macOS）或apt install pandoc（Linux）

搜索命令

搜索已索引的文档：

# 基本搜索
local-faiss search "What is FAISS?"

# 获取更多结果
local-faiss search -k 5 "similarity search algorithms"

结果显示：

源文件路径
FAISS距离得分
重新排序得分（如果在MCP配置中启用）
文本预览（前300个字符）

CLI特性

✅ 增量索引：添加到现有索引，不覆盖。
✅ 进度输出：显示每个文件的索引进度。
✅ 共享配置：使用与MCP服务器相同的设置。
✅ 自动检测：支持通配符模式和递归文件夹。
✅ 格式支持：原生处理PDF、TXT、MD；使用pandoc支持DOCX等。

📚 详细文档

与MCP客户端的配置

Claude Code

将此服务器添加到你的Claude Code MCP配置（.mcp.json）中：

用户范围配置 (~/.claude/.mcp.json)：

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

使用自定义索引目录：

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

使用自定义嵌入模型：

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

启用重新排序：

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

完整配置，包含嵌入和重新排序：

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

项目特定配置 (./.mcp.json 在你的项目中)：

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

替代方法：使用Python模块（如果命令不在PATH中）：

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

Claude Desktop

将此服务器添加到你的Claude Desktop配置中：

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

🔧 技术细节

架构

嵌入模型：可通过--embed标志配置（默认：all-MiniLM-L6-v2，384维）。
- 支持任何Hugging Face句子转换器模型。
- 自动检测嵌入维度。
- 模型选择与索引一起持久化。
索引类型：FAISS IndexFlatL2，用于精确的L2距离搜索。
分块：将文档分割成约500个单词的块，重叠50个单词。
存储：索引保存为faiss.index，元数据保存为metadata.json。

选择嵌入模型

不同的模型有不同的权衡：

| 模型 | 维度 | 速度 | 质量 | 使用场景 | |-------|-----------|-------|---------|----------| | all-MiniLM-L6-v2 | 384 | 快 | 好 | 默认，平衡性能 | | all-mpnet-base-v2 | 768 | 中等 | 更好 | 更高质量的嵌入 | | paraphrase-multilingual-MiniLM-L12-v2 | 384 | 快 | 好 | 多语言支持 | | all-MiniLM-L12-v2 | 384 | 中等 | 更好 | 相同大小下更好的质量 |

重要提示：一旦使用特定模型创建了索引，后续运行必须使用相同的模型。服务器将检测维度不匹配并发出警告。

开发

独立测试

在不使用MCP基础设施的情况下测试FAISS向量存储功能：

source venv/bin/activate
python test_standalone.py

此测试：

初始化向量存储。
摄取示例文档。
执行语义搜索查询。
测试持久性和重新加载。
清理测试文件。

单元测试

运行完整的测试套件：

pytest tests/ -v

运行特定的测试文件：

# 测试嵌入模型功能
pytest tests/test_embedding_models.py -v

# 运行独立集成测试
python tests/test_standalone.py

测试套件包括：

test_embedding_models.py：对自定义嵌入模型、维度检测和兼容性进行全面测试。
test_standalone.py：不使用MCP基础设施的端到端集成测试。

📄 许可证

本项目采用MIT许可证。

local_faiss_mcp

README

🚀 本地FAISS MCP服务器

🚀 快速开始

✨ 主要特性

核心功能

v0.2.0亮点

📦 安装指南

从PyPI安装（推荐）

可选：扩展格式支持

从源代码安装

💻 使用示例

运行服务器

可用工具

1. ingest_document

2. query_rag_store

可用提示

1. extract-answer

2. summarize-documents

命令行界面

索引命令

搜索命令

CLI特性

📚 详细文档

与MCP客户端的配置

Claude Code

Claude Desktop

🔧 技术细节

架构

选择嵌入模型

开发

独立测试

单元测试

📄 许可证

运行方式说明

托管运行

本地运行 / 其它方式