RAGbox 中文文档

ragbox 可以让你从命令行、HTTP 服务或 Node.js 应用里直接询问 Markdown/MDX 文档。

它会把文档目录变成本地可查询索引，适合产品文档、API 指南、运维 runbook、内部手册和 monorepo 多包文档。基础流程不需要部署向量数据库。

适合这些场景：

• 对本地 docs 目录提问
• 查看一次回答用了哪些文档和章节
• 文档变化时持续刷新索引
• 通过 HTTP 把文档问答接进内部 backend
• 在本地、CI 和容器里使用同一套索引/查询流程

快速开始

默认路径按“开箱即用”设计：安装 ragbox，让它在当前项目里准备 PageIndex，然后直接索引和提问。

# 安装 CLI
npm install -g @bndynet/ragbox

# 克隆 PageIndex 到 ./.ragbox/PageIndex，创建 Python venv，
# 安装 PageIndex 依赖，并写入 ragbox.config.json
ragbox setup pageindex

继续下一步前，先编辑 ragbox.config.json：填好模型配置，并把 docs.rootDir / docs.outputDir 改成你的文档目录和索引目录。

{
  "version": 1,
  "pageIndex": {
    "cli": "./.ragbox/PageIndex/run_pageindex.py",
    "python": "./.ragbox/pageindex-venv/bin/python"
  },
  "llm": {
    "baseUrl": "https://api.openai.com/v1",
    "model": "gpt-4o-mini",
    "apiKey": "sk-..."
  },
  "serve": {
    "authToken": "YOUR_RAGBOX_SERVE_TOKEN",
    "host": "127.0.0.1",
    "port": 8787
  },
  "docs": {
    "rootDir": "./docs",
    "outputDir": "./.ragbox-index"
  }
}

如果有多个文档目录，改用 项目配置 里的 sources 映射。然后索引和提问：

# 基于配置里的 docs/source 生成本地索引
ragbox index

# 提问
ragbox query "怎么配置认证？"

# 可选：文档变化时持续刷新索引
ragbox watch --jsonl

如果想用一个前台进程同时负责索引、watch 和 query HTTP API，使用 start：

ragbox start

如果只是想临时脱离当前终端运行，可以加 --background：

ragbox start --background
ragbox stop

需要临时覆盖配置时，仍然可以显式传路径：

ragbox index ./docs --output-dir ./.ragbox-index
ragbox query ./.ragbox-index "怎么配置认证？"

如果不想把凭证写进 JSON，同样也支持通过环境变量或命令参数传入模型配置：

export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://api.openai.com/v1

ragbox index ./docs \
  --output-dir ./.ragbox-index \
  --model gpt-4o-mini

ragbox query ./.ragbox-index "怎么配置认证？" \
  --api-key sk-... \
  --base-url https://api.openai.com/v1 \
  --model gpt-4o-mini

Setup 做了什么

ragbox setup pageindex 会帮你准备本地 PageIndex 依赖：

• 克隆 PageIndex 到 ./.ragbox/PageIndex
• 创建 ./.ragbox/pageindex-venv
• 安装 PageIndex Python 依赖
• 把 pageIndex.cli 和 pageIndex.python 写入 ragbox.config.json
• 把 .ragbox/ 加入 .gitignore

如果你已经有 PageIndex checkout，可以使用 ragbox setup pageindex --dir ../PageIndex --skip-install，或手动设置 PAGEINDEX_CLI。

前置条件

默认 setup 需要：

• Node.js 18 或更新版本
• Git，用于克隆 PageIndex
• 带 venv 和 pip 的 Python 3，用于安装 PageIndex 依赖
• 一个包含 .md 或 .mdx 的文档目录
• 一个兼容 OpenAI /chat/completions 的模型服务
• 模型服务 API key

常见使用方式

