人工智能AI 应用MCP 服务【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址https://gitcode.com/GitHub_Trending/ma/markitdown点击查看免费下载MarkItDown 是当前仓库提供的一个 Python 包与命令行工具用于把各种文件与 Office 文档转换为 Markdown供 LLM 与文本分析管线使用。本文以测试样例movie-theater-booking-2024.pdf影院订场订单及其期望输出 movie-theater-booking-2024.md 为主体完整拆解这类无边框表单 多区域表格的 PDF 是如何被还原成带管道的结构化 Markdown 的。读完本文你将掌握 MarkItDown 表单式 PDF 的转换结果形态、底层列检测算法原理以及如何在本地复现并验证这类转换。为什么表单式 PDF是表格提取的硬骨头PDF 中的表格分为两类一类是绘制了可见框线单元格边框的规则表格另一类是只靠文字对齐、没有任何边框的表单式form-style布局——例如发票、订场单、库存盘点表、体检报告。后者的行列关系完全隐含在文字的 X/Y 坐标里普通按文本流抽取的方式要么把单元格内容粘连成一行要么丢失列结构。movie-theater-booking-2024.pdf正是这类文档的代表一份 STARLIGHT CINEMAS 的影院订场订单包含订单头部、预订机构、客户、预订汇总、总计、账户代表、放映计划等多个区域其中既有键值对式的表单又有多列表格还有行内注释文本。MarkItDown 的 PDF 转换器对它输出的期望结果被固化为测试基准存入 expected_outputs/movie-theater-booking-2024.md。完整转换输出逐段解析下面这段 Markdown 就是 MarkItDown 对movie-theater-booking-2024.pdf的完整转换结果与期望输出文件逐行一致它揭示了表单式 PDF 的还原策略表格区域用|分隔的 Markdown 表呈现非表格内容保留为普通文本行。订单头部与订单信息BOOKING ORDER、Print Date、Page 1 of 1、影院品牌等头部文本按普通文本输出紧随其后的Orders区域是一个键值对表单被识别为一张表BOOKING ORDER Print Date 12/15/2024 14:30:22 Page 1 of 1 STARLIGHT CINEMAS Orders | Order / Rev: | 2024-12-5678 | | | Cinema: | | Downtown Multiplex | | ------------ | -------------- | --- | --- | ---------------- | --- | ------------------ | | Alt Order #: | SC-WINTER-2024 | | | Primary Contact: | | Sarah Johnson | Product Desc: Holiday Movie Marathon Package Location: NYC-01 | Estimate: | EST-456 | | | Region: | | NORTHEAST | | -------------------- | ----------------------- | --- | --- | ------- | --- | --------- | | Booking Dates: | 12/20/2024 - 12/31/2024 | | | | | | | Original Date / Rev: | 12/01/24 / 12/10/24 | | | | | | | Order Type: | Premium Package | | | | | |注意几个关键细节键Order / Rev:与值2024-12-5678被分配到不同单元格第二列起还预留了空单元格用于对齐右侧的Cinema:/Downtown MultiplexProduct Desc: Holiday Movie Marathon Package Location: NYC-01这一行没有进入表格而是保持为普通文本——说明算法基于列对齐情况对每一行做了表格行 / 非表格行分类每个表块都带有标准的---分隔行这是 Markdown 表头语法的一部分。预订机构Booking Agency与地址文本Booking Agency | Name: | Premier Entertainment Group | | | | | | | ---------------- | --------------------------- | --- | --- | -------------- | --- | --------- | | | | | | Billing Type: | | Net 30 | | Contact: | Michael Chen | | | | | | | | | | | Payment Terms: | | Corporate | | Billing Contact: | accountingpremierent.com | | | | | | | | | | | Commission: | | 10% | 555 Broadway Suite 1200 New York, NY 10012该区域展示了一个双栏表单左栏是机构名称/联系人/开票邮箱右栏是Billing Type、Payment Terms、Commission。两栏共用一张表、通过空单元格占位对齐而机构地址555 Broadway Suite 1200与New York, NY 10012属于整页宽度的段落文本被排除在表格之外。客户Customer信息Customer | Name: | Universal Studios Distribution | | | | | | | -------------- | ------------------------------ | --- | --- | --- | --- | --- | | Category: | Film Distributor | | | | | | | Contact Email: | bookingsuniversalstudios.com | | | | | | | Customer ID: | CUST-98765 | | | | | | | Revenue Code: | FILM-PREMIUM | | | | | |预订汇总Booking Summary与总计TotalsBooking Summary | Start Date | End Date | # Shows | Gross Amount | Net Amount | | | | ---------- | -------- | ------- | ------------ | ---------- | --- | --- | | 12/20/24 | 12/31/24 | 48 | $12,500.00 | $11,250.00 | | | Totals | Month | # Shows | Gross Amount | | Net Amount | | Occupancy | | ------------- | ------- | ------------ | --- | ---------- | --- | --------- | | December 2024 | 48 | $12,500.00 | | $11,250.00 | | 85% | | Totals | 48 | $12,500.00 | | $11,250.00 | | 85% |货币金额、占比、场次数字都被原样保留如$12,500.00、85%、48说明提取过程中单元格内容不做数值解析仅做文本切分与对齐。账户代表Account Representatives与放映计划Show Schedule DetailsAccount Representatives Representative Territory Region Start Date / End Date Commission % | Sarah Johnson | NYC Metro | NORTHEAST | 12/20/24 - 12/31/24 | | 100% | | | ------------- | --------- | --------- | ------------------- | --- | ---- | --- | Show Schedule Details Ln Screen Start End Movie Title Format Showtime Days Shows Rate Type Total 1 SCR-1 12/20/24 12/25/24 Holiday Spectacular IMAX 3D 7:00 PM Daily 12 $250 PM $3,000 (Runtime: 142 min); Holiday Season Premium 2 SCR-2 12/20/24 12/31/24 Winter Wonderland Standard 4:30 PM Daily 24 $150 MT $3,600 (Runtime: 98 min); Matinee Special 3 SCR-1 12/26/24 12/31/24 New Year Mystery 4DX 9:30 PM Daily 12 $300 PM $3,600 (Runtime: 116 min); Premium ExperienceAccount Representatives的表头行Representative Territory Region Start Date / End Date Commission %以普通文本出现说明该行未被判定为表格行数据行则进入表格。而Show Schedule Details区域比较特殊表头与三行放映数据以空格分隔的纯文本形式保留每行字段数量多且间距并不完全对齐每部影片的补充说明如(Runtime: 142 min); Holiday Season Premium紧随其后独立成行——这正是表格行 / 段落行混合布局的典型结果。Show Details 与总计行Show Details | Show Screen | Date Range | Title | Showtime | Days Type | Rate | Revenue | | ----------- | ---------- | ----- | -------- | --------- | ---- | ------- | 1 SCR-1 12/20-12/25 Holiday Spectacular 7:00 PM Daily PM $250 $3,000 This booking order is subject to cinema availability and standard terms. 2 SCR-2 12/20-12/31 Winter Wonderland 4:30 PM Daily MT $150 $3,600 All showtimes are approximate and subject to change. 3 SCR-1 12/26-12/31 New Year Mystery 9:30 PM Daily PM $300 $3,600 | Total Revenue: | | | | | | $12,500.00 | | -------------- | --- | --- | --- | --- | --- | ---------- |这里可以看到 MarkItDown 对列结构存在但行内容宽窄不一的页面采取的策略表头被格式化为带---的 Markdown 表头但具体数据行因跨列文本过长被当作普通文本行免责声明This booking order is subject to cinema availability and standard terms.与All showtimes are approximate and subject to change.则作为段落文本穿插其间最后的总计行Total Revenue: ... $12,500.00又被还原成表格。源码级原理_pdf_converter.py的表单式表格提取算法上述输出并非偶然而是 _pdf_converter.py 中一套完整的基于词坐标的列检测流程的产物。核心入口是PdfConverter.convert见_pdf_converter.py#L520-L589与_extract_form_content_from_words见_pdf_converter.py#L120-L395。逐页双路径表单页走 pdfplumber纯文本页走 pdfminerPdfConverter.convert用pdfplumber.open打开文件后逐页调用_extract_form_content_from_words(page)若该页被判定为表单式布局返回带|表格的 Markdown 片段否则记录为普通页用page.extract_text()提取纯文本每页处理完毕立即page.close()释放 pdfplumber 的缓存对象使内存占用不随页数增长若整份文档没有任何表单页则回退到pdfminer.high_level.extract_text处理全文因为它对散文类文本的间距还原更好任何异常或空结果也会回退到 pdfminer保证转换不中断。最后还有一步后处理_merge_partial_numbering_lines用于合并 MasterFormat 风格的.1、.2部分编号与后续文本行。表单检测的五步流水线_extract_form_content_from_words的核心逻辑可概括为取词与按行分组page.extract_words(keep_blank_charsTrue, x_tolerance3, y_tolerance3)拿到每个词的坐标再按 Y 坐标容差 5聚成行行内按x0排序。行类型初判行宽超过页面宽度 55% 且文本超过 60 字符判为段落行首个词匹配^\.\d$MasterFormat 部分编号判为列表项行词起点按间距 50 聚成列组得到该行列数。全局列结构学习收集所有列数 ≥ 3 且非段落的行的 X 坐标用自适应容差聚类出全局列边界先统计相邻坐标间隙取间隙的 70 百分位作为容差并夹紧到[25, 50]数据不足时回退 35。形式判定防误判平均列宽 30 像素、列密度 10 列/英寸、或列数超过max(15, 20 * page_width/612)时直接判定为不是表单返回None交给 pdfminer——这正是学术论文多栏排版不会被误当成表格的原因。行分类与表格区域还原某行若与 2 个及以上全局列对齐则标记为表格行连续表格行构成表区域表格区域内逐行按列边界把词分配到单元格输出时先格式化表头行与---分隔行再输出数据行最后用ljust对齐各列宽度表区域外的行按普通文本输出。若整个页面表格行占比不足 20%同样返回None。另外_pdf_converter.py 还提供了_extract_tables_from_words作为补充路径其列聚类容差固定为 20、要求列数在 3–10 之间、行需横跨多列、且超过 30% 的单元格文本长于 30 字符就放弃——这些启发式共同保证了只有真正的表才转成表。接受条件与依赖PdfConverter.accepts接受.pdf扩展名以及application/pdf、application/x-pdf两种 MIME 前缀见_pdf_converter.py#L70-L75。它依赖pdfplumber与pdfminer.six在 pyproject.toml 中对应[pdf]可选依赖组pdfminer.six20251230、pdfplumber0.11.9若未安装会抛出MissingDependencyException。测试如何锁死这份期望输出movie-theater-booking-2024.md之所以能作为期望输出存在是因为 test_pdf_tables.py 中有两组测试在守护它test_movie_theater_booking_pdf_extractiontest_pdf_tables.py#L654-L719断言输出包含管道符|并逐一校验订单号2024-12-5678、产品描述Holiday Movie Marathon Package、预订日期区间、备用订单号SC-WINTER-2024、影院品牌以及机构名Premier Entertainment Group、联系人Michael Chen、客户名Universal Studios Distribution、CUST-98765、金额$12,500.00/$11,250.00、影片标题与费率等关键字段。TestPdfFullOutputComparison.test_movie_theater_full_outputtest_pdf_tables.py#L730-L777直接把MarkItDown().convert()的实时输出与这份期望文件逐行对比——行数差不超过 2、管道符数量 80、---分隔行数量 8、表格行数量 15并要求五个关键片段全部命中。这种全量输出对比 关键字段校验的双层设计保证算法升级不会悄悄破坏既有输出结构。同目录下的RECEIPT、SPARSE、REPAIR、MEDRPT等期望文件与测试还覆盖了无表小票、无边框表、多页发票、扫描件等场景其中扫描件无文本层的期望输出为空字符串test_pdf_tables.py#L951-L978说明当前离线转换依赖 PDF 文本层扫描件需借助 OCR 插件仓库中另有markitdown-ocr包处理。本地复现与验证安装MarkItDown 要求 Python ≥ 3.10。安装全部可选依赖或仅安装 PDF 相关依赖均可pip install markitdown[all] # 或只装 PDF 支持 pip install markitdown[pdf]也可从仓库源码安装见 packages/markitdown/README.mdgit clone https://gitcode.com/GitHub_Trending/ma/markitdown cd markitdown pip install -e packages/markitdown[all]命令行转换markitdown packages/markitdown/tests/test_files/movie-theater-booking-2024.pdf booking.md markitdown packages/markitdown/tests/test_files/movie-theater-booking-2024.pdf -o booking.md cat packages/markitdown/tests/test_files/movie-theater-booking-2024.pdf | markitdown从标准输入读取时可用-x/--extension、-m/--mime-type、-c/--charset提供格式提示见 __main__.py。将生成的booking.md与 expected_outputs/movie-theater-booking-2024.md 对比即可验证一致性。Python APIfrom markitdown import MarkItDown md MarkItDown() result md.convert(packages/markitdown/tests/test_files/movie-theater-booking-2024.pdf) print(result.markdown) # DocumentConverterResult.markdown print(result.text_content) # 旧版别名等价于 markdownMarkItDown.convert会自动区分本地路径、URL 与二进制流字符串路径按 scheme 分发到convert_uri或convert_localrequests.Response走convert_response可读流走convert_stream见 _markitdown.py。结果对象DocumentConverterResult见 _base_converter.py除markdown外还支持title元数据与__str__。运行测试仓库测试目录位于packages/markitdown/tests可直接运行 PDF 表格相关测试python -m pytest packages/markitdown/tests/test_pdf_tables.py -k movie_theater适用边界与注意事项依赖与文本层前提离线 PDF 转换依赖pdfplumber/pdfminer.six对无文本层的扫描件期望输出为空需要 OCR如markitdown-ocr插件才能提取内容。输出定位MarkItDown 面向 LLM 与文本分析输出以可读、可检索为准并非高保真排版还原不同布局下表格行与文本行的判定如Show Schedule Details区域会因列对齐情况而不同。安全边界MarkItDown 以当前进程权限执行 I/O与open()、requests.get()类似在不可信环境中应消毒输入并尽量调用最窄的convert_*方法如convert_stream、convert_local详见 README.md 的安全说明。借助movie-theater-booking-2024这份样例你可以把表单式 PDF → 结构化 Markdown从黑盒变成白盒既能看到算法输出的真实形态也能在 _pdf_converter.py 中逐行追踪列检测、行分类与表格还原的实现细节还能通过 test_pdf_tables.py 的断言理解质量保障手段。赞分享人工智能AI 应用MCP 服务【免费下载链接】markitdownPython tool for converting files and office documents to Markdown.项目地址https://gitcode.com/GitHub_Trending/ma/markitdown点击查看免费下载相关推荐如何在CMake项目中集成reflect-cpp完整配置与依赖管理教程如何在CMake项目中集成reflect cpp完整配置与依赖管理教程 reflect cpp是一个强大的C反射库支持JSON、XML、YAML等多种数Windows防撤回神器RevokeMsgPatcher让重要消息不再错过Windows防撤回神器RevokeMsgPatcher让重要消息不再错过 你是否曾经遇到过这样的场景工作群里领导发的重要通知你刚要点开查看却看到对方桌面应用即时通讯knowledge-catalog OKF 订单表概念文档解析以 acme_retail 的 Customer Orders 表为例理解 BigQuery 表语义治理knowledge catalog OKF 订单表概念文档解析以 acme_retail 的 Customer Orders 表为例理解 BigQuery 表数据目录AI Agent人工智能知识管理示例工程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
