一、项目定位与适用场景

nbrag 是一个发布在 PyPI 的 Python 包，用于在本地构建文本知识库，并通过 MCP（Model Context Protocol）服务器 把该知识库的能力暴露给任意兼容 MCP 的客户端。资料来源：README.md:1-9

该项目的核心价值在于让用户完全掌控自己的语料：当需要让大模型基于内部文档、规范、手册、笔记、本地项目文档或 Python 源码进行回答时，可借助 nbrag 在本地完成向量化、检索与原文回溯，而无需把数据外送到托管型 RAG 服务。资料来源：README.md:11-19

适用场景包括：

• 索引私有或本地的文本（外部服务不可见）
• 基于自有文件构建领域知识库
• 让 MCP 客户端同时检索向量化分块与原始存储文本
• 将存储保留在本机上

需要注意：nbrag 是 text-first 的。源材料若是 PDF、Word、图片、扫描件或网页，应先转换为 .md、.txt、.html 再摄入，以获得最佳效果。资料来源：README.md:21-25

二、整体架构与数据流

nbrag 由"摄入端"与"服务端"两段组成。摄入端以 batch_ingest() 与 set_collection_profile() 写入 ChromaDB 与本地索引；服务端通过 python -m nbrag 启动 MCP 进程，向 MCP 客户端暴露检索类工具。资料来源：README.md:75-83, README.md:95-102

flowchart LR
    A[本地文本文件<br/>.md / .txt / .html] --> B[batch_ingest<br/>分块 + Embedding]
    B --> C[(ChromaDB<br/>+ 本地索引)]
    C --> D[set_collection_profile<br/>人类可读元数据]
    D --> E[python -m nbrag<br/>MCP Server]
    E -->|stdio 或 streamable-http| F[MCP Client<br/>IDE / Agent]
    F -->|工具调用| E
    E -->|检索结果 + 原文| F

三、配置体系

nbrag 的配置按以下优先级生效：CLI 参数 > 环境变量 > YAML 配置 > 默认值。资料来源：README.md:115-119

主要环境变量如下表所示：

资料来源：README.md:121-137。YAML 配置文件会自动按 ./nbrag_config.yaml、./nbrag_config.yml、~/.config/nbrag/config.yaml、~/.config/nbrag/config.yml 的顺序查找。资料来源：README.md:139-157

MCP 服务支持两种传输模式：

• stdio：一客户端对应一服务进程，适合单 IDE 窗口使用
• streamable-http：通过 --port 指定端口，多客户端可共享同一本地服务进程

资料来源：README.md:89-93, README.md:95-102

四、MCP 工具能力矩阵

服务端启动后会暴露一组以检索为核心的 MCP 工具。可按能力维度整理如下：

资料来源：README.md:119-125

五、与传统（naive）RAG 的差异

传统 RAG 通常是"一次性 retrieve top-k → 拼进 prompt"的固定管线；而 nbrag 提供了两点本质差异：

1. 知识库由用户自行准备并掌控：通过 batch_ingest() 显式摄入本地文本，配合 set_collection_profile() 补充 display_name、description、aliases、tags 等人类可读元数据，使 collection 既有稳定的机器标识（slug-like 的 collection_name），又具备良好的可发现性。资料来源：README.md:75-83, README.md:85-87
2. 检索通过 MCP 工具暴露：客户端可以在多次调用间进行搜索 → 精化 → 检视原文 → 拉取更多上下文的迭代流程，而不是单次取 top-k 后即终止。资料来源：README.md:125-131

此外，nbrag 在仓库内还附带了 nbrag/skills/ 目录，可被第三方工具的 skills 扫描器识别，复制到目标项目下即可被自动加载。资料来源：nbrag/skills/readme.md:1-1

项目以 MIT 协议开源。资料来源：README.md:191-191

See Also

• 快速开始与安装：README.md:27-31
• 摄入与集合描述 API：README.md:75-87
• 传输模式与客户端配置：README.md:89-113

概览与设计目标

