BytesRouter

主题

LlamaParse 文档版本 跟随上游 源快照 687b39ae 更新于 2026-10-16

预览阶段

Verify API 会对一份文档或图片做一次异步的真实性审查。预览阶段 API 访问受限，且接口可能变动。

开始之前

调用 Verify API 需要：

  • 一个有权访问 Verify 的 LlamaCloud API key
  • 承接该任务的 LlamaCloud project 的 ID
  • 一个待审查的 PDF、DOCX、PNG、JPEG 或 WebP 文件

把 API key 与 project ID 设成环境变量：

终端窗口

export LLAMA_CLOUD_API_KEY="llx-..."
export PROJECT_ID="YOUR_PROJECT_ID"

为 Verify 配好 SDK 客户端

SDK 从 Python 与 TypeScript 2.18.0、Java 1.9.0、Go 1.10.0 起，把 Verify 暴露在 client.alpha.verify 下。alpha 命名空间意味着这些方法会在小版本之间变动。下面每一步同时也给出等价的 REST 调用。

  • Python
  • TypeScript
  • Go
  • Java

终端窗口

pip install "llama-cloud>=2.18"
import os
import time

from llama_cloud import LlamaCloud

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

终端窗口

npm install @llamaindex/llama-cloud
import fs from "fs";
import LlamaCloud from "@llamaindex/llama-cloud";

const client = new LlamaCloud({ apiKey: process.env.LLAMA_CLOUD_API_KEY });

终端窗口

go get github.com/run-llama/llama-parse-go
import (
  "context"
  "fmt"
  "log"
  "os"
  "time"

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

ctx := context.Background()
client := llamacloud.NewClient() // reads LLAMA_CLOUD_API_KEY
implementation("ai.llamaindex:llama-cloud:1.9.0")
import ai.llamaindex.llamacloud.client.LlamaCloudClient;
import ai.llamaindex.llamacloud.client.okhttp.LlamaCloudOkHttpClient;
import ai.llamaindex.llamacloud.models.alpha.verify.VerifyCreateParams;
import ai.llamaindex.llamacloud.models.alpha.verify.VerifyCreateResponse;
import ai.llamaindex.llamacloud.models.alpha.verify.VerifyGetDetailsResponse;
import ai.llamaindex.llamacloud.models.alpha.verify.VerifyGetParams;
import ai.llamaindex.llamacloud.models.alpha.verify.VerifyGetResponse;
import ai.llamaindex.llamacloud.models.alpha.verify.VerifyListParams;
import ai.llamaindex.llamacloud.models.files.FileCreateParams;
import ai.llamaindex.llamacloud.models.files.FileCreateResponse;
import java.nio.file.Paths;

LlamaCloudClient client = LlamaCloudOkHttpClient.fromEnv();

运行一个 Verify 任务

1. 上传文件

先下载一份改过合计金额的示例 PDF 用于审查：

终端窗口

curl -fL -o document.pdf https://cloud.llamaindex.ai/assets/demos/verify/overrun-totals-fraud.pdf

用 Files API 上传该文档：

  • Python
  • TypeScript
  • Go
  • Java
  • cURL
file_obj = client.files.create(file="document.pdf", purpose="user_data")
file_id = file_obj.id
const fileObj = await client.files.create({
  file: fs.createReadStream("document.pdf"),
  purpose: "user_data",
});
const fileId = fileObj.id;
f, err := os.Open("document.pdf")
if err != nil {
  log.Fatal(err)
}
defer f.Close()

fileObj, err := client.Files.New(ctx, llamacloud.FileNewParams{
  File:    f,
  Purpose: "user_data",
})
if err != nil {
  log.Fatal(err)
}
fileID := fileObj.ID
FileCreateResponse fileObj = client.files().create(
    FileCreateParams.builder()
        .file(Paths.get("document.pdf"))
        .purpose("user_data")
        .build());
String fileId = fileObj.id();

终端窗口

curl --request POST \
  "https://api.cloud.llamaindex.ai/api/v1/beta/files?project_id=${PROJECT_ID}" \
  --header "Authorization: Bearer ${LLAMA_CLOUD_API_KEY}" \
  --form "file=@document.pdf" \
  --form "purpose=user_data"

把该文件的 id 存成 FILE_ID。

2. 创建任务

为已上传的文件创建一个 Verify 任务：

  • Python
  • TypeScript
  • Go
  • Java
  • cURL
job = client.alpha.verify.create(
    file_input=file_id,
    configuration={"tier": "agentic"},
)
print(job.id, job.status)
const job = await client.alpha.verify.create({
  file_input: fileId,
  configuration: { tier: "agentic" },
});
console.log(job.id, job.status);
job, err := client.Alpha.Verify.New(ctx, llamacloud.AlphaVerifyNewParams{
  FileInput:     fileID,
  Configuration: llamacloud.AlphaVerifyNewParamsConfiguration{Tier: "agentic"},
})
if err != nil {
  log.Fatal(err)
}
fmt.Println(job.ID, job.Status)
VerifyCreateResponse job = client.alpha().verify().create(
    VerifyCreateParams.builder()
        .fileInput(fileId)
        .configuration(VerifyCreateParams.Configuration.builder()
            .tier(VerifyCreateParams.Configuration.Tier.AGENTIC)
            .build())
        .build());
System.out.println(job.id() + " " + job.status());

终端窗口

curl --request POST \
  "https://api.cloud.llamaindex.ai/api/alpha/verify?project_id=${PROJECT_ID}" \
  --header "Authorization: Bearer ${LLAMA_CLOUD_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "file_input": "FILE_ID",
    "configuration": {
      "tier": "agentic"
    }
  }'

