document-extraction-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Nutrient Data Extraction

Nutrient数据提取

Two GA primitives, two scripts. parse
(

scripts/parse.py

) returns the whole-document model — typed elements (paragraphs, tables, formulas, pictures, key-value regions, handwriting) with bounding boxes, or clean whole-document Markdown. extract
(

scripts/extract.py

) returns just the fields you define in a JSON Schema, each grounded to a page region by a per-field citation.

两个正式发布的核心功能，对应两个脚本。parse
（

scripts/parse.py

）会返回完整文档模型——包含带边界框的类型化元素（段落、表格、公式、图片、键值区域、手写内容），或是整洁的完整文档Markdown格式。extract
（

scripts/extract.py

）仅返回你在JSON Schema中定义的字段，每个字段都带有对应的引用信息，可定位到页面的具体区域。

Choosing parse vs extract

选择parse还是extract

The request is about…	Use	Why
Named target fields — "the invoice number and total", "these fields", "map to my schema", "with citations"	`extract`	One call returns your fields, cited — no need to walk every element
The whole document — "parse this", "whole-document Markdown", "chunk for embeddings", RAG, search indexing, migration	`parse`	Whole-document model / Markdown for open-ended retrieval
Every table / all key-value regions (no target schema)	`parse` (spatial)	Enumerate all elements; `extract` needs a schema of what to pull

For RAG chunking of a parsed document, see the sibling

grounded-rag-ingestion

skill. For PDF generation, conversion, OCR, redaction, signing, or any

/build

-based workflow, use the sibling

document-processor-api

skill.

请求场景…	使用	原因
指定目标字段——“发票编号和总额”“这些字段”“映射到我的Schema”“带引用信息”	`extract`	一次调用即可返回带引用的目标字段，无需遍历所有元素
处理完整文档——“解析此文档”“生成完整文档Markdown”“切分用于嵌入向量”、RAG、搜索索引、内容迁移	`parse`	完整文档模型/Markdown适用于开放式检索场景
提取所有表格/所有键值区域（无目标Schema）	`parse` （空间模式）	可枚举所有元素； `extract` 需要指定提取目标的Schema

如需对解析后的文档进行RAG切分，可查看关联的

grounded-rag-ingestion

技能。如需PDF生成、格式转换、OCR、脱敏、签名或任何基于

/build

的工作流，请使用关联的

document-processor-api

技能。

When to use

使用场景

Extract known fields with citations (invoice number, totals, dates, parties) → extract
.
Build a RAG ingestion pipeline: PDF -> Markdown -> chunks -> embeddings → parse
.
Index content for search or migrate documents into a new CMS → parse
.
Reconstruct page layout, or run layout-aware understanding (semantic roles, table cell spans, formulas in LaTeX, picture alt descriptions) → parse
.

提取带引用的已知字段（发票编号、总额、日期、参与方）→ extract
。
构建RAG数据摄入流程：PDF -> Markdown -> 切分块 -> 嵌入向量 → parse
。
为搜索场景建立内容索引，或将文档迁移至新CMS → parse
。
重建页面布局，或进行基于布局的文档理解（语义角色、表格单元格跨度、LaTeX格式公式、图片替代描述）→ parse
。

/extraction/extract

— schema field extraction with citations

/extraction/extract

—— 带引用的Schema字段提取

Define the fields you want in a JSON Schema (root

type: object

);

extract

returns

output.data

with those values and

output.metadata

with a per-field citation grounding each to a page region (

options.includeCitations

defaults on). Accepts a local file or a URL.

bash

undefined

在JSON Schema（根节点

type: object

）中定义所需字段；

extract

会返回包含对应值的

output.data

，以及包含每个字段引用信息（可定位到页面区域）的

output.metadata

（

options.includeCitations

默认开启）。支持本地文件或URL作为输入。

bash

undefined

Pull schema-defined fields from a local invoice, with citations (default)

从本地发票中提取Schema定义的字段，默认带引用信息

uv run scripts/extract.py --input invoice.pdf --schema fields.json --out result.json

From a URL, higher-accuracy mode, persist the run

从URL提取，启用高精度模式，保存运行记录

uv run scripts/extract.py --url https://example.com/form.pdf --schema fields.json
--out result.json --mode understand --store-run


Cost: `extract` bills the chosen parse mode **plus a flat +6 credits/page** (structure 7.5,
understand 15, agentic 24 cr/page). Extract has no `text` mode — the cheapest path is `structure`.
The script prints the server's authoritative
usage after the call and gates high estimates behind `--yes`. See
`references/extract-output-and-citations.md` for the response shape and citation structure.

