llamaparse

LlamaParse 技能

使用 LlamaParse 解析非结构化文档（例如 PDF、DOCX、PPTX、XLSX），并提取其中的内容（文本、Markdown、图像等）。

初始设置

调用此技能时，请回复：

I'm ready to use LlamaParse to parse files. Before we begin, please confirm that:

- `LLAMA_CLOUD_API_KEY` is set as environment variable within the current environment
- `@llamaindex/llama-cloud@latest` is installed and available within the current Node environment

If both of them are set, please provide:

1. One or more files to be parsed
2. Specific parsing options, such as tier, API version, custom prompt, processing options...
3. Any requests you might have regarding the parsed content of the file.

I will produce a Typescript script to run the parsing job and, once you approved its execution, I will report the results back to you based on your request.

然后等待用户输入。

---

步骤 0 — 安装 llama-cloud（可选）

如果用户尚未安装 @llamaindex/llama-cloud 包，请运行以下命令将其添加到当前环境中：

npm install @llamaindex/llama-cloud@latest

步骤 1 — 编写 TypeScript 脚本

用户确认已设置环境变量并提供解析任务所需的详细信息后，编写一个 TypeScript 脚本。

编写 TS 脚本时，可参考以下资料：

• 参考 example.ts 脚本，其中涵盖了 LlamaParse 所需的大多数配置
• 参考完整的 LlamaParse 文档，获取 https://developers.llamaindex.ai/python/cloud/llamaparse/api-v2-guide/ 页面。

脚本编写最佳实践

生成脚本时请遵循以下准则：

1. 始终使用顶层 LlamaCloud 客户端

所有解析操作都使用 LlamaCloud（API 客户端）：

import LlamaCloud from "@llamaindex/llama-cloud";

// Define a client
const client = new LlamaCloud({
  apiKey: process.env["LLAMA_CLOUD_API_KEY"], // This is the default and can be omitted
});

2. 采用两步上传 → 解析模式

始终先上传以获取文件 ID，然后使用文件 ID 进行解析。切勿将原始文件字节直接传递给 parse()。

import { readFile, writeFile } from "fs/promises";
import { basename } from "path";

// 1. Convert the file path into a File object
const buffer = await readFile(filePath);
const fileName = basename(filePath);
const file = new File([buffer], fileName);
// 2. Upload the file to the cloud
const fileObj = await client.files.create({
  file: file,
  purpose: "parse",
});
// 3. Get the file ID
const fileId = fileObj.id;
// 4. Use the file ID to parse the file
const result = await client.parsing.parse({
  tier: "agentic",
  version: "latest",
  file_id: fileId,
  ...
});

如果用户已有文件 ID（例如之前上传时获得的 ID），则跳过上传步骤，直接使用该 ID。

3. 选择合适的层级

层级	适用场景
fast	优先考虑速度；适用于简单文档
cost_effective	注重预算；适用于直接提取文本
agentic	复杂布局、表格、混合内容（默认推荐）
agentic_plus	高级分析，准确度最高

除非用户另有指定或文档较简单，否则默认使用 agentic。

4. 始终包含 expand 参数

expand 参数用于控制返回的内容。省略该参数会返回最少的数据。请始终明确指定所需内容：

值	返回内容
text_full	通过 result.text_full 返回纯文本
markdown_full	通过 result.markdown_full 返回 Markdown
items	通过 result.items.pages 返回页面级 JSON
text_content_metadata	每页文本元数据
markdown_content_metadata	每页 Markdown 元数据
items_content_metadata	每页项目元数据
images_content_metadata	带预签名 URL 的图像列表
output_pdf_content_metadata	输出 PDF 元数据
xlsx_content_metadata	Excel 专属元数据

仅在需要预签名 URL 或页面级详细信息时，才请求 *_content_metadata 元数据变体——它们会增加载荷大小。

5. 防范 None 结果

发生故障时，result.text_full、result.markdown_full 和 result.items 可能为 undefined。请始终进行防护：

const text = result.text_full ?? "";
const markdown = result.markdown_full ?? "";

6. 使用结构化选项进行高级配置

使用正确的嵌套键对选项进行分组：

const result = await client.parsing.parse({
  tier: "agentic",
  version: "latest",
  file_id: fileId,
  input_options: {
    presentation: {
      skip_embedded_data: false,
    },
  },
  output_options: {
    images_to_save: ["screenshot"],
    markdown: {
      tables: { output_tables_as_markdown: true },
      annotate_links: true,
    },
  },
  processing_options: {
    specialized_chart_parsing: "agentic",
    ocr_parameters: { languages: ["de", "en"] },
  },
  agentic_options: {
    custom_prompt:
      "Extract text from the provided file and translate it from German to English.",
  },
  expand: [
    "markdown_full",
    "images_content_metadata",
    "markdown_content_metadata",
  ],
});

用户希望指导提取过程（翻译、摘要、结构化提取等）时，请使用 agentic_options.custom_prompt。

7. 下载图像需要 httpx 和身份验证

当 expand 中包含 images_content_metadata 时，请使用带 Bearer 身份验证的预签名 URL 下载图像：

if (result.images_content_metadata) {
  for (const image of result.images_content_metadata.images) {
    if (image.presigned_url) {
      const response = await fetch(image.presigned_url, {
        headers: {
          Authorization: `Bearer ${process.env["LLAMA_CLOUD_API_KEY"]}`,
        },
      });
      if (response.ok) {
        const content = await response.bytes();
        await writeFile(image.filename, content);
      }
    }
  }
}

8. 使用 Node shebang

生成的每个脚本都应包含 Node shebang：

#!/usr/bin/env node

---

步骤 2 — 执行 TypeScript 脚本

生成 TypeScript 脚本后，请执行以下操作：

1. 向用户展示脚本，并征求运行权限（具体取决于当前权限设置）
2. 获得运行许可后，执行脚本
3. 根据用户的请求查看结果

强烈建议使用 npx tsx script.ts 运行 TypeScript 脚本。