使用布局解析器处理文档

布局解析器会提取文本、表格和列表等文档内容元素，并创建内容感知数据块，以便生成式 AI 和发现应用从中检索信息。

布局解析器功能

  • 解析文档布局。您可以向布局解析器输入 HTML 或 PDF 文件，以识别文本块、表格、列表等内容元素以及标题和标头等结构元素。这些元素有助于定义文档的组织结构和层次结构，其中包含丰富的内容和结构元素，可为信息检索和发现创建更多背景信息。

  • 对文档进行分块。布局解析器可以将文档分解为多个块，这些块会保留原始文档的布局层次结构的相关上下文信息。生成答案的 LLM 可以使用分块来提高相关性并减少计算负荷。

    在分块过程中考虑文档的布局，可以在用于检索和 LLM 生成时提高内容的语义连贯性并减少噪声。一个数据块中的所有文本都来自同一布局实体，例如标题、子标题或列表。

  • Gemini 布局解析器。预览版。 Gemini 布局解析器可提高 PDF 文件的表格识别、阅读顺序和文本识别方面的布局质量。您可以为处理器选择布局解析器处理器版本 pretrained-layout-parser-v1.4-2025-08-25、pretrained-layout-parser-v1.5-2025-08-25 或 pretrained-layout-parser-v1.5-pro-2025-08-25，以默认启用该功能。

  • 将图片和表格解析为注释。预览版。 布局解析器可以识别解析的文档中是否存在图片或表格。 找到后，系统会将其注释为描述性文本块，其中包含图片和表格中描绘的信息。

限制

存在以下限制：

  • 在线处理：
    • 输入文件大小上限（所有文件类型均为 20 MB）
    • 每个 PDF 文件的页数上限为 15
  • 批处理：
    • PDF 文件的单个文件大小上限为 1 GB
    • 每个 PDF 文件的页数上限为 500

按文件类型进行布局检测

下表列出了布局解析器可以检测到的每种文档文件类型的元素。

文件类型 MIME 类型 检测到的元素 限制
HTML text/html 段落、表格、列表、标题、标头、页面页眉、页面页脚 请注意，解析很大程度上依赖于 HTML 标记，因此可能无法捕获基于 CSS 的格式。
PDF application/pdf 段落、表格、标题、标头、页眉、页脚 跨多个页面的表格可能会拆分为两个表格。
DOCX application/vnd.openxmlformats-officedocument.wordprocessingml.document 段落、跨多个页面的表格、列表、标题、标头元素 不支持嵌套表。
PPTX application/vnd.openxmlformats-officedocument.presentationml.presentation 段落、表格、列表、标题、标头元素 为了准确识别标题，应在 PowerPoint 文件中将标题标记为标题。不支持嵌套表格和隐藏幻灯片。
XLSX application/vnd.openxmlformats-officedocument.spreadsheetml.sheet Excel 电子表格中的表格，支持 INT、FLOAT 和 STRING 值 不支持检测多个表格。隐藏的工作表、行或列也可能会影响检测。系统可以处理最多包含 500 万个单元格的文件。
XLSM application/vnd.ms-excel.sheet.macroenabled.12 启用了宏的电子表格，支持 INT、FLOAT 和 STRING 值 不支持检测多个表格。隐藏的工作表、行或列也可能会影响检测。

处理器版本

布局解析器可使用以下模型。如需更改模型版本，请参阅管理处理器版本。

如需为默认处理器配额发出配额增加请求 (QIR)，请按照管理配额中的步骤操作。

模型版本 说明 发布渠道 发布日期
pretrained-layout-parser-v1.0-2024-06-03 文档布局分析的正式版。这是默认的预训练处理器版本。 稳定版 2024 年 6 月 3 日
pretrained-layout-parser-v1.5-2025-08-25 预览版由 Gemini 2.5 Flash LLM 提供支持，可更好地分析 PDF 文件中的布局。建议想要试用新版本的用户选择此选项。如果用于非 PDF 文件，其行为将与稳定的 pretrained-layout-parser-v1.0-2024-06-03 相同。 候选版本 2025 年 8 月 25 日
pretrained-layout-parser-v1.5-pro-2025-08-25 由 Gemini 2.5 Pro LLM 提供支持的预览版，可更好地分析 PDF 文件布局。v1.5-pro 的延迟时间比 v1.5 更长。如果用于非 PDF 文件，其行为将与稳定版 v1.0 相同。 候选版本 2025 年 8 月 25 日

准备工作

如需开启布局解析器，请按以下步骤操作：

  1. 按照创建和管理处理器中的说明创建布局解析器。

    处理器类型名称为 LAYOUT_PARSER_PROCESSOR。

  2. 按照启用处理器中的说明启用布局解析器。