| 目标 | 使用方式 | | --- | --- | | 从零开始 | npm install -g @bndynet/ragbox，然后 ragbox setup pageindex | | 先在一个 docs 目录试用 | ragbox index ./docs --output-dir ./.ragbox-index，然后 ragbox query ./.ragbox-index "..." | | 不想每次重复路径 | 使用 ragbox setup pageindex 写入的 ragbox.config.json，或运行 ragbox init | | 多个文档目录一起查询 | 配置 sources，分别跑 ragbox index --source <name>，再用 ragbox query --all-sources "..." | | 调试回答质量 | ragbox query --trace --json "..." 或 ragbox trace query "..." | | 检查索引和 HTTP 服务状态 | ragbox status ./.ragbox-index | | 诊断本地配置问题 | ragbox doctor | | 编辑文档时自动更新索引 | ragbox watch ./docs --output-dir ./.ragbox-index --jsonl | | 跑完整本地服务流程 | ragbox start --auth-token <token> | | 只服务一个已经生成好的索引 | ragbox serve ./.ragbox-index --auth-token <token> |

项目配置

ragbox setup pageindex 会为默认本地 setup 创建或更新 ragbox.config.json。补上模型凭证后，典型配置如下：

{
  "version": 1,
  "pageIndex": {
    "cli": "./.ragbox/PageIndex/run_pageindex.py",
    "python": "./.ragbox/pageindex-venv/bin/python"
  },
  "llm": {
    "baseUrl": "https://api.openai.com/v1",
    "model": "gpt-4o-mini",
    "apiKey": "sk-..."
  },
  "serve": {
    "authToken": "YOUR_RAGBOX_SERVE_TOKEN",
    "host": "127.0.0.1",
    "port": 8787
  },
  "docs": {
    "rootDir": "./docs",
    "outputDir": "./.ragbox-index"
  }
}

如果你只想创建配置、不安装 PageIndex，也可以运行：

ragbox init
ragbox init --docs-dir ./content --output-dir ./.idx

配置文件中的相对路径会按配置文件所在目录解析。Server 端部署可以把 baseUrl、model、serve.host、serve.port 和 apiKey 一起放在私有 ragbox.config.json，或按环境拆成 ragbox.config.prod.json。如果配置文件会提交到仓库或共享给他人，就不要写真实 apiKey，改用环境变量或 secret manager。

只有一个文档源时，用顶层 docs 就够了，不需要传 --source。项目里确实有多个命名文档源时，再使用可选的 sources 映射。

之后命令会自动使用配置里的 docs：

ragbox index
ragbox query "怎么配置认证？"
ragbox watch --jsonl
ragbox start
ragbox --config ./ragbox.config.json index

如果有多个文档目录，在 sources 里给每个目录起一个名字。这个模式适合 monorepo、产品文档加 API 文档、多个 app/package 各自有 docs 的项目：

{
  "version": 1,
  "pageIndex": {
    "cli": "./.ragbox/PageIndex/run_pageindex.py",
    "python": "./.ragbox/pageindex-venv/bin/python"
  },
  "llm": {
    "baseUrl": "https://api.openai.com/v1",
    "model": "gpt-4o-mini",
    "apiKey": "sk-..."
  },
  "serve": {
    "authToken": "YOUR_RAGBOX_SERVE_TOKEN",
    "host": "127.0.0.1",
    "port": 8787
  },
  "sources": {
    "ragbox": {
      "rootDir": "./ragbox",
      "outputDir": "./.ragbox-index/ragbox",
      "include": ["**/*.md", "**/*.mdx"]
    },
    "icharts": {
      "rootDir": "./icharts",
      "outputDir": "./.ragbox-index/icharts",
      "include": ["**/*.md", "**/*.mdx"]
    }
  }
}

这个多 source 目录结构的可运行示例在 ./examples/ragbox.config.json。

命名 source 分别索引，query 时可以全局查，也可以限定 source：

ragbox index --source ragbox
ragbox index --source icharts

ragbox query "ragbox start 是做什么的？"
ragbox query --source ragbox "query trace 是怎么工作的？"
ragbox query --source ragbox,icharts "这些项目如何处理运行时流程？"
ragbox query --all-sources "当前示例有哪些文档主题？"
ragbox start --all-sources

配置了多个 source 时，ragbox query "..." 默认查询全部 source。--all-sources 是同样行为的显式写法；要缩小范围时再用 --source。

也可以按环境拆配置文件：

ragbox --config prod index
ragbox --config ./ragbox.config.prod.json query "怎么部署？"

配置

