将您的文档直接引入 AI 流水线 — 在本地、使用 Python，只需一次 pip install。

今天我们在 PyPI 上发布了 GroupDocs.Markdown for Python via .NET 的首个公开版本。该库可以将 PDF、Word、Excel、EPUB 等 20 多种格式转换为干净、语义化的 Markdown——这是 LLM、RAG 流水线以及静态站点生成器最擅长处理的格式。

如果您已经关注了 .NET 9 月发布（或 [26.3 版完整 API 大改]（https://releases.groupdocs.com/markdown/net/release-notes/2026/groupdocs-markdown-for-net-26-3-release-notes/）），其背后的原理是相同的：文档的排版承载语义，保留这种语义结构才能让 RAG 系统给出高质量答案。前文已经深入阐述了 问题（OCR 会扁平化结构，LLM 需要 Markdown）和 解决方案（基于 DOM 的渲染器遍历文档并输出 Markdown）——这里不再赘述。

下面我们直接来看 Python 开发者可以获得的全新特性。

您将获得

  • 单一 wheel 包，无运行时依赖。 pip install groupdocs-markdown-net 会下载一个自包含的 wheel，其中已打包 .NET 运行时及所有必需的本地库。无需自行安装 dotnet、Microsoft Office、Adobe Acrobat，也不依赖云服务。
  • 跨平台。 支持 Windows x64/x86、Linux x64、macOS x64 与 Apple Silicon（ARM64）。兼容 Python 3.5 至 3.14。
  • 符合 Python 习惯的 API。 类名使用 PascalCase，方法和属性使用 snake_case，枚举值使用 UPPER_SNAKE_CASE。上下文管理器能够确定性地释放已加载的文档。
  • 真正的异步支持。 每个静态和实例方法都有对应的 _async 版本。文件 I/O 为异步实现，CPU 密集型的转换在工作线程上执行——您的 asyncio 事件循环保持空闲。
  • 友好的 AI 代理支持。 安装的 wheel 中包含 AGENTS.md 文件，帮助编码助手（Claude Code、Cursor、GitHub Copilot、Codex）自动发现 API、惯用用法以及故障排查技巧。文档同样以 llms.txt、单文件语料库 llms-full.txt、每页 Markdown 以及 MCP 服务器的形式发布——详情请参见下文 AI-friendly by design。

入门指南

pip install groupdocs-markdown-net

最简转换只需一行代码：

from groupdocs.markdown import MarkdownConverter

# 转换为字符串
md = MarkdownConverter.to_markdown("business-plan.docx")

# 或直接写入文件
MarkdownConverter.to_file("business-plan.docx", "business-plan.md")

就是这么简单——无需配置、无需选项、无需模板。评估模式下会处理前 3 页并添加水印。若要去除限制，请使用许可证：

from groupdocs.markdown import License

License().set_license("path/to/license.lic")

或者将 GROUPDOCS_LIC_PATH 设置为环境变量，导入时会自动加载。

支持的格式

Python 包支持的格式与 .NET 库保持一致：

  • PDF — .pdf
  • Word / Rich Text — .doc, .docx, .docm, .dot, .dotx, .dotm, .rtf, .odt, .ott
  • 电子表格 — .xls, .xlsx, .xlsb, .xlsm, .csv, .tsv, .ods, .ots
  • 电子书 — .epub, .mobi
  • 文本 / 标记 / 帮助 — .txt, .xml, .chm

Pythonic 示例

转换选项与图片策略

from groupdocs.markdown import (
    MarkdownConverter,
    ConvertOptions,
    MarkdownFlavor,
    ExportImagesToFileSystemStrategy,
)

strategy = ExportImagesToFileSystemStrategy("output/images")
strategy.images_relative_path = "images"  # ![](images/img-001.png)

options = ConvertOptions()
options.flavor = MarkdownFlavor.GIT_HUB
options.heading_level_offset = 1      # # Title -> ## Title
options.include_front_matter = True    # 前置 YAML 元数据
options.image_export_strategy = strategy

MarkdownConverter.to_file("report.docx", "output/report.md", convert_options=options)

