llamacloud-index

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LlamaCloud Index v2 — Agentic Retrieval Guide

LlamaCloud Index v2 — 代理式检索指南

Answer questions from documents stored in Index v2, the managed knowledge base of the LlamaParse Platform. Every operation is a single authenticated HTTP call, so from a shell the cheapest interface is

curl

jq

: you can compose calls, batch independent lookups into one command, and bound exactly how much output enters the conversation.

Index v2 is built for agentic retrieval: beyond semantic search, it gives you file-system-like access to the underlying documents (PDFs, Office documents, images, and other unstructured files). This skill is about using that access well — navigating the index the way you would a file system, instead of firing a single one-shot RAG query and hoping the top results contain the answer.

从LlamaParse Platform的托管知识库Index v2（https://developers.llamaindex.ai/llamaparse/cloud-index-v2/getting_started/）中存储的文档回答问题。所有操作均为单次认证HTTP调用，因此在Shell环境下，最简便的方式是结合`curl` +

jq

：你可以组合调用、将独立查询批量整合为一个命令，并精准控制进入对话的输出内容量。

Index v2专为代理式检索打造：除语义搜索外，它还提供类似文件系统的方式访问底层文档（PDF、Office文档、图片及其他非结构化文件）。本技能旨在教你如何充分利用这种访问能力——像操作文件系统一样浏览索引，而非仅发送单次RAG查询并寄希望于顶部结果包含答案。

Setup

配置

bash

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")

If a call returns

, ask the user to check

LLAMA_CLOUD_API_KEY

(and the region) — do not retry in a loop.

bash

export LLAMA_BASE="https://api.cloud.llamaindex.ai/api/v1"   # 欧盟账号请使用：https://api.cloud.eu.llamaindex.ai/api/v1
AUTH=(-H "Authorization: Bearer $LLAMA_CLOUD_API_KEY" -H "Content-Type: application/json")

若调用返回

错误，请提示用户检查

LLAMA_CLOUD_API_KEY

（及区域）——请勿循环重试。

The API

API说明

Operation	Call	Key body fields
List indexes	`GET /indexes`	—
Retrieve passages	`POST /retrieval/retrieve`	`index_id` , `query` , `top_k` , `rerank` ( `{enabled, top_n}` , enabled by default), `score_threshold` , `static_filters` , `custom_filters`
Find files	`POST /retrieval/files/find`	`index_id` , `file_name_contains` (substring, recommended) or `file_name` (exact)
Grep a file	`POST /retrieval/files/grep`	`index_id` , `file_id` , `pattern` (regex), `context_chars`
Read a file	`POST /retrieval/files/read`	`index_id` , `file_id` , `offset` , `max_length` (chars; omit for full file)

file_id

values come from the find and retrieve responses. Full parameter reference: retrieval · file operations.