Server 端使用时，建议把稳定配置集中写在 ragbox.config.json：PageIndex 路径、docs 路径、serve host/port、LLM baseUrl、model，以及私有配置文件里的 apiKey。环境变量和命令参数仍然支持，适合覆盖配置、接 secret manager，或临时运行。

配置解析优先级为：命令行参数、ragbox.config.json、环境变量、默认值。

| 配置 | 环境变量 | 配置 / 命令参数 | 用于 | 默认值 | | --- | --- | --- | --- | --- | | PageIndex 脚本 | PAGEINDEX_CLI | ragbox setup pageindex 写入配置 | index, watch, start | 索引时必填 | | Python 可执行文件 | PAGEINDEX_PYTHON | --pageindex-python | index, watch, start | python3 | | 输出目录 | RAGBOX_OUTPUT_DIR | --output-dir | index, watch, start | <folder>/.pageindex | | 并发数 | PAGEINDEX_CONCURRENCY | --concurrency | index, watch, start | 1 | | PageIndex runner | PAGEINDEX_RUNNER | --pageindex-runner | index, watch, start | auto | | API Base URL | OPENAI_BASE_URL | --base-url | index, watch, query | https://api.openai.com/v1 | | API Key | OPENAI_API_KEY | --api-key | index, watch, query | query 必填，PageIndex 通常也需要 | | 模型 | PAGEINDEX_MODEL, LLM_MODEL | --model | index, watch, query | gpt-4o-mini | | Serve host | RAGBOX_SERVE_HOST | serve.host, --host | start, serve, status, doctor | 127.0.0.1 | | Serve port | RAGBOX_SERVE_PORT | serve.port, --port | start, serve, status, doctor | 8787 | | Serve token | RAGBOX_SERVE_TOKEN | serve.authToken, --auth-token | start, serve | 无 | | Watch debounce | RAGBOX_WATCH_DEBOUNCE_MS | --debounce-ms | watch | 500 | | Watch 重试次数 | RAGBOX_WATCH_RETRY_ATTEMPTS | --retry-attempts | watch | 0 | | Watch 重试延迟 | RAGBOX_WATCH_RETRY_DELAY_MS | --retry-delay-ms | watch | 1000 | | Watch 锁文件 | RAGBOX_WATCH_LOCK_FILE | --lock-file | watch | 无 | | Watch staging | RAGBOX_WATCH_STAGING | --staging | watch | 关闭 | | Watch staging 输出目录 | RAGBOX_WATCH_STAGING_OUTPUT_DIR | --staging-output-dir | watch | <outputDir>.staging | | Watch health 文件 | RAGBOX_WATCH_HEALTH_FILE | --health-file | watch | 无 | | Watch webhook | RAGBOX_WATCH_WEBHOOK_URL | --webhook | watch | 无 |

私有 server 配置可以把 llm.apiKey 写进 JSON，让部署自包含。配置文件会提交、共享或交给平台 secret 管理时，不要在 JSON 里写真实 key，改用 OPENAI_API_KEY。--api-key 适合本地测试，但可能出现在 shell history 或进程列表里。

命令说明

这一节是命令参考。如果你是第一次使用，建议先看 快速开始 和 常见使用方式。

ragbox setup pageindex

把 PageIndex 克隆到 ./.ragbox/PageIndex，创建 ./.ragbox/pageindex-venv，安装 PageIndex Python 依赖，更新 ragbox.config.json，并把 .ragbox/ 加入 .gitignore。

ragbox setup pageindex
ragbox setup pageindex --ref v0.1.0
ragbox setup pageindex --skip-install
ragbox setup pageindex --dir ../PageIndex --no-write-config

自动化场景可以使用 --json。如果项目用其它方式管理本地生成工具，可以使用 --no-gitignore。

ragbox init

只创建 ragbox.config.json，不安装 PageIndex。适合你想手动编辑路径，或自己管理 PageIndex 的场景。

ragbox init
ragbox init --docs-dir ./content --output-dir ./.idx
ragbox init --output ./configs/ragbox.config.json --force

ragbox index <folder>

为 Markdown/MDX 文档目录生成或更新本地索引。使用 query 或 serve 前需要先执行它。

