快速上手 | BytesRouter

快速开始

上传文档

本指南使用一份包含发票与出口证明的运输单据示例包。先下载它：

终端窗口

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

然后用 Files API 上传。

Python
TypeScript
Go
Java
CLI
cURL

如果还没装 Python SDK，先安装：

终端窗口

pip install "llama-cloud>=2.8"

然后上传你的文件：

from llama_cloud import LlamaCloud

client = LlamaCloud()  # reads LLAMA_CLOUD_API_KEY from the environment

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

如果还没装 TypeScript SDK，先安装：

终端窗口

npm install @llamaindex/llama-cloud

然后上传你的文件：

import fs from "fs";
import { LlamaCloud } from "@llamaindex/llama-cloud";

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

const fileObj = await client.files.create({
  file: fs.createReadStream('file.pdf'),
  purpose: 'split',
});
console.log(fileObj.id);

如果还没装 Go SDK，先安装：

终端窗口

go get github.com/run-llama/llama-parse-go

然后上传你的文件：

package main

import (
  "context"
  "fmt"
  "log"
  "os"

  llamacloud "github.com/run-llama/llama-parse-go"
)

func main() {
  client := llamacloud.NewClient()

  f, err := os.Open("file.pdf")
  if err != nil {
    log.Fatal(err)
  }
  defer f.Close()

  fileObj, err := client.Files.New(context.TODO(), llamacloud.FileNewParams{
    File:    f,
    Purpose: "split",
  })
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(fileObj.ID)
}

如果还没装 Java SDK，先安装：

implementation("ai.llamaindex:llama-cloud:1.3.0")

然后上传你的文件：

import ai.llamaindex.llamacloud.client.LlamaCloudClient;
import ai.llamaindex.llamacloud.client.okhttp.LlamaCloudOkHttpClient;
import ai.llamaindex.llamacloud.models.files.FileCreateParams;
import ai.llamaindex.llamacloud.models.files.FileCreateResponse;
import java.nio.file.Paths;

LlamaCloudClient client = LlamaCloudOkHttpClient.fromEnv();

FileCreateResponse fileObj = client.files().create(
    FileCreateParams.builder()
        .file(Paths.get("file.pdf"))
        .purpose("split")
        .build()
);
System.out.println(fileObj.id());

如果还没装 CLI，先安装：

终端窗口

go install github.com/run-llama/llama-parse-cli/cmd/llp@latest

然后上传你的文件：

终端窗口

llp files create \
  --file file.pdf \
  --purpose split

终端窗口

curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/files' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -F 'purpose=split' \
  -F 'file=@file.pdf;type=application/pdf'

把返回的 id 存为你的 FILE_ID。

创建切分任务

用你的文件 ID 与类别定义创建一个切分任务：

Python
TypeScript
Go
Java
CLI
cURL

job = client.beta.split.create(
  document_input={"type": "file_id", "value": file_obj.id},
  configuration={
    "categories": [
      {
        "name": "invoice",
        "description": "A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms"
      },
      {
        "name": "certificate",
        "description": "A certificate of origin, health certificate, or other export certificate issued by a government agency or chamber of commerce"
      }
    ]
  },
)

const job = await client.beta.split.create({
  document_input: { type: "file_id", value: fileObj.id },
  configuration: {
    categories: [
      {
        name: "invoice",
        description: "A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms"
      },
      {
        name: "certificate",
        description: "A certificate of origin, health certificate, or other export certificate issued by a government agency or chamber of commerce"
      }
    ]
  },
});

job, err := client.Beta.Split.New(context.TODO(), llamacloud.BetaSplitNewParams{
  DocumentInput: llamacloud.SplitDocumentInputParam{
    Type:  "file_id",
    Value: fileObj.ID,
  },
  Configuration: llamacloud.BetaSplitNewParamsConfiguration{
    Categories: []llamacloud.SplitCategoryParam{
      {
        Name:        "invoice",
        Description: llamacloud.String("A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms"),
      },
      {
        Name:        "certificate",
        Description: llamacloud.String("A certificate of origin, health certificate, or other export certificate issued by a government agency or chamber of commerce"),
      },
    },
  },
})
if err != nil {
  log.Fatal(err)
}

import ai.llamaindex.llamacloud.models.beta.split.SplitCategory;
import ai.llamaindex.llamacloud.models.beta.split.SplitCreateParams;
import ai.llamaindex.llamacloud.models.beta.split.SplitCreateResponse;
import ai.llamaindex.llamacloud.models.beta.split.SplitDocumentInput;