操作	调用方式	请求体核心字段
列出索引	`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

值可从查找和检索响应中获取。完整参数参考：检索 · 文件操作。

Step 0 — Pick an Index

步骤0 — 选择索引

Discover once per conversation, not before every query:

bash

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

If more than one index plausibly matches the user's question, ask the user which one to use — do not silently query the wrong knowledge base. If the user already gave you an index ID, skip discovery entirely.

每次对话只需执行一次索引发现，无需在每次查询前重复操作：

bash

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

若有多个索引可能匹配用户问题，请询问用户选择哪一个——请勿静默查询错误的知识库。若用户已提供索引ID，则直接跳过发现步骤。

The Agentic Retrieval Loop

代理式检索循环

Treat the index like a file system you can explore, not a black box you query once:

Discover —
```
GET /indexes
```
to find the right index.
Locate —
```
find
```
to identify the files relevant to the question.
Search —
```
grep
```
for exact patterns within a file.
Retrieve —
```
retrieve
```
for hybrid (sparse + dense) semantic search.
Inspect —
```
read
```
a bounded window of a file when you need surrounding context.

You rarely need all five steps for one question. The skill is choosing the right entry point (below) and iterating: a first retrieval that names a promising document is a reason to grep inside it, not a reason to stop.

将索引视为可探索的文件系统，而非黑盒式的单次查询工具：

发现 — 调用
```
GET /indexes
```
找到合适的索引。
定位 — 使用
```
find
```
识别与问题相关的文件。
搜索 — 在文件内使用
```
grep
```
匹配精确模式。
检索 — 使用
```
retrieve
```
进行混合（稀疏+稠密）语义搜索。
查看 — 当需要上下文内容时，调用
```
read
```
读取文件的限定范围内容。

单个问题很少需要全部五个步骤。本技能的核心是选择合适的入口点（如下所示）并迭代：首次检索发现有希望的文档时，应在该文档内进行grep操作，而非停止检索。

Choosing the Right Call

选择合适的调用方式

Situation	Start with
Open or conceptual question ("what does the report say about churn?")	`retrieve`
Question spans multiple documents or you don't know the wording used	`retrieve`
Looking for an exact term, identifier, figure, or section heading in a known file	`grep`
The user names or implies a specific document ("in the Q3 report…")	`find` , then grep/retrieve within it
You need continuous context around a passage you already located	`read` with `offset` / `max_length`

Rules of thumb:

retrieve
matches meaning;
grep
matches patterns. Use retrieval when you know what you mean but not how the document phrases it. Use grep when you know the literal string (a product name, an account code, "Section 4.2").
Verification flows are grep-shaped. "Does the contract mention X?" is a grep in the located file, not a retrieval.
Scope retrieval to one file with a filter instead of reading it whole:
```
"static_filters": {"parsed_directory_file_id": {"operator": "eq", "value": "<file-id>"}}
```
runs semantic search inside just that document.
Bound every call. Set
```
top_k
```
for retrieval (and
```
rerank.top_n
```
to cap what the reranker returns),
```
context_chars
```
for grep,
```
offset
```
/
```
max_length
```
for reads. Never let an unbounded response into the conversation.

场景	起始调用
开放式或概念性问题（如“报告中关于客户流失的内容是什么？”）	`retrieve`
问题涉及多个文档或你不清楚文档中的表述方式	`retrieve`
在已知文件中查找精确术语、标识符、数据或章节标题	`grep`
用户明确提及或暗示特定文档（如“在第三季度报告中……”）	`find` ，然后在该文件内进行grep/检索
需要已定位段落的连续上下文	使用 `offset` / `max_length` 参数调用 `read`

经验法则：

retrieve
匹配语义；
grep
匹配模式。当你清楚需求但不确定文档表述方式时，使用检索；当你知道确切字符串（如产品名称、账户代码、“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
```
。绝不要让无限制的响应进入对话。

Working Examples

实用示例

bash

undefined

bash

undefined

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)"'

curl -s "${AUTH[@]}" -X POST "$LLAMA_BASE/retrieval/retrieve" -d '{ "index_id": "<index-id>", "query": "碳排放强度目标", "top_k": 5 }' | jq -r '.results[] | "== 文件 (.static_fields.parsed_directory_file_id) 页码(.static_fields.page_range_start)-(.static_fields.page_range_end) 得分 (.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}'

curl -s "${AUTH[@]}" -X POST "$LLAMA_BASE/retrieval/files/find"
-d '{"index_id": "<index-id>", "file_name_contains": "季度"}' | 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)"'

curl -s "${AUTH[@]}" -X POST "$LLAMA_BASE/retrieval/files/grep"
-d '{"index_id": "<index-id>", "file_id": "<file-id>", "pattern": "收入|利润", "context_chars": 200}'
| jq -r '.items[] | "[(.start_char)-(.end_char)] (.content)"'

Read a window around a grep hit (never the whole file by default)

读取grep匹配结果附近的内容（默认绝不读取完整文件）

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'


Batch independent lookups into one command instead of one call per turn — several greps or retrievals in a single `for`-loop with labeled output cost one round-trip, not five.

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或检索并添加标签输出，仅需一次往返，而非五次。

Grounding Answers

答案依据

Every claim in your answer must be backed by content you actually retrieved:

