默认情况下，LiteParse 只返回文本、几何信息与页面元数据。PDF 能携带的其他内容（内嵌图片、矢量图形、批注、表单字段、标签结构树、逐字形排版信息）都是需要显式开启的，各自有自己的开关。

这让默认输出的形态保持小、稳定且易于产出。也意味着：如果你知道文件里确有某份数据却在输出里找不到，多半是漏了一个开关。

每个选项都会消耗解析时间与输出体积。只开启你真正会用的那部分。

速查表

Rust / Python / CLI	Node / WASM	新增内容
extract_images / --extract-images	extractImages	images[], image_error_count
extract_vector_graphics / --extract-vector-graphics	extractVectorGraphics	pages[].vector_graphics
extract_annotations / --extract-annotations	extractAnnotations	pages[].annotations
extract_form_fields / --extract-form-fields	extractFormFields	pages[].form_fields
extract_structure_tree / --extract-structure-tree	extractStructureTree	pages[].structure_tree
extract_blocks / --extract-blocks	extractBlocks	pages[].blocks
extract_content_bounds / --extract-content-bounds	extractContentBounds	pages[].content_bounds
extract_xfa_packets / --extract-xfa-packets	extractXfaPackets	xfa_packets[]
extract_text_metadata / --extract-text-metadata	extractTextMetadata	text_items[] 上的额外键
include_complexity / --complexity	includeComplexity	pages[].complexity
emit_word_boxes （无 CLI 参数）	emitWordBoxes	TextItem.words（仅绑定层）

有一个开关默认是开的：extract_links（用 --no-links 关闭）。见 Markdown 指南。

开启选项

• TypeScript
• Python
• Rust
• CLI

import { LiteParse } from "@llamaindex/liteparse";

const parser = new LiteParse({
  outputFormat: "json",
  extractImages: true,
  extractFormFields: true,
  extractAnnotations: true,
  extractTextMetadata: true,
});

const result = await parser.parse("form.pdf");

from liteparse import LiteParse

parser = LiteParse(
    output_format="json",
    extract_images=True,
    extract_form_fields=True,
    extract_annotations=True,
    extract_text_metadata=True,
)

result = parser.parse("form.pdf")

use liteparse::{LiteParse, LiteParseConfig, OutputFormat};

let config = LiteParseConfig {
    output_format: OutputFormat::Json,
    extract_images: true,
    extract_form_fields: true,
    extract_annotations: true,
    extract_text_metadata: true,
    ..Default::default()
};

let result = LiteParse::new(config).parse("form.pdf").await?;

终端窗口

lit parse form.pdf --format json \
  --extract-images \
  --extract-form-fields \
  --extract-annotations \
  --extract-text-metadata

内嵌图片

extract_images 会解码内嵌位图，并在文档级的 images 数组里返回它们的字节与元数据。配合 image_output_dir 使用可以把每张图片写到磁盘，而不是留在内存里。

终端窗口

lit parse report.pdf --format json --extract-images --image-output-dir ./images

{
  "images": [
    {
      "id": "p1_i0",
      "name": "image_p1_0.png",
      "path": "./images/image_p1_0.png",
      "page": 1,
      "bbox": { "x": 72.0, "y": 118.5, "width": 240.0, "height": 160.0 },
      "width": 800,
      "height": 533,
      "rotation": 0.0,
      "format": "png"
    }
  ],
  "image_error_count": 0
}

请注意：

• image_output_dir 要求同时开启 extract_images —— 单独设置它是配置错误。为向后兼容，image_mode: "embed" 也会隐含开启抽取。
• 同一张图片在文档里出现多次时会设置 duplicate_of；重复项指向规范条目的 id，而不是重新存放一份像素。
• image_error_count 统计解码失败的图片数。为零时该键不出现。
• 这与 image_mode 是两件事，后者只控制图片引用如何写进 markdown。见 Markdown 指南。

矢量图形

extract_vector_graphics 会上报每页的矢量绘制操作，分为填充/描边的 shapes 与笔直的 lines。用来寻找表格线、下划线、分隔线与图表几何很合适。

{
  "vector_graphics": {
    "shapes": [
      {
        "bbox": { "x": 72.0, "y": 400.0, "width": 180.0, "height": 90.0 },
        "stroke": true,
        "stroke_color": "#000000",
        "fill": false,
        "has_curve": true
      }
    ],
    "lines": [
      {
        "x1": 72.0, "y1": 512.0, "x2": 540.0, "y2": 512.0,
        "stroke": true,
        "stroke_width": 0.5,
        "stroke_color": "#cccccc",
        "fill": false
      }
    ]
  }
}

批注

extract_annotations 按页返回 PDF 批注 —— 注释、高亮与链接目标。

{
  "annotations": [
    {
      "subtype": "Link",
      "rect": { "x": 72.0, "y": 300.0, "width": 120.0, "height": 12.0 },
      "uri": "https://example.com"
    },
    {
      "subtype": "Highlight",
      "contents": "check this figure",
      "title": "Reviewer 2",
      "created": "D:20260714093000Z",
      "quadpoint_rects": [
        { "x": 72.0, "y": 280.0, "width": 200.0, "height": 11.0 }
      ]
    }
  ]
}

