Beta

把 processing_options.forms 设为 "enrich" 后，Parse 会在它判定为表单的那些页上额外跑一轮表单分析，并把每一页作为结构化 JSON 返回：小节、带标签及其填写值的字段、复选框与签名状态、可填写网格，以及每个字段的边界框。常规的 markdown 与 items 输出会同时返回。用 expand=["forms"] 读回这份 JSON。

Beta

表单增强输出处于 beta 阶段，仍在积极改进中，输出的形状与字段用词都可能变化。

什么时候用它

• 把填好的表单装载进你自己的系统，以表单上印着的字段标识为键（1a、Part III、第 13 格）。
• 区分空白字段与已填字段，并直接读取复选框与签名状态，而不是从文本去推断。
• 搭建一个复核界面，高亮显示每个字段取值来自页面上的什么位置。
• 从税务表、申请表、理赔单与登记表中做键值抽取，扫描件或原生数字件皆可。

如果你只需要按页面原样排布的文本，output_options.spatial_text 是更轻的替代，且在任何档位都可用。若要用你自己的 schema 保证 JSON 形状，请改用 Extract。

选项

选项	类型	默认值	作用
processing_options.forms	"default" or "enrich"	"default"	"enrich" 在被判定为表单的页上跑表单分析。fast 档不可用。含表单的页每页加 10 credit；不含表单的页返回空的 forms 列表且不额外收费。
output_options.spatial_text	object	unset	为表单与收据保留空白的文本。用 expand=["text"] 取回。
input_options.image.camera_photo_correction	boolean	unset	针对拍摄下来的表单：解析前先裁剪、校正透视并抚平光照。

取结果时用 expand=["forms"] 直接拿到内联 JSON，或用 expand=["forms_content_metadata"] 拿到同一份 JSON 作为文件的预签名下载地址。在 Web 界面里，请到 Processing Options > Forms 下打开 Enriched forms output；结果页随后会多出一个 Forms 标签。

示例

下载一份填了测试数据的样例 Form W-2，存为 w2.pdf：

终端窗口

curl -fL -o w2.pdf https://cloud.llamaindex.ai/assets/demos/parse/form-w2.pdf

上传它、开启表单分析，并把每张表单打平成字段列表打印出来：

from llama_cloud import LlamaCloud

client = LlamaCloud()  # reads LLAMA_CLOUD_API_KEY from the environment

file = client.files.create(file="./w2.pdf", purpose="parse")

result = client.parsing.parse(
    file_id=file.id,
    tier="agentic",
    version="latest",
    processing_options={"forms": "enrich"},
    expand=["forms"],
)

for page in result.forms.pages:
    if not page.success:
        print(f"page {page.page_number} failed: {page.error}")
        continue
    for form in page.forms:
        print(form.list.md)  # flattened "label: value" bullets, ready for a prompt

表单增强示例 会安装 llama-cloud>=2.15，即带有 forms 结果字段的版本。在 Python SDK 里，驼峰式的 API 字段以 snake_case 形式暴露（valueItems 变成 value_items、isEmpty 变成 is_empty），而 json 暴露为 json_。

你会拿到什么

result.forms.pages 每页一条。每个被识别出的表单都同时带着两份内容：json 是结构化树，list 是打平后的项目符号列表，其 md 可以原样塞进提示词。下面这段摘自一份填好的 W-2（已做删减）：

{
  "page_number": 1, "page_width": 612, "page_height": 792, "success": true,
  "forms": [{
    "json": [
      { "type": "field", "field": "text", "id": "1", "label": "Wages, tips, other compensation", "value": "29,513",
        "bbox": [{ "x": 349.2, "y": 96.5, "w": 114.0, "h": 12.2 }] },
      { "type": "field", "field": "text", "id": "d", "label": "Control number", "isEmpty": true },
      { "type": "field", "field": "multi_select", "id": "13", "valueItems": [
        { "type": "field", "field": "checkbox", "label": "Statutory employee", "value": true },
        { "type": "field", "field": "checkbox", "label": "Retirement plan", "value": false } ] }
    ],
    "list": { "md": "- [1] Wages, tips, other compensation: 29,513\n- [d] Control number:\n- [13]\n  - [x] Statutory employee\n  - [ ] Retirement plan" }
  }]
}

这棵树有四种节点类型：

type	含义
section	表单上印着的一个分组（Part III、第 15 格）；items 按阅读顺序存放它的子节点。
field	一个待填项。field 可为 text、checkbox、single_select、multi_select 或 signature。
table	一张可填写的网格，含 columns 与 rows；单元格是字符串、空白时为 null，或是 { "items": [...] } 并自带其字段。html 把该网格渲染成 HTML 表格。
text	不属于任何字段、标题或表格的印刷文字，例如标题、说明或备注；value 原样保存它。

value 的读法取决于字段种类：text 原样保存填入的文本，空白字段是 isEmpty: true 且没有 value；checkbox 与 signature 保存一个布尔值（是否勾选、是否签署）；single_select 与 multi_select 没有 value，而在 valueItems 里列出各自选项，每个选项通常是一个自带布尔值的 checkbox。bbox 以页面点为单位，与 items 同一坐标空间。读某一页之前务必先看 success：表单分析失败的那页形如 { "page_number": N, "success": false, "error": "..." }。

2.17.0 之前的 Python SDK，以及 1.8.0 之前的 Java 与 C# SDK 无法读取 text 节点，因此对这些版本的响应会把它们从 json 中省略。升级 SDK 即可收到。不上报自身版本的 SDK 会被当作旧版处理。

另请参阅

• 表单增强输出示例：遍历整棵树、处理选择型字段、下载 forms 文件，各 SDK 都有
• 配置 Parse：表单增强输出
• 响应形态：forms：每个字段与节点类型
• 版面与边界框：把字段框渲染到页面截图上
• OCR 与语言：扫描与拍摄的表单