nbrag 的数据接入管线负责把本地文本文件（.md、.txt、.html、以及 Python 源码）转化为可被 MCP 客户端检索的混合索引。整个管线以 nbrag/ingest.py 中的 batch_ingest() 为统一入口，按顺序完成「扫描 → 原始文件快照 → 切片 → embedding → 多索引落地」的流程（资料来源：nbrag/ingest.py:1-120）。区别于一次性的 naive RAG，nbrag 把每一步都暴露为可配置、可重建的阶段，因此同一个 collection 可以在不停服的情况下被反复重建。

主入口：`batch_ingest()`

batch_ingest() 是整条管线的总入口，参数语义如下（资料来源：README.md:60-90）：

该函数会委托 nbrag/storage.py 创建底层 ChromaDB 客户端与本地索引目录，并依次触发后续阶段。

切片与原始文件快照

切片由 nbrag/chunker.py 负责，默认配置为 chunk_size=1000、chunk_overlap=150，可通过环境变量 NBRAG_CHUNK_SIZE 与 NBRAG_CHUNK_OVERLAP 覆盖（资料来源：README.md:120-130）。为了让 MCP 工具在命中后能定位到原始上下文，nbrag/ingest.py 在切片前会先把整份文件以原文形式写入 NBRAG_RAW_FILES_PATH（默认位于 NBRAG_DB_PATH/raw_files 之下，资料来源：README.md:115-120），供 nbrag_get_raw_file、nbrag_get_file_chunks 等检索后回溯使用。

Embedding 与向量索引

向量侧的 embedding 由 nbrag/embeddings.py 调用 OpenAI 兼容接口完成，默认 base_url 指向 SiliconFlow、默认模型为 BAAI/bge-m3（资料来源：README.md:105-115）。切片得到的文本块经 embedding 后写入 ChromaDB 集合，配合 BAAI/bge-reranker-v2-m3 重新排序模型支撑 nbrag_search 与 nbrag_search_and_fetch 工具。

BM25 与符号索引

为了支持精确文本检索与 Python 源码场景，管线并行维护两套辅助索引：

• nbrag/bm25_index.py 构建词法索引，驱动 nbrag_search_only_bm25、nbrag_search_only_vector 与 nbrag_grep（资料来源：README.md:160-185）；
• nbrag/symbol_index.py 抽取 Python 模块、类、函数等符号，配合 set_collection_profile() 的 aliases/tags 元数据，帮助客户端在代码类问题上快速收敛目标范围。

flowchart LR
    A[paths / file_extensions] --> B[raw_files 快照]
    B --> C[chunker 切片]
    C --> D[embeddings 向量]
    C --> E[bm25_index 词法]
    C --> F[symbol_index 符号]
    D --> G[(ChromaDB)]
    E --> G
    F --> G
    G --> H[MCP 检索工具]

常见失败模式

• 摄入 PDF/扫描件时未先转 .md/.txt/.html，切片质量会显著下降（资料来源：README.md:30-35）。
• 调整切片或 embedding 参数时若忘记 delete_first=True，新参数不会生效。
• API key 未设置时 embedding 阶段会直接报错，需要先 export NBRAG_API_KEY。

See Also

• 配置参考与 CLI 参数：README.md
• MCP 工具能力总览：README "MCP capabilities overview" 一节
• 集合元数据描述函数 set_collection_profile()：见 README "Why set_collection_profile() matters" 一节

1. 设计定位：与朴素 RAG 的区别

朴素 RAG 通常是固定的一次性流程：检索 top-k 个文本片段并直接拼入 prompt。nbrag 在两点上不同：

• 由用户准备并控制知识库：通过 batch_ingest() 与 set_collection_profile() 显式建立与描述 collection。
• 检索通过 MCP 工具暴露：客户端可搜索、细化、查阅原文，并按需获取更多上下文。

资料来源：README.md

2. MCP 工具能力分类

nbrag 在服务启动后暴露一组面向检索的 MCP 工具。按能力归类如下：

资料来源：README.md

3. 关键运行时参数

检索与重排效果由以下环境变量驱动，配置优先级为：CLI 参数 > 环境变量 > YAML 配置 > 默认值。资料来源：README.md