For PDF generation, conversion, OCR, redaction, signing, watermarking, or any `/build`-based
workflow, use the sibling `document-processor-api` skill.

uv run scripts/extract.py --url https://example.com/form.pdf --schema fields.json
--out result.json --mode understand --store-run


费用说明：`extract`的费用为所选解析模式的费用**加上每页固定6积分**（structure模式7.5积分/页，understand模式15积分/页，agentic模式24积分/页）。`extract`无`text`模式——最经济的选择是`structure`模式。脚本会在调用后打印服务器返回的权威使用量，若预估费用较高，需通过`--yes`确认执行。响应格式和引用结构可查看`references/extract-output-and-citations.md`。

如需PDF生成、格式转换、OCR、脱敏、签名、加水印或任何基于`/build`的工作流，请使用关联的`document-processor-api`技能。

Setup

配置步骤

DWS Extract is a separate product from DWS Processor and has its own API key.

Get a Nutrient DWS Extract API key at https://dashboard.nutrient.io/.

Export it as

NUTRIENT_EXTRACT_API_KEY

bash

export NUTRIENT_EXTRACT_API_KEY="pdf_live_..."

Scripts live in
```
scripts/
```
relative to this SKILL.md. Use the directory containing this SKILL.md as the working directory:
bash
```
cd <directory containing this SKILL.md> && uv run scripts/<script>.py --help
```

Calling

/extraction/parse

with a DWS Processor key returns

. If your tenant has been migrated to global DWS API keys, a single key set as either

NUTRIENT_EXTRACT_API_KEY

NUTRIENT_API_KEY

will work for both products.

DWS Extract是独立于DWS Processor的产品，拥有独立的API密钥。

前往https://dashboard.nutrient.io/获取Nutrient DWS Extract API密钥。

将其导出为

NUTRIENT_EXTRACT_API_KEY

环境变量：

bash

export NUTRIENT_EXTRACT_API_KEY="pdf_live_..."

脚本位于当前SKILL.md所在目录的
```
scripts/
```
文件夹下，请将该目录作为工作目录：
bash
```
cd <SKILL.md所在目录> && uv run scripts/<script>.py --help
```

使用DWS Processor密钥调用

/extraction/parse

会返回

错误。若你的租户已迁移至全局DWS API密钥，只需设置

NUTRIENT_EXTRACT_API_KEY

或

NUTRIENT_API_KEY

其中一个即可同时用于两款产品。

/extraction/parse

— one primitive, two output shapes

/extraction/parse

—— 一个核心功能，两种输出格式

One call returns the full structural document model — typed elements with bounding boxes, confidence scores, and reading order — or a whole-document Markdown string. You always receive all element types in a single call.

一次调用即可返回完整的结构化文档模型——包含带边界框、置信度分数和阅读顺序的类型化元素，或是完整文档的Markdown字符串。单次调用会返回所有类型的元素。

Picking a mode

选择模式

Choose based on the user's intent and acceptable credit cost. All costs are extraction credits per page — a separate billing bucket from the processor API credits consumed by

/build

/sign

, OCR, and other DWS Processor endpoints.

Principle — decide from the request alone; do not ask the user clarifying questions. Walk the checks below in order. Each rule that fires sets a minimum mode — the final pick is the highest minimum across all rules that fired. If none fired, use the default (rule 5).

Explicit features named in the request are non-negotiable.
- Key-value pairs, form fields, semantic role classification (Title / SectionHeader / etc.), formulas, or handwriting → at minimum
```
understand
```
  (9 cr/pg).
- Alt text on pictures, charts, or diagrams →
```
agentic
```
  (18 cr/pg).
Document type implied by the request or filename.
- ```
form
```
  ,
```
invoice
```
  ,
```
receipt
```
  ,
```
application
```
  ,
```
claim
```
  → likely contains key-value pairs →
```
understand
```
  .
- ```
chart
```
  ,
```
infographic
```
  , or diagram-heavy doc + the user wants descriptions →
```
agentic
```
  .
OCR signal from filename or request (
```
scanned
```
,
```
image-based
```
,
```
photographed
```
,
```
handwritten
```
,
```
screenshot
```
) →
```
structure
```
minimum;
```
text
```
mode silently fails on image-only input.
Output format from intent. RAG, search indexing, embeddings, or content migration →
```
markdown
```
. Layout overlay, per-element processing, or bounded extraction →
```
spatial
```
.
No cues match anything above → documented default
```
structure
```
+
```
spatial
```
(1.5 cr/pg). Handles both born-digital and scanned, gives bounded typed elements with table cells, never silently drops content.

