Index 快速上手 | BytesRouter

Index 是一套精简的 API，用来在你的文档上构建可检索的索引。它按三步模型工作：

目录（Directory） —— 上传并整理你的源文档。
索引（Index） —— 在一个目录上创建索引。这会触发解析、切块、嵌入与向量库写入，全部自动完成。
检索 / 对话（Retrieve / Chat） —— 用混合检索或内置的对话智能体查询已索引的文档。

要接一个智能体？

让兼容 MCP 的智能体查询索引，并不需要写 SDK 代码。LlamaParse MCP 已把在你索引上的检索与文件操作暴露成智能体工具；一步装好 Claude Code 与 Codex 的做法见 Skills 与 Plugins 页。

前置条件

一个 LlamaCloud 账户，套餐为 Starter、Pro 或 Enterprise
一个 API key（如何创建）

安装 SDK

Python
TypeScript
Go
Java
CLI

终端窗口

pip install "llama-cloud>=2.18"

from llama_cloud import AsyncLlamaCloud

client = AsyncLlamaCloud()  # reads LLAMA_CLOUD_API_KEY from the environment

终端窗口

npm install @llamaindex/llama-cloud

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

const client = new LlamaCloud(); // reads LLAMA_CLOUD_API_KEY from the environment

终端窗口

go get github.com/run-llama/llama-parse-go

import (
  "context"

  llamacloud "github.com/run-llama/llama-parse-go"
)

ctx := context.Background()

// NewClient reads LLAMA_CLOUD_API_KEY from the environment.
client := llamacloud.NewClient()

implementation("ai.llamaindex:llama-cloud:1.9.0")

import ai.llamaindex.llamacloud.client.LlamaCloudClient;
import ai.llamaindex.llamacloud.client.okhttp.LlamaCloudOkHttpClient;

// fromEnv reads LLAMA_CLOUD_API_KEY from the environment.
LlamaCloudClient client = LlamaCloudOkHttpClient.fromEnv();

终端窗口

go install github.com/run-llama/llama-parse-cli/cmd/llp@latest

export LLAMA_CLOUD_API_KEY="<your-api-key>"

第 1 步 —— 创建目录

目录是源文件的容器。可以把它理解成一个存放待索引文档的文件夹。

Python
TypeScript
Go
Java
CLI

directory = await client.beta.directories.create(
    name="my-docs",
    description="Product documentation",
)
print(directory.id)  # e.g. "dir-abc123"

const directory = await client.beta.directories.create({
  name: "my-docs",
  description: "Product documentation",
});
console.log(directory.id);

directory, err := client.Beta.Directories.New(ctx, llamacloud.BetaDirectoryNewParams{
  Name:        "my-docs",
  Description: llamacloud.String("Product documentation"),
})
if err != nil {
  log.Fatal(err)
}
fmt.Println(directory.ID) // e.g. "dir-abc123"

import ai.llamaindex.llamacloud.models.beta.directories.DirectoryCreateParams;
import ai.llamaindex.llamacloud.models.beta.directories.DirectoryCreateResponse;

DirectoryCreateResponse directory = client.beta().directories().create(
    DirectoryCreateParams.builder()
        .name("my-docs")
        .description("Product documentation")
        .build());
System.out.println(directory.id()); // e.g. "dir-abc123"

终端窗口

DIRECTORY_ID=$(llp beta:directories create \
  --name "my-docs" \
  --description "Product documentation" | jq -r '.id')

echo "$DIRECTORY_ID"

第 2 步 —— 把文件上传到目录

先把文件上传到 LlamaCloud，再加入你的目录。跟着做的话，可以把美国财政部 FY2024 财报的执行摘要下载为 report.pdf：

终端窗口

curl -fL -o report.pdf https://fiscal.treasury.gov/system/files/files/reports-statements/financial-report/2024/executive-summary-2024.pdf

Python
TypeScript
Go
Java
CLI

# Upload a file
with open("report.pdf", "rb") as f:
    file_obj = await client.files.create(file=f, purpose="user_data")

# Add the file to the directory
await client.beta.directories.files.add(
    directory.id,
    file_id=file_obj.id,
)

import fs from 'fs';

// Upload a file
const fileObj = await client.files.create({
  file: fs.createReadStream("./report.pdf"),
  purpose: "user_data",
});

// Add the file to the directory
await client.beta.directories.files.add(directory.id, {
  file_id: fileObj.id,
});

