xberg

Xberg 文档提取

Xberg 是一个文档智能库，采用 Rust 核心，并提供 Python、TypeScript/Node.js、Ruby、PHP、Go、Java、C#、Elixir、WebAssembly、Dart、Kotlin Android、Swift、Zig 和 C 绑定。它可从 140 种独特文件扩展名对应的 107 种格式中提取文本、表格、元数据和图像，并支持 53 个兼容 MIME 别名，涵盖 PDF、Office 文档、图像、HTML、电子邮件、归档文件和学术格式。

在编写以下代码时使用此技能：

• 从文档中提取文本或元数据
• 对扫描文档或图像执行 OCR
• 批量处理多个文件
• 配置提取选项（输出格式、分块、OCR、语言检测）
• 实现自定义插件（后处理器、验证器、OCR 后端）

如果此会话中已注册 xberg MCP 服务，请优先使用其工具，而不是通过 shell 调用 CLI — 它们提供相同的提取功能，并使用结构化参数和结果。

安装

Python

pip install xberg

Node.js

npm install @xberg-io/xberg

Rust

cargo add xberg

# Cargo.toml
[dependencies]
xberg = { version = "1.1.0", features = ["full"] }
tokio = { version = "1", features = ["full"] }
# feature flags: pdf, ocr, chunking, embeddings, language-detection, keywords, api, mcp
#                (or "formats" / "full" aggregates); tokio-runtime is on by default

CLI

brew install xberg-io/tap/xberg
# or run without a persistent install (the CLI proxy package self-installs the binary):
npx @xberg-io/[email protected] --help
uvx --from xberg-cli==1.3.8 xberg --help
# or download a prebuilt binary from the latest GitHub release:
#   https://github.com/xberg-io/xberg/releases/latest
# or build from source:
cargo install xberg-cli

快速入门

该库的入口点为 extract(input, config) 和 extract_batch(inputs, config)。两者均返回一个 ExtractionResult 封装对象 — 提取的文档位于 result.results 中，每个文档的数据（content、tables、metadata 等）位于各自的 result.results[i] 中。Python 和 Node 仅支持异步操作。

Python

import asyncio
from xberg import ExtractInput, extract, ExtractionConfig

async def main() -> None:
    result = await extract(ExtractInput(uri="document.pdf"), ExtractionConfig())
    doc = result.results[0]
    print(doc.content)    # extracted text
    print(doc.metadata)   # document metadata
    print(doc.tables)     # extracted tables

asyncio.run(main())

Node.js

import { extract } from "@xberg-io/xberg";

const output = await extract({ kind: "uri", uri: "document.pdf" });
const doc = output.results[0];
console.log(doc.content);
console.log(doc.metadata);
console.log(doc.tables);

Rust

use xberg::{extract, ExtractInput, ExtractionConfig};

#[tokio::main]
async fn main() -> xberg::Result<()> {
    let output = extract(ExtractInput::from_uri("document.pdf"), &ExtractionConfig::default()).await?;
    println!("{}", output.results[0].content);
    Ok(())
}

CLI

xberg extract document.pdf
xberg extract document.pdf --format json
xberg extract document.pdf --content-format markdown

配置

所有语言使用相同的配置结构，并遵循各语言惯用的命名约定。

Python（snake_case）

from xberg import (
    ExtractInput, extract,
    ExtractionConfig, OcrConfig, TesseractConfig, PdfConfig, ChunkingConfig, OutputFormat,
)

config = ExtractionConfig(
    ocr=OcrConfig(
        backend="tesseract",
        language=["eng"],
        tesseract_config=TesseractConfig(psm=6, enable_table_detection=True),
    ),
    pdf_options=PdfConfig(passwords=["secret123"]),
    chunking=ChunkingConfig(max_characters=1000, overlap=200),
    output_format=OutputFormat("markdown"),
)

result = await extract(ExtractInput(uri="document.pdf"), config)

Node.js（camelCase）

import { extract, type ExtractionConfig } from "@xberg-io/xberg";