Quote or paraphrase only from the returned passages and file contents, and cite the source — retrieval results carry the file ID and page range (
```
static_fields.page_range_start
```
/
```
_end
```
) for exactly this purpose.
Do not fill gaps with prior knowledge. If the results only partially answer the question, retrieve again with a refined query or grep the relevant file — don't improvise the rest.
If the index does not contain the answer, say so explicitly rather than answering from general knowledge. Offer to answer without the index if that is still useful.
When passages conflict, surface the conflict and the source files instead of picking one silently.

回答中的每一个结论都必须基于实际检索到的内容：

仅引用或改写返回的段落和文件内容，并注明来源——检索结果携带的文件ID和页码范围（
```
static_fields.page_range_start
```
/
```
_end
```
）正是为此设计。
请勿用先验知识填补信息空白。若结果仅部分回答问题，请使用优化后的查询重新检索或在相关文件中执行grep——不要自行补充内容。
若索引中不包含答案，请明确告知，而非基于通用知识作答。若有用，可提供不依赖索引的回答选项。
当段落内容冲突时，请明确指出冲突及来源文件，而非静默选择其中一个。

Common Pitfalls

常见误区

Don't paste whole files into context. An unbounded
```
read
```
on a large document floods the conversation with content you'll pay for on every subsequent turn. If you need one fact, grep; if you need the relevant passages, retrieve (optionally filtered to the file); if you need a region, read a window. Read a file in full only when nothing narrower can answer the question.
Don't one-shot RAG. A single retrieve call is the floor, not the ceiling. If the top passages don't answer the question, refine the query, or pivot: use the file IDs surfaced by retrieval to grep or inspect the most promising document.
Don't grep for paraphrases. Grep matches patterns, not meaning. If your grep for the user's phrasing comes back empty, that does not mean the answer is absent — switch to
```
retrieve
```
.
Don't dump raw JSON. Always pipe through
```
jq
```
to project just the fields you need; a raw retrieval response is mostly metadata you don't want in context.
Don't repeat identical calls. Re-running the same retrieval or grep returns the same results. Change the query, the pattern, or the call.
Don't guess the index. Querying the wrong knowledge base produces confidently wrong, well-cited answers. When multiple indexes could match, ask.
Don't answer around missing content. Absence of results is information: report what you searched and what wasn't there.

请勿将完整文件粘贴到上下文中。对大型文档执行无限制的
```
read
```
会导致对话内容过载，且后续每轮对话都会产生额外成本。若只需单个事实，使用grep；若需相关段落，使用检索（可选择限定到特定文件）；若需特定区域，读取限定范围内容。仅当更窄范围的操作无法回答问题时，才读取完整文件。
请勿仅使用单次RAG。单次检索是基础操作，而非最终方案。若顶部段落未回答问题，请优化查询，或转向其他操作：使用检索返回的文件ID在最有希望的文档中执行grep或查看操作。
请勿用grep匹配意译内容。grep匹配的是模式，而非语义。若用用户的表述执行grep无结果，并不意味着答案不存在——请切换到
```
retrieve
```
。
请勿直接输出原始JSON。始终通过
```
jq
```
过滤出所需字段；原始检索响应大多是不需要带入上下文的元数据。
请勿重复执行相同调用。重复执行相同的检索或grep会得到相同结果。请修改查询、模式或调用方式。
请勿猜测索引。查询错误的知识库会产生看似可信但实际错误的带来源回答。当多个索引可能匹配时，请询问用户。
请勿回避缺失内容。无结果本身也是信息：请告知用户你搜索的内容及未找到的结果。

No Shell Access?

无Shell访问权限？

If you are running in an environment without a shell, the same operations are exposed as tools by the LlamaParse MCP server (

https://mcp.llamaindex.ai/mcp

, or scoped to one index at

/index/{indexId}/mcp

) — the workflow and discipline above apply unchanged.

若你所在环境无Shell访问权限，相同操作可通过LlamaParse MCP服务器（

https://mcp.llamaindex.ai/mcp

，或限定单个索引的地址

/index/{indexId}/mcp

）作为工具调用——上述工作流程和规则完全适用。