响应里含该 Verify 任务的 id 与初始 status。把 id 存成 JOB_ID。

请求体接受：

字段说明
file_input必填。待审查的已上传文件 ID。目前只支持文件这一种输入，任务的 document_input_type 也始终反映为文件输入。
configuration可选的审查配置；省略时使用默认值。
transaction_id可选的幂等键，作用域限于该 project。重复使用同一个键会返回原任务，新请求体被忽略。
webhook_configurations可选的出站 webhook 端点列表，在任务状态变化时通知。Verify 任务发送 verify.* 事件；事件清单与载荷见 Webhooks。
webhook_configuration_ids可选的已保存 webhook 配置 ID 列表（最多 4 个），用于通知本任务。见复用已保存的配置。

configuration 对象接受：

字段说明
tierfast 用于快速初筛，agentic 用于更全面的审查。默认为 agentic。fast 档面向扫描件与原生产数字文档；手机拍摄这类拍照件应使用 agentic 档才能得到可靠结果。
target_pages可选的、以逗号分隔的从 1 开始的 PDF 页号或页范围，例如 1,3,5-7。省略则审查全部页。其他文件类型会忽略该字段。

3. 取回结果

Verify 任务会先经过 PENDING 与 RUNNING，再到 COMPLETED、FAILED 或 CANCELLED。轮询该任务直到它离开前两个状态，并用 expand=result 要求返回结果：

  • Python
  • TypeScript
  • Go
  • Java
  • cURL
job = client.alpha.verify.get(job.id, expand=["result"])
while job.status in ("PENDING", "RUNNING"):
    time.sleep(5)
    job = client.alpha.verify.get(job.id, expand=["result"])

if job.status == "COMPLETED" and job.result:
    print(job.result.verdict, job.result.overall_score)
let current = await client.alpha.verify.get(job.id, { expand: ["result"] });
while (current.status === "PENDING" || current.status === "RUNNING") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  current = await client.alpha.verify.get(job.id, { expand: ["result"] });
}