const config: ExtractionConfig = {
  ocr: { backend: "tesseract", language: ["eng"] },
  pdfOptions: { passwords: ["secret123"] },
  chunking: { maxCharacters: 1000, overlap: 200 },
  outputFormat: "markdown",
};

const output = await extract({ kind: "uri", uri: "document.pdf" }, config);

Rust（snake_case）

use xberg::{extract, ExtractInput, ExtractionConfig, OcrConfig, ChunkingConfig, OutputFormat};

let config = ExtractionConfig {
    ocr: Some(OcrConfig {
        backend: "tesseract".into(),
        language: vec!["eng".to_string()],
        ..Default::default()
    }),
    chunking: Some(ChunkingConfig {
        max_characters: 1000,
        overlap: 200,
        ..Default::default()
    }),
    output_format: OutputFormat::Markdown,
    ..Default::default()
};

let output = extract(ExtractInput::from_uri("document.pdf"), &config).await?;

配置文件（TOML）

output_format = "markdown"

[ocr]
backend = "tesseract"
language = "eng"

[chunking]
max_characters = 1000
overlap = 200

[pdf_options]
passwords = ["secret123"]

# CLI: auto-discovers xberg.toml/yaml/yml/json in current/parent directories
xberg extract doc.pdf
# or explicit:
xberg extract doc.pdf --config xberg.toml
xberg extract doc.pdf --config-json '{"ocr":{"backend":"tesseract","language":"deu"}}'

批量处理

extract_batch 接收一个 ExtractInput 列表，并返回一个封装对象，其 results 数组按发现顺序保存文档；一个输入可能会生成多个文档。每个输入的失败会记录在 result.errors 中，并附带输入索引。

Python

from xberg import ExtractInput, extract_batch, ExtractionConfig

inputs = [
    ExtractInput(uri="doc1.pdf"),
    ExtractInput(uri="doc2.docx"),
    ExtractInput(uri="doc3.xlsx"),
]
output = await extract_batch(inputs, ExtractionConfig())

for doc in output.results:
    print(f"{len(doc.content)} chars extracted")

Node.js

import { extractBatch } from "@xberg-io/xberg";

const output = await extractBatch([
  { kind: "uri", uri: "doc1.pdf" },
  { kind: "uri", uri: "doc2.docx" },
]);
for (const doc of output.results) {
  console.log(`${doc.content.length} chars`);
}

Rust

use xberg::{extract_batch, ExtractInput, ExtractionConfig};

let config = ExtractionConfig::default();
let inputs = vec![ExtractInput::from_uri("doc1.pdf"), ExtractInput::from_uri("doc2.docx")];
let output = extract_batch(inputs, &config).await?;

CLI

