只有在你已有 Extract v1 接入时才需要这一页。 全新开始请用 v2 的概览与 SDK 指南。

Extract v2 保留了同一核心思路（由 schema 驱动的抽取），但改变了配置与运行任务的方式：

• v1 以长期存在的抽取智能体为中心，任务运行绑定 extraction_agent_id。
• v2 以抽取配置（已保存或内联）为中心，任务直接用 file_input + 配置创建。
• v2 还接受一个 Parse 任务 ID（pjb-...）作为输入，因此可以解析一次、抽取多次。

快速迁移清单

• 把 v1 的智能体/任务端点换成 v2 的 extract 端点。
• 把 extraction_agent_id + file_id 换成 file_input，再加 configuration_id 或内联 configuration 之一。
• 把 v1 的 config.extraction_mode（FAST、BALANCED、MULTIMODAL、PREMIUM）换成 v2 的 configuration.tier（cost_effective、agentic），外加可选的 parse_tier。
• 更新状态处理：v1 的 SUCCESS/ERROR/PARTIAL_SUCCESS 在 v2 变成 COMPLETED/FAILED。
• 如果你原本在管理智能体，请迁移到已保存的产品配置（product_type=extract_v2）。
• 把 SDK 代码从 client.extraction.* 的写法改为 client.extract.*。

概念对照

Extract v1	Extract v2	变了什么
Extraction Agent	Extraction Configuration	智能体的增删改查被可复用的配置对象取代
extraction_agent_id	configuration_id（已保存）或 configuration（内联）	v2 的任务请求必须指明配置来源
file_id	file_input	v2 接受文件 ID（dfl-...）或 parse 任务 ID（pjb-...）
config.extraction_mode	configuration.tier（外加可选 parse_tier）	v2 把抽取与解析的选择分开了
/jobs/{id}/result	GET /api/v2/extract/{id}	v2 在任务资源上直接返回 extract_result

端点对照（REST API）

任务

v1	v2
POST /api/v1/extraction/jobs	POST /api/v2/extract?project_id=...
GET /api/v1/extraction/jobs/{job_id}	GET /api/v2/extract/{job_id}?project_id=...
GET /api/v1/extraction/jobs/{job_id}/result	GET /api/v2/extract/{job_id}?project_id=...
没有对应的取消端点	POST /api/v2/extract/{job_id}/cancel?project_id=...

配置 / schema

v1	v2
POST /api/v1/extraction/extraction-agents	POST /api/v1/beta/configurations?project_id=...，带 product_type=extract_v2
GET /api/v1/extraction/extraction-agents	GET /api/v1/beta/configurations?project_id=...&product_type=extract_v2
POST /api/v1/extraction/extraction-agents/schema/validation	POST /api/v2/extract/schema/validation
POST /api/v1/extraction/extraction-agents/schema/generate	POST /api/v2/extract/schema/generate?project_id=...

请求/响应字段对照

创建任务的请求

v1（POST /api/v1/extraction/jobs）	v2（POST /api/v2/extract）
extraction_agent_id	configuration_id 或 configuration
file_id	file_input
data_schema_override	把 schema 放进内联的 configuration.data_schema
config_override	内联 configuration 的各字段

状态对照

v1 状态	v2 状态
PENDING	PENDING 或 RUNNING
SUCCESS	COMPLETED
PARTIAL_SUCCESS	COMPLETED（细看结果与元数据以辨详情）
ERROR	FAILED
CANCELLED	CANCELLED

档位 / 模式对照

v1 用的是 extraction_mode；v2 则显式分出抽取档与解析档。

v1 extraction_mode	v2 configuration.tier	典型的 v2 解析选择
FAST	cost_effective	parse_tier: "cost_effective"
BALANCED	cost_effective（要更高质量就用 agentic）	parse_tier: "agentic"
MULTIMODAL	agentic	parse_tier: "agentic"
PREMIUM	agentic	parse_tier: "agentic_plus"