不进行转换的文档检查

from groupdocs.markdown import MarkdownConverter

info = MarkdownConverter.get_info("business-plan.docx")
print(f"{info.file_format}, {info.page_count} pages, author: {info.author}")

加载受密码保护的文件

from groupdocs.markdown import MarkdownConverter, LoadOptions, FileFormat

load_opts = LoadOptions(FileFormat.DOCX)
load_opts.password = "secret"

MarkdownConverter.to_file("protected.docx", "output.md", load_options=load_opts)

流与上下文管理器

from groupdocs.markdown import MarkdownConverter

with open("document.docx", "rb") as stream:
    with MarkdownConverter(stream) as converter:
        converter.convert("document.md")

异步 API — 并发转换多个文档

由于文件 I/O 为异步，asyncio.gather() 能让单个工作线程在不阻塞的情况下处理多个文档：

import asyncio
from groupdocs.markdown import MarkdownConverter

async def convert_many():
    await asyncio.gather(
        MarkdownConverter.to_file_async("a.docx", "a.md", None),
        MarkdownConverter.to_file_async("b.pdf",  "b.md", None),
        MarkdownConverter.to_file_async("c.xlsx", "c.md", None),
    )

asyncio.run(convert_many())

这使得库天然适配 FastAPI 等 ASGI 框架——单个工作进程即可服务大量并发转换请求，避免线程争用。

错误处理

所有转换方法在失败时都会抛异常，常见场景有专门的异常类型：

from groupdocs.markdown import (
    MarkdownConverter,
    DocumentProtectedException,
    InvalidFormatException,
    GroupDocsMarkdownException,
)

try:
    MarkdownConverter.to_file("annual-report.docx", "annual-report.md")
except DocumentProtectedException:
    print("密码错误或缺失。")
except InvalidFormatException:
    print("文件损坏或不受支持。")
except GroupDocsMarkdownException as ex:
    print(f"转换失败: {ex}")

为 RAG 与 LLM 流水线而建

Markdown 是嵌入模型和检索流水线的首选输入格式——它保留标题、列表、表格和强调，同时易于分块和分词。典型的 RAG 导入流程如下：

import re
from groupdocs.markdown import MarkdownConverter, ConvertOptions, SkipImagesStrategy, MarkdownFlavor

options = ConvertOptions()
options.image_export_strategy = SkipImagesStrategy()   # RAG 只需文本
options.flavor = MarkdownFlavor.COMMON_MARK

MarkdownConverter.to_file("business-plan.pdf", "business-plan.md", convert_options=options)

with open("business-plan.md", "r", encoding="utf-8") as f:
    markdown = f.read()

# 按顶层标题拆分，然后对每块进行嵌入/索引
chunks = [c for c in re.split(r"\n#{1,2} ", markdown) if c.strip()]

因为库完全在本地运行，敏感文档永不离开您的环境——这正是受监管行业、法务团队以及内部知识库的常见需求。

AI-friendly by design

大多数 Python SDK 将 AI 编码助手视为事后考虑——开发者仍需手动指向文档、粘贴示例或通过试错调试。GroupDocs.Markdown for Python via .NET 颠覆了这一思路：库的设计让 Claude Code、Cursor、GitHub Copilot、Codex 等助手能够零配置直接使用。

AGENTS.md 随 wheel 一同发布

这是首个在已安装的 wheel 中捆绑 AGENTS.md 文件的 GroupDocs 包。该文件遵循新兴的 AGENTS.md 规范——专为 AI 编码助手而非人类编写的纯 Markdown README。

执行 pip install groupdocs-markdown-net 后，文件位于：

site-packages/groupdocs/markdown/AGENTS.md

AI 助手读取该文件后即可立即了解：

  • 完整的 公开 API（类、方法、枚举、异常）以及它们之间的关系。
  • 最常见场景的 惯用用法——静态 vs 实例 API、同步 vs 异步、图片策略、Front Matter、错误处理。
  • 常见陷阱 及规避方法——例如哪些 ConvertOptions 重载接受 None、如何处理受密码保护的文件、如何捕获转换警告。
  • 平台特定问题的排查（macOS 上的 libSkiaSharp、Linux 上的 ICU）。