if (current.status === "COMPLETED" && current.result) {
  console.log(current.result.verdict, current.result.overall_score);
}
getParams := llamacloud.AlphaVerifyGetParams{Expand: []string{"result"}}
current, err := client.Alpha.Verify.Get(ctx, job.ID, getParams)
if err != nil {
  log.Fatal(err)
}
for current.Status == "PENDING" || current.Status == "RUNNING" {
  time.Sleep(5 * time.Second)
  current, err = client.Alpha.Verify.Get(ctx, job.ID, getParams)
  if err != nil {
    log.Fatal(err)
  }
}

if current.Status == "COMPLETED" {
  fmt.Println(current.Result.Verdict, current.Result.OverallScore)
}
VerifyGetParams getParams = VerifyGetParams.builder().addExpand("result").build();
VerifyGetResponse current = client.alpha().verify().get(job.id(), getParams);
while (current.status().equals(VerifyGetResponse.Status.PENDING)
        || current.status().equals(VerifyGetResponse.Status.RUNNING)) {
    Thread.sleep(5000);
    current = client.alpha().verify().get(job.id(), getParams);
}

current.result().ifPresent(result ->
    System.out.println(result.verdict() + " " + result.overallScore()));

终端窗口

curl --request GET \
  "https://api.cloud.llamaindex.ai/api/alpha/verify/JOB_ID?project_id=${PROJECT_ID}&expand=result" \
  --header "Authorization: Bearer ${LLAMA_CLOUD_API_KEY}"

当状态为 COMPLETED 时，result 对象包含：

字段说明
verdict整体真实性结论。
overall_score该文档被篡改的可能性，取值 0 到 1。
confidence现有证据对该结论的支持强度，取值 0 到 1。
tampering_score真实文档被局部编辑的可能性，取值 0 到 1。
synthetic_score整篇文档系凭空伪造的可能性，取值 0 到 1。
reasoning对该结论的通俗解释。
composite_scores针对该文档适用的各个真实性问题分别给出的得分。
suspect_regions参与结论的、按重要性排序的文档区域（在能够定位到具体区域时给出）。

如何把这些字段用于审查流程，见解读 Verify 的检查结论。

4. 查看支撑证据

任务完成后，取回结论背后的详细发现：

  • Python
  • TypeScript
  • Go
  • Java
  • cURL
details = client.alpha.verify.get_details(job.id)
for heatmap in details.heatmaps or []:
    print(heatmap.page, heatmap.kind, heatmap.url, heatmap.expires_at)
const details = await client.alpha.verify.getDetails(job.id);
for (const heatmap of details.heatmaps ?? []) {
  console.log(heatmap.page, heatmap.kind, heatmap.url, heatmap.expires_at);
}
details, err := client.Alpha.Verify.GetDetails(ctx, job.ID, llamacloud.AlphaVerifyGetDetailsParams{})
if err != nil {
  log.Fatal(err)
}
for _, heatmap := range details.Heatmaps {
  fmt.Println(heatmap.Page, heatmap.Kind, heatmap.URL, heatmap.ExpiresAt)
}
VerifyGetDetailsResponse details = client.alpha().verify().getDetails(job.id());
details.heatmaps().ifPresent(heatmaps -> heatmaps.forEach(heatmap ->
    System.out.println(heatmap.page() + " " + heatmap.kind() + " " + heatmap.url())));

终端窗口

curl --request GET \
  "https://api.cloud.llamaindex.ai/api/alpha/verify/JOB_ID/details?project_id=${PROJECT_ID}" \
  --header "Authorization: Bearer ${LLAMA_CLOUD_API_KEY}"

详情里包含支撑证据、分组得分、定位区域、可视化叠加图，以及未能运行的检查项。被列为不可用的检查项，代表的并不是它检查出结果干净，而是它针对该文件没有成功运行。