SDK 迁移示例

v1 的写法

• Python
• TypeScript

from llama_cloud import LlamaCloud

client = LlamaCloud(api_key="...")

agent = client.extraction.extraction_agents.create(
    name="invoice-agent",
    data_schema=schema,
    config={"extraction_mode": "BALANCED"},
)

job = client.extraction.jobs.create(
    extraction_agent_id=agent.id,
    file_id=file_id,
)

import LlamaCloud from '@llamaindex/llama-cloud';

const client = new LlamaCloud({ apiKey: '...' });

const agent = await client.extraction.extractionAgents.create({
  name: 'invoice-agent',
  data_schema: schema,
  config: { extraction_mode: 'BALANCED' },
});

const job = await client.extraction.jobs.create({
  extraction_agent_id: agent.id,
  file_id: fileId,
});

v2 的写法

下载一张样例发票：

终端窗口

curl -fL -o invoice.pdf https://media.githubusercontent.com/media/run-llama/llama-datasets/main/llama_agents/invoice-contracts/invoice-2-1.pdf

• Python
• TypeScript

from llama_cloud import LlamaCloud

client = LlamaCloud()  # reads LLAMA_CLOUD_API_KEY from the environment

schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string"},
        "total_amount": {"type": "number"},
    },
}

file = client.files.create(file="./invoice.pdf", purpose="extract")

job = client.extract.create(
    file_input=file.id,  # or parse_job.id
    configuration={
        "data_schema": schema,
        "tier": "agentic",
        "parse_tier": "agentic",
        "extraction_target": "per_doc",
        "cite_sources": True,
    },
)

job = client.extract.wait_for_completion(job.id)
print(job.extract_result)

import LlamaCloud from '@llamaindex/llama-cloud';
import fs from 'fs';

const client = new LlamaCloud(); // reads LLAMA_CLOUD_API_KEY from the environment

const schema = {
  type: 'object',
  properties: {
    invoice_number: { type: 'string' },
    total_amount: { type: 'number' },
  },
};

const file = await client.files.create({
  file: fs.createReadStream('./invoice.pdf'),
  purpose: 'extract',
});

let job = await client.extract.create({
  file_input: file.id,  // or parseJob.id
  configuration: {
    data_schema: schema,
    tier: 'agentic',
    parse_tier: 'agentic',
    extraction_target: 'per_doc',
    cite_sources: true,
  },
});

job = await client.extract.waitForCompletion(job.id);
console.log(job.extract_result);

Go、Java 与 CLI 从未提供过 Extract v1 接口，所以这些 SDK 里没有需要迁移的 v1 代码 —— 直接从 Extract SDK 指南里的 v2 写法开始即可。

界面迁移说明

在 v2 界面里，你操作的是抽取配置，而不是抽取智能体。

• 需要遗留界面的 v1 用户，可以在 Settings → Preferences 下把 Extract API 设为 v1。该偏好只保存在当前浏览器里，且只有具备遗留 v1 权限的组织才看得到它。
• 做 v2 迁移时，请把你的 schema 重建或导入为配置，再从这些配置发起任务。
• 如果你管理着许多长期重复的流水线，请把配置存下来并按 configuration_id 引用。

生产环境的推荐迁移路径

1. 挑一个现有的 v1 智能体，把它的 schema 与设置移植成一份 v2 配置。
2. 用同一批样例文件在 v1 与 v2 各跑一遍，比对抽出的字段与元数据。
3. 更新客户端代码，把任务状态当作 PENDING/RUNNING/COMPLETED/FAILED/CANCELLED 处理。
4. 把批量流程改为在 v2 创建任务时传 configuration_id。
5. 验证通过后把流量切到 /api/v2/extract，在灰度期间保留 v1 作为回退。

另请参阅

• Extract 概览
• Extract SDK
• Extract REST API
• 使用已保存的配置
• Extract v1 文档（遗留）