已弃用

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

LlamaExtract 提供若干高级能力，在抽取数据之外返回额外的元数据与洞见。这些扩展在界面里位于 Advanced Settings 之下，并把 schema 级的元数据返回在响应的 extraction_metadata 字段里。

引用

引用会为每个抽取字段给出来源信息，让你能精确回溯每条数据出自原文的哪里。

工作机制：对 schema 里每一个叶子层字段，引用会返回：

• 该信息出现在第几页
• 用于得出该字段取值的原文逐字文本
• 指出被引文字在页面上确切位置的边界框坐标（x、y、w、h）
• 页面尺寸（width、height），帮你把边界框准确地绘制出来

引用信息既出现在 API 响应（extraction_metadata.field_metadata）里，也会在 LlamaCloud 界面上可视化。

API 响应结构示例（标量字段）：

"extraction_metadata": {
  "field_metadata": {
    "phone": {
      "citation": [
        {
          "page": 1,
          "matching_text": "(555) 123-4567",
          "bounding_boxes": [
            {
              "x": 177,
              "y": 82,
              "w": 318,
              "h": 43
            }
          ],
          "page_dimensions": {
            "width": 612,
            "height": 792
          }
        }
      ]
    }
  }
}

数组字段： 引用挂在叶子子字段这一层，而不是数组元素那一层。field_metadata 这棵树与你抽出的数据结构一一镜像，只是每个叶子取值被替换成了它的引用元数据。

对于像 key_facts: list[KeyFact] 这样、KeyFact 含一个 fact: str 字段的 schema，元数据结构是：

"extraction_metadata": {
  "field_metadata": {
    "key_facts": [
      {
        "fact": {
          "citation": [
            {
              "page": 3,
              "matching_text": "Revenue grew 114% year-over-year",
              "bounding_boxes": [{ "x": 50, "y": 200, "w": 400, "h": 20 }],
              "page_dimensions": { "width": 612, "height": 792 }
            }
          ]
        }
      },
      {
        "fact": {
          "citation": [
            {
              "page": 7,
              "matching_text": "Operating expenses increased to $3.2B",
              "bounding_boxes": [{ "x": 50, "y": 310, "w": 380, "h": 20 }],
              "page_dimensions": { "width": 612, "height": 792 }
            }
          ]
        }
      }
    ]
  }
}

注意：引用的路径是 field_metadata.key_facts[i].fact.citation，不是 field_metadata.key_facts[i].citation。元数据里的每个数组元素都按位置对应到抽出数据里的同一元素。

用法：用 SDK 里的 ExtractConfig.cite_sources 参数开启该能力。

适用场景：

• 合规与审计要求
• 事实核查与验证流程
• 理解抽取的质量与准确度
• 用边界框坐标自建高亮/批注功能

限制：

• 只在 MULTIMODAL 与 PREMIUM 抽取模式下可用

推理

推理为抽出的取值给出解释，帮你理解每个抽取决策背后的逻辑。

工作机制：对 schema 里每一个顶层字段，推理会返回：

• 基于所给文本、对该取值的一段简短解释
• 若文本中没有足够信息抽出该字段，则给出错误信息

用法：用 SDK 里的 ExtractConfig.use_reasoning 参数开启该能力。

适用场景：

• 调试抽取结果
• 理解模型的决策过程
• 依据抽取逻辑反过来改进 schema 设计

限制：

• 只在 BALANCED、MULTIMODAL 与 PREMIUM 抽取模式下可用

置信度得分（Beta）

置信度得分给出系统对抽出不取值的信心有多强的量化指标，帮你识别可能不可靠的抽取。

工作机制：该能力会在抽取元数据里加上三个与置信度相关的字段：

• parsing_confidence：表示相关上下文从源文档中被解析得如何的置信度。仅在 Multimodal 抽取模式下可用。
• extraction_confidence：表示基于该 JSON schema 字段的抽取相关度的置信度。
• confidence：把解析置信度与抽取置信度合在一起的组合得分。

用法：用 SDK 里的 ExtractConfig.confidence_scores 参数开启置信度得分。

**⚠️ 重要：**得分是未校准的。正确理解才能用对：

• 相对尺度才有意义，绝对值没有：置信度得分并未与真实准确率对齐。0.6 分不表示「60% 准确」—— 它也可能意味着模型在完全臆造。
• 用来比较，而不是当阈值：关注得分之间的相对差异而非绝对值。0.9 分的字段比 0.6 分的可靠，但两个分数都不能直接换算成准确率。
• 文本越长的字段得分越低：摘要、描述这类长文本字段平均分通常更低。这不代表准确度更低 —— 而是因为构造长文本的合理方式很多，模型对任一具体措辞自然更不「确定」。
• 阈值要按场景实测：触发人工复核的置信度阈值，必须用你自己的文档与场景测试后才能定。适用于财务数据抽取的阈值，未必适用于法律文书处理。
• Beta 能力可能变动：这是实验性功能。随着数据积累我们可能调整计算方式，包括在未来发布里加入真正的校准。

限制：

• 目前有不超 100 页的规模限制
• 只在 MULTIMODAL 与 PREMIUM 抽取模式下可用

适用场景：

• 质量保证流程（需先把阈值调准）
• 对多个字段的抽取可靠度做相对排序
• 在阈值验证之后，挑出可能需要人工复核的文档

性能考量

⚠️ 重要：引用与置信度得分会显著拖慢抽取的处理时长。只有当额外的元数据对你的场景确有必要时才开启它们。

配置与用法

关于如何用 Python SDK 与 REST API 配置并使用这些扩展的完整示例，见 配置选项 页。

那一节包含：

• 带扩展设置的完整 Python SDK 示例
• REST API 的 curl 命令示例
• 涵盖所有可用选项的配置参考表

扩展能力速查：

• Python
• TypeScript
• Python（legacy）

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")
file_id = file_obj.id

result = client.extraction.extract(
    file_id=file_id,
    data_schema={
        /* your extraction schema */
    },
    config={
        "cite_sources": True,        # Enable citations
        "use_reasoning": True,       # Enable reasoning
        "confidence_scores": True,   # Enable confidence scores (MULTIMODAL/PREMIUM only)
        "extraction_mode": "MULTIMODAL"  # Required for confidence scores
    }
)

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: {
    /* your extraction schema */
  },
  config: {
    cite_sources: true,        // Enable citations
    use_reasoning: true,       // Enable reasoning
    confidence_scores: true,   // Enable confidence scores (MULTIMODAL/PREMIUM only)
    extraction_mode: 'MULTIMODAL'  // Required for confidence scores
  }
});

from llama_cloud import ExtractConfig, ExtractMode

config = ExtractConfig(
    cite_sources=True,        # Enable citations
    use_reasoning=True,       # Enable reasoning
    confidence_scores=True,   # Enable confidence scores (MULTIMODAL/PREMIUM only)
    extraction_mode=ExtractMode.MULTIMODAL  # Required for confidence scores
)