SplitCreateResponse job = client.beta().split().create(
    SplitCreateParams.builder()
        .documentInput(
            SplitDocumentInput.builder()
                .type("file_id")
                .value(fileObj.id())
                .build())
        .configuration(
            SplitCreateParams.Configuration.builder()
                .addCategory(
                    SplitCategory.builder()
                        .name("invoice")
                        .description("A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms")
                        .build())
                .addCategory(
                    SplitCategory.builder()
                        .name("certificate")
                        .description("A certificate of origin, health certificate, or other export certificate issued by a government agency or chamber of commerce")
                        .build())
                .build())
        .build()
);

终端窗口

llp beta:split create \
  --document-input "{type: file_id, value: $FILE_ID}" \
  --configuration '{categories: [{name: invoice, description: "A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms"}, {name: certificate, description: "A certificate of origin, health certificate, or other export certificate issued by a government agency or chamber of commerce"}]}'

终端窗口

curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/split/jobs' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -d '{
    "document_input": {
      "type": "file_id",
      "value": "YOUR_FILE_ID"
    },
    "configuration": {
      "categories": [
        {
          "name": "invoice",
          "description": "A commercial document requesting payment for goods or services, typically containing line items, totals, and payment terms"
        },
        {
          "name": "certificate",
          "description": "A certificate of origin, health certificate, or other export certificate issued by a government agency or chamber of commerce"
        }
      ]
    }
  }'

响应里含任务 ID 与初始状态：

{
  "id": "spl-abc123...",
  "status": "pending"
}

轮询任务完成

任务是异步处理的。轮询状态直到它进入终态 —— completed、failed 或 cancelled：

Python
TypeScript
Go
Java
CLI
cURL

completed_job = client.beta.split.wait_for_completion(
    job.id,
    polling_interval=1.0,
    verbose=True,
)

const completedJob = await client.beta.split.waitForCompletion(
  job.id,
  { pollingInterval: 1.0, verbose: true, }
);

completedJob, err := client.Beta.Split.Get(context.TODO(), job.ID, llamacloud.BetaSplitGetParams{})
if err != nil {
  log.Fatal(err)
}
for completedJob.Status != "completed" &&
  completedJob.Status != "failed" &&
  completedJob.Status != "cancelled" {
  time.Sleep(2 * time.Second)
  completedJob, err = client.Beta.Split.Get(context.TODO(), job.ID, llamacloud.BetaSplitGetParams{})
  if err != nil {
    log.Fatal(err)
  }
}

import ai.llamaindex.llamacloud.models.beta.split.SplitGetResponse;

SplitGetResponse completedJob = client.beta().split().get(job.id());
while (!completedJob.status().equals("completed")
    && !completedJob.status().equals("failed")
    && !completedJob.status().equals("cancelled")) {
    Thread.sleep(2000);
    completedJob = client.beta().split().get(job.id());
}

终端窗口

while true; do
  STATUS=$(llp beta:split get "$JOB_ID" | jq -er '.status') || break
  case "$STATUS" in
    completed|failed|cancelled) break ;;
  esac
  sleep 2
done

llp beta:split get "$JOB_ID"

终端窗口

curl -X 'GET' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/split/jobs/YOUR_JOB_ID' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

取得结果

任务成功结束后，响应里会带上切分结果。在这份示例包里，两张发票会作为 invoice 段返回，出口证明作为 certificate 段，而采购订单与运输单据则归入 uncategorized。段的边界与置信度在不同次运行之间会有差异。某一次运行返回：

{
  "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" }
    ]
  }
}

每个段包含：

category：被分到的类别名
pages：属于该段的页号数组（从 1 开始）
confidence_category：置信档位（high、medium 或 low）

进阶选项

未分类页

默认情况下，没有命中任何已定义类别的页会被归为 uncategorized 并包含在结果里。你可以用 splitting_strategy 里的 allow_uncategorized 选项控制这一行为：

取值	行为
`"include"`（默认）	未命中任何类别的页会被归为 `uncategorized` 并包含在结果里
`"forbid"`	所有页都必须被分到已定义的类别中
`"omit"`	未命中任何类别的页不会出现在结果里

例如，要把未分类页从结果里排除：

Python
TypeScript
Go
Java
CLI
cURL

