LlamaParse 完整参数配置指南

练习两年半的攻城狮

310人浏览 · 2026-08-06 15:00:19

练习两年半的攻城狮 · 2026-08-06 15:00:19 发布

LlamaParse 完整参数配置指南：从入门到精通

文章目录

LlamaParse 完整参数配置指南：从入门到精通

前言

LlamaParse 是 LlamaIndex 官方推出的 GenAI 原生文档解析服务，支持 PDF、Word、PPT、Excel 等 130+ 种文件格式，能够将包含表格、图表、图片的复杂文档精准解析为 LLM 友好的 Markdown 或结构化数据。本文基于官方文档，系统梳理 LlamaParse 的所有常用参数，并提供丰富的代码示例。

环境准备：使用前需在 LlamaCloud 获取 API Key。可设置为 apiKey 参数或环境变量 LLAMA_CLOUD_API_KEY。

一、安装与认证

1.1 安装

pip install llama-parse

1.2 基础用法

from llama_parse import LlamaParse

# 方式一：直接传入 API Key
parser = LlamaParse(api_key="llx-...")

# 方式二：从环境变量 LLAMA_CLOUD_API_KEY 读取（推荐）
parser = LlamaParse()

# 解析单个文件
documents = parser.load_data("./document.pdf")

# 解析结果
for doc in documents:
    print(doc.text)

二、核心参数速查表

LlamaParse 的所有参数均在初始化 LlamaParse() 时传入。以下是完整参数列表：

分类	参数名	类型	默认值	说明
认证	`api_key`	str	环境变量	LlamaCloud API 密钥
解析层级	`tier`	str	`"agentic"`	解析层级：`fast` / `cost_effective` / `agentic` / `agentic_plus`
	`version`	str	`"latest"`	解析引擎版本，可指定日期版本（如 `"2026-01-08"`）
输出格式	`result_type`	str	`"text"`	输出格式：`"markdown"` / `"text"` / `"json"`
	`page_separator`	str	`"\n---\n"`	页面分隔符，支持 `{page_number}` 变量
	`page_prefix`	str	`""`	每页前缀，支持 `{page_number}`
	`page_suffix`	str	`""`	每页后缀，支持 `{page_number}`
页面控制	`split_by_page`	bool	`True`	是否按页拆分，每个页面生成独立 Document
	`target_pages`	str	None	指定页码（逗号分隔，从0开始），支持范围如 `"0-2,6-22"`
	`max_pages`	int	None	限制最大解析页数
	`bounding_box`	str	None	裁剪页面区域（顺时针：上,右,下,左，比例0-1）
OCR 与文本	`language`	str	`"en"`	OCR 语言，多个用逗号分隔（如 `"eng,chi"`）
	`disable_ocr`	bool	`False`	禁用 OCR
	`skip_diagonal_text`	bool	`False`	跳过对角线文本（水印等）
	`do_not_unroll_columns`	bool	`False`	不展开多栏文本
缓存控制	`invalidate_cache`	bool	`False`	强制重新解析，绕过 48 小时缓存
	`do_not_cache`	bool	`False`	不缓存解析结果
性能	`num_workers`	int	`4`	并发请求数
	`partition_pages`	int	None	大文档分页并行解析（每任务页数）
	`check_interval`	int	`1`	状态检查间隔（秒）
	`max_timeout`	int	`2000`	最大超时时间（秒）
	`verbose`	bool	`True`	显示解析进度
高级	`parsing_instructions`	str	None	自定义解析指令
	`fast_mode`	bool	`False`	快速模式，跳过 OCR 和表格/标题重建
	`ignore_errors`	bool	`True`	忽略错误，返回空数组
	`auto_mode`	bool	`False`	自动选择最佳策略（费用更高）
	`spreadsheet_extract_sub_tables`	bool	`False`	Excel 中提取多个子表格
	`spreadsheet_force_formula_computation`	bool	`False`	强制重新计算公式
	`disable_image_extraction`	bool	`False`	禁用图片提取

三、参数详解与使用示例

3.1 解析层级（tier）

LlamaParse 提供四个解析层级，在速度、质量、成本之间做权衡：

Tier	说明	适用场景
`fast`	仅输出空间文本，不输出 Markdown	纯文本、单列无表格文档
`cost_effective`	AI 逐页解析，平衡性价比	文本为主、含简单表格的文档
`agentic`	AI 智能体解析，默认推荐	含图片、图表、多栏布局的文档
`agentic_plus`	最高精度 AI 解析	财务报表、学术论文等复杂文档

from llama_parse import LlamaParse

# 快速模式（纯文本）
parser_fast = LlamaParse(tier="fast")

# 性价比模式
parser_ce = LlamaParse(tier="cost_effective")

# 智能解析（默认，推荐）
parser_agentic = LlamaParse(tier="agentic")

