检索 | BytesRouter

检索端点做的是混合检索，把向量相似度与全文搜索结合起来。结果可以按内置字段或用户自定义元数据过滤，并重排以获得更高的相关性。

提示

兼容 MCP 的智能体可以通过 LlamaParse MCP 的 retrieveFromIndex 工具跑同一套混合检索，无需写任何 SDK 代码。

基础检索

Python
TypeScript
Go
Java
CLI

results = await client.retrieval.retrieve(
    index_id="<your-index-id>",
    query="What were the Q3 revenue figures?",
    top_k=10,
)

for result in results.results:
    print(f"Score: {result.score}, Rerank: {result.rerank_score}")
    print(result.content)

const results = await client.retrieval.retrieve({
  index_id: "<your-index-id>",
  query: "What were the Q3 revenue figures?",
  top_k: 10,
});

for (const result of results.results) {
  console.log(`Score: ${result.score}, Rerank: ${result.rerank_score}`);
  console.log(result.content);
}

results, err := client.Retrieval.Get(ctx, llamacloud.RetrievalGetParams{
  IndexID: "<your-index-id>",
  Query:   "What were the Q3 revenue figures?",
  TopK:    llamacloud.Int(10),
})
if err != nil {
  log.Fatal(err)
}

for _, result := range results.Results {
  fmt.Printf("Score: %v, Rerank: %v\n", result.Score, result.RerankScore)
  fmt.Println(result.Content)
}

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

RetrievalRetrieveResponse results = client.retrieval().retrieve(
    RetrievalRetrieveParams.builder()
        .indexId("<your-index-id>")
        .query("What were the Q3 revenue figures?")
        .topK(10)
        .build());

for (RetrievalRetrieveResponse.Result result : results.results()) {
    System.out.println("Score: " + result.score().orElse(null)
        + ", Rerank: " + result.rerankScore().orElse(null));
    System.out.println(result.content());
}

终端窗口

llp beta:retrieval retrieve \
  --index-id "<your-index-id>" \
  --query "What were the Q3 revenue figures?" \
  --top-k 10 \
  | jq -r '.results[] | "Score: \(.score), Rerank: \(.rerank_score)\n\(.content)"'

参数

参数	类型	默认值	说明
`index_id`	`string`	必填	要检索的索引 ID。
`query`	`string`	必填	自然语言查询。
`top_k`	`int`	服务端默认值	最多返回多少条结果。
`vector_pipeline_weight`	`float`	`null`	向量检索的权重（0—1）。
`full_text_pipeline_weight`	`float`	`null`	全文检索的权重（0—1）。
`score_threshold`	`float`	`null`	返回结果的最低分。
`num_candidates`	`int`	`null`	ANN 候选数量（越大越准，也越慢）。

重排序

重排默认开启。混合检索取回候选后，会由重排模型重新打分以提升相关性。

Python
TypeScript
Go
Java
CLI

# Disable reranking
results = await client.retrieval.retrieve(
    index_id="<your-index-id>",
    query="summary of findings",
    rerank={"enabled": False},
)

# Keep reranking but limit to top 3
results = await client.retrieval.retrieve(
    index_id="<your-index-id>",
    query="summary of findings",
    rerank={"enabled": True, "top_n": 3},
)

// Disable reranking
const results = await client.retrieval.retrieve({
  index_id: "<your-index-id>",
  query: "summary of findings",
  rerank: { enabled: false },
});

// Keep reranking but limit to top 3
const results2 = await client.retrieval.retrieve({
  index_id: "<your-index-id>",
  query: "summary of findings",
  rerank: { enabled: true, top_n: 3 },
});

// Disable reranking
results, err := client.Retrieval.Get(ctx, llamacloud.RetrievalGetParams{
  IndexID: "<your-index-id>",
  Query:   "summary of findings",
  Rerank:  llamacloud.RetrievalGetParamsRerank{Enabled: llamacloud.Bool(false)},
})
if err != nil {
  log.Fatal(err)
}

// Keep reranking but limit to top 3
results2, err := client.Retrieval.Get(ctx, llamacloud.RetrievalGetParams{
  IndexID: "<your-index-id>",
  Query:   "summary of findings",
  Rerank:  llamacloud.RetrievalGetParamsRerank{Enabled: llamacloud.Bool(true), TopN: llamacloud.Int(3)},
})
if err != nil {
  log.Fatal(err)
}

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