只有 subtype 一定存在；批注未携带的其他键都会被省略。

表单字段

extract_form_fields 返回 AcroForm 控件及其解析后的值。

{
  "form_fields": [
    {
      "id": "f0",
      "type": "text",
      "page": 1,
      "annotation_index": 0,
      "widget_index": 0,
      "field_flags": 0,
      "name": "applicant_name",
      "value": "Ada Lovelace",
      "rect": { "x": 150.0, "y": 640.0, "width": 220.0, "height": 18.0 }
    },
    {
      "id": "f1",
      "type": "checkbox",
      "page": 1,
      "annotation_index": 1,
      "widget_index": 0,
      "field_flags": 0,
      "name": "agree_terms",
      "checked": true
    }
  ]
}

控件类型在 JSON 里序列化为 type，在 Node 与 Python 对象上也叫 type。单选组与复选框组会暴露 control_count/control_index 用来把同级控件关联起来，选项类字段会暴露 options/selected_options。

对于XFA 表单（另一种基于 XML 的表单技术），请改用 extract_xfa_packets，它在文档级返回原始的 XFA 数据包。

相关项：render_form_fields 会把已填写的字段外观画进渲染出的位图。它影响的是截图与 OCR 输入像素，而不是 JSON 的键。

结构树

extract_structure_tree 返回标签 PDF 的逻辑结构 —— 即撰写时生成的段落、标题、表格与列表大纲。只有确实做过标签化的 PDF 才有。

{
  "structure_tree": {
    "roots": [
      {
        "type": "Document",
        "children": [
          {
            "type": "H1",
            "marked_content_ids": [0],
            "actual_text": "Quarterly Report",
            "children": []
          },
          {
            "type": "P",
            "marked_content_ids": [1, 2],
            "children": []
          }
        ]
      }
    ]
  }
}

marked_content_ids 可以关联回文字项上的 mcid 字段（需要开启 extract_text_metadata），从而把重建出的文本映射到它原本的角色。

版面块

extract_blocks 会把页面拆解成若干块 —— 标题、段落、列表项、表格、代码、分隔线与图形 —— 每块都带上它来自页面的哪个区域。这与 Markdown 渲染器所用的分类是同一套。

终端窗口

lit parse document.pdf --format json --extract-blocks

只有与该块 kind 相关的字段才会出现：

{
  "kind": "heading",
  "text": "Quarterly Report",
  "level": 1,
  "bbox": { "x": 72.0, "y": 114.88, "width": 284.0, "height": 21.0 }
}

字段	适用的 Kinds	含义
kind	所有	heading, paragraph, list_item, code, table, grid_fallback, rule, figure
bbox	所有	所占区域，坐标空间与 text_items 一致
text	heading, paragraph, list_item	渲染出的文本
level	heading, list_item	标题层级 1–6，或列表嵌套深度
bold, italic	paragraph, list_item	当整块都被强调时出现
ordered, marker	list_item	列表是否有序，以及原样出现的标记（138.、iii)、•）
lines, lang	code, grid_fallback	逐行的原文，以及尽力而为的语言提示
header, rows	table	单元格，每个都自带 text 与 bbox
id, format	figure	与 Markdown 输出里的 img_{id}.{format} 目标对应

bbox 是构成该块的所有来源行的并集，因此一个换行的标题或多行段落会上报它占据的整条区域 —— 而不只是第一行。

表格

表格单元格是对象而不是裸字符串：每个单元格自带 bbox，于是一个单元格可以映射回它被读取的那块区域。

{
  "kind": "table",
  "bbox": { "x": 67.9, "y": 511.1, "width": 458.4, "height": 111.0 },
  "header": [
    { "text": "Title of each class", "bbox": { "x": 132.7, "y": 511.1, "width": 64.0, "height": 8.0 } },
    { "text": "Trading symbol(s)",   "bbox": { "x": 288.7, "y": 511.1, "width": 35.0, "height": 8.0 } }
  ],
  "rows": [
    [
      { "text": "Common Stock", "bbox": { "x": 67.9, "y": 522.4, "width": 193.0, "height": 9.5 } },
      { "text": "AAPL",         "bbox": { "x": 293.8, "y": 522.4, "width": 24.0, "height": 9.5 } }
    ]
  ]
}

对有框表格，单元格的框就是画出的网格单元；对无边框表格，则是该单元格由哪些跨度构成所对应的范围。只为补齐参差网格而存在的单元格没有 bbox —— 它们背后没有任何墨迹。

把表格装进 dataframe 因此只需两行转换：

• Python
• TypeScript

import pandas as pd
from liteparse import LiteParse

result = LiteParse(extract_blocks=True).parse("10-k.pdf")

for page in result.pages:
    for block in page.blocks or []:
        if block.kind == "table":
            df = pd.DataFrame(
                [[c.text for c in row] for row in block.rows],
                columns=[c.text for c in block.header or []],
            )

import { LiteParse } from "@llamaindex/liteparse";

const { pages } = await new LiteParse({ extractBlocks: true }).parse("10-k.pdf");