User intent	Mode	Output format	Cost	Notes
RAG / search indexing / content migration — born-digital PDF	`text`	`markdown`	1 cr/pg	Cheapest path; no OCR or AI needed
RAG / search indexing — scanned or image-based PDF	`structure`	`markdown`	1.5 cr/pg	OCR required before Markdown assembly
Form / invoice — enumerate all key-value regions (no target schema)	`understand`	`spatial`	9 cr/pg	AI key-value + table detection. For named fields ("the invoice number and total"), use `extract` instead
Layout-aware document understanding	`understand`	`spatial`	9 cr/pg	Semantic paragraph roles (Title, SectionHeader, etc.)
Deep visual understanding (charts, diagrams, alt text)	`agentic`	`spatial`	18 cr/pg	VLM adds alt descriptions on every picture element
Default / ambiguous intent	`structure`	`spatial`	1.5 cr/pg	Good balance: OCR + spatial elements, low cost

Confirm before running when the estimated cost exceeds 200 extraction credits — roughly 11 pages of

agentic

, 22 of

understand

, 133 of

structure

, or 200 of

text

. Surface the estimate (

pages × cost_per_page

) and ask the operator to confirm before invoking. Under that threshold, just run.

mode='text'

is incompatible with

output_format='spatial'

; the client rejects the combination before the network call.

根据用户需求和可接受的积分成本选择模式。所有费用均为每页提取积分——与

/build

、

/sign

、OCR及其他DWS Processor端点消耗的处理器API积分属于不同计费桶。

原则——仅根据请求内容判断；无需向用户确认细节。 按以下顺序检查规则，触发的每条规则会设置最低模式要求——最终选择所有触发规则中的最高最低模式。若没有规则触发，则使用默认模式（规则5）。

请求中明确提及的功能为必填项。
- 键值对、表单字段、语义角色分类（标题/章节标题等）、公式或手写内容→最低需使用
```
understand
```
  模式（9积分/页）。
- 图片、图表或示意图的替代文本→需使用
```
agentic
```
  模式（18积分/页）。
请求或文件名暗示的文档类型。
- ```
form
```
  、
```
invoice
```
  、
```
receipt
```
  、
```
application
```
  、
```
claim
```
  →可能包含键值对→使用
```
understand
```
  模式。
- ```
chart
```
  、
```
infographic
```
  或含大量示意图的文档，且用户需要描述内容→使用
```
agentic
```
  模式。
文件名或请求中的OCR信号（
```
scanned
```
、
```
image-based
```
、
```
photographed
```
、
```
handwritten
```
、
```
screenshot
```
）→最低需使用
```
structure
```
模式；
```
text
```
模式在纯图片输入时会静默失败。
需求对应的输出格式。RAG、搜索索引、嵌入向量或内容迁移→
```
markdown
```
格式。布局叠加、逐元素处理或边界提取→
```
spatial
```
格式。
无匹配上述任何线索→使用文档默认的
```
structure
```
+
```
spatial
```
模式（1.5积分/页）。可处理原生数字PDF和扫描件，返回带边界的类型化元素及表格单元格，不会静默丢失内容。

用户需求	模式	输出格式	费用	说明
RAG/搜索索引/内容迁移——原生数字PDF	`text`	`markdown`	1积分/页	最经济的选择；无需OCR或AI处理
RAG/搜索索引——扫描件或图片型PDF	`structure`	`markdown`	1.5积分/页	生成Markdown前需先进行OCR
表单/发票——枚举所有键值区域（无目标Schema）	`understand`	`spatial`	9积分/页	AI键值对+表格检测。如需提取指定字段（“发票编号和总额”），请使用 `extract`
基于布局的文档理解	`understand`	`spatial`	9积分/页	支持语义段落角色（标题、章节标题等）
深度视觉理解（图表、示意图、替代文本）	`agentic`	`spatial`	18积分/页	VLM会为每个图片元素添加替代描述
默认/模糊需求	`structure`	`spatial`	1.5积分/页	平衡方案：支持OCR+空间元素，成本低

当预估费用超过200提取积分时，请先确认再执行——约等于11页

agentic

模式、22页

understand

模式、133页

structure

模式或200页

text

模式。需展示预估费用（

页数 × 每页成本

）并请求操作人员确认后再调用。低于该阈值则直接执行。

mode='text'

与

output_format='spatial'

不兼容；客户端会在网络调用前拒绝该组合。

Invocation

调用示例

bash

undefined

bash

undefined

Default: structure mode, spatial output

默认：structure模式，spatial输出

uv run scripts/parse.py --input doc.pdf --out out.json

Markdown for RAG (text mode — cheapest)

生成用于RAG的Markdown（text模式——最经济）