ragbox index ./docs
ragbox index ./docs --output-dir ./.ragbox-index
ragbox index ./docs --output-dir ./.ragbox-index --json
ragbox index ./docs --output-dir /var/lib/ragbox/docs-index --concurrency 2
ragbox index ./docs --pageindex-python /opt/venvs/pageindex/bin/python
ragbox index ./docs --base-url https://api.openai.com/v1 --model gpt-4o-mini

它会扫描 **/*.md 和 **/*.mdx，计算文件 hash，只重新索引新增、修改、之前失败的文件，并跳过未变化的 ready 文件。

如果有文档索引失败，普通输出会继续把统计信息写到 stdout，并把失败文档路径和 PageIndex 错误写到 stderr。

使用 --json 可以输出带版本号的机器可读结果，包含输出路径、统计信息和失败文档明细：

{
  "version": 1,
  "command": "index",
  "rootDir": "/repo/docs",
  "outputDir": "/repo/.ragbox-index",
  "manifestPath": "/repo/.ragbox-index/manifest.json",
  "rootTreePath": "/repo/.ragbox-index/root-tree.json",
  "generatedAt": "2026-01-01T00:00:00.000Z",
  "counts": {
    "total": 12,
    "ready": 12,
    "failed": 0,
    "added": 12,
    "modified": 0,
    "retryFailed": 0,
    "unchanged": 0,
    "deleted": 0
  },
  "failures": []
}

ragbox inspect [target]

查看索引里有哪些文档、每篇文档的状态和统计信息。适合确认“到底索引进去了什么”。

ragbox inspect ./.ragbox-index
ragbox inspect --source ragbox
ragbox inspect --all-sources --json

ragbox status [target]

检查索引是否已经可以 query，并探测本机 HTTP 服务的 /health 是否可达。服务探测会先使用 serve.host / serve.port，再使用 RAGBOX_SERVE_HOST / RAGBOX_SERVE_PORT，默认是 127.0.0.1:8787。

ragbox status ./.ragbox-index
ragbox status --all-sources
ragbox status --json

ragbox doctor [target]

检查本地配置、PageIndex CLI 路径、LLM 设置、API key 是否存在、索引是否有效，以及本机 ragbox HTTP 服务是否健康。

ragbox doctor
ragbox doctor --source ragbox --json
ragbox doctor --all-sources

ragbox query [target] <question>

基于 docs 目录或已有索引目录回答问题。如果传 docs 目录，目录下需要有默认的 .pageindex 索引。

ragbox query ./docs "怎么配置认证？"
ragbox query ./.ragbox-index "部署步骤是什么？"
ragbox query ./docs/.pageindex "怎么配置认证？"
ragbox query ./.ragbox-index "怎么配置认证？" --model gpt-4o-mini --api-key sk-...
ragbox query ./.ragbox-index "怎么配置认证？" --json
ragbox query ./.ragbox-index "怎么配置认证？" --trace
ragbox trace query ./.ragbox-index "怎么配置认证？"
ragbox query "部署步骤是什么？"
ragbox query --source ragbox,icharts "这些项目如何处理运行时流程？"
ragbox query --all-sources "部署步骤是什么？"

这里建议使用和索引时相同的 --base-url，通常是 OpenAI-compatible 根地址，例如 https://api.openai.com/v1。如果某些代理只能提供完整接口地址，query 也兼容完整的 /chat/completions URL。

显式传 target 时，第一个参数可以是：

• docs 目录，里面有 .pageindex/manifest.json 和 .pageindex/root-tree.json
• 索引输出目录，里面有：

manifest.json
root-tree.json
indexes/

查询流程：

1. 读取 manifest.json 和 root-tree.json
2. 让 LLM 从文档树中选择相关文档
3. 读取相关文档的 PageIndex JSON
4. 去掉节点里的 text 字段，只让 LLM 基于结构选择相关节点
5. 回到完整 JSON 中取出选中节点的 text
6. 把这些文本拼成上下文，让 LLM 生成最终答案

对多个配置 source，ragbox query "..." 默认查询全部 source。可以用 --source 传逗号分隔的名字来缩小范围，也可以用 --all-sources 显式表达全局查询。多源 query 会对每个 source 执行正常的结构化查询流程，然后让 LLM 基于各 source 选出的片段融合成一个最终回答。来源引用会加上 source 前缀，例如 ragbox:start-command.md#n1。