// Upload a file
f, err := os.Open("report.pdf")
if err != nil {
  log.Fatal(err)
}
defer f.Close()

fileObj, err := client.Files.New(ctx, llamacloud.FileNewParams{
  File:    f,
  Purpose: "user_data",
})
if err != nil {
  log.Fatal(err)
}

// Add the file to the directory
_, err = client.Beta.Directories.Files.Add(ctx, directory.ID, llamacloud.BetaDirectoryFileAddParams{
  FileID: fileObj.ID,
})
if err != nil {
  log.Fatal(err)
}

import java.nio.file.Paths;

import ai.llamaindex.llamacloud.models.beta.directories.files.FileAddParams;
import ai.llamaindex.llamacloud.models.files.FileCreateParams;
import ai.llamaindex.llamacloud.models.files.FileCreateResponse;

// Upload a file
FileCreateResponse fileObj = client.files().create(
    FileCreateParams.builder()
        .file(Paths.get("report.pdf"))
        .purpose("user_data")
        .build());

// Add the file to the directory
client.beta().directories().files().add(
    directory.id(),
    FileAddParams.builder()
        .fileId(fileObj.id())
        .build());

终端窗口

# Upload a file
FILE_ID=$(llp files create \
  --file ./report.pdf \
  --purpose user_data | jq -r '.id')

# Add the file to the directory
llp beta:directories:files add \
  --directory-id "$DIRECTORY_ID" \
  --file-id "$FILE_ID"

第 3 步 —— 创建索引

创建索引会启动一条自动流水线，把源目录里的所有文件解析、切块、嵌入并索引进向量库。

Python
TypeScript
Go
Java
CLI

index = await client.indexes.create(
    source_directory_id=directory.id,
)
print(f"Index ID: {index.id}")
print(f"Status: {index.metadata['status']}")

const index = await client.indexes.create({
  source_directory_id: directory.id,
});
console.log("Index ID:", index.id);
console.log("Status:", index.metadata?.status);

index, err := client.Indexes.New(ctx, llamacloud.IndexNewParams{
  SourceDirectoryID: directory.ID,
})
if err != nil {
  log.Fatal(err)
}
fmt.Println("Index ID:", index.ID)
fmt.Println("Status:", index.Metadata["status"])

import ai.llamaindex.llamacloud.models.indexes.IndexCreateParams;
import ai.llamaindex.llamacloud.models.indexes.IndexCreateResponse;

IndexCreateResponse index = client.indexes().create(
    IndexCreateParams.builder()
        .sourceDirectoryId(directory.id())
        .build());
System.out.println("Index ID: " + index.id());
System.out.println("Status: " + index.metadata()
    .map(m -> m._additionalProperties().get("status"))
    .map(v -> v.convert(String.class))
    .orElse("unknown"));

终端窗口

INDEX_ID=$(llp beta:indexes create \
  --source-directory-id "$DIRECTORY_ID" | jq -r '.id')

echo "Index ID: $INDEX_ID"

第 4 步 —— 等待索引就绪

索引是异步构建的。轮询直到状态变为 ready。

Python
TypeScript
Go
Java
CLI

import asyncio

while True:
    idx = await client.indexes.get(index.id)
    status = idx.metadata["status"] if idx.metadata else "unknown"

    if status == "ready":
        print("Index is ready!")
        break
    elif status == "failed":
        print("Index build failed:", idx.metadata["error_message"])
        break

    print(f"Status: {status} -- waiting...")
    await asyncio.sleep(2)

