bm25s

环境要求

• Python 环境（README 未指定最低版本，建议 3.9+）
• pip 或 uv 包管理工具
• 如需 MCP 服务接入 Claude Desktop，需安装 uv 并准备好本地索引目录
• 如需低内存检索，磁盘可存放导出的索引文件

安装与启动步骤

1. 1安装 bm25s

   用 pip 安装 bm25s 本体，这是最小安装，只包含 numpy 等最基础依赖。

   pip install bm25s

   复制

2. 2安装核心依赖

   README 强烈推荐，包含 json 加载、进度条、词干提取与 JIT 编译等核心能力。

   pip install "bm25s[core]"

   复制

3. 3可选安装词干提取

   如果只想用词干提取提升检索效果，可单独安装 PyStemmer。

   pip install PyStemmer

   复制

4. 4可选安装全部扩展

   安装所有额外依赖，体积更大但功能最全；也可单独装 CLI 扩展获得彩色交互选择器。

   pip install "bm25s[full]"
   pip install "bm25s[cli]"

   复制

5. 5验证导入

   导入 bm25s 不报错即表示库安装成功；若失败请检查 Python 环境与 pip 版本。

   python -c "import bm25s"

   复制

6. 6加载索引检索

   用 BM25HF 从 Hugging Face Hub 加载索引与语料，mmap=True 走内存映射以显著降低内存占用。

   import bm25s
   import Stemmer  # optional: for stemming
   
   retriever = bm25s.BM25HF.load_from_hub(
       f"{user}/bm25s-animals", load_corpus=True, mmap=True
   )

   复制

7. 7配置 MCP 服务

   先安装 mcp 扩展，再把配置写入 Claude Desktop 的 claude_desktop_config.json，路径需全部替换为绝对路径。

   uv pip install "bm25s[mcp]"

   复制

关键配置

如何确认成功

终端执行 python -c "import bm25s" 无报错即安装成功；能加载他人共享的 BM25HF 索引并返回检索结果说明可用。

常见问题

注意事项

• README 的 Quickstart 代码片段不完整，完整 API 用法请参考官网 bm25s.github.io 与仓库示例目录。
• f"{user}/bm25s-animals" 中的 {user} 需替换为实际的 Hugging Face 用户或组织名。
• 磁盘占用参考：仅 bm25s 约 51MB，安装 bm25s[core] 约 188MB，远小于 pyserini（约 6976MB）。
• MCP 配置中的目录与 uv 路径必须写成绝对路径，克隆到哪就以哪为准。