LlamaParse 免费文档解析额度：每月一万 credits 够做文档问答原型

接口形态与鉴权方式

LlamaParse 提供的不是对话补全接口，而是文档解析接口：把 PDF、Office、图片等文件提交上去，返回适合喂给大模型的 Markdown 或结构化 JSON。接口的 base_url 形态为 https://api.cloud.llamaindex.ai，解析相关路径都以 /api/parsing/ 开头，鉴权通过请求头 Authorization: Bearer <API_KEY> 完成。平台上没有可选的对话模型名，需要对话能力时要另外接入大模型 API，把解析结果作为上下文传过去。

先把密钥放进环境变量，避免写死在代码和仓库里：

export LLAMA_CLOUD_API_KEY="llx-你的密钥"

第一步：上传文件，创建解析任务

关键参数说明：file 是待解析文件，支持 130 多种格式与 80 多种语言；result_type 决定输出形态，常用 markdown（保留标题层级与表格结构）或 json；parse_mode 是解析档位，fast 最省 credits、balanced 折中、premium 效果更好但更贵，Auto Mode 会按页智能选档，官方称最多可省 80% 的 credits；parsing_instruction 用自然语言写要求，例如保留表格、按栏切分；target_pages 只解析指定页，调试阶段最省钱。

curl -X POST "https://api.cloud.llamaindex.ai/api/parsing/upload" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -H "Accept: application/json" \
  -F "file=@./report.pdf" \
  -F "parse_mode=balanced" \
  -F "result_type=markdown" \
  -F "parsing_instruction=保留表格结构，用 Markdown 表格输出"

返回体里会带一个任务 id，把它记下来用于下一步查询。

第二步：轮询状态，取回解析结果

解析是异步的，先查任务状态，返回成功后再取内容。轮询间隔建议 2 到 5 秒，不要写成死循环，设置一个最大重试次数。

curl -X GET "https://api.cloud.llamaindex.ai/api/parsing/job/{job_id}" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"

curl -X GET "https://api.cloud.llamaindex.ai/api/parsing/job/{job_id}/result/markdown" \
  -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" \
  -o report.md

需要固定字段的 JSON 时，把上一步的结果路径换成 /result/json，或在 SDK 里传入结构化模型，具体字段定义方式以官方文档为准。

第三步：用 Python SDK 更省事

SDK 封装了上传与轮询，批量处理时更稳。免费档只有 5 个并发任务，把并发数压在 2 到 3 更安全。

import os
from llama_parse import LlamaParse

parser = LlamaParse(
    api_key=os.environ["LLAMA_CLOUD_API_KEY"],
    result_type="markdown",
    parse_mode="balanced",
    parsing_instruction="保留表格结构，用 Markdown 表格输出；图片给出图注。",
    num_workers=2,
)

documents = parser.load_data("./report.pdf")
print(documents[0].text[:800])

拿到的 Markdown 文本再做分块、向量化和入库，就是一条完整的 RAG 前处理链路。

额度耗尽与限流的典型表现与排查顺序

1. 先看 HTTP 状态码：401 或 403 多为密钥错误、密钥被删或没有所属项目的权限；429 表示触发限流或额度不足。
2. 打开控制台用量页面确认当月剩余 credits。用尽后接口会直接报错，要等下个计费周期刷新才恢复，不会自动降级，也不会悄悄扣费。
3. 核对并发数：免费档同时最多 5 个解析任务，批处理脚本里把 num_workers 控制在 2 到 3，并给失败任务加退避重试。
4. 检查文件本身：页数、体积是否过大，是否为加密 PDF，扫描件是否需要 OCR。先用 target_pages 只跑 1 到 3 页验证参数是否正确。
5. 检查解析档位：premium 的单页消耗明显高于 fast，日常批量任务用 Auto Mode 或 balanced 更划算。
6. 最后排查网络与重试逻辑：轮询间隔过短会放大请求量，对 5xx 错误做指数退避，成功的结果及时落盘成 .md 文件，避免重复解析浪费额度。