function sleep(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

while (true) {
  const idx = await client.indexes.get(index.id);
  const status = (idx.metadata?.status as string) ?? "unknown";

  if (status === "ready") {
    console.log("Index is ready!");
    break;
  } else if (status === "failed") {
    console.error("Index build failed:", idx.metadata?.error_message);
    break;
  }

  console.log(`Status: ${status} -- waiting...`);
  await sleep(2000);
}

for {
  idx, err := client.Indexes.Get(ctx, index.ID, llamacloud.IndexGetParams{})
  if err != nil {
    log.Fatal(err)
  }

  status, ok := idx.Metadata["status"].(string)
  if !ok {
    status = "unknown"
  }

  if status == "ready" {
    fmt.Println("Index is ready!")
    break
  } else if status == "failed" {
    fmt.Println("Index build failed:", idx.Metadata["error_message"])
    break
  }

  fmt.Printf("Status: %s -- waiting...\n", status)
  time.Sleep(2 * time.Second)
}

import ai.llamaindex.llamacloud.models.indexes.IndexGetResponse;

while (true) {
    IndexGetResponse idx = client.indexes().get(index.id());
    String status = idx.metadata()
        .map(m -> m._additionalProperties().get("status"))
        .map(v -> v.convert(String.class))
        .orElse("unknown");

    if (status.equals("ready")) {
        System.out.println("Index is ready!");
        break;
    } else if (status.equals("failed")) {
        System.out.println("Index build failed: " + idx.metadata()
            .map(m -> m._additionalProperties().get("error_message"))
            .map(v -> v.convert(String.class))
            .orElse(""));
        break;
    }

    System.out.println("Status: " + status + " -- waiting...");
    Thread.sleep(2000);
}

终端窗口

while true; do
  IDX=$(llp beta:indexes get --index-id "$INDEX_ID") || { printf '%s\n' "$IDX" >&2; break; }
  METADATA=$(printf '%s\n' "$IDX" | jq -c '.metadata // {}')
  STATUS=$(printf '%s\n' "$METADATA" | jq -r '.status // "unknown"')

  if [ "$STATUS" = "ready" ]; then
    echo 'Index is ready!'
    break
  elif [ "$STATUS" = "failed" ]; then
    printf '%s\n' "$METADATA" | jq -r '"Index build failed: \(.error_message // .)"'
    break
  fi

  echo "Status: $STATUS -- waiting..."
  sleep 2
done

第 5 步 —— 检索

索引就绪后，就能对它发起混合检索查询。

Python
TypeScript
Go
Java
CLI

results = await client.retrieval.retrieve(
    index_id=index.id,
    query="What are the key findings?",
    top_k=5,
)

for result in results.results:
    print(f"Score: {result.score}")
    print(result.content[:200])
    print("---")

const results = await client.retrieval.retrieve({
  index_id: index.id,
  query: "What are the key findings?",
  top_k: 5,
});

for (const result of results.results) {
  console.log(`Score: ${result.score}`);
  console.log(result.content.slice(0, 200));
  console.log("---");
}

results, err := client.Retrieval.Get(ctx, llamacloud.RetrievalGetParams{
  IndexID: index.ID,
  Query:   "What are the key findings?",
  TopK:    llamacloud.Int(5),
})
if err != nil {
  log.Fatal(err)
}

for _, result := range results.Results {
  fmt.Printf("Score: %v\n", result.Score)
  content := result.Content
  if len(content) > 200 {
    content = content[:200]
  }
  fmt.Println(content)
  fmt.Println("---")
}

import ai.llamaindex.llamacloud.models.retrieval.RetrievalRetrieveParams;
import ai.llamaindex.llamacloud.models.retrieval.RetrievalRetrieveResponse;

RetrievalRetrieveResponse results = client.retrieval().retrieve(
    RetrievalRetrieveParams.builder()
        .indexId(index.id())
        .query("What are the key findings?")
        .topK(5)
        .build());

for (RetrievalRetrieveResponse.Result result : results.results()) {
    System.out.println("Score: " + result.score().orElse(null));
    String content = result.content();
    System.out.println(content.substring(0, Math.min(200, content.length())));
    System.out.println("---");
}

终端窗口

llp beta:retrieval retrieve \
  --index-id "$INDEX_ID" \
  --query "What are the key findings?" \
  --top-k 5 \
  | jq -r '.results[] | "Score: \(.score)\n\(.content[0:200])\n---"'

后续步骤

检索指南 —— 混合检索的参数、过滤与重排
文件操作 —— 在索引内搜索、grep 与读取文件
对话 —— 在你的索引上做 RAG 的内置对话智能体
同步 —— 新增或更新文件后重新同步索引
LlamaParse MCP —— 让兼容 MCP 的智能体在你的索引上发现、搜索与检索

索引

数据加载

查询

存储

成本分析

应用

聊天机器人

问答

结构化数据

智能体

Chat Engines

Query Engine

连接器

文档与节点

摄取流水线

节点解析器

大语言模型

提示词

回调

节点后处理器

响应合成器

检索器

路由

结构化输出

现有数据

Presets and Modes

能力

起步

能力

Examples

Azure Deployment

Databases and Queues

LLM Integrations

前置条件

安装 SDK

第 1 步 —— 创建目录

第 2 步 —— 把文件上传到目录

第 3 步 —— 创建索引

第 4 步 —— 等待索引就绪

第 5 步 —— 检索

后续步骤

友情链接