// Disable reranking
RetrievalRetrieveResponse results = client.retrieval().retrieve(
    RetrievalRetrieveParams.builder()
        .indexId("<your-index-id>")
        .query("summary of findings")
        .rerank(RetrievalRetrieveParams.Rerank.builder()
            .enabled(false)
            .build())
        .build());

// Keep reranking but limit to top 3
RetrievalRetrieveResponse results2 = client.retrieval().retrieve(
    RetrievalRetrieveParams.builder()
        .indexId("<your-index-id>")
        .query("summary of findings")
        .rerank(RetrievalRetrieveParams.Rerank.builder()
            .enabled(true)
            .topN(3)
            .build())
        .build());

终端窗口

# Disable reranking
llp beta:retrieval retrieve \
  --index-id "<your-index-id>" \
  --query "summary of findings" \
  --rerank '{"enabled": false}'

# Keep reranking but limit to top 3
llp beta:retrieval retrieve \
  --index-id "<your-index-id>" \
  --query "summary of findings" \
  --rerank '{"enabled": true, "top_n": 3}'

过滤

你可以用内置的静态字段（页范围、块序号）或用户自定义的元数据来过滤结果。

静态过滤

静态过滤作用于每个块都存的内置字段。目前支持的字段是 parsed_directory_file_id，它可以把检索范围限定到指定文件。

Python
TypeScript
Go
Java
CLI

found = await client.retrieval.find(
    index_id="<your-index-id>",
    file_name="quarterly-report.pdf",
)
if not found.items:
    raise SystemExit("quarterly-report.pdf is not in the index")
file_id = found.items[0].file_id

results = await client.retrieval.retrieve(
    index_id="<your-index-id>",
    query="revenue breakdown",
    static_filters={
        "parsed_directory_file_id": {"operator": "eq", "value": file_id},
    },
)

const found = await client.retrieval.find({
  index_id: "<your-index-id>",
  file_name: "quarterly-report.pdf",
});
if (found.items.length === 0) {
  throw new Error("quarterly-report.pdf is not in the index");
}
const fileId = found.items[0].file_id;

const results = await client.retrieval.retrieve({
  index_id: "<your-index-id>",
  query: "revenue breakdown",
  static_filters: {
    parsed_directory_file_id: { operator: "eq", value: fileId },
  },
});

found, err := client.Retrieval.Find(ctx, llamacloud.RetrievalFindParams{
  IndexID:  "<your-index-id>",
  FileName: llamacloud.String("quarterly-report.pdf"),
})
if err != nil {
  log.Fatal(err)
}
if len(found.Items) == 0 {
  log.Fatal("quarterly-report.pdf is not in the index")
}
fileID := found.Items[0].FileID

results, err := client.Retrieval.Get(ctx, llamacloud.RetrievalGetParams{
  IndexID: "<your-index-id>",
  Query:   "revenue breakdown",
  StaticFilters: llamacloud.RetrievalGetParamsStaticFilters{
    ParsedDirectoryFileID: llamacloud.RetrievalGetParamsStaticFiltersParsedDirectoryFileID{
      Operator: "eq",
      Value: llamacloud.RetrievalGetParamsStaticFiltersParsedDirectoryFileIDValueUnion{
        OfString: llamacloud.String(fileID),
      },
    },
  },
})
if err != nil {
  log.Fatal(err)
}

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

RetrievalFindPage found = client.retrieval().find(
    RetrievalFindParams.builder()
        .indexId("<your-index-id>")
        .fileName("quarterly-report.pdf")
        .build());
if (found.items().isEmpty()) {
    throw new IllegalStateException("quarterly-report.pdf is not in the index");
}
String fileId = found.items().get(0).fileId();

RetrievalRetrieveResponse results = client.retrieval().retrieve(
    RetrievalRetrieveParams.builder()
        .indexId("<your-index-id>")
        .query("revenue breakdown")
        .staticFilters(RetrievalRetrieveParams.StaticFilters.builder()
            .parsedDirectoryFileId(RetrievalRetrieveParams.StaticFilters.ParsedDirectoryFileId.builder()
                .operator(RetrievalRetrieveParams.StaticFilters.ParsedDirectoryFileId.Operator.EQ)
                .value(fileId)
                .build())
            .build())
        .build());

