llamacloud-index

LlamaCloud Index v2 — Agentic 检索指南

从存储在 Index v2 中的文档回答问题。Index v2 是 LlamaParse Platform 托管的知识库。每项操作都是一次经过身份验证的 HTTP 调用，因此在 shell 中，最轻量的接口是 curl + jq：你可以组合调用，将互不依赖的查询批处理到一条命令中，并精确限制进入对话的输出量。

Index v2 专为 Agentic 检索而构建：除了语义搜索，它还能让你像访问文件系统一样访问底层文档（PDF、Office 文档、图像及其他非结构化文件）。本技能旨在帮助你善用这种访问方式——像操作文件系统一样浏览索引，而不是只发起一次 RAG 查询，然后寄希望于排名靠前的结果中恰好包含答案。

设置

export LLAMA_BASE="https://api.cloud.llamaindex.ai/api/v1"   # EU accounts: https://api.cloud.eu.llamaindex.ai/api/v1
AUTH=(-H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" -H "Content-Type: application/json")

如果调用返回 401/403，请让用户检查 LLAMA_CLOUD_API_KEY（以及区域）——不要循环重试。

API

操作	调用	主要请求体字段
列出索引	GET /indexes	—
检索片段	POST /retrieval/retrieve	index_id、query、top_k、rerank（{enabled, top_n}，默认启用）、score_threshold、static_filters、custom_filters
查找文件	POST /retrieval/files/find	index_id、file_name_contains（子字符串，推荐）或 file_name（精确匹配）
在文件中搜索	POST /retrieval/files/grep	index_id、file_id、pattern（正则表达式）、context_chars
读取文件	POST /retrieval/files/read	index_id、file_id、offset、max_length（字符数；省略则读取整个文件）

file_id 的值来自 find 和 retrieve 响应。完整参数参考：检索 · 文件操作。

步骤 0 — 选择索引

每次对话只发现一次，无需在每次查询前都执行：

curl -s "${AUTH[@]}" "$LLAMA_BASE/indexes" | jq '.items[] | {id, name, description}'

如果有多个索引都可能符合用户的问题，请询问用户要使用哪一个——不要默默查询错误的知识库。如果用户已提供索引 ID，则完全跳过发现步骤。

Agentic 检索循环

把索引视为可供探索的文件系统，而不是只查询一次的黑箱：

1. 发现 — 使用 GET /indexes 找到合适的索引。
2. 定位 — 使用 find 找出与问题相关的文件。
3. 搜索 — 使用 grep 在文件中搜索精确模式。
4. 检索 — 使用 retrieve 执行混合（稀疏 + 稠密）语义搜索。
5. 查看 — 需要上下文时，使用 read 读取文件中有范围限制的片段。

回答一个问题时，很少需要用到全部五个步骤。关键在于选择合适的切入点（见下文）并不断迭代：首次检索若提到了有希望的文档，就应继续在其中搜索，而不是就此止步。

选择合适的调用方式

情况	从这里开始
开放式或概念性问题（“报告中关于客户流失说了什么？”）	retrieve
问题涉及多个文档，或你不知道文档使用的措辞	retrieve
在已知文件中查找确切术语、标识符、数字或章节标题	grep
用户指出或暗示了某个特定文档（“在 Q3 报告中……”）	find，然后在其中使用 grep/retrieve
需要查看已定位段落周围的连续上下文	使用 read，并设置 offset/max_length

经验法则：

• retrieve 匹配含义；grep 匹配模式。 知道自己想找什么，但不知道文档如何表述时，使用检索。知道确切字符串（产品名称、账户代码、“Section 4.2”）时，使用 grep。
• 验证类流程适合用 grep。 “合同中是否提到了 X？”应在已定位的文件中使用 grep，而不是检索。
• 通过筛选器将检索范围限定在单个文件中，而不是读取整个文件："static_filters": {"parsed_directory_file_id": {"operator": "eq", "value": "<file-id>"}} 会仅在该文档内进行语义搜索。
• 为每次调用设置上限。 为检索设置 top_k（并设置 rerank.top_n 以限制重排器返回的结果数），为 grep 设置 context_chars，为读取设置 offset/max_length。绝不要让无上限的响应进入对话。

操作示例

# Retrieve passages (bounded, with file and page provenance)
curl -s "${AUTH[@]}" -X POST "$LLAMA_BASE/retrieval/retrieve" -d '{
  "index_id": "<index-id>", "query": "carbon intensity targets", "top_k": 5
}' | jq -r '.results[] | "== file \(.static_fields.parsed_directory_file_id) pp.\(.static_fields.page_range_start)-\(.static_fields.page_range_end) score \(.score)\n\(.content)"'

