用途
local_faiss_mcp 旨在为 RAG 应用提供本地的向量数据库功能，可作为 MCP 服务器与 Claude、Copilot 等 AI 代理集成，实现文档的语义搜索和记忆存储。它适用于需要本地化、无外部依赖的向量检索场景。
主要能力
- 本地向量存储：使用 FAISS 进行高效的相似性搜索，无需外部依赖。
- 文档摄入：自动对文档进行分块和嵌入存储。
- 语义搜索：使用句子嵌入通过自然语言查询文档。
- 持久化存储：索引和元数据保存到磁盘。
- MCP 兼容：可与任何支持 MCP 的 AI 代理或客户端配合使用。
- 命令行工具：v0.2.0 引入
local-faiss命令，支持独立索引和搜索。 - 文档格式：原生支持 PDF、TXT、MD；通过 pandoc 支持 DOCX、HTML、EPUB 等 40+ 格式。
- 重排序：两阶段检索与重排序，提升结果质量。
- 自定义嵌入：可选择任意 Hugging Face 嵌入模型。
- MCP 提示：内置用于答案提取和摘要的提示。
使用方式
安装
推荐从 PyPI 安装：
pip install local-faiss-mcp
升级：
pip install --upgrade local-faiss-mcp
可选扩展格式支持：安装 pandoc（macOS: brew install pandoc；Linux: apt install pandoc）。
运行服务器
- 使用安装的命令：
local-faiss-mcp（需查看具体命令） - 作为 Python 模块运行：
python -m local_faiss_mcp - 开发/测试：直接运行脚本
命令行参数：
--index-dir：存储 FAISS 索引和元数据的目录（默认当前目录）--embed：Hugging Face 嵌入模型名称（默认all-MiniLM-L6-v2）--rerank：启用重排序并指定交叉编码器模型（默认BAAI/bge-reranker-base）
可用工具
ingest_document：将文档摄入向量存储。参数：document（必需，文本内容或文件路径）、source（可选，文档来源标识，默认 "unknown"）。自动检测文件路径并解析。query_rag_store：查询向量存储以获取相关文档块。参数：query（必需，搜索查询文本）、top_k（可选，返回结果数量，默认 3）。
可用提示
extract-answer：从检索到的文档块中提取最相关的答案并附上引用。参数：query、chunks（JSON 数组，包含text、source、distance字段）。summarize：从多个文档块中创建聚焦的摘要。参数：topic、chunks、max_length（可选，默认 200 词）。
命令行接口
local-faiss CLI 提供独立文档索引和搜索：
- 索引文档：
local-faiss index <路径>（支持 glob 模式和递归文件夹） - 搜索：
local-faiss search <查询> - 配置自动从
./.mcp.json、~/.claude/.mcp.json或~/.mcp.json读取，若无则创建默认配置。 - 增量索引，不覆盖已有索引，显示进度。
MCP 客户端配置
在 Claude Code 的 .mcp.json 中添加服务器配置（示例见官方文本）。支持用户级、项目级配置，可自定义索引目录、嵌入模型和重排序。
技术细节
- 嵌入模型：默认
all-MiniLM-L6-v2（384 维），支持任意 Hugging Face sentence-transformers 模型，自动检测维度，模型选择与索引一同持久化。 - 索引类型：FAISS IndexFlatL2，精确 L2 距离搜索。
- 分块：文档分割为约 500 词块，重叠 50 词。
- 存储：索引保存为
faiss.index，元数据保存为metadata.json。
适用场景
- 为 AI 代理提供本地文档记忆和语义搜索。
- 构建基于本地文档的 RAG 问答系统。
- 需要无外部依赖、隐私保护的向量检索应用。
限制
- 需自行安装和配置依赖（如 pandoc 用于扩展格式）。
- 索引创建后需使用相同嵌入模型，否则维度不匹配会警告。
- 其他限制暂未提供。
