Xberg Python 实战：用 `url.mode = “document“` 从远程 URL 提取文本文档

• 后端
• AI 应用
• NLP

本篇指南围绕 xberg（以 Rust 为核心的 Polyglot 文档智能引擎）的 Python 绑定，讲解如何通过ExtractInput(kind="uri")将一个远程文本文档的 URL 直接交给extract()异步接口，配合ExtractionConfig.from_json('{"url":{"mode":"document"}}')指定 URL 提取模式，最终读取results[0].content与summary.remote_urls。读完本文，你将掌握 xberg Python API 下"按文档模式拉取远程 URL 并结构化提取"的最小可运行方案，以及UrlExtractionConfig中与文档下载相关的关键参数如何影响实际行为。

适用场景与运行前提

xberg 的 URL 提取支持两类形态：把 URL 当作待抓取的网页（爬取模式），或把 URL 当作指向某份文档的地址（文档模式）。本文聚焦后者：目标地址返回的是text/plain之类的文本/文档内容，而非 HTML 页面本身。典型场景包括：

• 从公开文本仓库、日志服务或 API 端点直接提取纯文本正文；
• 按固定地址批量消费远程文档（配合extract_batch的 URI 输入）；
• 在 RAG/知识库流水线中，把"文档所在 URL"作为输入来源，而不是先把文件下载到本地。

运行前提与注意事项：

• 需要安装 xberg 的 Python 包（对应仓库中的 packages/python），其__init__.py、api.py通过xberg._xberg这一 Rust 原生绑定暴露extract、ExtractInput、ExtractionConfig等符号；
• side_effect: server表明该场景依赖可访问的 HTTP(S) 服务：目标 URL 必须能被运行 xberg 的进程访问；
• 示例使用asyncio.run()驱动，因为extract是协程接口，需要事件循环。

最小可运行示例（来自官方片段）

下面的代码取自仓库自动生成的 Python 片段 docs-site/src/snippets-generated/python/url/url_remote_text_document.md（由 alef 工具链生成，内容与 fixtures/url/url_remote_text_document.json 保持一致），它是本文讨论的核心骨架：

import asyncio from xberg import extract, ExtractInput, ExtractInputKind from xberg._xberg import ExtractionConfig async def main() -> None: input = ExtractInput(kind=ExtractInputKind("uri"), uri="https://example.com") config = ExtractionConfig.from_json("{\"url\":{\"mode\":\"document\"}}") result = await extract(input, config) print(result.results[0].content) print(result.summary.remote_urls) asyncio.run(main())

把其中的uri替换为实际的目标地址（例如某个返回纯文本的端点），即可跑通一次"远程文本文档"的提取。

输入构造：ExtractInput 与 ExtractInputKind

ExtractInput是提取请求的输入载体，kind字段决定输入类型。示例中ExtractInputKind("uri")明确将输入声明为 URL 形式，随后通过uri="https://example.com"给出地址。与之并列的还有 bytes 等输入类型，用于直接传二进制内容；选用uri意味着整个下载与解码流程由 xberg 内部的 URL 管线负责。

在 Python 绑定中，ExtractInput及相关配置类型定义于 packages/python/xberg/options.py，底层类型签名可从 packages/python/xberg/_xberg.pyi 的类型桩查看。ExtractInputKind作为 Rust 侧pyclass枚举暴露给 Python，ExtractInput(kind=..., uri=...)的写法等价于把一条"URI 类型输入"送入提取管线。

核心配置：url.mode 与 UrlExtractionConfig

示例中的ExtractionConfig.from_json('{"url":{"mode":"document"}}')是全程最关键的一行——它把 URL 提取模式显式设为document。

三种模式的含义

从 packages/python/xberg/_xberg.pyi 的类型桩可以看到UrlExtractionMode枚举包含三个成员：

• AUTO（默认）：由 xberg 根据 URL/响应内容自动决定按网页还是按文档处理；
• DOCUMENT：把 URL 当作文档地址，直接下载并提取，即本文场景；
• CRAWL：把 URL 当作种子页面进行爬取。

对应到 packages/python/xberg/options.py 中的UrlExtractionConfig，其mode字段默认值为"auto"。显式指定"document"的好处是行为确定：无论响应是什么内容类型，都走"下载→识别格式→提取"的文档管线，避免被误判为需要渲染的网页。