使用 --json 可以输出带版本号的结果契约。单 source query 返回 QueryResult；多 source query 返回融合后的 answer、每个 source 的 results、带 source 前缀的 sources、warnings 和 timingsMs。

单 source QueryResult 字段：

• answer：最终回答文本
• contextBytes 和 contextTokens：最终 answer context 的大小；tokens 为估算值
• selectedDocuments：从 root-tree.json 中选中的文档，包含 selectionReason，必要时包含 skipReason
• selectedNodes：每篇文档中选中的 PageIndex 节点，包含 selectionReason、可选 skipReason 和 textBytes
• sources：最终回答使用的来源引用和节点文本
• warnings：不可用文档、缺失节点或空上下文等提醒
• timingsMs：解析、选择和生成回答的耗时
• trace：只有使用 --trace 或 ragbox trace query 时才会出现，包含文档/节点选择阶段的 LLM 原始响应、prompt/response 字节数、context 大小和非致命失败记录

致命 query 错误会带上失败阶段，例如 Query failed during select-documents: ...。

ragbox start [folder]

运行完整本地服务流程：启动 watch、提供 HTTP query API，并持续刷新索引。

ragbox start
ragbox start --auth-token dev-token
ragbox start --host 127.0.0.1 --port 8787 --jsonl
ragbox start --background
ragbox start --source ragbox
ragbox start --all-sources
ragbox start ./docs --output-dir ./.ragbox-index

当你已经通过 ragbox setup pageindex 准备好默认本地配置，并希望用一个前台进程跑本地开发、内网服务或容器时，优先使用 start。HTTP serve 会在 watcher 注册后立即启动，所以初始索引还在运行时，/ 和 /health 已经可以响应。/health 在首个索引快照可查询前返回 503；初始索引完成后，以及之后每次 watch 成功更新索引，都会刷新 serve 里的索引快照。

传入 --background 时，start 会脱离当前终端后台运行。后台进程默认把 stdout/stderr 写到 ./ragbox.log，并把 PID 写到 ./ragbox.pid。可以用 --log-file <path> 和 --pid-file <path> 覆盖路径；如果不想写 PID 文件，可以传 --no-pid-file。

在同一个工作目录运行 ragbox stop，会读取 ./ragbox.pid 并停止对应后台进程。如果启动时用了自定义 pid 文件，停止时也传同一个 --pid-file <path>。

配置了多个 source 时，ragbox start 默认启动全部 source。可以用 --source ragbox,icharts 限定范围，也可以用 --all-sources 显式表达全局启动。

start 不会创建或修改 ragbox.config.json；默认本地 setup 先运行 ragbox setup pageindex，如果你想自己管理 PageIndex，再用 ragbox init 手动配置。

ragbox stop

读取当前工作目录的 ./ragbox.pid，停止由 ragbox start --background 启动的后台进程。

ragbox stop
ragbox stop --pid-file /var/run/ragbox.pid
ragbox stop --force

默认发送 SIGTERM，等待进程退出后删除 pid 文件。传 --force 时发送 SIGKILL。

ragbox serve [target]

启动一个前台 HTTP 服务，供外部系统通过 REST API 查询文档。使用前先通过 ragbox index 生成索引，或者用 ragbox watch 持续刷新索引。

ragbox serve ./.ragbox-index \
  --host 127.0.0.1 \
  --port 8787 \
  --auth-token dev-token

多 source 项目可以直接基于配置文件启动：

ragbox serve --config ./ragbox.config.json --host 0.0.0.0 --port 8787

Public HTTP contract：

• GET /：公开服务入口，返回 health 摘要和 endpoint 列表。
• GET /health：公开 readiness endpoint，适合 load balancer、Kubernetes、systemd 和 smoke check。所有已知索引都可 query 时返回 200，否则返回 503。
• GET /indexes：返回当前服务端缓存的索引校验快照。配置 token 后需要 Authorization: Bearer <token>。
• POST /query：基于单个 target、选定 source 或全部 source 回答问题。配置 token 后需要鉴权。
• POST /reload：重新读取 config/source target，并刷新服务端索引校验快照。配置 token 后需要鉴权。

单索引请求：

curl http://127.0.0.1:8787/
curl http://127.0.0.1:8787/health
ragbox status ./.ragbox-index