# Locate a document by name substring
curl -s "${AUTH[@]}" -X POST "$LLAMA_BASE/retrieval/files/find" \
  -d '{"index_id": "<index-id>", "file_name_contains": "quarterly"}' | jq '.items[] | {file_id, file_name}'

# Grep it — context comes back with the match, no follow-up read needed
curl -s "${AUTH[@]}" -X POST "$LLAMA_BASE/retrieval/files/grep" \
  -d '{"index_id": "<index-id>", "file_id": "<file-id>", "pattern": "revenue|profit", "context_chars": 200}' \
  | jq -r '.items[] | "[\(.start_char)-\(.end_char)] \(.content)"'

# Read a window around a grep hit (never the whole file by default)
curl -s "${AUTH[@]}" -X POST "$LLAMA_BASE/retrieval/files/read" \
  -d '{"index_id": "<index-id>", "file_id": "<file-id>", "offset": 12000, "max_length": 4000}' | jq -r '.content'

将彼此独立的查询批量放入一条命令，而不是每轮调用一次：在单个 for 循环中执行多个 grep 或检索并标注输出，只需一次往返，而不是五次。

为回答提供依据

回答中的每项主张都必须有你实际检索到的内容作为依据：

• 只引用或转述返回的段落和文件内容，并注明来源——检索结果会提供文件 ID 和页码范围（static_fields.page_range_start/_end），正是为了方便引用。
• 不要用已有知识填补空白。如果结果只能部分回答问题，请使用更精确的查询再次检索，或对相关文件运行 grep——不要自行补充其余内容。
• 如果索引中没有答案，请明确说明，而不是根据一般知识作答。如果仍有帮助，可以提出在不使用索引的情况下回答。
• 如果段落内容相互矛盾，请指出矛盾以及相关来源文件，不要默默地选择其中一种说法。

常见问题

• 不要将整个文件粘贴到上下文中。 对大型文档执行无上限的 read 会让大量内容涌入对话，而你在之后的每轮中都要为这些内容付费。如果只需要一个事实，请用 grep；如果需要相关段落，请用 retrieve（可选按文件筛选）；如果需要某个区域，请读取一段内容。只有在没有更精简的方式可以回答问题时，才完整读取文件。
• 不要只做一次 RAG 查询。 一次 retrieve 调用只是起点，不是终点。如果排名靠前的段落无法回答问题，请改进查询，或调整方法：使用检索结果中的文件 ID，对最有希望的文档运行 grep 或检查文档。
• 不要用同义转述进行 grep。 Grep 匹配模式，而非含义。如果使用用户的措辞进行 grep 后没有结果，并不代表答案不存在——请改用 retrieve。
• 不要直接输出原始 JSON。 始终通过 jq 仅选取所需字段；原始检索响应大多是你不希望放入上下文的元数据。
• 不要重复完全相同的调用。 重复运行相同的检索或 grep 会返回相同结果。请更改查询、模式或调用方式。
• 不要猜测索引。 查询错误的知识库会产生看似可信且引用充分、实际却错误的答案。如果可能匹配的索引不止一个，请先询问。
• 不要绕过缺失内容继续作答。 没有结果本身也是一种信息：说明你搜索了什么，以及没有找到什么。

无法访问 Shell？

如果你运行的环境没有 Shell，LlamaParse MCP server（https://mcp.llamaindex.ai/mcp，或通过 /index/{indexId}/mcp 限定到单个索引）会以工具的形式提供相同操作——上述工作流和规范依然适用。