终端窗口

FILE_ID=$(llp beta:retrieval find \
  --index-id "<your-index-id>" \
  --file-name "quarterly-report.pdf" \
  --max-items 1 \
  | jq -r '.file_id // empty')
if [ -z "$FILE_ID" ]; then
  echo "could not find quarterly-report.pdf in the index" >&2
else
  llp beta:retrieval retrieve \
    --index-id "<your-index-id>" \
    --query "revenue breakdown" \
    --static-filters "$(jq -cn --arg id "$FILE_ID" '{parsed_directory_file_id: {operator: "eq", value: $id}}')"
fi

自定义元数据过滤

自定义过滤匹配的是文件加入目录时附上的用户自定义元数据。

Python
TypeScript
Go
Java
CLI

results = await client.retrieval.retrieve(
    index_id="<your-index-id>",
    query="contract terms",
    custom_filters={
        "category": {"operator": "eq", "value": "legal"},
        "year": {"operator": "gte", "value": 2024},
    },
)

const results = await client.retrieval.retrieve({
  index_id: "<your-index-id>",
  query: "contract terms",
  custom_filters: {
    category: { operator: "eq", value: "legal" },
    year: { operator: "gte", value: 2024 },
  },
});

results, err := client.Retrieval.Get(ctx, llamacloud.RetrievalGetParams{
  IndexID: "<your-index-id>",
  Query:   "contract terms",
  CustomFilters: map[string]*llamacloud.RetrievalGetParamsCustomFilterUnion{
    "category": {
      OfValueFilter: &llamacloud.RetrievalGetParamsCustomFilterValueFilter{
        Operator: "eq",
        Value: llamacloud.RetrievalGetParamsCustomFilterValueFilterValueUnion{
          OfString: llamacloud.String("legal"),
        },
      },
    },
    "year": {
      OfValueFilter: &llamacloud.RetrievalGetParamsCustomFilterValueFilter{
        Operator: "gte",
        Value: llamacloud.RetrievalGetParamsCustomFilterValueFilterValueUnion{
          OfFloat: llamacloud.Float(2024),
        },
      },
    },
  },
})
if err != nil {
  log.Fatal(err)
}

import java.util.Map;

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

RetrievalRetrieveResponse results = client.retrieval().retrieve(
    RetrievalRetrieveParams.builder()
        .indexId("<your-index-id>")
        .query("contract terms")
        .customFilters(RetrievalRetrieveParams.CustomFilters.builder()
            .putAdditionalProperty("category", JsonValue.from(Map.of("operator", "eq", "value", "legal")))
            .putAdditionalProperty("year", JsonValue.from(Map.of("operator", "gte", "value", 2024)))
            .build())
        .build());

终端窗口

llp beta:retrieval retrieve \
  --index-id "<your-index-id>" \
  --query "contract terms" \
  --custom-filters '{"category": {"operator": "eq", "value": "legal"}, "year": {"operator": "gte", "value": 2024}}'

响应格式

响应里的每条结果包含：

字段	说明
`content`	检索到的块的文本内容。
`score`	混合检索的相关性得分。
`rerank_score`	重排器的得分（若做了重排）。
`metadata`	与该块关联的用户自定义元数据。
`static_fields.parsed_directory_file_id`	该块所属解析文件的 ID。
`static_fields.page_range_start` / `page_range_end`	该块覆盖的页号。
`static_fields.chunk_index`	该块在文件中的位置。
`static_fields.chunk_token_count`	该块的 token 数。

索引

数据加载

查询

存储

成本分析

应用

聊天机器人

问答

结构化数据

智能体

Chat Engines

Query Engine

连接器

文档与节点

摄取流水线

节点解析器

大语言模型

提示词

回调

节点后处理器

响应合成器

检索器

路由

结构化输出

现有数据

Presets and Modes

能力

起步

能力

Examples

Azure Deployment

Databases and Queues

LLM Integrations

基础检索

参数

重排序

过滤

静态过滤

自定义元数据过滤

响应格式

友情链接