xberg Python 实战：用 extract 接口从 PDF 中提取文本与元数据

后端AI 应用NLP【免费下载链接】xbergPolyglot document intelligence with a Rust core: extract text, metadata, images, tables, and structured data from 106 formats across 140 file extensions, plus code intelligence for 371 languages. Fifteen bindings, with CLI, REST API, and MCP server.项目地址https://gitcode.com/gh_mirrors/kr/xberg点击查看免费下载在 xberg 的 Python 绑定中所有提取入口extract、extract_batch、extract_with_external_redaction都围绕同一个统一的输入类型ExtractInput展开。本篇以仓库中 Python 示例片段 format_pdf_text.md 为核心讲清楚如何用一条extract调用完成「从远程 URI 下载 PDF 并提取纯文本」这一最常见的文档摄取场景并结合 packages/python/xberg/options.py 与 packages/python/xberg/api.py 的源码解释每个输入字段的作用、底层转换链路以及该示例对应的端到端测试与断言依据帮你把这段最小示例扩展为可落地的 PDF 文本提取方案。核心示例一行 extract 完成 PDF 文本提取该示例片段对应 format_pdf_text.md完整代码如下import asyncio from xberg import extract, ExtractInput, ExtractInputKind async def main() - None: input ExtractInput(filenamefake_memo.pdf, kindExtractInputKind(uri), mime_typeapplication/pdf, urihttps://example.com/pdf/fake_memo.pdf) result await extract(input) print(result.results[0].metadata) asyncio.run(main())这段代码做的事情很直接构造一个ExtractInput声明文档来源是一个 HTTP(S) URI并给出application/pdf的 MIME 提示与文件名提示以await extract(input)触发提取打印第一个提取结果的metadata文档元数据如标题、作者、页数等 PDF 信息字段。有两点需要特别注意extract是异步函数。从源码看api.py 中extract的定义是async def extract(input, config) - ExtractionResult它最终调用 Rust 绑定_rust.extract(...)因此必须运行在事件循环中示例用asyncio.run(main())驱动。config参数是可选的。该示例没有传ExtractionConfig即使用默认配置提取。如果需要控制输出格式如 markdown、页码范围、OCR 开关等可以把配置作为第二个参数传入await extract(input, config)。解析 ExtractInput每个字段到底控制什么ExtractInput是 Python 绑定中所有公共提取入口的统一输入类型其定义见 options.py。逐字段拆解如下字段类型默认值说明kindExtractInputKind \| struri来源类型。bytes要求提供bytesuri要求提供uribytesbytes \| NoneNone当kindbytes时的原始文档字节uristr \| NoneNone当kinduri时的本地路径、file://URI 或 HTTP(S) URLmime_typestr \| NoneNoneMIME 类型提示用于选择提取器filenamestr \| NoneNone文件名提示用于 MIME 检测与元数据configFileExtractionConfig \| NoneNone针对单份输入的提取覆盖配置per-input overrides对照示例代码各字段的取值意图是kindExtractInputKind(uri)ExtractInputKind是一个带BYTES/URI成员的枚举见 _xberg.pyi构造时可以直接传字符串uri或bytes。Python 侧的_to_rust_extract_input会把它统一强转为 Rust 绑定的枚举再交给核心处理urihttps://example.com/pdf/fake_memo.pdf文档来自网络 URL。由于uri同时支持本地路径与file://形式这段代码里的 URL 换成./memo.pdf就能改为读本地文件其余逻辑不变mime_typeapplication/pdf显式告诉核心这是一个 PDF避免歧义。对于 PDF这是准确的 MIME 类型filenamefake_memo.pdf文件名提示。除了辅助 MIME 检测它还会进入文档元数据方便在批量结果中区分来源。另外ExtractInput还提供了from_json(json_str)类方法可以直接从 JSON 字符串构造输入对象例如从配置中心或上游 JSON 消息体加载这对于批处理管线很实用。底层链路Python 输入如何进入 Rust 核心从源码结构看Python 层的extract只是一个薄的类型转换层真正的提取发生在 Rust 核心中。以 api.py 的调用链为例_to_rust_extract_input(value)如果传入的是str先json.loads解析如果是dict则对kind做枚举强转_coerce_enum、对config做FileExtractionConfig转换再构造ExtractInputasync def extract(input, config)把 Python 对象转成_rust.ExtractInput与_rust.ExtractionConfigconfig 为None时传入默认的ExtractionConfig()然后await _rust.extract(...)得到ExtractionResult。这意味着Python 层对输入做了容错处理——dict、JSON 字符串、ExtractInput实例三种形式都能接受类型一致性由 Rust 绑定保证results、content、metadata等返回结构在所有语言绑定间保持同构这也是该示例可以直接映射到其他语言片段如 format_pdf_text.md、format_pdf_text.md的原因。同类入口还有extract_batch一次传入list[ExtractInput]共享同一份ExtractionConfig见 api.py——当你有一批 PDF 要摄取时用extract_batch替代多次extract即可。结果结构content、metadata 与批量 summary示例打印的是result.results[0].metadata而extract返回的ExtractionResult还包含更多可用信息result.results[i].content提取出的文本正文。对于默认配置的 PDF 输入就是逐页文本的拼接结果result.results[i].metadata文档元数据标题、作者、页数等PDF 这类自带元信息头的格式通常都能提取到result.summary.results批量场景下的结果数量统计参见通用示例 extract.mdimport asyncio from xberg import ExtractInput, extract async def main() - None: output await extract(ExtractInput(kinduri, uridocument.pdf)) print(output.results[0].content) print(fResults: {output.summary.results}) asyncio.run(main())也就是说同一个extract调用既能满足「只要正文」的场景读content也能满足「要文档信息」的场景读metadata无需切换 API。端到端验证fixture 与断言说明了什么该示例不是孤立的代码片段它在仓库中有一份对应的测试 fixtureformat_pdf_text.json。从中可以看到这个场景的完整契约输入契约kind: uri、mime_type: application/pdf、filename: fake_memo.pdfURI 指向一个 mock 服务器路径/pdf/fake_memo.pdf响应体为仓库测试文档test_documents/pdf/fake_memo.pdfContent-Type 为application/pdf。这说明示例中的example.comURL 在 CI 里是被 mock 服务器替代的本地 PDF断言契约结果不得为错误not_errorresults[0].content长度至少 50正文必须包含Mallori或May之一。这三条断言精确界定了「PDF 文本提取成功」的最低标准——提取出的确实是这份备忘录的可读文本而不是空串或乱码。对应的 Python 端到端测试是 test_format_specific.py 中的test_format_pdf_text它从环境变量MOCK_SERVER_URL拼出 fixture 地址把 JSON 输入反序列化为ExtractInput后执行await extract(input)与示例片段使用的是完全一致的调用方式。该测试文件由仓库的 alef 工具链统一生成文件头标注auto-generated by aleffixture、文档片段与 e2e 测试三者保持同构这也是仓库示例可以放心直接复制到生产代码的原因。使用前提与常见变体结合上面的源码与测试依据落地这段代码时需要确认的前提安装使用 xberg 的 Python 包xberg示例依赖的extract、ExtractInput、ExtractInputKind均从顶层包导出见 packages/python/xberg/init.py网络前提kinduri且uri为 HTTP(S) 地址时运行时需要能访问该 URL本地文件则可直接传路径无需起服务器异步前提extract必须在事件循环内执行配置前提示例未传ExtractionConfig走默认提取策略。若要输出 markdown、限制页码pages配置、开启 OCR扫描件 PDF或调整输出格式可参考同目录的其他配置示例如 config_pages.md 所在的配置系列并作为extract的第二个参数传入。常见的三个变体# 1. 读本地文件uri 直接给路径 local_input ExtractInput(kinduri, uri./memo.pdf, filenamememo.pdf) # 2. 直接读内存字节省去 MIME/文件名猜测的麻烦 bytes_input ExtractInput( kindbytes, bytesopen(memo.pdf, rb).read(), mime_typeapplication/pdf, filenamememo.pdf, ) # 3. 批量摄取一次传多个输入 from xberg import extract_batch batch_result await extract_batch([local_input, bytes_input])三个变体分别对应「本地路径」「内存字节」「多文档并发」三类真实场景底层都汇入同一条_to_rust_extract_input - _rust.extract链路因此行为与断言标准与主示例完全一致。小结extract(ExtractInput(...))是 xberg Python 绑定中提取单份文档包括 PDF 纯文本的主入口配合metadata/content即可同时拿到文档信息与正文ExtractInput的kind/uri/bytes/mime_type/filename五个字段决定了文档从哪来、按什么格式解析ExtractInputKind支持uri与bytes两种来源示例对应的 fixture format_pdf_text.json 与 e2e 测试 test_format_specific.py 给出了该场景的输入契约与成功断言正文长度、关键词命中可作为回归验证的参照。赞分享后端AI 应用NLP【免费下载链接】xbergPolyglot document intelligence with a Rust core: extract text, metadata, images, tables, and structured data from 106 formats across 140 file extensions, plus code intelligence for 371 languages. Fifteen bindings, with CLI, REST API, and MCP server.项目地址https://gitcode.com/gh_mirrors/kr/xberg点击查看免费下载相关推荐xberg C FFI 实战用 extract 接口从 URI 提取 PPTX 演示文稿内容xberg C FFI 实战用 extract 接口从 URI 提取 PPTX 演示文稿内容 本篇以 xberg 仓库中自动生成的 C 语言 E2E 示例 f后端AI 应用NLPxberg Python 绑定实战用 extract 接口完成 DOCX 文档的独立文本抽取xberg Python 绑定实战用 extract 接口完成 DOCX 文档的独立文本抽取 本文基于 xberg 文档站自动生成的 Python 代码片段后端AI 应用NLPxberg Python 绑定实战用 bytes 输入调用 extract 完成内存中 PDF 文档提取xberg Python 绑定实战用 bytes 输入调用 extract 完成内存中 PDF 文档提取 本篇围绕 xberg 仓库中自动生成的 Python后端AI 应用NLP上一篇DLSS Swapper游戏性能优化的智能管家一键升级你的游戏体验下一篇DLSS Swapper终极指南如何一键升级游戏DLSS/FSR/XeSS版本提升性能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考