# 最高精度
parser_premium = LlamaParse(tier="agentic_plus", version="2026-01-08")

documents = parser_premium.load_data("financial_report.pdf")

版本锁定：指定 version="2026-01-08" 可锁定解析行为，确保生产环境结果可复现。

3.2 输出格式（result_type）

控制解析结果的输出格式：

值	说明
`"markdown"`	Markdown 格式，保留标题、列表、表格等结构
`"text"`	纯文本，更紧凑
`"json"`	JSON 结构化数据

# Markdown 输出（推荐用于 RAG）
parser = LlamaParse(result_type="markdown")

# 纯文本输出（更紧凑）
parser = LlamaParse(result_type="text")

documents = parser.load_data("document.pdf")
print(documents[0].text)

3.3 页面控制

split_by_page：按页拆分

控制是否将每一页拆分为独立的 Document 对象：

# 默认：每页一个 Document（推荐）
parser = LlamaParse(split_by_page=True)

# 整个文档合并为一个 Document
parser = LlamaParse(split_by_page=False)

documents = parser.load_data("document.pdf")
for doc in documents:
    print(f"页码: {doc.metadata.get('page_number')}")
    print(doc.text[:200])

target_pages：指定页面

只解析特定页面，页码从 0 开始：

# 解析第1页、第3-6页和第11页
parser = LlamaParse(
    target_pages="0,2-5,10"  # 第1页=0
)

# 解析第5-14页
parser = LlamaParse(target_pages="4-13")

documents = parser.load_data("document.pdf")

max_pages：限制页数

限制最大解析页数：

# 只解析前10页
parser = LlamaParse(max_pages=10)

bounding_box：裁剪区域

去除页眉、页脚等干扰区域：

# 去除顶部10%
parser = LlamaParse(bounding_box="0.1,0,0,0")

# 去除顶部10%和底部20%
parser = LlamaParse(bounding_box="0.1,0,0.2,0")

documents = parser.load_data("document.pdf")

3.4 页面分隔与装饰

page_separator：自定义分隔符

自定义页面之间的分隔符，支持 {page_number} 变量：

parser = LlamaParse(
    page_separator="\n\n--- 第 {page_number} 页 ---\n\n"
)

page_prefix / page_suffix：页面前后缀

为每页添加前缀或后缀：

parser = LlamaParse(
    page_prefix="### 第 {page_number} 页\n\n",
    page_suffix="\n\n---\n"
)

3.5 OCR 与文本处理

language: OCR 语言

指定 OCR 语言，提升识别准确率:

# 中英文混合
parser = LlamaParse(language="eng,chi")

# 日文
parser = LlamaParse(language="jpn")

支持的语言列表可在 GitHub 查看。

disable_ocr：禁用 OCR

对于纯文本 PDF，禁用 OCR 可提升速度：

parser = LlamaParse(disable_ocr=True)

skip_diagonal_text：跳过对角线文本

避免将水印等对角线文本误识别为内容：

parser = LlamaParse(skip_diagonal_text=True)

do_not_unroll_columns：保留多栏布局

不展开多栏文本，保留原始排版顺序：

parser = LlamaParse(do_not_unroll_columns=True)

3.6 性能优化

num_workers：并发数

控制同时发送的并发请求数，默认 4：

# 增加并发加速大文档解析
parser = LlamaParse(num_workers=8)

partition_pages：大文档分页并行

将大文档拆分为多个子任务并行处理：

# 1000 页文档拆分为 10 个任务（每任务 100 页）
parser = LlamaParse(
    partition_pages=100,
    num_workers=4,
    max_pages=1000  # 必须配合 target_pages 或 max_pages 才能并发
)

注意：partition_pages 必须配合 target_pages 或 max_pages 才能并发执行。

verbose：显示进度

控制是否显示解析进度：

parser = LlamaParse(verbose=False)  # 静默模式

3.7 缓存控制

LlamaParse 默认缓存解析结果 48 小时，重复解析同一文件不消耗积分：

# 强制重新解析（绕过缓存）
parser = LlamaParse(invalidate_cache=True)

# 不缓存结果
parser = LlamaParse(do_not_cache=True)

3.8 高级功能

parsing_instructions：自定义解析指令

用自然语言指导 AI 如何解析：

parser = LlamaParse(
    tier="agentic",
    parsing_instructions="请特别关注文档中的所有表格数据，"
                         "将表格以清晰的Markdown格式输出。"
)

fast_mode：快速模式

跳过 OCR 和表格/标题重建，显著加速：

parser = LlamaParse(fast_mode=True)

注意：fast_mode 与 tier="agentic" 不兼容。

auto_mode：自动模式

自动选择最佳解析策略（费用更高）：

parser = LlamaParse(auto_mode=True)

四、与 SimpleDirectoryReader 集成

LlamaParse 可直接注入 SimpleDirectoryReader，实现批量文档解析：

