跳转到内容
LlamaIndex Python Documentation
TypeScript

快速入门

LlamaSheets 是一个新的测试版 API，用于从杂乱的电子表格中提取区域和表格。文档理解的关键步骤是规范化输入。使用 LlamaSheets API，它将

  1. 智能识别每个电子表格中的区域
  2. 隔离并提取电子表格中的每个区域
  3. 将它们输出为Parquet文件，这是一种受多种语言支持的便携格式，能够保留类型信息。例如，您可以直接在Python中使用Pandas将这些文件加载为数据框。
  4. 生成关于区域（提取的位置、标题、描述）和电子表格（标题、描述）的额外元数据，以协助下游流程。

基本用法

Section titled “Basic Usage”

Python SDK 提供了一种跨多个 API 调用的端到端方法来完成提取。

from llama_cloud_services.beta.sheets import LlamaSheets, SpreadsheetParsingConfig


client = LlamaSheets(api_key="...")


results = await client.aextract_regions(
    "path_to_file.xlsx",  # Supports paths, bytes, and streams
    config=SpreadsheetParsingConfig(
        sheet_names=None, # Parse all sheets
        generate_additional_metadata=True, # Generate titles/descriptions per sheet
    )
)


# Download parquet files
file_bytes = await client.adownload_region_result(
    results.id,
    results.regions[0].region_id,
    result_type="table",  # can be `table`, `extra`, or `cell_metadata`
)


# Download parquet files and convert to pandas dataframes
df = await client.adownload_region_as_dataframe(
    results.id,
    results.regions[0].region_id,
    result_type="table",
)

底层用法

Section titled “Lower-Level Usage”

使用LlamaSheets API进行区域和表格提取通常包含4个主要步骤。

下面，我们将使用 Python SDK 和原始 HTTP 调用详细说明每个步骤。

1. 上传文件

Section titled “1. Upload a File”

首先，上传一个文件，并获取文件ID：

from llama_cloud_services.beta.sheets import LlamaSheets


# Initialize the client
client = LlamaSheets(api_key="your_api_key")


# Upload a file
file_response = await client.aupload_file("path/to/your/spreadsheet.xlsx")
print(f"File ID: {file_response.id}")

2. 创建一个任务

Section titled “2. Create a job”

使用文件ID，您可以创建一个提取任务以获取任务ID：

from llama_cloud_services.beta.sheets.types import SpreadsheetParsingConfig


# Create a job with optional configuration
config = SpreadsheetParsingConfig(
    sheet_names=None,  # Parse all sheets (default)
    generate_additional_metadata=True  # Generate extra metadata
)


job = await client.acreate_job(file_id=file_response.id, config=config)
print(f"Job ID: {job.id}")
print(f"Status: {job.status}")

你也可以将配置作为字典传递：

job = await client.acreate_job(
    file_id=file_response.id,
    config={"generate_additional_metadata": True}
)

3. 等待完成

Section titled “3. Wait for completion”

现在您有了作业ID，可以等待作业完成：

# Wait for the job to complete (polls automatically)
job_result = await client.await_for_completion(job_id=job.id)
print(f"Job Status: {job_result.status}")


# Access extracted regions metadata
if job_result.regions:
    print(f"Found {len(job_result.regions)} region(s)")
    for region in job_result.regions:
        print(f"  - Region ID: {region.region_id}")
        print(f"    Sheet: {region.sheet_name}")
        print(f"    Location: {region.location}")


for worksheet_metadata in job_result.worksheet_metadata:
    print(f"Worksheet Title: {worksheet_metadata.title}")
    print(f"Worksheet Description: {worksheet_metadata.description}")

或者，您可以手动轮询：

while True:
    job_result = await client.aget_job(job_id=job.id, include_results_metadata=True)


    if job_result.status in ["SUCCESS", "PARTIAL_SUCCESS", "ERROR", "FAILURE"]:
        break


    print(f"Status: {job_result.status}")
    await asyncio.sleep(5)

4. 下载结果

Section titled “4. Download the result”

完成作业后，您可以下载生成的Parquet文件并读取有关作业结果的任何附加元数据：

from llama_cloud_services.beta.sheets.types import SpreadsheetResultType
import pandas as pd


# Download a region directly as a pandas DataFrame
region_id = job_result.regions[0].region_id
result_type = job_result.regions[0].region_type
df = await client.adownload_region_as_dataframe(
    job_id=job.id,
    region_id=region_id,
    result_type=result_type,  # Use region_type from result or `cell_metadata`
)


print(f"Region shape: {df.shape}")
print(df.head())


# Optionally, download cell metadata
metadata_df = await client.adownload_region_as_dataframe(
    job_id=job.id,
    region_id=region_id,
    result_type=SpreadsheetResultType.CELL_METADATA
)
print(f"Metadata shape: {metadata_df.shape}")

您也可以下载原始 Parquet 字节：

# Download as raw bytes
parquet_bytes = await client.adownload_region_result(
    job_id=job.id,
    region_id=region_id,
    result_type=SpreadsheetResultType.TABLE
)


# Save to file
with open("region.parquet", "wb") as f:
    f.write(parquet_bytes)

理解输出格式

Section titled “Understanding the Output Format”

当 LlamaSheets 任务成功完成后，您将收到关于提取区域的丰富结构化数据。本节将解释输出的不同组成部分。