说明：上述默认值是面向中文/英文混合文本的推荐起点；当切换模型或语料类型时，优先调整 NBRAG_CHUNK_SIZE 与 NBRAG_CHUNK_OVERLAP，再观察 nbrag_search_and_fetch 的命中率。

4. 传输模式与客户端接入

nbrag 同时支持两种 MCP 传输：

``bash python -m nbrag ``

``bash python -m nbrag --transport streamable-http --port 9101 ``

• stdio：单客户端独占一个服务进程，适合 IDE 单窗口直连。
• streamable-http：多客户端/多窗口共享同一个本地服务进程，便于复用已建立的索引。

stdio 模式下，客户端配置需指向安装了 nbrag 的 Python 解释器：

{
  "mcpServers": {
    "nbrag": {
      "command": "python",
      "args": ["-m", "nbrag"],
      "env": { "NBRAG_API_KEY": "sk-xxx" }
    }
  }
}

HTTP 模式下，先启动共享服务，再将客户端指向 http://localhost:9101/mcp。资料来源：README.md

5. 常见失败模式与处理建议

• 检索不到预期片段：先调用 nbrag_list 与 nbrag_stats 确认目标 collection 存在且文档已被导入；再分别尝试 nbrag_search_only_bm25 与 nbrag_search_only_vector 区分是语义还是词法失效。
• 命中片段上下文不足：使用 nbrag_get_adjacent_chunks 或 nbrag_get_chunks_by_lines 在命中点附近扩展；如需回溯原文，调用 nbrag_get_raw_file。
• 客户端连接失败：检查 NBRAG_API_KEY 是否在客户端环境注入；HTTP 模式下确认端口与 url 字段一致。

6. 与 skills 目录的关系

nbrag/skills/readme.md 要求用户将该目录复制到自身项目下、被第三方工具认可扫描的 skills 目录中。这意味着 nbrag 的检索行为不仅由 MCP 工具本身决定，还可由随包发布的 skills 描述来引导客户端更规范地使用工具。资料来源：nbrag/skills/readme.md

See Also

• README.md — 安装、配置、客户端接入
• nbrag/mcp_tools.py — 工具实现
• nbrag/retrieval.py — 检索与重排逻辑
• nbrag/server.py — MCP 服务端与传输注册
• nbrag/defaults.py — 默认模型与路径常量

配置体系

nbrag 的配置遵循清晰的优先级链，使得同一套代码可以在不同环境下复用，资料来源：README.md:114-118。

CLI 参数 > 环境变量 > YAML 配置文件 > 内置默认值

环境变量

nbrag 默认对接 SiliconFlow 兼容的 OpenAI 风格 embedding / rerank 端点，关键环境变量整理如下，资料来源：README.md:120-130：

YAML 配置文件

YAML 是环境变量之外最常用的集中化配置方式。包在启动时会按下列顺序自动搜索，资料来源：README.md:132-137：

1. ./nbrag_config.yaml
2. ./nbrag_config.yml
3. ~/.config/nbrag/config.yaml
4. ~/.config/nbrag/config.yml

配置示例，资料来源：README.md:139-150：

embedding:
  api_key: ${NBRAG_API_KEY}
  base_url: https://api.siliconflow.cn/v1
  model: BAAI/bge-m3

rerank:
  model: BAAI/bge-reranker-v2-m3

storage:
  db_path: ./rag_db

chunking:
  chunk_size: 1000
  chunk_overlap: 150

注意 api_key 字段支持 ${NBRAG_API_KEY} 这种 shell 风格占位符，便于在不同部署环境复用同一份 YAML。config.example.yaml 提供了可复制的模板，建议在仓库中保留，资料来源：config.example.yaml。

命令行参数

python -m nbrag 同时支持 CLI 参数覆盖，常见用法包括，资料来源：README.md:152-159：

python -m nbrag --help
python -m nbrag --transport stdio
python -m nbrag --transport streamable-http --port 9101
python -m nbrag --api-key sk-xxx
python -m nbrag --db-path /data/rag
python -m nbrag --config ./nbrag_config.yaml

