内容
# nbrag
[English](README.md) | [简体中文](README.zh-CN.md)
`nbrag` 是一个用于构建本地文本知识库并通过 MCP 服务器暴露的 PyPI 包。
在您希望 MCP 兼容的客户端检索您控制的文件中的证据时使用，例如内部文档、法规、手册、笔记、本地项目文档或 Python 源代码。
nbrag 内置了向量搜索、BM25 搜索和混合搜索。通过精心设计的提示和 10 多个 MCP 工具，AI 代理可以检索最相关的证据。
## 何时使用 nbrag
`nbrag` 是一个很好的选择，当您需要：
- 索引 **私有或本地文本**，托管服务无法访问
- 从您自己的文件中构建 **特定领域的知识库**
- 让 MCP 客户端搜索 **向量化的块和存储的原始文本**
- 将存储保留在 **您自己的机器上**
`nbrag` 以文本为中心。如果您的源材料以 PDF、Word、图像、扫描件或网页等形式存在，请在摄入前将其转换为 `.md`、`.txt` 或 `.html` 以获得最佳结果。
## 安装
```bash
pip install nbrag
```
要确认软件包可用：
```bash
python -m nbrag --help
```
## 配置 API 密钥
默认情况下，`nbrag` 使用 SiliconFlow 兼容的嵌入和重新排序端点。在摄入或提供服务之前，请设置 `NBRAG_API_KEY`。
Linux/macOS：
```bash
export NBRAG_API_KEY=sk-xxx
```
Windows PowerShell：
```powershell
$env:NBRAG_API_KEY = "sk-xxx"
```
## 快速入门
正常的工作流程是：
1. 准备一个文本文件目录
2. 使用 `batch_ingest()` 摄入
3. 使用 `set_collection_profile()` 描述集合
4. 启动 MCP 服务器
5. 连接您的 MCP 客户端
### 最小摄入示例
创建一个名为 `ingest_my_docs.py` 的脚本：
```python
from nbrag import batch_ingest, set_collection_profile
batch_ingest(
paths=[
"D:/docs/company_policies",
"D:/docs/product_manuals",
],
collection_name="company_knowledge",
file_extensions=[".md", ".txt", ".html"],
delete_first=True,
verbose=True,
)
set_collection_profile(
"company_knowledge",
display_name="公司知识库",
description="内部政策和产品手册。",
aliases=["公司文档", "政策", "手册"],
tags=["内部", "政策", "手册"],
)
```
使用 Python 运行：
```bash
python ingest_my_docs.py
```
一些实用的注意事项：
- `collection_name` 是稳定的机器面向标识符（知识库名称）
- `file_extensions` 允许您限制摄入哪些文本文件
- `delete_first=True` 如果您需要调整参数，可以完全重建此集合。但是，如果支持增量导入，请避免在导入前删除它。
- `verbose=True` 在您学习或调试摄入流程时很有用
### 为什么 `set_collection_profile()` 很重要
Chroma 集合名称应保持简单和类似 slug，例如 `company_knowledge`。
`set_collection_profile()` 添加了人类面向的元数据，帮助人类和 MCP 路由了解集合的内容：
- `display_name`
- `description`
- `aliases`
- `tags`
该元数据存储在向量存储内部的单独位置，用于使集合选择更容易和更清晰。
## Python 源代码使用相同的摄入流程
Python 项目不需要单独的摄入流程。实际上，您通常只需要更改：
- 您摄入的目录
- `file_extensions` 列表，例如 `['.py', '.md', '.txt']`
- `set_collection_profile()` 中的集合描述
示例：
```python
from nbrag import batch_ingest, set_collection_profile
batch_ingest(
paths=[
"D:/projects/my_framework/src",
"D:/projects/my_framework/docs",
],
collection_name="my_framework",
file_extensions=[".py", ".md", ".txt"],
delete_first=True,
verbose=True,
)
set_collection_profile(
"my_framework",
display_name="我的框架源代码和文档",
description="Python 源代码和 my_framework 文档。",
aliases=["my_framework", "框架源代码", "框架文档"],
tags=["python", "源代码", "文档"],
)
```
## 启动 MCP 服务器
### 标准输入/输出模式
当一个客户端拥有一个服务器进程时，请使用标准输入/输出。
```bash
python -m nbrag
```
### HTTP 模式
当多个客户端或多个 IDE 窗口应该共享一个本地服务器进程时，请使用 HTTP 模式。
```bash
python -m nbrag --transport streamable-http --port 9101
```
## 配置 MCP 客户端
### 标准输入/输出配置
将客户端指向安装了 `nbrag` 的 Python 环境。
示例：
```json
{
"mcpServers": {
"nbrag": {
"command": "python",
"args": ["-m", "nbrag"],
"env": {
"NBRAG_API_KEY": "sk-xxx"
}
}
}
}
```
如果您的客户端不使用与 shell 相同的解释器，请将 `python` 替换为完整的解释器路径。
### HTTP 配置
首先启动共享的本地服务器：
```bash
python -m nbrag --transport streamable-http --port 9101
```
然后将客户端指向：
```json
{
"mcpServers": {
"nbrag": {
"url": "http://localhost:9101/mcp"
}
}
}
```
## MCP 功能概述
服务器启动后，`nbrag` 公开了一组面向检索的 MCP 工具。对于人类读者来说，了解它们的最简单方法是按功能：
| 功能 | 代表工具 | 涵盖内容 |
|---|---|---|
| 搜索 | `nbrag_search`, `nbrag_search_and_fetch` | 对摄入集合的语义和混合检索 |
| 搜索检查 | `nbrag_search_only_bm25`, `nbrag_search_only_vector` | 检查仅限于词法或仅限于向量的行为 |
| 精确文本查找 | `nbrag_grep` | 存储的原始文本的逐行匹配 |
| 原始文本读取 | `nbrag_get_raw_file`, `nbrag_get_file_chunks` | 读取存储的原始文件或块视图 |
| 扩展和查找 | `nbrag_get_adjacent_chunks`, `nbrag_get_chunks_by_lines`, `nbrag_find_files` | 扩展命中周围的上下文并解析确切的文件路径 |
| 库存和路由 | `nbrag_stats`, `nbrag_list` | 发现集合和浏览导入的文档 |
## 这与朴素 RAG 的区别
朴素 RAG 通常是一个固定的单次流水线：检索 top-k 块一次，并将它们放入提示中。
`nbrag` 在两个实用方面有所不同：
- 您自己准备和控制知识库
- 通过 MCP 工具公开检索，客户端可以根据需要搜索、完善、检查原始文本并获取更多上下文
## 配置参考
配置优先级：
```text
命令行参数 > 环境变量 > YAML 配置 > 默认值
```
### 环境变量
| 变量 | 是否必需 | 默认值 | 描述 |
|---|---:|---|---|
| `NBRAG_API_KEY` | 是 | | 嵌入/重新排序 API 密钥 |
| `NBRAG_BASE_URL` | 否 | `https://api.siliconflow.cn/v1` | OpenAI 兼容的 API 基地址 |
| `NBRAG_EMBEDDING_MODEL` | 否 | `BAAI/bge-m3` | 嵌入模型 |
| `NBRAG_RERANK_MODEL` | 否 | `BAAI/bge-reranker-v2-m3` | 重新排序模型 |
| `NBRAG_DB_PATH` | 否 | `<project>/rag_db` | ChromaDB 和本地索引路径 |
| `NBRAG_RAW_FILES_PATH` | 否 | `<db_path>/raw_files` | 存储的原始文件快照路径 |
| `NBRAG_CHUNK_SIZE` | 否 | `1000` | 块大小 |
| `NBRAG_CHUNK_OVERLAP` | 否 | `150` | 块重叠 |
### YAML 配置
`nbrag` 自动查找：
1. `./nbrag_config.yaml`
2. `./nbrag_config.yml`
3. `~/.config/nbrag/config.yaml`
4. `~/.config/nbrag/config.yml`
示例：
```yaml
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
```
### 命令行界面
```bash
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
```
## 开发
```bash
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
```
## 许可证
MIT