任务结果结构

Section titled “Job Result Structure”

任务结果对象包含：

{
  "id": "job-id",
  "status": "SUCCESS",
  "file_id": "original-file-id",
  "config": { /* your parsing config */ },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:05:00Z",
  "regions": [
    {
      "region_id": "uuid-here",
      "sheet_name": "Sheet1",
      "location": "A2:E11",
      "title": "Some title",
      "description": "Some description"
    }
  ],
  "worksheet_metadata": [
    {
      "sheet_name": "Sheet1",
      "title": "Sales Data Q1 2024",
      "description": "Quarterly sales figures with revenue, units sold, and regional breakdowns"
    }
  ],
  "errors": []
}

关键字段：

  • regionsregions: 提取区域和表格的数组，包含其ID和位置信息
  • worksheet_metadata: 为每个工作表生成标题和描述（当generate_additional_metadata: true时）
  • status: 为以下之一：SUCCESS、PARTIAL_SUCCESS、ERROR 或 FAILURE

区域表数据（Parquet文件）

Section titled “Region Table Data (Parquet Files)”

每个提取的区域都保存为包含标准化表格数据的Parquet文件。Parquet是一种列式存储格式，具有以下特点：

  • 保留数据类型（日期、数字、字符串、布尔值）
  • 具有高效率和压缩性
  • 可以被 pandas、polars、DuckDB 及许多其他工具读取

示例区域结构：

import pandas as pd


df = pd.read_parquet("region.parquet")
print(df.head())


# Output:
#    col_0  col_1      col_2       col_3  col_4
# 0     44  -124.6  Value_0_2  2020-01-01  False
# 1    153   -34.4  Value_1_2  2020-01-02   True
# 2    184    34.4  Value_2_2  2020-01-03  False

单元格元数据（Parquet文件）

Section titled “Cell Metadata (Parquet Files)”

除了区域数据外，您还可以下载丰富的细胞级元数据，这些数据提供了提取区域中每个细胞的详细信息。这对于以下情况特别有用：

  • 理解单元格格式与样式
  • 分析表格结构与布局
  • 检测数据类型和模式
  • 为下游处理保留格式

以下类型的字段可用：

位置与布局：

  • row_number, column_number: 单元格坐标
  • coordinatecoordinate: Excel 样式的单元格引用（例如，“A1”）
  • relative_row_position, relative_column_position: 归一化位置（0.0 到 1.0）
  • is_in_first_row, is_in_last_row, is_in_first_column, is_in_last_column: 布尔标志
  • distance_from_origin, distance_from_center: 几何距离

格式化：

  • font_bold, font_italic: 字体样式标志
  • font_sizefont_size: 字体大小（单位：点）
  • font_color_rgb, background_color_rgb: 颜色值
  • has_border, border_style_score: 边框信息
  • horizontal_alignment, vertical_alignment: 对齐值
  • text_wraptext_wrap: 文本换行设置

单元格属性：

  • is_merged_cellis_merged_cell: 该单元格是否为合并范围的一部分
  • horizontal_size, vertical_size: 单元格尺寸
  • alignment_indentalignment_indent: 缩进级别

数据类型检测：

  • data_typedata_type: 检测到的类型（数字、文本、日期等）
  • is_date_likeis_date_like: 日期检测的布尔标志
  • is_percentage, is_currency: 用于特殊数字格式的布尔标志
  • number_format_categorynumber_format_category: Excel 数字格式类别
  • text_lengthtext_length: 文本内容长度
  • has_special_charshas_special_chars: 文本是否包含特殊字符

内容：

  • cell_value: 已处理的单元格值
  • raw_cell_value: 原始未处理值

聚类与分组：

  • group, sub_group: 单元格分组标识符
  • l0_category, f_group: 层次化分类

示例元数据使用：

import pandas as pd


# Load cell metadata
metadata_df = pd.read_parquet("metadata.parquet")


# Find all header cells (first row)
headers = metadata_df[metadata_df['is_in_first_row'] == True]


# Find all bolded cells (likely headers or emphasis)
bold_cells = metadata_df[metadata_df['font_bold'] == True]


# Find date columns
date_cells = metadata_df[metadata_df['is_date_like'] == True]
date_columns = date_cells['column_number'].unique()


# Analyze formatting patterns
print(f"Font sizes used: {metadata_df['font_size'].unique()}")
print(f"Data types present: {metadata_df['data_type'].unique()}")

下载结果

Section titled “Downloading Results”

您可以为每个提取区域下载两种类型的parquet文件：

  1. 表格数据 (result_type="table"): 实际表格内容
  2. 额外数据 (result_type="extra"): 任何不严格属于数据表格的区域（注释、标题等）
  3. 单元格元数据 (result_type="cell_metadata"): 丰富的格式设置与位置元数据

所有数据均以parquet文件格式存储，可轻松加载到pandas DataFrame中进行数据分析。

测试版限制

Section titled “Beta Limitations”

作为测试阶段的一部分，有几个关键限制需要注意：

  1. 作业创建限制为每秒1个请求
  2. 工作表大小限制为最多100列或10,000行（以每个工作表先达到的限制为准）

了解更多

Section titled “Learn More”

除了仅仅提取区域外，还有许多下游用例可以封装这些输出。