for (const page of pages) {
  for (const block of page.blocks ?? []) {
    if (block.kind !== "table") continue;
    const grid = [block.header ?? [], ...block.rows].map((r) => r.map((c) => c.text));
  }
}

文字元数据

extract_text_metadata 会为 text_items[] 里的每一项补充排版细节。不开启时，一个文字项只带 text、x、y、width、height、font_name 与 font_size。

{
  "text": "Quarterly Report",
  "x": 72.0, "y": 118.5, "width": 180.4, "height": 14.0,
  "rotation": 0.0,
  "font_name": "Helvetica-Bold",
  "font_size": 14.0,
  "font_height": 14.2,
  "font_ascent": 11.1,
  "font_descent": -3.1,
  "font_weight": 700,
  "text_width": 180.4,
  "font_is_buggy": false,
  "mcid": 0,
  "fill_color": "#111111"
}

当你需要比 markdown 输出更强的控制力时，font_weight 与 fill_color 就是自己判断强调与标题的实用手段。font_is_buggy 会标记那些 LiteParse 不得不估算度量的字体 —— 这些项给出的尺寸要谨慎对待。

内容边界

extract_content_bounds 会为每页加上一个 content_bounds 矩形：实际内容的边界框，忽略页面声明的 media box。可以用它裁掉留白，或检测内容远离名义页面区域的页。

{ "content_bounds": { "x": 68.0, "y": 96.0, "width": 476.0, "height": 620.0 } }

逐词框

emit_word_boxes 会把每个文字项拆成逐词的子框（TextItem.words），用于词级别的边界框归属。

这一项只在库与绑定层提供。逐词框被刻意排除在 --format json 之外，因为在一篇文字密集的文档里，它的体积会压过其余所有载荷。没有 CLI 参数；请从 Node、Python、Rust 或 WASM 里使用它。

• TypeScript
• Python

const parser = new LiteParse({ emitWordBoxes: true });
const result = await parser.parse("report.pdf");

for (const item of result.pages[0].textItems) {
  for (const word of item.words ?? []) {
    console.log(word.text, word.x, word.y, word.width, word.height);
  }
}

parser = LiteParse(emit_word_boxes=True)
result = parser.parse("report.pdf")

for item in result.pages[0].text_items:
    for word in item.words:
        print(word.text, word.x, word.y, word.width, word.height)

没有 CLI 参数的选项

有几个配置项只能从库与绑定层访问：

选项	说明
emit_word_boxes	逐词子框（见上文）。
crop_box	把输出限制在每页的某个子区域。文字项只有完全落在其中才会保留。
skip_diagonal_text	丢弃与最近直角偏离超过 2° 的文字 —— 水印与斜盖章。
page_orientation_corrections	在抽取前对指定页做反向旋转，角度取自你自己的朝向分类器（见下文）。
detect_screenshot_rects	在截图结果里填充 rects。
render_form_fields	把表单字段外观画进渲染出的页面。
ocr_failure_fatal	为 false 时，系统性的 OCR 失败返回部分结果而不是报错。默认为 true。
ocr_hedge_delays_ms	针对 HTTP OCR 服务的请求对冲时间表。对内置 Tesseract 无影响。

crop_box 接受从每边裁掉的比例。在 Node 与 WASM 里它是一个对象，在 Python 里是 (top, right, bottom, left) 元组：

• TypeScript
• Python

// Drop the top 10% and bottom 5% of every page
const parser = new LiteParse({
  cropBox: { top: 0.1, right: 0.0, bottom: 0.05, left: 0.0 },
});

# (top, right, bottom, left)
parser = LiteParse(crop_box=(0.1, 0.0, 0.05, 0.0))

纠正页面朝向

LiteParse 会遵循页面的 /Rotate 项，但一页若只是内容上下颠倒或侧放（常见于扫描页），并不带这种提示：它的文字层（或 OCR 位图）是自下而上读取的，于是阅读顺序与标签/取值对都会反过来。如果你在渲染出的页面上跑了朝向分类器，就把它的结论交给 page_orientation_corrections。每条记录指明一个从 1 开始的页号，以及该页内容呈现出的顺时针旋转角（0、90、180 或 270）；LiteParse 会在抽取前反向旋转该页，于是文字坐标、阅读顺序、页面尺寸、OCR 位图与截图都会正向输出。未列出的页，以及超出文档末尾的页，保持原样不变。

• TypeScript
• Python

// Page 3 was scanned upside down, page 7 sideways (content rotated 90° clockwise)
const parser = new LiteParse({
  pageOrientationCorrections: [
    { page: 3, angle: 180 },
    { page: 7, angle: 90 },
  ],
});

# (page, angle) pairs
parser = LiteParse(page_orientation_corrections=[(3, 180), (7, 90)])

后续步骤

• 文档复杂度：在解析前先给文档分流。
• Markdown 输出：markdown 里的图片、链接与页眉/页脚处理。
• 视觉引用：把块与文字项的框变成渲染页面上的高亮。
• CLI 参考：逐条列出每个命令的参数。
• API 参考：完整的 LiteParseConfig 字段清单。