UrlExtractionConfig 关键参数

UrlExtractionConfig提供以下可直接在配置 JSON 中覆盖的字段（默认值与说明见 packages/python/xberg/options.py）：

嵌套 CrawlConfig 中的文档相关项

UrlExtractionConfig.crawl可嵌套传入CrawlConfig（同文件 packages/python/xberg/options.py）。与"远程文档下载"强相关的字段包括：

• download_documents: bool = True：是否下载非 HTML 文档（PDF、DOCX、图片、代码等）。默认开启，这正是 document 模式能拿到正文的前提之一；
• document_max_size: int | None = 52428800：单个文档下载的大小上限，默认 50 MB；
• document_mime_types: list[str] = []：允许下载的 MIME 类型白名单，为空时使用内置默认集；
• document_output_dir/document_content_encoding：将下载字节流式写盘或编码进内存的选项；
• ssrf：出站网络请求的 SSRF 策略，默认拒绝访问私网地址、仅允许 http/https、最多跟随 5 次重定向。

这些参数说明，即便使用最简配置，xberg 也内置了体积上限与 SSRF 防护等安全边界，适合直接接入不可信 URL 场景。

结果解读：content 与 summary.remote_urls

调用await extract(input, config)返回的result中，本例只使用了两处：

• result.results[0].content：第一个提取结果的正文字符串。对于纯文本文档，即为下载到的正文内容；
• result.summary.remote_urls：本次提取中实际访问的远程 URL 数量（汇总字段）。

测试夹具 fixtures/url/url_remote_text_document.json 对此做了明确断言：

{ "mock_responses": [ { "path": "/", "method": "GET", "status_code": 200, "headers": { "content-type": "text/plain; charset=utf-8" }, "body_inline": "Remote document hello from Xberg URL e2e.\n" } ], "assertions": [ { "type": "not_error" }, { "type": "contains", "field": "results[0].content", "value": "Remote document hello" }, { "type": "equals", "field": "summary.remote_urls", "value": 1 } ] }

可见标准行为是：对返回text/plain的端点，xberg 下载正文写入results[0].content，并把这次远程访问计入summary.remote_urls。当文档内部还链接了其他文档、且配置允许跟随时，该计数会相应增长，可用于观测一次提取实际触发了多少次网络请求。

底层实现与测试佐证

• 入口函数：extract是api.py中定义的async def extract(...)（见 packages/python/xberg/api.py），它与extract_batch、extract_with_external_redaction共同构成 Python 侧公共 API；
• 原生绑定：ExtractionConfig.from_json经由xberg._xberg（Rust 原生模块）解析 JSON 并构建配置，Python 侧仅做轻量封装，因此配置字段与 Rust 侧保持一致；
• 端到端验证：本示例对应的端到端用例由仓库的 mock server 驱动（参见 scripts/e2e/run-with-mock-server.sh），夹具模拟了GET /返回text/plain; charset=utf-8的响应，再断言提取结果与remote_urls计数，保证文档所展示的写法在真实调用链路上可复现。

常见调整

• 不指定 mode：省略url配置时走auto模式，xberg 根据响应内容自动决策；对内容类型明确、仅需正文的场景，显式document更稳妥；
• 多文档跟随：若希望提取结果中记录的remote_urls覆盖文档内链接的多个文件，可配合CrawlConfig.follow_document_urls与document_url_depth控制跟随深度与范围；
• 受限网络环境：通过CrawlConfig.ssrf、document_max_size、document_mime_types收紧下载边界；内网部署时注意默认 SSRF 策略会拒绝私网地址，需按需显式配置放行。

综上，url.mode = "document"是 xberg Python 绑定中"URL 即文档源"的标准开关：一行 JSON 配置，配合ExtractInput(kind="uri")与extract()协程调用，即可把远程文本文档纳入统一的提取流水线，并从summary.remote_urls观察网络触达情况。仓库中的 fixtures/url/url_remote_text_document.json 与 docs-site/src/snippets-generated/python/url/url_remote_text_document.md 是可直接对照验证的官方样例。

• 后端
• AI 应用
• NLP