xberg batch *.pdf --format json
xberg batch docs/*.docx --content-format markdown

OCR

OCR 会自动处理图像和扫描版 PDF。默认后端为 Tesseract（原生绑定，无需外部安装）。

后端

使用 OcrConfig.backend 选择：

• tesseract（默认）：内置原生绑定。支持所有 Tesseract 语言。
• paddleocr（"paddleocr" / "paddle-ocr"）：基于 ONNX 的 PaddleOCR。
• vlm：视觉语言模型 OCR（通过 OcrConfig.vlm_config 配置）。

可在 Python/Node 中通过 register_ocr_backend 注册自定义后端（参见高级功能）。

语言代码

config = ExtractionConfig(ocr=OcrConfig(language=["eng"]))          # English
config = ExtractionConfig(ocr=OcrConfig(language=["eng", "deu"]))   # Multiple
# The single-string shorthand ("eng+deu") is only accepted in config files / --config-json,
# not in the OcrConfig constructor (Python takes a list, Node takes an array).

强制使用 OCR

config = ExtractionConfig(force_ocr=True)  # OCR even if text is extractable

结果封装与文档字段

extract / extract_batch 返回一个 ExtractionResult 封装：results（文档列表）、errors（每个输入的失败信息）和 summary（计数）。每个文档的字段位于 results 中的对应文档上——先绑定 doc = result.results[0]（Python/Node）或 &output.results[0]（Rust）。

字段	Python（doc.）	Node.js（doc.）	Rust（document.）	说明
文本内容	content	content	content	提取的文本（str/String）
MIME 类型	mime_type	mimeType	mime_type	输入文档的 MIME 类型
元数据	metadata	metadata	metadata	文档元数据（扁平映射）
表格	tables	tables	tables	提取的表格，包含单元格和 Markdown
语言	detected_languages	detectedLanguages	detected_languages	检测到的语言（如果已启用）
分块	chunks	chunks	chunks	文本块（如果已启用分块）
图像	images	images	images	提取的图像（如果已启用）
元素	elements	elements	elements	语义元素（如果格式为 element_based）
页面	pages	pages	pages	每页内容（如果已启用页面提取）
关键词	extracted_keywords	extractedKeywords	extracted_keywords	提取的关键词（如果已启用）

错误处理

Python

失败时，extract / extract_batch 会抛出普通的 RuntimeError——这些入口不会抛出类型化的 XbergError 子类，因此请捕获 RuntimeError。extract_batch 期间每个输入的失败会以非致命错误的形式报告在 result.errors 中。

from xberg import ExtractInput, extract, ExtractionConfig

try:
    result = await extract(ExtractInput(uri="file.pdf"), ExtractionConfig())
    for err in result.errors:
        print(f"Per-input error: {err}")
except RuntimeError as e:
    print(f"Extraction failed: {e}")

Node.js

Node 绑定会抛出普通的 Error 对象（不会导出类型化的错误子类）。使用 instanceof Error 捕获，并检查 output.errors 中非致命的单输入失败。

import { extract } from "@xberg-io/xberg";

try {
  const output = await extract({ kind: "uri", uri: "file.pdf" });
  if (output.errors.length > 0) {
    console.error("Per-input errors:", output.errors);
  }
} catch (e) {
  if (e instanceof Error) {
    console.error(`Extraction failed: ${e.message}`);
  }
}

Rust

use xberg::{extract, ExtractInput, ExtractionConfig, XbergError};

let config = ExtractionConfig::default();
match extract(ExtractInput::from_uri("file.pdf"), &config).await {
    Ok(output) => println!("{}", output.results[0].content),
    Err(XbergError::Parsing { message, .. }) => eprintln!("Parse error: {message}"),
    Err(XbergError::Ocr { message, .. }) => eprintln!("OCR error: {message}"),
    Err(XbergError::UnsupportedFormat(mime)) => eprintln!("Unsupported: {mime}"),
    Err(e) => eprintln!("Error: {e}"),
}

常见陷阱

1. 返回结果是一个封装对象：extract / extract_batch 返回包含 results、errors 和 summary 的 ExtractionResult。每个文档的字段（content、tables、chunks 等）位于 result.results[i] 中，而不在顶层返回值中。
2. 仅支持异步：Python 和 Node 没有同步版本，始终使用 await extract(...)。Rust 的 extract 是异步的；请使用 #[tokio::main] 或异步上下文。
3. 构建输入对象：传入 ExtractInput，而不是裸路径。使用 ExtractInput(uri=...) / ExtractInput::from_uri(...)（Python/Rust）或 { kind: "uri", uri: "..." }（Node）；对于字节数据，使用 kind="bytes"，并设置 bytes / mime_type。
4. Python 的 ChunkingConfig 字段：使用 max_characters 和 overlap 构造（默认值为 1000 / 200）；这些也是可读取的属性。将配置作为字典/JSON 传入时，也接受 max_chars / max_overlap 别名。Node 使用 maxCharacters / overlap；Rust 结构体字段为 max_characters / overlap。
5. Python 错误：extract / extract_batch 失败时会抛出普通的 RuntimeError，而不是类型化的 XbergError 子类；请捕获 RuntimeError。Node 会抛出普通的 Error（没有类型化的错误子类）。
6. Rust 的 extract 签名：extract(input, &config)——配置是一个引用。默认配置请使用 &ExtractionConfig::default()。
7. CLI 中的 --format 与 --content-format：--format 控制 CLI 输出（text、json 或 toon）。--content-format 控制内容渲染（plain、markdown、djot、html、json 或 doctags）。
8. 配置文件字段名：在 TOML/YAML/JSON 配置文件中使用 snake_case——[chunking] 字段为 max_characters 和 overlap；其他字段使用 output_format、pdf_options 等名称。

支持的格式（摘要）

类别	扩展名
PDF	.pdf
Word	.docx、.docm、.doc、.dotx、.dotm、.dot、.odt、.pages、.wpd、.wp、.wp5、.wp6、.hwp、.hwpx
电子表格	.xlsx、.xlsm、.xlsb、.xls、.xla、.xlam、.xltm、.xltx、.xlt、.ods、.numbers
演示文稿	.pptx、.pptm、.ppt、.pps、.ppsx、.potx、.potm、.pot、.odp、.key
电子书	.epub、.fb2
图像	.png、.jpg、.jpeg、.gif、.webp、.bmp、.tiff、.tif、.jp2、.jpg2、.j2c、.j2k、.jpc、.jbig2、.jb2、.pnm、.pbm、.pgm、.ppm、.heic、.heics、.heif、.heifs、.hif、.avif、.avcs、.svg
标记语言	.html、.htm、.xhtml、.xht、.xml、.kml
数据	.json、.geojson、.jsonl、.ndjson、.yaml、.yml、.toml、.csv、.tsv、.dbf、.sqlite、.sqlite3、.db、.gpkg、.gpkx
文本	.txt、.adoc、.asciidoc、.vtt、.md、.markdown、.commonmark、.qmd、.rmd、.mdx、.djot、.dj、.doctags、.rst、.org、.rtf
电子邮件	.eml、.msg、.pst
压缩包	.zip、.tar、.tgz、.gz、.7z
音频/视频	.mp3、.mpga、.m4a、.wav、.webm、.mp4、.mpg4、.mp4v、.m4v、.mpeg、.mpg、.mpe、.m1v、.m2v
学术	.bib、.ris、.nbib、.enw、.tex、.latex、.typ、.typst、.jats、.nxml、.ipynb、.docbook、.dbk、.docbook4、.docbook5、.opml

CSL JSON 可通过显式 MIME 类型支持，但没有注册的文件扩展名。

请参阅 references/supported-formats.md，了解包含 MIME 类型的完整格式参考。

其他资源

特定主题的详细参考文件：

• Python API 参考 — 所有函数、配置类、插件协议及精确签名
• Node.js API 参考 — 所有函数、TypeScript 接口及工作池 API
• Rust API 参考 — 所有函数及其功能门控、结构体和 Cargo.toml 示例
• CLI 参考 — 所有命令、标志、配置优先级和退出代码
• 配置参考 — TOML/YAML/JSON 格式、自动发现、环境变量及完整架构
• 支持的格式 — 格式系列、扩展名、功能及权威的发现命令
• 高级功能 — 插件、嵌入、MCP 服务、API 服务及安全限制
• 其他语言绑定 — Go、Ruby、Java、C#、PHP、Elixir、WASM、Dart、Kotlin Android、Swift、Zig、C 和 Docker

相关技能

面向特定任务的同系列技能提供比本概览更深入的内容：

• xberg-extracting-with-ocr — OCR 后端、语言包、强制 OCR 和调优。
• xberg-extracting-tables — 感知布局的表格检测和表格模型。
• xberg-chunking — 分块大小/重叠、markdown/yaml/语义分块器和 chunk 命令。
• xberg-extracting-keywords — YAKE/RAKE 关键词、语言检测和 embed 命令。
• xberg-batch-extraction — batch 命令、--file-configs、并行处理和错误恢复。
• xberg-picking-a-format — 为每种使用场景选择 --format / --content-format。

完整文档：https://docs.xberg.io GitHub：https://github.com/xberg-io/xberg