使用布局解析器发送在线处理请求

  1. 将文档输入到布局解析器以进行解析和分块。

    按照发送处理请求中的批处理请求说明操作。

    在 ProcessDocumentRequest 中配置 ProcessOptions.layoutConfig 中的字段。

    REST

    在使用任何请求数据之前，请先进行以下替换：

    • LOCATION：处理器的位置，例如：
      • us - 美国
      • eu - 欧盟
    • PROJECT_ID：您的 Google Cloud 项目 ID。
    • PROCESSOR_ID：自定义处理器的 ID。
    • MIME_TYPE：布局解析器支持 application/pdf 和 text/html。
    • DOCUMENT：要拆分为块的内容。布局解析器接受原始 PDF 或 HTML 文档，或由布局解析器输出的已解析文档。
    • CHUNK_SIZE：可选。拆分文档时使用的块大小（以 token 为单位）。
    • INCLUDE_ANCESTOR_HEADINGS：可选。布尔值。在拆分文档时是否包含祖先标题。

    HTTP 方法和网址：

    POST https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID:process

    请求 JSON 正文： 

    // Sample for inputting raw documents such as PDF or HTML
{
  "rawDocument": {
    "mimeType": "MIME_TYPE",
    "content": "DOCUMENT"
  },
  "processOptions": {
    "layoutConfig": {
      "chunkingConfig": {
        "chunkSize": "CHUNK_SIZE",
        "includeAncestorHeadings": "INCLUDE_ANCESTOR_HEADINGS",
      }
    }
  }
}

    如需发送请求，请选择以下方式之一：

    curl

    将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

    curl -X POST \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
         "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID:process"

    PowerShell

    将请求正文保存在名为 request.json 的文件中，然后执行以下命令： 

    $headers = @{  }

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://LOCATION-documentai.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID:process" | Select-Object -Expand Content
    响应包含处理后的文档，其中包含布局和分块信息，格式为 Document.documentLayout 和 Document.chunkedDocument。

    Python

    如需了解详情，请参阅 Document AI Python API 参考文档。

    如需向 Document AI 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

    
from typing import Optional, Sequence

from google.api_core.client_options import ClientOptions
from google.cloud import documentai

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"
# location = "YOUR_PROCESSOR_LOCATION" # Format is "us" or "eu"
# processor_id = "YOUR_PROCESSOR_ID" # Create processor before running sample
# processor_version = "rc" # Refer to https://cloud.google.com/document-ai/docs/manage-processor-versions for more information
# file_path = "/path/to/local/pdf"
# mime_type = "application/pdf" # Refer to https://cloud.google.com/document-ai/docs/file-types for supported file types


def process_document_layout_sample(
    project_id: str,
    location: str,
    processor_id: str,
    processor_version: str,
    file_path: str,
    mime_type: str,
) -> documentai.Document:
    process_options = documentai.ProcessOptions(
        layout_config=documentai.ProcessOptions.LayoutConfig(
            chunking_config=documentai.ProcessOptions.LayoutConfig.ChunkingConfig(
                chunk_size=1000,
                include_ancestor_headings=True,
            )
        )
    )

    document = process_document(
        project_id,
        location,
        processor_id,
        processor_version,
        file_path,
        mime_type,
        process_options=process_options,
    )

    print("Document Layout Blocks")
    for block in document.document_layout.blocks:
        print(block)

    print("Document Chunks")
    for chunk in document.chunked_document.chunks:
        print(chunk)



def process_document(
    project_id: str,
    location: str,
    processor_id: str,
    processor_version: str,
    file_path: str,
    mime_type: str,
    process_options: Optional[documentai.ProcessOptions] = None,
) -> documentai.Document:
    # You must set the `api_endpoint` if you use a location other than "us".
    client = documentai.DocumentProcessorServiceClient(
        client_options=ClientOptions(
            api_endpoint=f"{location}-documentai.googleapis.com"
        )
    )

    # The full resource name of the processor version, e.g.:
    # `projects/{project_id}/locations/{location}/processors/{processor_id}/processorVersions/{processor_version_id}`
    # You must create a processor before running this sample.
    name = client.processor_version_path(
        project_id, location, processor_id, processor_version
    )

    # Read the file into memory
    with open(file_path, "rb") as image:
        image_content = image.read()

    # Configure the process request
    request = documentai.ProcessRequest(
        name=name,
        raw_document=documentai.RawDocument(content=image_content, mime_type=mime_type),
        # Only supported for Document OCR processor
        process_options=process_options,
    )

    result = client.process_document(request=request)

    # For a full list of `Document` object attributes, reference this page:
    # https://cloud.google.com/document-ai/docs/reference/rest/v1/Document
    return result.document

使用布局解析器批处理文档

使用以下过程在单个请求中解析多个文档并将其分块。

  1. 将文档输入到布局解析器以进行解析和分块。

    按照发送处理请求中的批处理请求说明操作。

    在发出 batchProcess 请求时，在 ProcessOptions.layoutConfig 中配置字段。

    输入

    以下 JSON 示例配置了 ProcessOptions.layoutConfig。

    "processOptions": {
  "layoutConfig": {
    "chunkingConfig": {
      "chunkSize": "CHUNK_SIZE",
      "includeAncestorHeadings": "INCLUDE_ANCESTOR_HEADINGS_BOOLEAN"
    }
  }
}

    替换以下内容：

    • CHUNK_SIZE：拆分文档时要使用的最大块大小（以令牌数量表示）。
    • INCLUDE_ANCESTOR_HEADINGS_BOOLEAN：在拆分文档时是否包含祖先标题。祖先标题是原始文档中子标题的父级标题。它们可以提供一个包含有关其在原始文档中的位置的额外上下文的块。一个块最多可包含两个级别的标题。

后续步骤

上一页
派生字段和签名检测
下一页
预训练概览