CLI 参数适合临时调试与 CI 中的一次性覆盖；长期运行的服务建议使用 YAML + 环境变量组合。

部署模式

nbrag 的 MCP 服务器支持两种传输模式，分别面向"一客户端一进程"和"多客户端共享进程"两种典型场景，资料来源：README.md:70-82。

flowchart LR
    A[MCP 客户端] -->|stdio| B[nbrag 进程]
    C[MCP 客户端 1] -->|HTTP| D[共享 nbrag 服务 :9101]
    E[MCP 客户端 2] -->|HTTP| D
    F[IDE 窗口 N] -->|HTTP| D

stdio 模式

适合本地单一客户端独占一个 nbrag 进程，资料来源：README.md:72-74：

python -m nbrag

该模式由客户端直接拉起子进程，环境变量需要通过客户端配置中的 env 字段注入。

HTTP 模式（streamable-http）

适合多个客户端或多个 IDE 窗口共享同一个本地服务进程，资料来源：README.md:76-82：

python -m nbrag --transport streamable-http --port 9101

服务启动后，端点暴露在 http://localhost:9101/mcp。这种模式常配合 scripts/start_http_rag_mcp.py 作为 systemd / 容器入口长期运行，而 scripts/start_local_rag_mcp.py 则适合一次性调试。

MCP 客户端连接

stdio 客户端配置示例（JSON），资料来源：README.md:86-99：

{
  "mcpServers": {
    "nbrag": {
      "command": "python",
      "args": ["-m", "nbrag"],
      "env": {
        "NBRAG_API_KEY": "sk-xxx"
      }
    }
  }
}

HTTP 客户端配置示例：

{
  "mcpServers": {
    "nbrag": {
      "url": "http://localhost:9101/mcp"
    }
  }
}

如果客户端使用的解释器与 shell 不同，需要把 python 替换为绝对路径，例如 python、/Users/me/.venv/bin/python 等。

扩展与开发

技能（skills）扩展

nbrag 把面向 AI 的检索工作流封装为 skills，便于第三方工具自动发现与调用。nbrag/skills/readme.md 指出，使用方应将整个 skills 文件夹复制到自己项目下被第三方工具识别的 skills 目录中，资料来源：nbrag/skills/readme.md:1-1。这种方式保持了主仓库与业务仓库的解耦：升级 nbrag 时只需同步该文件夹。

知识库增量与全量重建

scripts/run_all_ingest.py 是常见的批量入库脚本入口。README 明确建议：只有在调整切片参数或更换 embedding 模型时使用 delete_first=True 全量重建；支持增量入库时，应避免预先删除集合，否则会产生重复 embedding 费用，资料来源：README.md:67-69。

开发模式安装

进行二次开发时使用可编辑安装，资料来源：README.md:163-168：

git clone https://github.com/ydf0509/nbrag.git
cd nbrag
pip install -e ".[dev]"

python -m nbrag
python -m nbrag --transport streamable-http --port 9101

常见故障与最佳实践

• API Key 未配置：NBRAG_API_KEY 缺失会导致 embedding / rerank 调用失败，CLI 上传 NBRAG_API_KEY 是最快的临时修复手段。
• 多客户端争用 embedding 配额：HTTP 模式下所有客户端共享同一 embedding Key，建议为不同业务分配独立的 NBRAG_API_KEY 或自部署兼容端点。
• 路径不一致：NBRAG_DB_PATH 与 NBRAG_RAW_FILES_PATH 在 YAML 与 CLI 中需保持一致，否则会出现"能搜但拿不到原文"的现象。
• 解释器不匹配：stdio 模式下客户端使用的 Python 环境若未安装 nbrag，应在 args 中显式指定绝对路径。

See Also

• 快速上手与 MCP 工具能力概览
• nbrag/config.py 配置加载实现
• nbrag/defaults.py 默认值定义
• 批量入库脚本入口

Pitfall Log / 踩坑日志

项目：ydf0509/nbrag

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/ydf0509/nbrag | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/ydf0509/nbrag | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/ydf0509/nbrag | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/ydf0509/nbrag | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/ydf0509/nbrag | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/ydf0509/nbrag | release_recency=unknown