uv run scripts/parse.py --input doc.pdf --out out.md --output-format markdown --mode text

Enumerate all key-value regions of a form (understand mode) — for NAMED fields use extract

枚举表单的所有键值区域（understand模式）——如需提取指定字段请使用extract

uv run scripts/parse.py --input doc.pdf --out out.json --mode understand

Agentic (VLM alt text on pictures)

Agentic模式（为图片添加VLM替代文本）

uv run scripts/parse.py --input doc.pdf --out out.json --mode agentic


The script prints extraction-credit usage after each run so you can verify the cost.

uv run scripts/parse.py --input doc.pdf --out out.json --mode agentic


脚本会在每次运行后打印提取积分使用量，以便你核对费用。

Downstream consumption

下游使用

After a single

/parse

call, slice the response for common needs:

Reading-order plain text: walk

output.elements

sorted by

(page.pageIndex, readingOrder)

, join

paragraph

and

handwriting

text

fields

Tables: project
```
cells[]
```
on each
```
table
```
element into rows/columns using
```
cell.row
```
and
```
cell.column
```
Key-value pairs: read
```
pairs[]
```
on each
```
keyValueRegion
```
element — each pair has
```
.key.value
```
and
```
.value.value
```
Formulas: read
```
latex
```
on each
```
formula
```
element
Pictures: read
```
classification
```
and
```
altDescription
```
(populated by
```
agentic
```
mode) on each
```
picture
```
element
Markdown output: call with
```
--output-format markdown
```
; the script writes the Markdown string directly

For the canonical response schema and per-mode field availability, see the official docs linked from

references/parse-output-filtering.md

; that file also lists the tools we suggest for filtering and reshaping the response.

单次

/parse

调用后，可根据需求处理响应内容：

按阅读顺序提取纯文本：按
```
(page.pageIndex, readingOrder)
```
排序遍历
```
output.elements
```
，拼接
```
paragraph
```
和
```
handwriting
```
元素的
```
text
```
字段
表格处理：将每个
```
table
```
元素的
```
cells[]
```
按
```
cell.row
```
和
```
cell.column
```
映射为行/列结构
键值对提取：读取每个
```
keyValueRegion
```
元素的
```
pairs[]
```
——每个键值对包含
```
.key.value
```
和
```
.value.value
```
公式提取：读取每个
```
formula
```
元素的
```
latex
```
字段
图片处理：读取每个
```
picture
```
元素的
```
classification
```
和
```
altDescription
```
（由
```
agentic
```
模式生成）
Markdown输出：调用时添加
```
--output-format markdown
```
参数；脚本会直接写入Markdown字符串

关于标准响应Schema和各模式的可用字段，请查看

references/parse-output-filtering.md

中链接的官方文档；该文件还列出了我们推荐的响应过滤和格式转换工具。

Input constraint

输入限制

parse.py

only accepts local file paths — the underlying API endpoint is multipart-only. For remote inputs, download the file first.

parse.py

仅接受本地文件路径——底层API端点仅支持multipart格式。如需处理远程输入，请先下载文件。

Rules

规则

Always preserve the printed credit-usage summary in script output so the operator can observe per-call cost.
Do not add a URL-fetch shortcut; the endpoint is multipart-only.

务必保留脚本输出中的积分使用量摘要，以便操作人员查看每次调用的成本。
请勿添加URL获取快捷方式；端点仅支持multipart格式。

document-extraction-api

Original

Translation

Nutrient Data Extraction

Nutrient数据提取

Choosing parse vs extract

选择parse还是extract

When to use

使用场景

`/extraction/extract`
— schema field extraction with citations

`/extraction/extract`
—— 带引用的Schema字段提取

Pull schema-defined fields from a local invoice, with citations (default)

从本地发票中提取Schema定义的字段，默认带引用信息

From a URL, higher-accuracy mode, persist the run

从URL提取，启用高精度模式，保存运行记录

Setup

配置步骤

`/extraction/parse`
— one primitive, two output shapes

`/extraction/parse`
—— 一个核心功能，两种输出格式

Picking a mode

选择模式

Invocation

调用示例

Default: structure mode, spatial output

默认：structure模式，spatial输出

Markdown for RAG (text mode — cheapest)

生成用于RAG的Markdown（text模式——最经济）

Enumerate all key-value regions of a form (understand mode) — for NAMED fields use extract

枚举表单的所有键值区域（understand模式）——如需提取指定字段请使用extract

Agentic (VLM alt text on pictures)

Agentic模式（为图片添加VLM替代文本）

Downstream consumption

下游使用

Input constraint

输入限制

Rules

规则