xberg-io/xberg · 上手攻略

  • 仓库：xberg-io/xberg
  • 链接：https://github.com/xberg-io/xberg
  • 分类：AI 工程 / 文档智能 / RAG 数据准备
  • 作者：Jay
  • 更新：2026-09-12

这是什么

Xberg 是用 Rust 编写的多格式文档智能提取引擎，下一代 Kreuzberg v4。声称支持 107 种文档格式 / 141 种文件扩展名 / 371 种编程语言，提供 15 种语言绑定（Python、Node.js、Rust、Go、Java、C#、Ruby、PHP、Elixir、Dart、Swift、Zig、WASM、Kotlin、C FFI），零 GPU 依赖，CPU 默认运行，GitHub Stars 9,293。

核心卖点：一份引擎搞定格式检测 → 文本读取 → OCR → 表格识别 → 代码结构提取 → 结构化输出，不再需要拼凑多个库。

解决什么问题

RAG 管道和文档处理流水线中，开发者通常要串联 PDF 库 + Word 库 + OCR 库 + HTML 解析库。Xberg 把全流程收敛到一个 API，从任意文档进、结构化内容出。适合：RAG 代码知识库构建、AI Agent 文档摄取、多语言 OCR、音频转写、代码结构索引。

快速安装

CLI（最快尝鲜）

# macOS / Linux
brew install xberg-io/tap/xberg

# Windows（Scoop）
scoop bucket add xberg https://github.com/xberg-io/scoop-bucket
scoop install xberg

# Docker（All-in-One）
docker pull ghcr.io/xberg-io/xberg:latest
docker run -p 8000:8000 ghcr.io/xberg-io/xberg:latest xberg serve --host 0.0.0.0 --port 8000

Python / Node.js / Rust / Go

pip install xberg                     # Python
npm install @xberg-io/xberg           # Node.js
cargo add xberg                       # Rust
go get github.com/xberg-io/xberg/packages/go@latest   # ⚠️ 必须指定 /packages/go

⚠️ Go 包路径必须带 /packages/go，直接 go get github.com/xberg-io/xberg 会失败。Python 包名是 xberg（不是 @xberg-io/xberg，那是 npm 的命名空间）。

核心用法

CLI 提取

xberg extract document.pdf                     # 单文件，输出 Markdown
xberg extract document.pdf --output-format json  # 输出 JSON
xberg batch ./docs/ --output ./output/         # 批量处理
xberg formats                                  # 查看支持格式
xberg doctor                                   # 健康检查

CLI 共 14 条命令：extract、batch、detect、formats、version、cache、tree-sitter、doctor、serve、mcp、api、embed、chunk、completions。

Python API

import asyncio
from xberg import ExtractInput, extract

async def main():
    output = await extract(ExtractInput(kind="uri", uri="document.pdf"))
    print(output.results[0].content)

asyncio.run(main())

REST API Server

xberg serve --host 0.0.0.0 --port 8000
# POST http://localhost:8000/  body: { "uri": "document.pdf" }

MCP Server（AI Agent 集成）

xberg mcp --transport stdio

Claude Desktop 配置（~/.claude_desktop_config.json）：

{ "mcpServers": { "xberg": { "command": "xberg", "args": ["mcp"] } } }

提供 9 个工具（extract、extract_batch、detect_mime_type、cache_stats 等）和 3 个提示词模板。

输出格式

支持 6 种：plain（纯文本）、markdown（RAG 最友好）、djot、html、json（树结构）、doctags（Docling 兼容）。

代码智能（RAG 分块用）

xberg tree-sitter ./src/  # 提取函数/类/import/docstring，371 种语言

典型适用场景

  • RAG 文档批量入库：PDF/Word/HTML → Markdown，xberg batch 跑目录
  • 扫描件 OCR：Tesseract / PaddleOCR 多后端链式 fallback
  • 代码库结构检索：tree-sitter 提取 371 语言语义块
  • AI Agent 读文档：MCP Server + Claude Desktop / Cursor / Gemini CLI
  • 音频转写：Whisper ONNX（需 --features transcription）处理 MP3/M4A/WAV
  • 学术论文结构提取：LaTeX、JATS、PubMed XML 支持

坑与注意

  1. Go 包路径必须带 /packages/go：go get github.com/xberg-io/xberg 会失败，官方文档用红色警告标出。

  2. 功能需要 Cargo feature flag：部分能力（url-ingestion、transcription、reranker、layout/ORT）需要从源码编译时显式启用。预编译 Docker 镜像已包含常用集。

  3. Python vs Node.js 包名不同：pip install xberg ≠ npm install @xberg-io/xberg，两者分别对应不同语言绑定，不要混用。

  4. Xberg Layout ≠ Xberg：benchmark 有两个独立条目——"Xberg"是纯 Rust 核心（快），"Xberg Layout"含 ML 布局模型（慢但布局重建更准）。默认指前者。

  5. benchmark 数据来自官方：性能对比由 xberg.io/benchmarks 发布，未经第三方独立验证。数字方向可信，但横向对比时建议自行复测。

  6. OCR 需额外模型：Tesseract / PaddleOCR / Candle 需要各自模型文件，VLM 后端需要 LLM API，默认不带。

  7. 音频转写需 feature flag：默认二进制不包含 Whisper，需要 --features transcription 重新编译或用对应 Docker 镜像。

与同类对比

方案 吞吐量 冷启动 内存 适合场景
Xberg 1.03 MB/s #1 64ms #1 39 MB RAG 管道、AI Agent 文档摄取
LiteParse 0.99 MB/s 76ms 17 MB 轻量高速提取
Tika 0.03 MB/s 1.6s 158 MB 企业格式兼容广
Unstructured 0.01 MB/s 23.4s 1.02 GB 生态成熟但重
Docling 0.00 MB/s 27.2s 1.57 GB ML 布局重建优先
MinerU — — 2.65 GB PDF 精度高但体积大

Benchmark 结论（native PDFs，p50）： - 吞吐 Xberg #1（1.03 MB/s） - 冷启动 Xberg #1（64ms） - 可靠性 Xberg 100%（#1） - 质量 F1 Xberg 0.98（与 Unstructured 并列第一）

一句话推荐结论

如果你在构建 RAG 管道或 AI Agent 文档摄取，需要一个零 GPU、启动极快、支持格式最广的 Rust 原生文档提取引擎，选 Xberg；如果更看重 ML 布局重建精度且能接受更慢的冷启动，开 Xberg Layout 模式。