LlamaParse

使用 LlamaParse API 将文档（PDF、图像、电子表格、演示文稿等，支持 130+ 种格式）解析为面向大语言模型（LLM）优化的文本、Markdown 和结构化数据。

前提条件

• Python 包：llama-cloud>=1.0（执行 pip install llama-cloud 安装）
• API 密钥：设置环境变量 LLAMA_CLOUD_API_KEY。密钥可在 https://cloud.llamaindex.ai 获取

验证配置是否就绪：

pip install llama-cloud>=1.0
export LLAMA_CLOUD_API_KEY=llx-...

快速开始

from llama_cloud import AsyncLlamaCloud
import asyncio

async def parse_document(file_path: str):
    client = AsyncLlamaCloud()  # 自动读取 LLAMA_CLOUD_API_KEY 环境变量
    file = await client.files.create(file=file_path, purpose="parse")
    result = await client.parsing.parse(
        file_id=file.id,
        tier="agentic",
        version="latest",
        expand=["markdown", "text"],
    )
    return result

result = asyncio.run(parse_document("document.pdf"))
print(result.markdown.pages[0].markdown)

核心概念

解析层级（必选 —— 任选其一）

必须同时指定 tier 和 version 参数。version="latest" 适用于开发阶段；生产环境中建议使用具体日期字符串（例如 "2026-01-08"），以确保结果可复现。

输出视图（expand 参数）

可在 expand 列表中请求一个或多个输出视图：

• markdown —— 结构化 Markdown，含标题、列表、表格等，适用于 RAG/LLM 流水线。
• text —— 每页清洗后的扁平化纯文本，适用于搜索与检索任务。
• items —— 页面元素（标题、段落、表格、图表等）构成的结构化树形对象，并附带每个元素的边界框（bounding box）。适用于需感知版式布局的处理场景。
• metadata —— 文档元数据。
• images_content_metadata —— 图像/截图元数据，包含预签名 URL（presigned URLs）。

访问结果方式示例：result.markdown.pages[i].markdown、result.text.pages[i].text、result.items.pages[i].items

输出选项

控制 Markdown 渲染行为：

output_options={
    "markdown": {
        "tables": {
            "output_tables_as_markdown": True,  # 或设为 False 以输出 HTML 表格
        },
    },
    "images_to_save": ["screenshot"],  # 保存页面截图
}

处理选项

processing_options={
    "ignore": {"ignore_diagonal_text": True},
    "ocr_parameters": {"languages": ["en"]},  # OCR 语言提示
    "specialized_chart_parsing": "agentic_plus",  # 将图表解析为结构化数据
}

自定义提示词（Agentic 解析指令）

以类似向 LLM 提示的方式引导解析器，适用于提取特定字段或转换输出格式：

from llama_cloud.types.parsing_create_params import (
    ProcessingOptions, ProcessingOptionsAutoModeConfiguration,
    ProcessingOptionsAutoModeConfigurationParsingConf
)

result = await client.parsing.parse(
    file_id=file.id,
    tier="agentic",
    version="latest",
    expand=["markdown"],
    processing_options=ProcessingOptions(
        auto_mode_configuration=[ProcessingOptionsAutoModeConfiguration(
            parsing_conf=ProcessingOptionsAutoModeConfigurationParsingConf(
                custom_prompt="仅从此收据中提取价格和总计金额。"
            )
        )]
    ),
)

常见工作流

解析单个文档

使用 scripts/parse_document.py 脚本：

python scripts/parse_document.py document.pdf --tier agentic --output markdown,text

批量解析文件夹

使用 scripts/batch_parse.py 脚本：

python scripts/batch_parse.py ./documents/ --tier agentic --max-concurrent 5

从文档中提取表格

在 expand 中请求 items，然后筛选出表格类元素：

for page in result.items.pages:
    for item in page.items:
        if hasattr(item, 'rows'):  # 表格元素
            print(f"第 {page.page_number} 页表格：共 {len(item.rows)} 行")
            # 可通过 item.csv、item.html、item.md 获取不同格式的表格内容

提取图表数据

启用专用图表解析功能，并从图表所在页面中提取表格行数据：

result = await client.parsing.parse(
    file_id=file.id,
    tier="agentic_plus",
    version="latest",
    processing_options={"specialized_chart_parsing": "agentic_plus"},
    expand=["items"],
)

下载页面截图

import httpx, re

result = await client.parsing.parse(
    file_id=file.id, tier="agentic", version="latest",
    output_options={"images_to_save": ["screenshot"]},
    expand=["images_content_metadata"],
)

for img in result.images_content_metadata.images:
    if img.presigned_url and re.match(r"^page_d+.jpg$", img.filename):
        async with httpx.AsyncClient() as http:
            resp = await http.get(img.presigned_url)
            with open(img.filename, "wb") as f:
                f.write(resp.content)

API 参考文档

完整 API 接口详情请参阅 references/api-reference.md。

外部服务与安全性

本功能依赖 LlamaParse API（https://cloud.llamaindex.ai），该服务由 LlamaIndex 提供，是一款云端文档解析服务。

• 需提供 API 密钥：必须设置环境变量 LLAMA_CLOUD_API_KEY，密钥请在 https://cloud.llamaindex.ai 获取。
• 数据外传：原始文档将上传至 LlamaParse API，在服务端完成解析；解析结果返回至本地机器。
• 无其他网络调用：脚本仅与 api.cloud.llamaindex.ai 通信；截图下载使用同一服务提供的预签名 URL。
• 脚本为参考工具：scripts/parse_document.py 和 scripts/batch_parse.py 是辅助脚本，仅供用户手动执行，不会被本功能自动调用。

使用提示

• 仅请求实际需要的 expand 视图 —— 请求越多，响应体积越大、延迟越高。
• 对于含图表/图形的文档，推荐使用 agentic_plus 层级并启用 specialized_chart_parsing。
• 生产环境中，请固定使用具体日期格式的 version（如 "2026-01-08"），避免使用 "latest"。
• 批量解析时建议基于信号量（semaphore）控制并发数，以遵守服务端速率限制。
• items 视图为每个元素提供边界框坐标（b_box），适用于空间分析等高级用途。