已弃用

本页记录的是已弃用的 Extract v1 API。新的接入请使用 Extract v2；改造已有的 v1 代码请见v1 到 v2 迁移指南。

LlamaExtract 的核心是 schema，它定义了你想从文档里抽取的数据结构。

怎么定义你的 schema

schema 由字段构成。每个字段有一个名称、一个类型，并可选地有一段描述。

• 字段名 —— 使用清晰、稳定的名字，与你对数据的用法相符（例如 invoice_number、vendor_name）。它们会成为抽出 JSON 里的键。
• 字段描述 —— 描述是给底层大模型的额外上下文。不只是给人看的文档：抽取模型靠它来决定抽什么。请用描述告诉模型该字段的取值可能是什么 —— 例如这个字段的含义、通常出现在文档的什么位置、可接受的格式或示例。描述写得更好，抽取通常就更准确、更一致。

schema 的限制

LlamaExtract 只支持 JSON Schema 规范的一个子集。 虽然受限，但足以覆盖大量使用场景。

• required 与可空字段的行为（含一个可空的 start_date 示例）见必填与可选字段。

• 如果你在 Python SDK 里用 Pydantic 指定 schema，可以用 Optional 注解把字段标为可选。

• 根节点必须是 object 类型。

• schema 的嵌套层数必须限制在 7 层以内。

重要的字段是键名/标题、类型与描述。用于格式化、默认值等的字段不支持。若你需要这些，可以把相应约束写进字段描述，和/或加一个后处理步骤。例如默认值可以这样实现：把字段设为可选，再把抽取结果里的 "null" 值替换成你的默认值。

• 其他 schema 限制：

  • 属性上限：整个 schema 合计 5,000 个属性。
  • 字符串内容总量上限：所有字符串（字段名、描述、枚举取值等）合计 120,000 字符。
  • 原始 schema 大小上限：原始 JSON schema 字符串 150,000 字符。

若在复杂的抽取场景下触及这些上限，考虑重构抽取流程以落在这套约束内，例如分批抽取字段子集，之后再合并起来。

技巧与最佳实践

• 尽量把 schema 嵌套控制在 3–4 层。
• 数据不一定存在时把字段设为可选（尤其是 boolean 与 int 字段，缺失值的默认容易造成混淆）。
• 要抽取数量不定的实体时，用 array 类型。但注意根节点不能用 array 类型。
• 用有描述性的字段名与详尽的字段描述。把格式说明或 few-shot 示例放进描述里。
• 最重要的是：从简单开始，边迭代边把需求加进 schema。

自动生成 schema

不必手工定义 schema，你可以用 LlamaExtract 的自动 schema 生成功能。系统能基于以下输入生成：

• 一段自然语言提示词：描述你要抽取什么数据
• 一个示例文件：上传文档，让系统从它的结构推断 schema
• 一份待改进的现有 schema：给出基础 schema，让系统优化或扩展它

这些输入可以组合使用 —— 例如同时给一个示例文件和一段提示词来引导生成。

用 REST API

终端窗口

curl -X 'POST' \
  'https://api.cloud.llamaindex.ai/api/v1/extraction/extraction-agents/schema/generate' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Extract invoice details including invoice number, date, vendor name, line items with descriptions and amounts, and total amount",
    "file_id": "optional-file-id-for-sample-document"
  }'

注意

自动生成的 schema 可能包含比你需要的更多字段。投产前请审阅生成的 schema 并删掉不必要的字段 —— 更少、定义清晰的字段通常会带来更好的抽取质量。

完整 API 文档见 LlamaExtract API 参考。

用 SDK 定义 schema

• Python
• TypeScript

Python SDK 可以这样安装：

终端窗口

pip install "llama-cloud<2.0"

schema 可以用 Pydantic 模型或 JSON Schema 来定义：

用 Pydantic（推荐）

from pydantic import BaseModel, Field
from typing import List, Optional
from llama_cloud_services import LlamaExtract

class Experience(BaseModel):
    company: str = Field(description="Company name")
    title: str = Field(description="Job title")
    start_date: Optional[str] = Field(description="Start date of employment")
    end_date: Optional[str] = Field(description="End date of employment")

class Resume(BaseModel):
    name: str = Field(description="Candidate name")
    experience: List[Experience] = Field(description="Work history")

schema = Resume.model_json_schema()

用 JSON Schema

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "description": "Candidate name"},
        "experience": {
            "type": "array",
            "description": "Work history",
            "items": {
                "type": "object",
                "properties": {
                    "company": {
                        "type": "string",
                        "description": "Company name",
                    },
                    "title": {"type": "string", "description": "Job title"},
                    "start_date": {
                        "anyOf": [{"type": "string"}, {"type": "null"}],
                        "description": "Start date of employment",
                    },
                    "end_date": {
                        "anyOf": [{"type": "string"}, {"type": "null"}],
                        "description": "End date of employment",
                    },
                },
            },
        },
    },
}

有了 schema，就能直接用 SDK 跑抽取：

from llama_cloud import LlamaCloud

client = LlamaCloud(api_key="your_api_key")

file_obj = client.files.create(file="path/to/your/document.pdf", purpose="extract")

result = client.extraction.extract(
    file_id=file_obj.id,
    data_schema=schema,
    config={},
)

TypeScript SDK 可以这样安装：

终端窗口

npm install @llamaindex/llama-cloud zod

schema 可以用 Zod 模型或 JSON Schema 来定义：

用 Zod（推荐）

import { z } from "zod";

const ExperienceSchema = z.object({
  company: z.string().describe("Company name"),
  title: z.string().describe("Job title"),
  start_date: z.string().nullable().describe("Start date of employment"),
  end_date: z.string().nullable().describe("End date of employment"),
});

const ResumeSchema = z.object({
  name: z.string().describe("Candidate name"),
  experience: z.array(ExperienceSchema).describe("Work history"),
});

const schema = ResumeSchema.toJSON();

用 JSON Schema

const schema = {
  type: "object",
  properties: {
    name: { type: "string", description: "Candidate name" },
    experience: {
      type: "array",
      description: "Work history",
      items: {
        type: "object",
        properties: {
          company: {
            type: "string",
            description: "Company name",
          },
          title: { type: "string", description: "Job title" },
          start_date: {
            anyOf: [{ type: "string" }, { type: "null" }],
            description: "Start date of employment",
          },
          end_date: {
            anyOf: [{ type: "string" }, { type: "null" }],
            description: "End date of employment",
          },
        },
      },
    },
  },
};

有了 schema，就能直接用 SDK 跑抽取：

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

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

const fileObj = await client.files.create({
  file: fs.createReadStream('path/to/your/document.pdf'),
  purpose: 'extract',
});

const result = await client.extraction.extract({
  file_id: fileObj.id,
  data_schema: schema,
  config: {},
});