llamacloud-index

LlamaCloud Index v2 — エージェント型検索ガイド

LlamaParse PlatformのマネージドナレッジベースであるIndex v2に保存されたドキュメントから、質問への回答を得られます。各操作は認証済みの HTTP 呼び出し 1 回で完了するため、シェルから利用する場合はcurlとjqの組み合わせが最も手軽です。呼び出しを組み合わせたり、独立した検索を 1 つのコマンドにまとめたり、会話に取り込む出力の量を正確に制限したりできます。

Index v2 はエージェント型検索向けに構築されています。セマンティック検索に加えて、基盤となるドキュメント（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（完全一致）
ファイルの grep	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 のレスポンスから取得できます。パラメーターの全リファレンス：retrieval · file operations。

ステップ 0 — インデックスを選択する

会話ごとに 1 回だけ検出し、クエリのたびに実行しないでください。

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

ユーザーの質問に合致する可能性のあるインデックスが複数ある場合は、どれを使用するかユーザーに尋ねてください。誤ったナレッジベースに黙ってクエリを送信しないでください。ユーザーがすでにインデックス ID を指定している場合は、検出を完全に省略してください。

エージェント型検索ループ

インデックスを一度だけクエリするブラックボックスではなく、探索できるファイルシステムとして扱ってください。

1. 検出 — GET /indexesで適切なインデックスを探します。
2. 特定 — findで質問に関連するファイルを特定します。
3. 検索 — grepでファイル内の完全一致パターンを検索します。
4. 取得 — retrieveでハイブリッド（スパース＋デンス）セマンティック検索を行います。
5. 確認 — 周辺のコンテキストが必要な場合は、readでファイルの範囲を指定して読み取ります。

1 つの質問ですべての 5 つのステップが必要になることはほとんどありません。適切な開始点（以下を参照）を選び、反復することがこのスキルの要点です。最初の検索で有望なドキュメントが見つかった場合は、そのドキュメント内を grep する理由になります。そこで検索を終える理由にはなりません。

適切な呼び出し方法の選択

状況	まず使うもの
オープンな質問や概念的な質問（「レポートには解約率について何と書かれていますか？」）	retrieve
複数のドキュメントにまたがる質問、または使われている表現がわからない場合	retrieve
既知のファイル内で、特定の用語、識別子、数値、セクション見出しを探す場合	grep
ユーザーが特定のドキュメントを指定または示唆している場合（「第3四半期のレポートでは……」）	find、次にそのドキュメント内で grep／retrieve
すでに見つけた箇所の前後を含む連続したコンテキストが必要な場合	offset／max_length を指定して read

基本的な指針：

• retrieve は意味を検索し、grep はパターンを検索します。 意図する内容はわかっていても、ドキュメント内での表現がわからない場合は検索を使います。文字列（製品名、アカウントコード、「Section 4.2」など）がわかっている場合は grep を使います。
• 検証には grep が適しています。 「契約書に X の記載はありますか？」という質問には、検索ではなく、特定したファイル内で grep を使います。
• ファイル全体を読むのではなく、フィルターを使って検索対象を1つのファイルに絞ります。 "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'

ターンごとに1回ずつ呼び出すのではなく、独立した検索を1つのコマンドにまとめます。ラベル付きの出力を使って、1つの for ループ内で複数の grep や検索を実行すれば、往復は5回ではなく1回で済みます。

回答の根拠付け

回答の各主張は、実際に取得した内容に基づいている必要があります。

• 返された箇所やファイルの内容から引用または要約し、その出典を示してください。検索結果には、この目的のためにファイル ID とページ範囲（static_fields.page_range_start／_end）が含まれています。
• 既有の知識で不足分を補わないでください。検索結果が質問に部分的にしか答えていない場合は、クエリを絞り込んで再検索するか、該当するファイルを grep してください。残りを即興で補わないでください。
• インデックスに答えが含まれていない場合は、一般知識から回答するのではなく、そのことを明確に伝えてください。インデックスを使わない回答が役立つ場合は、その旨を提案してください。
• 箇所の内容が食い違う場合は、どちらかを黙って選ぶのではなく、食い違いと出典ファイルを示してください。

よくある落とし穴

• ファイル全体をコンテキストに貼り付けないでください。 大きなドキュメントに対して上限のない read を使うと、会話に大量の内容が入り、その後のすべてのターンでコストがかかります。事実を1つ確認するなら grep、該当箇所が必要なら（必要に応じてファイルに絞って）検索、特定範囲が必要ならウィンドウを指定して読み取ります。より限定的な方法では質問に答えられない場合に限り、ファイル全体を読んでください。
• RAG を一度きりで済ませないでください。 retrieve を1回呼び出すのは最低限であり、上限ではありません。上位の箇所で質問に答えられない場合は、クエリを絞り込むか、検索結果に表示されたファイル ID を使って、有望なドキュメントを grep または確認してください。
• 言い換え表現を grep で探さないでください。 grep が検索するのは意味ではなくパターンです。ユーザーの表現で grep して結果が空でも、答えが存在しないとは限りません。retrieve に切り替えてください。
• 生の JSON を出力しないでください。 必要なフィールドだけを取り出すため、必ず jq を通してください。生の検索結果には、コンテキストに不要なメタデータが大半を占めています。
• 同一の呼び出しを繰り返さないでください。 同じ検索や grep を再実行しても、同じ結果が返されます。クエリ、パターン、または呼び出し方を変更してください。
• インデックスを当てずっぽうで選ばないでください。 間違ったナレッジベースを検索すると、根拠が適切に示された、もっともらしく誤った回答になります。該当する可能性のあるインデックスが複数ある場合は、確認してください。
• 不足している内容を推測で補って回答しないでください。 検索結果がないことも情報のひとつです。何を検索し、何が見つからなかったかを伝えてください。

シェルにアクセスできない場合

シェルのない環境で実行している場合は、同じ操作を LlamaParse MCP サーバー（https://mcp.llamaindex.ai/mcp、または /index/{indexId}/mcp で特定のインデックスに限定したもの）のツールとして利用できます。上記のワークフローと手順はそのまま適用されます。