一个 Split 任务会返回同一个对象 —— split 任务 —— 来自 POST /api/v1/split/jobs、GET /api/v1/split/jobs/{split_job_id} 以及取消端点。SDK 的 client.split.create() 与 client.split.get() 返回的也是它。本页列出该对象的每个字段及其含义。要定义类别、跑任务请看快速上手；请求侧见 Split API 参考。

Split 目前处于 beta 阶段，可能发生破坏性变更。

任务外层结构

字段	类型	说明
id	string	任务标识，带 spl- 前缀。传给 GET /api/v1/split/jobs/{split_job_id}。
status	string	任务状态。见任务状态。
file_input	string	该任务所运行的文件 ID 或 parse 任务 ID。
document_input_type	string	file_input 指向什么：file_id、parse_job_id 或 url。
categories	array	任务据此切分的类别，每项含 name 与可选的 description。取自请求或已保存配置的回显。
splitting_strategy	object	任务实际使用的策略：allow_uncategorized、custom_instructions 与 min_pages_per_split。见未分类页与合并。
parse_tier	string 或 null	请求的 Parse 档位。null 表示使用默认的 fast。当 file_input 是已完成的 Parse 任务时不使用。
parse_config_id	string 或 null	请求的已保存 parse 配置 ID（若有）。优先级高于 parse_tier。
target_pages	string 或 null	请求的页选择（从 1 开始，"1-3,7"），若有。仅当 file_input 是已完成的 Parse 任务时接受。
configuration_id	string 或 null	本任务使用的已保存配置 ID（若有）。
result	object 或 null	切分出的段。仅当 status 为 completed 时存在。见 result.segments。
error_message	string 或 null	任务失败原因，当 status 为 failed 时给出。
transaction_id	string 或 null	创建时提供的幂等键（若有）。重复使用同一个键会返回原任务。
project_id	string	任务所属的 project。
user_id	string	创建该任务的用户。
created_at, updated_at	datetime	创建时间与最后更新时间戳。

任务状态

Split 的状态是小写的，这与 Extract、Classify 任务的全大写状态不同。

status	含义
pending	已排队，尚未开始。
processing	正在处理。
completed	已结束；result 已填充。
failed	因错误终止；result 为 null，请读 error_message。
cancelled	被用户取消；result 为 null。

轮询 GET /api/v1/split/jobs/{split_job_id}，直到状态落到三个终态之一。

result.segments

result 只有一个字段 segments，其数组的每个元素对应检测出的一节文档。每个段包含：

字段	类型	说明
category	string	该段被分到的类别 name；当没有任何类别命中且 allow_uncategorized 为 include 时为 uncategorized。
pages	array of integers	构成该段的页号（从 1 开始）。
confidence_category	string	对该归属的置信度：high、medium 或 low。

页号取自输入文档本身，因此设置了 target_pages 时它们仍指向原始页。Split 判断的是「一份文档在哪里结束、下一份从哪里开始」，所以相邻的段可以共用同一类别：连续三份发票的打包件会返回三个 invoice 段，而不是一个。

接快速上手里那份运输单据示例包：

{
  "id": "spl-abc123...",
  "status": "completed",
  "result": {
    "segments": [
      { "category": "invoice", "pages": [1], "confidence_category": "high" },
      { "category": "uncategorized", "pages": [2], "confidence_category": "high" },
      { "category": "invoice", "pages": [3], "confidence_category": "high" },
      { "category": "uncategorized", "pages": [4], "confidence_category": "high" },
      { "category": "uncategorized", "pages": [5], "confidence_category": "high" },
      { "category": "uncategorized", "pages": [6], "confidence_category": "high" },
      { "category": "uncategorized", "pages": [7], "confidence_category": "high" },
      { "category": "uncategorized", "pages": [8], "confidence_category": "high" },
      { "category": "certificate", "pages": [9], "confidence_category": "high" },
      { "category": "uncategorized", "pages": [10], "confidence_category": "high" },
      { "category": "certificate", "pages": [11], "confidence_category": "high" },
      { "category": "certificate", "pages": [12], "confidence_category": "high" },
      { "category": "certificate", "pages": [13], "confidence_category": "high" },
      { "category": "certificate", "pages": [14], "confidence_category": "high" },
      { "category": "certificate", "pages": [15], "confidence_category": "high" }
    ]
  }
}