job = client.beta.split.create(
  document_input={"type": "file_id", "value": file_obj.id},
  configuration={
    "categories": [
      {
        "name": "invoice",
        "description": "A commercial document requesting payment for goods or services"
      }
    ],
    "splitting_strategy": {"allow_uncategorized": "omit"}
  },
)

const job = await client.beta.split.create({
  document_input: { type: "file_id", value: fileObj.id },
  configuration: {
    categories: [
      {
        name: "invoice",
        description: "A commercial document requesting payment for goods or services"
      }
    ],
    splitting_strategy: { allow_uncategorized: "omit" }
  },
});

job, err := client.Beta.Split.New(context.TODO(), llamacloud.BetaSplitNewParams{
  DocumentInput: llamacloud.SplitDocumentInputParam{
    Type:  "file_id",
    Value: fileObj.ID,
  },
  Configuration: llamacloud.BetaSplitNewParamsConfiguration{
    Categories: []llamacloud.SplitCategoryParam{
      {
        Name:        "invoice",
        Description: llamacloud.String("A commercial document requesting payment for goods or services"),
      },
    },
    SplittingStrategy: llamacloud.BetaSplitNewParamsConfigurationSplittingStrategy{
      AllowUncategorized: "omit",
    },
  },
})
if err != nil {
  log.Fatal(err)
}

SplitCreateResponse job = client.beta().split().create(
    SplitCreateParams.builder()
        .documentInput(
            SplitDocumentInput.builder()
                .type("file_id")
                .value(fileObj.id())
                .build())
        .configuration(
            SplitCreateParams.Configuration.builder()
                .addCategory(
                    SplitCategory.builder()
                        .name("invoice")
                        .description("A commercial document requesting payment for goods or services")
                        .build())
                .splittingStrategy(
                    SplitCreateParams.Configuration.SplittingStrategy.builder()
                        .allowUncategorized(
                            SplitCreateParams.Configuration.SplittingStrategy.AllowUncategorized.OMIT)
                        .build())
                .build())
        .build()
);

终端窗口

llp beta:split create \
  --document-input "{type: file_id, value: $FILE_ID}" \
  --configuration '{categories: [{name: invoice, description: "A commercial document requesting payment for goods or services"}], splitting_strategy: {allow_uncategorized: omit}}'

终端窗口

curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/split/jobs' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -d '{
    "document_input": {
      "type": "file_id",
      "value": "YOUR_FILE_ID"
    },
    "configuration": {
      "categories": [
        {
          "name": "invoice",
          "description": "A commercial document requesting payment for goods or services"
        }
      ],
      "splitting_strategy": {
        "allow_uncategorized": "omit"
      }
    }
  }'

用 "omit" 时，不匹配 invoice 的页就不会出现在响应里。若要把所有页都强行归入已定义类别，则把 allow_uncategorized 设为 "forbid"。

自定义指令

splitting_strategy 里的 custom_instructions 接受自由形式的指引，用来影响段边界落在哪里、以及页面如何被分类。它适合放那些塞不进单条类别描述的规则 —— 例如告诉分类器：近乎空白的扫描页属于它前面那份文档，而不是新起一个段。指令最长 5,000 字符。

Python
TypeScript
Go
Java
CLI
cURL

job = client.beta.split.create(
  document_input={"type": "file_id", "value": file_obj.id},
  configuration={
    "categories": [
      {
        "name": "invoice",
        "description": "A commercial document requesting payment for goods or services"
      }
    ],
    "splitting_strategy": {
      "custom_instructions": "Near-blank scanned pages, such as blank backs or separator sheets, continue the preceding document instead of starting a new segment."
    }
  },
)

const job = await client.beta.split.create({
  document_input: { type: "file_id", value: fileObj.id },
  configuration: {
    categories: [
      {
        name: "invoice",
        description: "A commercial document requesting payment for goods or services"
      }
    ],
    splitting_strategy: {
      custom_instructions: "Near-blank scanned pages, such as blank backs or separator sheets, continue the preceding document instead of starting a new segment."
    }
  },
});

job, err := client.Beta.Split.New(context.TODO(), llamacloud.BetaSplitNewParams{
  DocumentInput: llamacloud.SplitDocumentInputParam{
    Type:  "file_id",
    Value: fileObj.ID,
  },
  Configuration: llamacloud.BetaSplitNewParamsConfiguration{
    Categories: []llamacloud.SplitCategoryParam{
      {
        Name:        "invoice",
        Description: llamacloud.String("A commercial document requesting payment for goods or services"),
      },
    },
    SplittingStrategy: llamacloud.BetaSplitNewParamsConfigurationSplittingStrategy{
      CustomInstructions: llamacloud.String("Near-blank scanned pages, such as blank backs or separator sheets, continue the preceding document instead of starting a new segment."),
    },
  },
})
if err != nil {
  log.Fatal(err)
}