curl -H "Authorization: Bearer dev-token" \
  http://127.0.0.1:8787/indexes

curl -X POST http://127.0.0.1:8787/query \
  -H "Authorization: Bearer dev-token" \
  -H "Content-Type: application/json" \
  -d '{"question":"怎么配置认证？","trace":true}'

多 source 请求：

curl -X POST http://localhost:8787/query \
  -H "Content-Type: application/json" \
  -d '{"source":"ragbox","question":"ragbox start 是做什么的？"}'

curl -X POST http://localhost:8787/query \
  -H "Content-Type: application/json" \
  -d '{"source":["ragbox","icharts"],"question":"这些项目如何处理运行时流程？"}'

curl -X POST http://localhost:8787/query \
  -H "Content-Type: application/json" \
  -d '{"allSources":true,"question":"当前示例有哪些文档主题？"}'

curl -X POST http://localhost:8787/reload

serve 首版面向本地服务、内网服务、container sidecar 和 docs backend。不要把 .ragbox-index 作为静态目录直接暴露，因为里面可能包含源文档正文。浏览器 widget 不应该直接携带 ragbox token；建议先请求自己的 backend，由 backend 负责用户登录、限流和审计，再转发给 ragbox serve。生产环境建议绑定 localhost 或内网地址，并配置 serve.authToken、--auth-token 或 RAGBOX_SERVE_TOKEN。

ragbox watch <folder>

先执行一次索引，然后监听文档变化并增量更新。

ragbox watch ./docs
ragbox watch ./docs --output-dir ./.ragbox-index
ragbox watch ./docs --output-dir /var/lib/ragbox/docs-index --concurrency 2
ragbox watch ./docs --base-url https://api.openai.com/v1 --model gpt-4o-mini
ragbox watch ./docs --output-dir ./.ragbox-index --jsonl
ragbox watch ./docs \
  --output-dir /var/lib/ragbox/docs-index \
  --staging \
  --retry-attempts 3 \
  --retry-delay-ms 2000 \
  --lock-file /var/run/ragbox/docs.lock \
  --health-file /var/run/ragbox/docs-health.json \
  --jsonl

watch 监听 .md 和 .mdx 文件的新增、修改、删除。它会忽略 node_modules、.git、.pageindex、dist、build，以及位于文档目录内的自定义输出目录。

使用 --jsonl 可以为集成场景输出带版本号的 JSON Lines 事件流。事件包括 watch-start、watch-lock-acquired、watch-file-event、watch-index-start、watch-index-retry、watch-index-partial-failure、watch-output-promoted、watch-index-done、watch-index-failed、watch-health、watch-webhook-failed、watch-lock-released、watch-stop 和 index-progress。

生产化 watch 选项：

• --retry-attempts 和 --retry-delay-ms 会重试抛错的索引运行，以及仍然留下 failed document 的运行。
• --lock-file 会在 watch 运行期间创建排他锁文件。第二个 watcher 如果发现锁已存在，会直接退出。
• --staging 会先索引到 staging 目录，只有在零 failed document 的干净运行后才 promote 到 active output。默认 staging 目录是 <outputDir>.staging；为了基于 rename 切换，建议和 outputDir 放在同一文件系统。
• --health-file 会写 readiness JSON，包含 status、ok、pid、lastSuccessAt、lastFailureAt 和最新统计。
• --webhook 会把每个 watch 事件作为 JSON POST 出去。Webhook 投递失败会报告为 watch-webhook-failed 事件，不会中断 watch。
• --debounce-ms 控制文件变化后等待多久再重新索引。

ragbox watch 有意以前台进程运行，这更适合 systemd service 或 container。建议使用 supervisor/container 的 restart policy，而不是在 CLI 里自行 fork daemon。

输出目录

默认输出：

docs/.pageindex/
  manifest.json
  root-tree.json
  indexes/
    <stable-doc-id>.pageindex.json
  state/
    file-state.json

自定义输出：

ragbox index ./docs --output-dir ./.ragbox-index
ragbox query ./.ragbox-index "..."

输出目录可能包含源文档正文和元数据。如果文档是私有的，不要把输出目录公开暴露。

生产使用建议

常见方式：