evidence 里的每一条描述一个发现：产出它的 tool、其信号 family、机器可读的 code、人类可读的 detail、一个 score，以及 hard —— 当该发现单独即可定案时为 true。metadata 存放该工具给出的原始值；它的键随工具而变，所以请把它当作供展示或审计的辅助细节，而不是一层固定形态的结构。

regions、heatmaps、page_dimensions 与 suspect_regions 上的 page 字段从 0 开始计数：PDF 的第一页、或一张独立图片，都是页 0。而 target_pages 从 1 开始计数，所以一个 configuration 里把 target_pages 设为 "3" 的任务，会把相应区域报在第 2 页上。metadata 或 detail 文本里出现的页号由各工具自己给出，可能从 1 开始。

每个定位到的区域都带一个 review 字段，给出审查者对该候选项的判断：confirmed、dismissed 或 unsure；若该区域未被单独复核，则为空字符串。review_note 解释这个判断。被判定为不成立的候选项不会出现在任务结果里那份经过筛选的 suspect_regions 列表中，但在这里仍可见。

热力图 URL 会过期

可视化叠加图以预签名 URL 返回，它们在响应生成后约一小时过期；每张叠加图的 expires_at 给出确切时间。请把它们当作临时下载链接：如果审查留痕或后续复核需要这些叠加图，请把图片字节下载下来自行保存。不要把 URL 持久化 —— 存下来的 URL 迟早会失效。只要任务还在保留期内，重新请求详情端点就会发出新的 URL。

管理 Verify 任务

操作方法与路径
创建任务POST /api/alpha/verify
查询任务GET /api/alpha/verify/{job_id}
查询支撑证据GET /api/alpha/verify/{job_id}/details
列出任务GET /api/alpha/verify
取消运行中的任务POST /api/alpha/verify/{job_id}/cancel

project_id 用于选定 project；不传时请求使用 API key 所属的 project。列出任务的请求可按状态、任务 ID 或创建时间过滤，并用 page_size 与 page_token 分页。

列出仍在运行的任务，并按 ID 取消其中一个。只有 PENDING 与 RUNNING 的任务可以被取消：

  • Python
  • TypeScript
  • Go
  • Java
  • cURL
for listed in client.alpha.verify.list(status="RUNNING"):
    print(listed.id, listed.file_input)

client.alpha.verify.cancel("JOB_ID")
for await (const listed of client.alpha.verify.list({ status: "RUNNING" })) {
  console.log(listed.id, listed.file_input);
}

await client.alpha.verify.cancel("JOB_ID");
iter := client.Alpha.Verify.ListAutoPaging(ctx, llamacloud.AlphaVerifyListParams{
  Status: llamacloud.AlphaVerifyListParamsStatusRunning,
})
for iter.Next() {
  fmt.Println(iter.Current().ID, iter.Current().FileInput)
}
if err := iter.Err(); err != nil {
  log.Fatal(err)
}

if _, err := client.Alpha.Verify.Cancel(ctx, "JOB_ID", llamacloud.AlphaVerifyCancelParams{}); err != nil {
  log.Fatal(err)
}
client.alpha().verify()
    .list(VerifyListParams.builder().status(VerifyListParams.Status.RUNNING).build())
    .autoPager()
    .forEach(listed -> System.out.println(listed.id() + " " + listed.fileInput()));

client.alpha().verify().cancel("JOB_ID");

终端窗口

curl --request GET \
  "https://api.cloud.llamaindex.ai/api/alpha/verify?project_id=${PROJECT_ID}&status=RUNNING" \
  --header "Authorization: Bearer ${LLAMA_CLOUD_API_KEY}"

curl --request POST \
  "https://api.cloud.llamaindex.ai/api/alpha/verify/JOB_ID/cancel?project_id=${PROJECT_ID}" \
  --header "Authorization: Bearer ${LLAMA_CLOUD_API_KEY}"

创建与取消任务需要对该 project 的写权限。只读的用户或 API key 在这两个请求上会拿到 403 Forbidden，但仍然可以查询、列出与查看任务。

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可