SplitCreateResponse job = client.beta().split().create(
    SplitCreateParams.builder()
        .documentInput(
            SplitDocumentInput.builder()
                .type("file_id")
                .value(fileObj.id())
                .build())
        .configuration(
            SplitCreateParams.Configuration.builder()
                .addCategory(
                    SplitCategory.builder()
                        .name("invoice")
                        .description("A commercial document requesting payment for goods or services")
                        .build())
                .splittingStrategy(
                    SplitCreateParams.Configuration.SplittingStrategy.builder()
                        .customInstructions("Near-blank scanned pages, such as blank backs or separator sheets, continue the preceding document instead of starting a new segment.")
                        .build())
                .build())
        .build()
);

终端窗口

llp beta:split create \
  --document-input "{type: file_id, value: $FILE_ID}" \
  --configuration '{categories: [{name: invoice, description: "A commercial document requesting payment for goods or services"}], splitting_strategy: {custom_instructions: "Near-blank scanned pages, such as blank backs or separator sheets, continue the preceding document instead of starting a new segment."}}'

终端窗口

curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/split/jobs' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -d '{
    "document_input": {
      "type": "file_id",
      "value": "YOUR_FILE_ID"
    },
    "configuration": {
      "categories": [
        {
          "name": "invoice",
          "description": "A commercial document requesting payment for goods or services"
        }
      ],
      "splitting_strategy": {
        "custom_instructions": "Near-blank scanned pages, such as blank backs or separator sheets, continue the preceding document instead of starting a new segment."
      }
    }
  }'

custom_instructions 会与 splitting_strategy 的其他选项以及你的类别描述一起生效，而不是取代它们。

页选择

target_pages 可把任务限制在某个已完成 Parse 任务的部分页上，并决定这些页按什么顺序被切分。它在 POST /api/v1/split/jobs 上可用，此时 file_input 传的是 Parse 任务 ID。

页按列出的顺序切分："2,1,3-5" 表示先读第 2 页，再第 1 页，然后第 3 到 5 页。这可以用来修正页序错乱的扫描件。段的 pages 仍保留文档自身的页号，并维持该顺序。超出文档末尾的页会被跳过。

终端窗口

curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v1/split/jobs' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -d '{
    "file_input": "YOUR_PARSE_JOB_ID",
    "configuration": {
      "categories": [
        {
          "name": "invoice",
          "description": "A commercial document requesting payment for goods or services"
        }
      ],
      "target_pages": "2,1,3-5"
    }
  }'

使用 project ID

如果你是在某个特定 project 内工作，请带上 project_id 查询参数：

Python
TypeScript
Go
Java
CLI
cURL

job = client.beta.split.create(
  ...,
  project_id="YOUR_PROJECT_ID"
)

const job = await client.beta.split.create({
  ...,
  project_id: "YOUR_PROJECT_ID"
});

job, err := client.Beta.Split.New(context.TODO(), llamacloud.BetaSplitNewParams{
  // ...
  ProjectID: llamacloud.String("YOUR_PROJECT_ID"),
})

SplitCreateResponse job = client.beta().split().create(
    SplitCreateParams.builder()
        // ...
        .projectId("YOUR_PROJECT_ID")
        .build()
);

终端窗口

llp beta:split create \
  --project-id YOUR_PROJECT_ID \
  ...

终端窗口

curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v1/beta/split/jobs?project_id=YOUR_PROJECT_ID' \
  ...

完整 API 文档

这里只是帮助你上手的部分端点。

全部可用端点见我们的完整 API 文档。

索引

数据加载

查询

存储

成本分析

应用

聊天机器人

问答

结构化数据

智能体

Chat Engines

Query Engine

连接器

文档与节点

摄取流水线

节点解析器

大语言模型

提示词

回调

节点后处理器

响应合成器

检索器

路由

结构化输出

现有数据

Presets and Modes

能力

起步

能力

Examples

Azure Deployment

Databases and Queues

LLM Integrations

快速开始

上传文档

创建切分任务

轮询任务完成

取得结果

进阶选项

未分类页

自定义指令

页选择

使用 project ID

完整 API 文档

友情链接