• 一个前台进程要同时负责索引、watch 和 serve 时，直接运行 ragbox start
• 部署时执行 ragbox index，再通过 ragbox serve 或 SDK 查询完成后的索引目录
• 文档会独立变化时，把 ragbox watch 作为后台服务运行

建议：

• 长期运行 watch 时，优先使用 --jsonl、--lock-file、--health-file、--retry-attempts 和 --staging
• 把输出目录放在源码目录外，例如 /var/lib/ragbox/docs-index
• 多副本应用需要读取同一份完整索引，可以挂载只读卷或随部署产物分发
• API key 可以放私有 server 配置、环境变量或 secret manager；不要提交真实 key
• 当 serve 不只绑定 localhost 时，使用 serve.authToken、RAGBOX_SERVE_TOKEN 或 --auth-token；如果配置会提交或共享，要把 token 当作密钥处理
• 先用 --concurrency 1，确认 PageIndex 和模型服务限流后再提高
• Markdown/MDX 索引保持默认 --pageindex-runner auto；它会优先使用 PageIndex 热 worker，无法使用时自动回退到单文件 CLI
• 如果要求零停机更新，可以先索引到 staging 目录，成功后再切换读目录

私有 server 配置示例：

{
  "version": 1,
  "pageIndex": {
    "cli": "/opt/PageIndex/run_pageindex.py",
    "python": "/opt/pageindex-venv/bin/python",
    "runner": "auto"
  },
  "llm": {
    "baseUrl": "https://api.openai.com/v1",
    "model": "gpt-4o-mini",
    "apiKey": "sk-..."
  },
  "serve": {
    "authToken": "YOUR_RAGBOX_SERVE_TOKEN",
    "host": "127.0.0.1",
    "port": 8787
  },
  "docs": {
    "rootDir": "/srv/app/docs",
    "outputDir": "/var/lib/ragbox/docs-index"
  }
}

ragbox --config ./ragbox.config.prod.json index --concurrency 2
ragbox --config ./ragbox.config.prod.json query "怎么配置认证？"

后台运行

本地或内网临时测试时，可以用 ragbox start --background 让同一个 start 流程脱离当前终端：

ragbox --config ./ragbox.config.prod.json start \
  --background

ragbox stop

长期运行的 server 仍然建议交给进程管理器托管，这样进程崩溃后可以自动重启，启动顺序也更清晰。

Linux server 推荐用 systemd：

[Unit]
Description=ragbox service
After=network.target

[Service]
WorkingDirectory=/srv/ragbox
ExecStart=/usr/local/bin/ragbox --config ./ragbox.config.prod.json start
Restart=always
RestartSec=5
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

sudo systemctl enable ragbox
sudo systemctl start ragbox
sudo systemctl status ragbox

如果使用 Node 生态，也可以用 pm2：

pm2 start "ragbox --config ./ragbox.config.prod.json start" --name ragbox
pm2 save
pm2 startup

容器部署时，让 ragbox start 保持为前台命令，然后使用平台的 restart policy，例如 Docker --restart unless-stopped 或 Kubernetes restartPolicy。

在 Node.js 中使用 ragbox

当你的 Node.js 服务需要创建索引、查询文档、校验索引，或以编程方式启动 serve 时，可以使用 SDK。

const {
  createIndex,
  inspectIndex,
  queryIndex,
  startServe,
  validateIndex,
  watchIndex
} = require("@bndynet/ragbox");

await createIndex("/srv/app/docs", {
  configPath: "./ragbox.config.json",
  outputDir: "/var/lib/ragbox/docs-index",
  pageIndexCli: "/opt/PageIndex/run_pageindex.py"
});

const result = await queryIndex(
  "/var/lib/ragbox/docs-index",
  "怎么配置认证？"
);

console.log(result.answer);
console.log(result.sources);

const validation = await validateIndex("/var/lib/ragbox/docs-index");
console.log(validation.ok);

const server = await startServe({
  target: "/var/lib/ragbox/docs-index",
  port: 8787,
  authToken: process.env.RAGBOX_SERVE_TOKEN
});
console.log(server.url);
await server.close();

const inspect = await inspectIndex("/var/lib/ragbox/docs-index");
console.log(inspect.counts);

