Collections API

在集合中搜索

搜索 collections 的基础 URL 与 REST API 共享，位于 https://api.x.ai。您必须使用 xAI API Key 进行身份验证，并在头部中添加 Authorization: Bearer <your xAI API key>。

---

POST /v1/documents/search

在给定集合中搜索与查询相关的内容。

请求体

• filter (string | null) — 可选的元数据过滤字符串，应用于搜索结果。 使用 AIP-160 过滤语法查询文档元数据。 支持比较运算符：=, !=, >, >=, <, <= 支持逻辑运算符：AND, OR 支持范围语法：field:10..20（包含） 示例：author = "John" 或 year > 2020 AND category = "finance"

• group_by (object)

  • aggregate (object | object)

  • keys (array<string>, required) — 用于对结果进行分组的元数据键（例如 "category", "department"）。 至少需要一个键。

• instructions (string | null) — 要包含在搜索查询中的用户定义说明。默认为通用搜索说明。

• limit (integer | null) — 要返回的块数量。 将始终返回最匹配的块。 可选，默认为 10。

• query (string, required) — 要搜索的查询，将使用与源文档相同的嵌入模型进行嵌入。

• ranking_metric ("RANKING_METRIC_UNKNOWN" | "RANKING_METRIC_L2_DISTANCE" | "RANKING_METRIC_COSINE_SIMILARITY")

• retrieval_mode (object | object | object)

• source (object, required) — DocumentsSource 定义要搜索的文档来源。

  • collection_ids (array<string>, required) — 要搜索的集合 ID。

  • rag_pipeline ("chroma_db" | "es")

响应体

• matches (array<object>, required) — 搜索匹配结果。

  • chunk_content (string, required) — 块内容。

  • chunk_id (string, required) — 块 ID。

  • collection_ids (array<string>, required) — 集合 ID。

  • fields (object, required) — 属于此块文档的元数据字段。

  • file_id (string, required) — 文档 ID。

  • page_number (integer) — 此块所属的主导页码（单页文档为 0）。

  • score (number, required) — 相关性分数。

请求示例：

{
  "query": "What is the revenue in the last quarter?",
  "source": {
    "collection_ids": [
      "collection_80100614-300c-4609-959b-a138fa90f542"
    ]
  },
  "filter": "document_type = \"financial_report\" AND year > 2020"
}

响应示例：

{
  "matches": [
    {
      "file_id": "file_ac3c5728-7399-41fc-bd62-0fef0042de9c",
      "chunk_id": "0199717c-511b-7a80-bab3-dfe9a27f82ab",
      "chunk_content": ", deferred revenue related to such customer payments amounted to $2.10 billion and $1.77 billion, respectively, mainly due to contractual payment terms. Revenue recognized from the deferred revenue balances as of December 31, 2024 and 2023 was $944 million and $873 million for the six months ended June 30, 2025 and 2024, respectively. We have elected the practical expedient to omit disclosure of the amount of the transaction price allocated to remaining performance obligations for contracts with an original expected contract length of one year or less. As of June 30, 2025, total transaction price allocated to performance obligations that were unsatisfied or partially unsatisfied for contracts with an original expected length of more than one year was $10.38 billion. Of this amount, we expect to recognize $5.47 billion in the next 12 months and the rest over the remaining performance obligation period. Changes in government and economic incentives or tariffs may impact the transaction price or our ability to e",
      "score": 1.1447691,
      "collection_ids": [
        "collection_80100614-300c-4609-959b-a138fa90f542"
      ]
    }
  ]
}