Python 中的 PDF 转 DOCX 转换教程：快速异步

Wed, 02 Sep 2026 12:20:11 +0000

将 PDF 文件转换为可编辑的 DOCX 文档是构建以文档为中心的 Python 应用程序时的常见需求。 GroupDocs.Conversion Cloud SDK for Python 让您能够在 Python 中执行 PDF 到 DOCX 的转换，具备高可靠性和云可扩展性。在本教程中，您将了解如何设置 SDK、运行异步转换以及为生产工作负载微调性能。

Python 中的 PDF 转 DOCX 转换，5 步

配置凭证和基础 URL：设置您的 GROUPDOCS_CLIENT_ID、GROUPDOCS_CLIENT_SECRET 和 API 基础 URL。

import os
CLIENT_ID = os.getenv("GROUPDOCS_CLIENT_ID", "YOUR_CLIENT_ID")
CLIENT_SECRET = os.getenv("GROUPDOCS_CLIENT_SECRET", "YOUR_CLIENT_SECRET")

初始化 API 客户端: 创建一个 Configuration 对象，然后创建 ApiClient 和 ConvertApi 实例。

from groupdocs_conversion_cloud import Configuration, ApiClient, ConvertApi
config = Configuration()
config.api_base_url = "https://api.groupdocs.cloud"
config.client_id = CLIENT_ID
config.client_secret = CLIENT_SECRET
api_client = ApiClient(config)
convert_api = ConvertApi(api_client)   # See API reference: [ConvertApi](https://reference.groupdocs.cloud/conversion/)

定义转换设置：指向云存储中的源 PDF，设置目标格式为 docx，并可选地指定输出路径。

from groupdocs_conversion_cloud import ConvertSettings
settings = ConvertSettings()
settings.file_path = "input.pdf"
settings.format = "docx"
settings.output_path = "output.docx"

执行异步转换：调用异步方法并等待返回的包含下载 URL 的响应。

import asyncio
async def run_conversion():
    response = await convert_api.convert_document_async(settings)
    return response.url
download_url = asyncio.run(run_conversion())

下载结果并清理：从 URL 流式传输 DOCX 文件并关闭客户端。

import requests
download_resp = requests.get(download_url, stream=True)
download_resp.raise_for_status()
with open("output.docx", "wb") as out_file:
    for chunk in download_resp.iter_content(chunk_size=8192):
        if chunk:
            out_file.write(chunk)
api_client.close()

完整代码示例：Python 中的 PDF 转 DOCX 异步转换

本示例演示如何使用 GroupDocs.Conversion Cloud SDK for Python 执行 PDF 到 DOCX 的异步转换。

import asyncio
import os
import requests
from groupdocs_conversion_cloud import (
    ConvertApi,
    ConvertSettings,
    Configuration,
    ApiClient
)

# Replace with your actual credentials or set them as environment variables
CLIENT_ID = os.getenv("GROUPDOCS_CLIENT_ID", "YOUR_CLIENT_ID")
CLIENT_SECRET = os.getenv("GROUPDOCS_CLIENT_SECRET", "YOUR_CLIENT_SECRET")

async def convert_pdf_to_docx():
    # Configuration
    config = Configuration()
    config.api_base_url = "https://api.groupdocs.cloud"
    config.client_id = CLIENT_ID
    config.client_secret = CLIENT_SECRET

# API client and Convert API instance
    api_client = ApiClient(config)
    convert_api = ConvertApi(api_client)

# Conversion settings
    settings = ConvertSettings()
    settings.file_path = "input.pdf"          # source file in GroupDocs Cloud storage
    settings.format = "docx"                  # target format
    settings.output_path = "output.docx"      # optional: path where the result will be stored

try:
        # Asynchronous conversion request
        # The SDK provides an async method that returns a response containing a download URL
        response = await convert_api.convert_document_async(settings)

# Download the converted DOCX file using the provided URL
        download_url = response.url
        download_resp = requests.get(download_url, stream=True)
        download_resp.raise_for_status()
        with open("output.docx", "wb") as out_file:
            for chunk in download_resp.iter_content(chunk_size=8192):
                if chunk:
                    out_file.write(chunk)

print("Conversion completed successfully. File saved as output.docx")
    finally:
        # Cleanup resources
        api_client.close()

if __name__ == "__main__":
    asyncio.run(convert_pdf_to_docx())

注意： 此代码示例演示了核心功能。在将其用于项目之前，请确保更新文件路径（input.pdf、output.docx 等）以匹配实际文件位置，验证所有必需的依赖项已正确安装，并在开发环境中彻底测试。如果遇到任何问题，请参阅官方文档或联系支持团队获取帮助。

使用 cURL 通过 REST API 将 PDF 转换为 DOCX