const watcher = await watchIndex("/srv/app/docs", {
  outputDir: "/var/lib/ragbox/docs-index",
  pageIndexCli: "/opt/PageIndex/run_pageindex.py",
  onEvent: (event) => console.log(event)
});
await watcher.ready;
await watcher.close();

自定义 LLM client：

const { queryIndex, startServe } = require("@bndynet/ragbox");

const llmClient = {
  async chatCompletion(request) {
    // request.messages, request.model, request.temperature
    return await callYourModelGateway(request);
  }
};

const result = await queryIndex(
  "/var/lib/ragbox/docs-index",
  "怎么配置认证？",
  {
    llmClient,
    model: "internal-docs-model"
  }
);

const server = await startServe({
  target: "/var/lib/ragbox/docs-index",
  llmClient,
  model: "internal-docs-model",
  port: 8787
});

llmClient 是一个只用于 SDK 的薄 provider 边界，负责 query 阶段的直接 chat completion。它适合接本地模型、内部模型网关、重试、超时、日志和测试 mock。ragbox 不会从配置文件动态加载 provider 插件；CLI 仍然使用 flags、config 和环境变量里的 OpenAI-compatible 设置。

包根入口导出稳定的产品化 SDK API。底层工具仍保留在 advanced namespace，适合更定制的集成：

const { advanced } = require("@bndynet/ragbox");

const location = await advanced.resolveQueryIndexLocation("/var/lib/ragbox/docs-index");

查询时发生了什么

简单说，ragbox 会保留文档结构，而不是一开始就把所有内容切成匿名 chunk：

• 每个 .md/.mdx 文件会生成一棵结构化 PageIndex 树
• 文档目录会生成一份索引清单
• 查询时先选择可能相关的文档，再选择文档里的相关章节
• 最终回答只基于选中的章节正文生成

所以 --trace 能告诉你选了哪些文档和节点。基础流程也因此不需要部署向量数据库。

与传统 Vector DB RAG 的对比

传统 Vector RAG 通常会切 chunk、做 embedding，再按向量相似度召回。ragbox 则优先保留源文档层级，并让 LLM 基于这棵结构树做选择。

| 维度 | Vector DB RAG | ragbox | | --- | --- | --- | | 索引单位 | 文本 chunk | Markdown/MDX 文件和 PageIndex 节点 | | 检索信号 | 向量相似度 | LLM 基于文档树和节点树选择 | | 存储 | 向量数据库加文档存储 | 输出目录下的本地 JSON 文件 | | 上下文形态 | 扁平 chunk 列表 | 带文件路径和 node id 的结构化节点 | | 优势 | 大规模模糊召回快 | 保留文档层级，引用来源更清晰 | | 取舍 | 需要 embedding 和索引基础设施 | 依赖 PageIndex 质量和 LLM 选择效果 |

两种方式也可以组合：先用向量检索做大范围候选召回，再用 PageIndex 树做结构化过滤、上下文组织和引用生成。

常见问题

• PAGEINDEX_CLI is required to run PageIndex：运行 ragbox setup pageindex，或设置 PAGEINDEX_CLI=/path/to/run_pageindex.py
• OPENAI_API_KEY is required for query：在私有 ragbox.config.json 里添加 llm.apiKey，或设置 OPENAI_API_KEY，也可以临时传 --api-key
• Expected a docs folder... or a ragbox output directory：query 的第一个参数可以传带 .pageindex/ 的 docs 目录，也可以直接传索引输出目录
• PageIndex completed but no generated JSON result was found：默认情况下，ragbox 会读取 PageIndex 写到 results/ 里的 JSON。如果你使用的自定义 wrapper 只支持显式输出路径，把 PAGEINDEX_OUTPUT_ARG 或 pageIndex.outputArg 设置成它的输出路径参数名。

限制

• 需要你本地已经安装并配置 PageIndex；ragbox setup pageindex 可以准备默认的本地 checkout 和虚拟环境
• 查询质量依赖 PageIndex JSON 结构和所使用的 LLM
• 当前基础流程是树结构选择，不是向量检索

贡献者开发

npm install
npm run build
npm run ragbox -- --help

Examples

可运行的本地 fixture 和 smoke-test 命令都放在 examples/README.md。需要用真实 PageIndex 和 LLM 配置验证 index、query、多 source 或 start 服务循环时，看那里即可。