实际效果是，您只需说 “使用 groupdocs-markdown-net 将这个 PDF 文件夹转换为 RAG 流水线的 Markdown”，助手即可一次性生成可运行代码——不出现幻觉式的方法名、参数顺序错误或错误的导入语句。

机器可读文档

对于在 AGENTS.md 中未覆盖的细节，完整的产品文档同样以机器可读形式提供：

  • 单文件语料库 — 整套文档合并为一个 Markdown 文件，可直接放入助手的上下文窗口：
    https://docs.groupdocs.com/markdown/python-net/llms-full.txt
  • 每页 Markdown — 在任意文档 URL 后追加 .md 即可获取原始源码：
    https://docs.groupdocs.com/markdown/python-net/quick-start-guide.md
  • llms.txt 索引 — 类似 llms.txt 的目录，帮助助手快速定位所需页面：
    https://docs.groupdocs.com/markdown/python-net/llms.txt

MCP 服务器用于实时文档查询

对于支持 Model Context Protocol 的助手，我们提供了 MCP 服务器。将以下配置加入 Claude Code 或 Cursor 即可：

{
  "mcpServers": {
    "groupdocs-docs": {
      "url": "https://docs.groupdocs.com/mcp"
    }
  }
}

随后，助手可以按需查询文档，而不必依赖可能已过时的训练数据。

Markdown 输入，Markdown 输出

这里形成了一个美好的闭环：库的 输出 是 Markdown——LLM 在 RAG 中最易解析的格式；而 文档本身 也是 Markdown，提供单文件供上下文窗口摄取。无论是让助手编写使用库的代码，还是让助手通过库理解您的文档，Markdown 都是共同的媒介。

导出示例

上面的代码片段已经是使用该库能够写出的最简实用程序。下面提供一个完整的可运行项目示例——包括源文档、Python 脚本、预生成输出、requirements.txt 与 Dockerfile，帮助您无需从零编写即可端到端体验。

源 DOCX

源文件 business-plan.docx 是一份结构丰富的商业计划书，包含标题、表格、图片和元数据。

Python 脚本

from groupdocs.markdown import MarkdownConverter, ConvertOptions, MarkdownFlavor

def quick_example():
    """将 Word 文档转换为 GitHub 风格的 Markdown，并添加 YAML front matter。"""

    # 一行代码 — 返回 Markdown 字符串
    md = MarkdownConverter.to_markdown("business-plan.docx")

    # 带选项 — 写入文件
    options = ConvertOptions()
    options.flavor = MarkdownFlavor.GIT_HUB
    options.include_front_matter = True
    options.heading_level_offset = 1
    MarkdownConverter.to_file("business-plan.docx", "quick-example.md", convert_options=options)

if __name__ == "__main__":
    quick_example()

输出 Markdown

quick-example.md 的输出以自动从文档元数据提取的 YAML front‑matter 块开头，随后是使用 GitHub Flavored 表格并已提升标题层级的转换内容（可直接嵌入更大的文档中）。

可运行示例应用

全部打包在一起： sample-app.zip。解压后执行：

cd src
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python quick_example.py

或使用 Docker 运行——随附的 Dockerfile 会在 Linux 上安装 ICU 依赖，满足捆绑的 .NET 运行时需求：

cd src
docker build -t groupdocs-markdown-python-example .
docker run --rm -v "$(pwd)/output:/app/output" groupdocs-markdown-python-example

总结

GroupDocs.Markdown for Python via .NET 将完整的文档转 Markdown 引擎以自包含的 wheel 形式带到 Python——无需外部运行时、无需云服务、无需意外。Pythonic API、异步支持以及首屈一指的 AI 工具集成，使其成为构建 RAG 系统、静态站点生成器或文档处理流水线的实用选择。

了解更多

支持与反馈

如有疑问或需要技术帮助，请前往我们的 Free Support Forum——我们随时乐意为您提供帮助。