您可以使用原始 HTTP 调用实现相同的结果。下面是复制异步转换工作流的 cURL 命令。

获取访问令牌

curl -X POST "https://api.groupdocs.cloud/connect/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

响应中包含 access_token。

上传源 PDF

curl -X POST "https://api.groupdocs.cloud/v2.0/storage/file/upload?path=input.pdf" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        -F "file=@/path/to/local/input.pdf"

开始异步转换

curl -X POST "https://api.groupdocs.cloud/v2.0/conversion/convert" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "filePath": "input.pdf",
           "outputPath": "output.docx",
           "format": "docx"
         }'

响应中包含一个 url 字段，用于获取生成的 DOCX 文件。

下载已转换的 DOCX

curl -L "https://api.groupdocs.cloud/v2.0/storage/file/download?path=output.docx" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        -o output.docx

欲了解更多详情，请参阅官方 API 文档。

安装和配置 GroupDocs.Conversion Cloud SDK for Python

pip install groupdocs-conversion-cloud

您也可以直接从发布页面下载软件包: 下载 GroupDocs.Conversion Cloud SDK for Python

先决条件：

Python 3.7 或更高版本
有效的 GroupDocs 客户端 ID 和密钥（可在您的 GroupDocs 账户中获取）

安装后，设置所需的环境变量，或如上步骤所示直接在代码中传递凭据。

GroupDocs.Conversion Cloud 将 PDF 转换为 DOCX 的关键特性

异步处理 - 非阻塞的转换调用使您的应用保持响应。
云存储集成 - 文件从 GroupDocs Cloud 存储读取并写入，无需本地 I/O。
格式保真度 - DOCX 输出保留原始 PDF 的布局、字体和图像。
可扩展架构 - 该服务能够处理大批量工作负载，适用于批处理作业或微服务。
全面的 API 参考 - 每个类和方法的详细文档可在 API 参考获取。

转换设置：PDF 转 DOCX 的选项

file_path - 云存储中源 PDF 的路径。
```
settings.file_path = "input.pdf"
```
format - 目标格式；Word 文档使用 "docx"。
```
settings.format = "docx"
```
output_path - 可选的转换后文件存储路径。
```
settings.output_path = "output.docx"
```
load_options - 高级 PDF 加载选项（例如密码、页码范围），可通过 PdfLoadOptions 设置。有关完整列表，请参阅文档。

异步 PDF 转 DOCX 转换的性能考虑

利用异步调用 - 使用 convert_document_async 可减少线程阻塞并提升吞吐量。
重用 ApiClient - 在整个应用程序生命周期内创建单个 ApiClient 实例，以避免重复握手。
流式下载 - 示例以 8 KB 块流式传输 DOCX 文件，保持低内存使用。
批量处理多个文件 - 对于批量转换，排队多个异步任务并使用 asyncio.gather 等待它们。

在 Python 中快速将 PDF 转换为 DOCX 的最佳实践

安全存储凭据；切勿硬编码。
在调用 API 之前验证源 PDF 是否存在。
使用环境变量来存放 GROUPDOCS_CLIENT_ID 和 GROUPDOCS_CLIENT_SECRET。
监控转换响应中的错误，并针对瞬时网络问题实现重试逻辑。
记录下载 URL 和转换耗时，以进行性能审计。

结论

在 Python 中实现 PDF 到 DOCX 的自动转换变得非常简单，只需使用 GroupDocs.Conversion Cloud SDK for Python。按照本指南操作后，您已经拥有了可工作的异步实现，了解了如何配置转换选项，并且知道如何针对大规模工作负载优化性能。请记得在产品页面查看定价详情，并从临时许可证页面获取用于测试的临时许可证。有了这些工具，您可以将可靠的文档转换集成到任何基于 Python 的服务或应用程序中。

常见问题

在 Python 中进行 PDF 转 DOCX 转换时，如何处理大型 PDF 文件？
使用异步 API 以避免阻塞主线程，并按照示例进行下载流式处理。SDK 在服务器端处理文件，因此您这边的内存消耗保持在最低水平。
如果源 PDF 受密码保护会怎样？
在 ConvertSettings 中的 PdfLoadOptions 设置 password 属性。SDK 会在转换前解密文件。请参阅文档获取确切语法。
我可以在 Docker 容器中运行转换吗？
是的。在 Docker 镜像中使用 pip install groupdocs-conversion-cloud 安装 SDK，配置环境变量，然后执行相同的异步脚本。这样可以隔离依赖并轻松扩展。
是否有办法在 Python 中监控 PDF 转 DOCX 转换的速度？
测量异步调用与下载完成之间的耗时。SDK 会立即返回一个 url；实际的处理时间体现在文件在该 URL 可用所需的时间上。

pdf to docx python on Document Processing REST APIs | GroupDocs Cloud