未分类页与合并

splitting_strategy 里有三个选项会改变 result.segments 中出现哪些页：

选项	取值	对结果的影响
allow_uncategorized	include（默认）	未命中任何类别的页会被归成 category 为 uncategorized 的段。文档的每一页都会落在某个段里。
	forbid	每一页都必须归入你定义的某个类别；不会返回 uncategorized 段。
	omit	未命中任何类别的页不进入 result.segments，因此各段 pages 的并集可能小于整篇文档。
min_pages_per_split	整数，默认 1	短于该页数的段会被并入相邻的段。1 表示禁用合并。
custom_instructions	string 或 null	自由形式的指引，用来影响边界落在哪里；它与类别描述一起生效，而不是取代它们。

任务实际使用的取值会在响应的 splitting_strategy 里回显，于是读结果的人能判断「少了页」是不是有意省略的。

Beta 端点的差异

Beta 端点 POST /api/v1/beta/split/jobs 与 GET /api/v1/beta/split/jobs/{split_job_id}（SDK 里是 client.beta.split）返回同样的 id、status、categories、configuration_id、result、error_message、project_id、user_id、created_at 与 updated_at。区别在于输入的呈现方式：

Beta 响应	取代了什么
document_input —— 一个含 type（file_id）与 value（文件 ID）的对象	file_input 与 document_input_type
没有 splitting_strategy、transaction_id、parse_tier、parse_config_id 或 target_pages 字段	策略回显、幂等键与 parse 设置

result.segments 在两种端点上完全一致。

两种端点都要求：请求要么带 configuration_id，要么带内联 configuration，不能同时给。GET /api/v1/split/jobs 的列出结果与其他产品一样是 items + next_page_token + 可选 total_size 的形态，可按 status 与 job_ids 过滤；SDK 里 client.split.list() 返回一个可直接迭代的游标。

把段用于下游流程

段的 pages 数组就是下一步的把手。file_input 里的文件 ID 可以复用，所以常见做法是「每个段一个下游任务」，用从该段生成的、从 1 开始的 target_pages 字符串把范围限定在这些页上，例如 "4-8"：

• Extract：在 Extract 配置里设 target_pages，并按 category 选择 data_schema。简历册示例就是这样拼字符串的：f"{min(segment.pages)}-{max(segment.pages)}"。
• Parse：在 Parse 配置里设 page_ranges.target_pages，见页范围。
• Classify：当某个段需要比 Split 类别更细的标签时，在 classify 任务上设 parsing_configuration.target_pages。

由于 pages 是列表而不是范围，请依据它的实际值拼字符串，不要假定这些页是连续的。

获取完整响应

下载一份包含发票与出口证明的运输单据示例包：

终端窗口

curl -fL -o bundle.pdf https://cloud.llamaindex.ai/assets/demos/split/shipping.pdf

import os
import time
from llama_cloud import LlamaCloud

client = LlamaCloud(api_key=os.environ["LLAMA_CLOUD_API_KEY"])

file_obj = client.files.create(file="bundle.pdf", purpose="split")

job = client.split.create(
    file_input=file_obj.id,
    configuration={
        "categories": [
            {"name": "invoice", "description": "A commercial document requesting payment for goods or services"},
            {"name": "certificate", "description": "A certificate of origin, health certificate, or other export certificate issued by a government agency or chamber of commerce"},
        ],
        "splitting_strategy": {"allow_uncategorized": "include"},
    },
)

# Poll until the job reaches a terminal state
job = client.split.get(job.id)
while job.status not in ("completed", "failed", "cancelled"):
    time.sleep(2)
    job = client.split.get(job.id)

print(job.status, job.splitting_strategy)
if job.result is None:
    print(f"No result: {job.error_message}")
else:
    for segment in job.result.segments:
        pages = f"{min(segment.pages)}-{max(segment.pages)}"
        print(segment.category, pages, segment.confidence_category)