from llama_parse import LlamaParse
from llama_index.core import SimpleDirectoryReader

parser = LlamaParse(
    result_type="markdown",
    split_by_page=True,
    tier="agentic",
    language="eng, chi",
    num_workers=4,
)

file_extractor = {
    ".pdf": parser,
    ".docx": parser,
    ".doc": parser,
    ".pptx": parser,
}

documents = SimpleDirectoryReader(
    input_dir="./data",
    file_extractor=file_extractor
).load_data()

for doc in documents:
    print(f"文件: {doc.metadata.get('file_name')}, 页码: {doc.metadata.get('page_number')}")
    print(doc.text[:200])

五、完整配置示例

示例 1：高精度财务报告解析

from llama_parse import LlamaParse

parser = LlamaParse(
    tier="agentic_plus",                     # 最高精度
    version="2026-01-08",                    # 锁定版本
    result_type="markdown",                  # Markdown 输出
    split_by_page=True,                      # 按页拆分
    target_pages="0-49",                     # 只解析前 50 页
    bounding_box="0.08,0,0.05,0",            # 去除页眉页脚
    language="eng",                          # 英文 OCR
    num_workers=8,                           # 并发加速
    parsing_instructions="Extract all financial tables with exact numbers. "
                         "Preserve table structures. "
                         "Identify revenue, expenses, and profit figures.",
)

documents = parser.load_data("annual_report.pdf")

for doc in documents:
    print(f"第 {doc.metadata.get('page_number')} 页")
    print(doc.text[:500])

示例 2：批量处理多种文档

from llama_parse import LlamaParse
from llama_index.core import SimpleDirectoryReader

parser = LlamaParse(
    result_type="markdown",
    split_by_page=True,
    tier="agentic",
    language="chi, eng",
    num_workers=4,
    verbose=False,  # 静默模式
)

file_extractor = {
    ".pdf": parser,
    ".docx": parser,
    ".doc": parser,
}

documents = SimpleDirectoryReader(
    input_dir="./docs",
    file_extractor=file_extractor,
    recursive=True,  # 递归子目录
).load_data()

print(f"共解析 {len(documents)} 页")

示例 3：大文档分页并行解析

from llama_parse import LlamaParse

parser = LlamaParse(
    tier="agentic",
    result_type="markdown",
    split_by_page=True,
    partition_pages=100,                     # 每 100 页一个任务
    num_workers=4,                           # 4 个任务并发
    max_pages=1000,                          # 必须设置才能并发
)

documents = parser.load_data("large_1000_pages.pdf")
print(f"共解析 {len(documents)} 页")

示例 4：去除水印 + 自定义分隔符

from llama_parse import LlamaParse

parser = LlamaParse(
    result_type="markdown",
    split_by_page=True,
    skip_diagonal_text=True,                 # 跳过水印
    page_separator="\n\n=== 第 {page_number} 页 ===\n\n",
    page_prefix="### Page {page_number}\n\n",
    bounding_box="0.05,0,0.05,0",            # 去除上下 5%
)

documents = parser.load_data("document.pdf")

六、常见问题与最佳实践

Q1：`split_by_page` 默认是什么？

默认 True，即每页生成一个独立的 Document。如需整个文档合并，设置 split_by_page=False。

Q2：`partition_pages` 为什么不并发？

原因：当 target_pages 和 max_pages 都未设置时，分页任务会顺序执行而非并发。

解决：至少设置其中一个：

parser = LlamaParse(partition_pages=100, max_pages=500)

Q3：如何选择 `tier`？

场景	推荐 Tier
纯文本、简单排版	`fast`
文本为主、含少量表格	`cost_effective`
含图表、多栏布局（大多数场景）	`agentic`
财务报表、学术论文	`agentic_plus`
混合复杂度文档	`agentic` + `auto_mode`

Q4：缓存机制是怎样的？

LlamaParse 默认缓存解析结果 48 小时。重复解析同一文件不消耗积分。如需强制重新解析，使用 invalidate_cache=True。

Q5：`result_type` 选 `markdown` 还是 `text`？

markdown：保留标题、列表、表格等结构，适合 RAG 和 LLM 使用
text：纯文本，更紧凑，适合存储

七、总结

LlamaParse 提供了丰富的参数配置，能够灵活应对各种文档解析场景：

场景	推荐配置
快速原型开发	`tier="fast"`
通用文档解析（推荐）	`tier="agentic"` + `result_type="markdown"` + `split_by_page=True`
财务报表/学术论文	`tier="agentic_plus"` + `parsing_instructions`
大文档批量处理	`partition_pages` + `num_workers` + `max_pages`
去除页眉页脚	`bounding_box="0.1,0,0.05,0"`
多语言文档	`language="eng,chi,spa"`
跳过水印	`skip_diagonal_text=True`