我们已在 LlamaParse 中引入了原生、智能的电子表格提取功能。

电子表格与 PDF（或任何其他文档格式）截然不同。它们可以拥有任意多的行/列，无法保证表格结构，并且信息可能跨多个工作表关联。处理电子表格的原生方式通常是通过代码解释器，而非 OCR。

我们引入了一个经过调优的智能引擎（模型+框架），它专为基于大规模 Schema 引导从电子表格中提取数据而设计。您可以将像资产负债表这样的密集工作表提取为干净、结构化的字段。

查看文档了解如何通过 API 集成：https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#spreadsheet-mode…

在用户界面中，选择 “agentic plus”，并在高级选项部分查看 “spreadsheet options”。

在此注册 LlamaParse！http://cloud.llamaindex.ai

配置提取任务

来源：https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/ 本页是提取任务的指南：任务构建的概念、如何编写驱动任务的 Schema、与 Schema 一起设置的每个选项，以及在扩展规模时保持提取准确性的实践。

有关逐字段的请求参考，请参阅提取 API 参考文档 (https://developers.llamaindex.ai/reference/resources/extract/)。有关任务可返回的额外元数据，请参阅元数据扩展 (https://developers.llamaindex.ai/llamaparse/extract/guides/extensions/)。

LlamaExtract 旨在成为一个灵活且可扩展的提取平台。该平台的核心概念如下：

• 提取配置：可复用的设置，包括 Schema、层级和提取选项。
• 数据 Schema：以 JSON/Pydantic 格式定义您想要提取数据的结构化定义。详见下文详解。
• 提取目标：定义提取的范围以及如何将 Schema 应用于文档。详见下文详解。
• 提取任务：使用配置从文档中提取结构化数据的异步任务。
• 提取运行：提取任务的结果，包括提取的数据和其他元数据。

数据 Schema定义了您希望从文档中提取数据的结构。它是一个 JSON Schema，指定了您所需信息的字段、类型和描述。

虽然 Schema 本质上是 JSON Schema（支持完整 JSON Schema 规范的一个子集），但我们的 Python SDK 允许您使用 Pydantic 模型，以获得更 Pythonic 的体验，支持类型验证和 IDE 支持。

字段、类型、大小限制以及提取任务接受的 JSON Schema 子集，在下面的 Schema 设计与限制 (https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#schema-design-and-restrictions) 中介绍。

提取目标决定了您的 Schema 如何应用于文档以及您收到的结果粒度。这是一个重要的配置选项，因为它从根本上改变了数据的提取方式。

提取目标可视化

per_doc (默认) per_page per_table_row 何时使用从整个文档中基于 JSON Schema 提取数据的默认模式 每页独立包含有关不同实体的信息（例如，每页包含关于不同投资组合公司的财务信息） 文档包含一个实体的有序列表（表格、项目符号/编号列表中，或由标题分隔），并且您想为每个实体提取相同的信息 工作原理 Schema 作为单个单元应用于整个文档 Schema 独立应用于文档的每一页 Schema 应用于文档中识别出的每个实体。LlamaExtract 自动检测区分实体的格式模式（表格行、列表项、章节标题等） 返回 一个与您的 Schema 匹配的 JSON 对象 每页一个 JSON 对象的数组，每个对象与您的 Schema 匹配 每个实体/行一个 JSON 对象的数组，每个对象与您的 Schema 匹配 示例用例 从合同、年度报告或研究论文中提取摘要信息 多页表格，其中每页代表一个不同的实体，或者文档每页包含一条记录 - 发票明细行（每行是一个产品/服务） - 员工名单或通讯录 - 含多个项目的采购订单 - 任何包含重复结构化实体的文档 重要说明 - 您的 Schema 应描述单个实体/页，而非列表。不要使用 extracted_result: list[template]，而是直接提供将在页面级别应用的模板 - 您的 Schema 应描述单个实体，而非列表。不要使用 extracted_result: list[template]，而是直接提供将在实体级别应用的模板

• 文档必须具有某种可区分不同实体的格式或结构（表格格式、项目符号、编号、标题等）
• 实体在文档中应按顺序出现

Schema 设计与限制

标题为“Schema 设计与限制”的部分 (https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#schema-design-and-restrictions)

Schema 是提取配置最重要的部分。它定义了您想要返回数据的结构，其字段描述是指引提取模型的关键。

如何定义您的 Schema

标题为“如何定义您的 Schema”的部分 (https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#how-to-define-your-schema)

Schema 由字段组成。每个字段都有一个名称、一个类型，以及可选的描述。

• 字段名称 — 使用清晰、稳定的名称，与您使用数据的方式相匹配（例如 invoice_number、vendor_name）。这些名称将成为提取后 JSON 中的键。
• 字段描述 — 描述是为底层 LLM 提供的额外上下文。它们不仅仅是为了文档：提取模型使用它们来决定提取什么内容。使用描述来引导模型理解该字段的可能值——例如，字段的含义、它在文档中通常出现的位置、可接受的格式或示例。更好的描述通常会导致更准确和一致的提取。

Schema 限制

标题为“Schema 限制”的部分 (https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#schema-restrictions)

LlamaExtract 仅支持 JSON Schema 规范的一个子集。 尽管有限制，但它足以满足广泛的用例。

• 如果您以 JSON 形式指定 Schema，可以通过两种方式标记可选字段：- 不将其包含在父对象的 required 数组中 - 显式使用 anyOf 和 null 类型将其标记为可空字段。请参阅示例 Schema (https://developers.llamaindex.ai/llamaparse/extract/api/) 中的 "start_date" 字段。
• 如果您使用 Python SDK 中的 Pydantic 来指定 Schema，可以使用 Optional 注解来标记可选字段。
• 根节点必须是 object 类型。
• Schema 嵌套深度限制在 7 层以内。
• 重要的字段是键名/标题、类型和描述。格式化、默认值等字段不受支持。如果您需要这些，可以将限制添加到字段描述中和/或使用后处理步骤。例如，可以通过将字段设为可选，然后从提取结果中将 "null" 值设置为默认值来支持默认值。
• 其他 Schema 限制：- 最大属性数：整个 Schema 中最多 5,000 个属性。- 最大总字符串内容：所有字符串（字段名称、描述、枚举值等）合计最多 120,000 个字符。- 最大原始 JSON Schema 大小：原始 JSON Schema 字符串最多 150,000 个字符。
• 如果您在复杂的提取用例中达到这些限制，请考虑重构您的提取流程以适应这些约束，例如通过提取字段子集，然后稍后将它们合并。

Agentic Plus 层级支持最多 3,200 个字段的 Schema，并且当 Schema 大小超过 200 个字段时，会按页收取更多费用。有关乘数，请参阅定价 (https://developers.llamaindex.ai/llamaparse/general/pricing)。即使您未接近限制，了解 Schema 大小如何计算也很有价值，因为它也是衡量提取难度的良好指标。

大小是指您提交的 Schema 中叶子字段的数量，即树底部的标量值。它不依赖于文档或返回的数据量。

• 对象本身不计入，只计入其内部的叶子节点。{"address": {"city": ..., "zip": ...}} 是 2 个字段。
• 数组计入其项目 Schema 一次，无论提取出多少项目。一个包含 40 个明细行、每行 5 个字段的数组算作 5 个字段，而不是 200 个。
• 标量数组（例如 {"tags": ["string"]}）算作 1 个字段。
• $ref 在每次使用的地方展开。如果三个字段都指向同一个 10 字段的 Address 定义，则算作 30 个字段，而不是 10 个。重用定义可以使您的 Schema 更易读，但不会使其变小。

因此，一个包含 30 个顶级标量和一个 10 列表格的 Schema 总共是 40 个字段，远低于乘数开始生效的阈值。

提示与最佳实践

标题为“提示与最佳实践”的部分 (https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#tips–best-practices)

• 尝试将 Schema 嵌套限制在 3-4 层以内。
• 当数据可能并非始终存在时，将字段设为可选（特别是 boolean 和 int 字段，缺失值的默认值可能会引起混淆）。
• 当您想提取可变数量的实体时，使用 array 类型。但请注意，根节点不能使用 array 类型。
• 使用描述性的字段名称和详细的描述。使用描述来传递格式说明或少样本示例。
• 最重要的是，从简单开始，并迭代构建您的 Schema 以纳入需求。

自动生成 Schema

标题为“自动生成 Schema”的部分 (https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#automatic-schema-generation)

您可以使用 LlamaExtract 的自动 Schema 生成功能，而不是手动定义 Schema。系统可以基于以下内容生成 Schema：

• 自然语言提示：描述您想要提取的数据
• 示例文件：上传一个文档，让系统根据其结构推断 Schema
• 要优化的现有 Schema：提供一个基础 Schema，让系统对其进行改进或扩展

您可以组合这些输入——例如，同时提供示例文件和提示来指导生成。

使用 REST API

标题为“使用 REST API”的部分 (https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#using-the-rest-api)

curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v2/extract/schema/generate?project_id={PROJECT_ID}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Extract invoice details including invoice number, date, vendor name, line items with descriptions and amounts, and total amount",
    "file_id": "optional-file-id-for-sample-document"
  }'

有关完整 API 文档，请参阅 LlamaExtract API 参考文档 (https://developers.llamaindex.ai/reference/resources/extract/)。

使用 SDK 定义 Schema

标题为“使用 SDK 定义 Schema”的部分 (https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#defining-schemas-with-sdks)

• Python (https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#tab-panel-539)
• TypeScript (https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#tab-panel-540)
• Go (https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#tab-panel-541)
• Java (https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#tab-panel-542)
• CLI (https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#tab-panel-543)

Python SDK 可以使用以下命令安装：

pip install llama-cloud>=2.1

可以使用 Pydantic 模型或 JSON Schema 来定义 Schema：

使用 Pydantic（推荐）

标题为“使用 Pydantic（推荐）”的部分 (https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#using-pydantic-recommended)

from pydantic import BaseModel, Field
from typing import List, Optional

class Experience(BaseModel):
    company: str = Field(description="Company name")
    title: str = Field(description="Job title")
    start_date: Optional[str] = Field(description="Start date of employment")
    end_date: Optional[str] = Field(description="End date of employment")

class Resume(BaseModel):
    name: str = Field(description="Candidate name")
    experience: List[Experience] = Field(description="Work history")

schema = Resume.model_json_schema()

使用 JSON Schema

标题为“使用 JSON Schema”的部分 (https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#using-json-schema)

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "description": "Candidate name"},
        "experience": {
            "type": "array",
            "description": "Work history",
            "items": {
                "type": "object",
                "properties": {
                    "company": {
                        "type": "string",
                        "description": "Company name",
                    },
                    "title": {"type": "string", "description": "Job title"},
                    "start_date": {
                        "anyOf": [{"type": "string"}, {"type": "null"}],
                        "description": "Start date of employment",
                    },
                    "end_date": {
                        "anyOf": [{"type": "string"}, {"type": "null"}],
                        "description": "End date of employment",
                    },
                },
            },
        },
    },
}

定义好 Schema 后，您可以直接使用 SDK 运行提取：

from llama_cloud import LlamaCloud

client = LlamaCloud(api_key="your_api_key")

file_obj = client.files.create(file="path/to/your/document.pdf", purpose="extract")
job = client.extract.create(
    file_input=file_obj.id,
    configuration={
            "data_schema": schema,
            "tier": "agentic",
        },
)

# 轮询任务完成状态
while job.status not in ("COMPLETED", "FAILED", "CANCELLED"):
    import time; time.sleep(2)
    job = client.extract.get(job.id)

配置选项

标题为“配置选项”的部分 (https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#configuration-options)

Schema 决定了返回什么数据。以下选项决定任务如何运行——哪个层级解读文档、读取哪些页面以及返回哪些额外元数据。提取目标 (https://developers.llamaindex.ai/llamaparse/extract/guides/configuring-extract/#extraction-target) 也属于这一类；它之所以在上方描述，是因为它改变了结果的结构，而不仅仅是质量。

提取层级决定了 LlamaExtract 从文档生成结构化数据所投入的精力。

Agentic Plus 在各类文档上提供最高的提取质量，包括简短或简单的文档。当您追求最佳结果且能接受更高成本和延迟时，请使用它。在处理长文档或复杂文档时，因为它会在结果上投入更多迭代努力，所以可能需要更长时间。它还支持最大的 Schema（最多 3,200 个字段）。