检索分析服务Elasticsearch版：使用指南

前提条件

• 已开通阿里云 Elasticsearch 服务，并已创建或准备创建 AI 引擎版实例。

• 已规划实例所在的 VPC、交换机、访问白名单和客户端网络。

• 已根据业务数据设计 Mapping。向量检索场景还需要确定向量模型、维度、相似度和更新方式。

• 操作账号具有相应权限。Collection 管理通常需要 manage，数据读取需要 read，数据写入需要 write；详细权限见本文后续说明。

创建实例

实例购买项和页面布局可能随地域、版本和产品阶段调整，以下步骤以控制台实际页面为准。AI 引擎版支持的地域和可用区以购买页实际可购买项为准。

1. 登录阿里云 Elasticsearch 控制台，进入实例创建页面。

2. 选择AI引擎版，并选择控制台提供的地域和可用区。该实例类型的 Elasticsearch 版本固定，创建页显示为 9.x 且不可选；实例创建完成后，可在实例列表或实例详情页查看具体的版本号。

3. 根据写入负载配置索引节点（Index 节点），根据查询负载配置查询节点（Search 节点）；其他可选组件以控制台为准。

4. 配置专有网络、虚拟交换机、登录名和登录密码。访问白名单不在创建页配置，需要在实例创建完成后进入实例的安全配置页设置。

5. 确认配置和费用后创建实例。实例状态变为可用后，记录 Elasticsearch 和 Kibana 的访问地址。

节点规格、节点数量下限及专有主节点配置以购买页当前可选项为准。

节点数量和规格应分别依据写入吞吐、查询并发、向量索引构建、活跃数据集及缓存需求确定。调整节点的具体操作和计费规则以控制台为准。

连接实例

您可以使用 Kibana Dev Tools、Elasticsearch 兼容客户端或任意 HTTP 客户端访问实例。实例地址、网络白名单、证书和认证方式以实例详情页为准。

AI 引擎版的访问域名因网络类型而异。域名只决定请求首先接入的节点角色，不限制请求类型。集群会将请求转发给实际负责处理的角色节点。

通过私网访问时，两个域名在功能上都支持读写。生产环境建议查询请求使用默认私网域名，写入请求使用索引节点私网域名，以减少对查询节点的网络带宽占用。Bulk 写入、返回结果较大的查询或高并发场景尤其需要区分使用。通过公网访问时，读写请求均使用默认公网域名。

例如，实例 ID 为 es-cn-xxx 时，索引节点私网域名为 es-cn-xxx-index.elasticsearch.aliyuncs.com。协议、端口和网络访问方式以控制台显示的信息为准。

实例默认使用 HTTP。若您在控制台主动开启 HTTPS，请将客户端连接协议切换为 HTTPS。

在 Kibana Dev Tools 中执行以下请求验证连接：

GET /

AI 引擎版 9.99.0 对应 Elasticsearch 内核版本 9.5.0，因此该请求返回的 version.number 为内核版本号，与控制台显示的 9.99.0 不同。后续 Elasticsearch 实际版本以集群 API 返回结果为准。安装自定义插件时，请使用与 AI 引擎版匹配的 9.99.0 版本号。

使用 cURL 时，请替换实例地址和凭据。生产环境不要在脚本或命令历史中明文保存密码：

curl --user '<username>:<password>' 'http://<elasticsearch-endpoint>/'

使用官方客户端时，请根据实例版本的 API 兼容性说明选择客户端版本，并复用客户端连接池，不要为每个请求重复创建客户端。

模式对比

Collection 提供命名空间模式和向量簇召回模式，两种模式二选一。模式由创建参数 slice_strategy 决定，创建后不能修改，并会影响 Slice 的业务含义、注册方式以及写入和查询路由。

向量簇召回模式会根据向量簇中心自动选择多个候选 Slice，并向这些 Slice 并行发起查询，但这并不表示存储向量时必须使用该模式。命名空间模式同样支持 dense_vector、KNN 和 DiskBBQ。仅当业务需要自动召回相关向量簇，并且已经完成聚类中心维护和召回率评测时，才选择向量簇召回模式。

选择命名空间模式后，请参见“快速入门 > 命名空间模式”。选择向量簇召回模式后，请参见“快速入门 > 向量簇召回模式”。本文其他 Collection 管理、数据 API、缓存预热、Alias、Copy Slice 和观测能力，如无特别说明，均适用于两种模式。

查询副本与高可用

两种模式的查询均由查询节点上的副本分片提供。index.number_of_replicas 至少需要设置为 1，否则无法提供查询。设置为 1 仅满足基本查询要求，不具备查询高可用能力。生产环境至少设置为 2，并配置至少两个查询节点，才能在单个查询节点故障时继续提供查询。

访问约定

• 应用始终通过 Collection 名或 Collection Alias 访问数据。

• 命名空间模式的写入和查询通过 _slice 指定命名空间。查询未提供 _slice 时会失败；确需查询全部 Slice 时，显式使用 _slice=_all。部分文档和查询 API 也兼容使用 routing，具体范围见下文。

• 向量簇召回模式写入时通过 _slice 或 routing_field 指定向量簇；KNN 查询可以根据查询向量自动选择多个候选 Slice。无法自动选择候选 Slice 的查询仍需显式提供 _slice，或在兼容 API 中使用 routing。

• Slice 用于组织数据和限定查询范围，不是账号权限边界。需要租户权限隔离时，应结合应用鉴权和产品支持的安全机制。

• 不要保存或直接访问 .sc-* 底层索引（Backing Index）。其名称和生命周期由系统管理。部分接口的响应体（如写入响应的 _index、注册 Slice 响应的 backing_index）会返回该名称，仅用于观察和排查，不应作为后续应用请求的目标。配置角色权限时需要使用 .sc-<collection>-* 通配符，请参见“运维与权限 > Collection 权限”。

routing 兼容参数

对 Collection 或 Collection Alias 使用本文列出的文档读写与查询 API 时，可以用 Elasticsearch 标准 routing 代替 _slice。该写法用于兼容已有客户端，新应用仍建议使用语义更明确的 _slice；同一个 URL 或同一个 Bulk、MGet item 不能同时提供两者。

该兼容方式不适用于 Collection 和 Slice 管理、缓存预热、Copy Slice、CAT、显式 Refresh 或 Reindex。Reindex 必须使用 source._slice 和 dest._slice。routing_field 是根据文档字段推导 Slice 的配置，并非 routing 的别名。

API 通用约定

• JSON 请求使用 Content-Type: application/json；Bulk 和 Multi Search 使用 Content-Type: application/x-ndjson，并保留请求体末尾换行符。

• Bulk、Multi Search 和批量管理接口可能出现 item 级失败。应用不能只判断 HTTP 状态码。注册 Slice 的单个接口和批量接口同样采用 item 级错误：请求整体返回 HTTP 200，但顶层 errors 可能为 true，需要逐个检查 items[].result。

• HTTP 429 表示服务端当前拒绝请求。客户端应采用有上限的指数退避，并只重试适合重试的操作。

• 连接超时或 HTTP 5xx 不代表写入一定没有发生。使用稳定文档 ID 或其他幂等机制核对后再重试。

• 通过 URL 传递大量 _slice 时，需要注意 HTTP 请求行的长度上限为 4096 字节。Slice 名较长时，可能在达到 Slice 数量上限之前先触发 too_long_http_line_exception。

Collection 管理 API 常用以下查询参数，具体支持范围以各接口说明为准。

管理请求返回 acknowledged=false 或发生超时，不表示服务端操作已经回滚；重试前应先查询资源当前状态。

命名空间模式：按 Slice 进行 DiskBBQ 向量检索

某企业知识库平台为多个租户提供检索增强生成（RAG）服务。应用完成租户鉴权后，可以确定当前租户 ID。用户提问时，只需要从该租户的知识库中召回语义相关的内容分段。

该场景在请求发起前已经能够确定查询范围，适合使用命名空间模式。本示例创建名为 knowledge-chunks 的 Collection，把每个租户作为一个 Slice。应用通过 _slice 指定租户知识库，再使用 DiskBBQ 在选定 Slice 内执行 KNN。Slice 用于组织数据和限定查询范围，租户鉴权仍由应用或受支持的 Elasticsearch 安全机制负责。

PUT /_slice_collection/knowledge-chunks
  {
    "settings": {
      "index.number_of_shards": 2,
      "index.number_of_replicas": 2
    },
    "mappings": {
      "properties": {
        "tenant_id": { "type": "keyword" },
        "document_id": { "type": "keyword" },
        "title": { "type": "text" },
        "content": { "type": "text" },
        "category": { "type": "keyword" },
        "updated_at": { "type": "date" },
        "embedding": {
          "type": "dense_vector",
          "dims": 4,
          "index": true,
          "similarity": "cosine",
          "index_options": {
            "type": "bbq_disk"
          }
        }
      }
    }
  }

{
    "acknowledged": true
  }

PUT /knowledge-chunks/_doc/chunk-1001?_slice=tenant-a
  {
    "tenant_id": "tenant-a",
    "document_id": "doc-refund-policy",
    "title": "退款与退货政策",
    "content": "重复购买的商品可以在订单完成后的七天内申请退款。",
    "category": "after-sales",
    "updated_at": "2026-07-30T10:00:00Z",
    "embedding": [0.82, 0.10, 0.05, 0.03]
  }

PUT /knowledge-chunks/_doc/chunk-1002?_slice=tenant-b
  {
    "tenant_id": "tenant-b",
    "document_id": "doc-shipping-status",
    "title": "查询物流状态",
    "content": "在订单详情页打开物流信息，即可查看最新配送状态。",
    "category": "shipping",
    "updated_at": "2026-07-30T10:01:00Z",
    "embedding": [0.12, 0.78, 0.06, 0.04]
  }

GET /knowledge-chunks/_doc/chunk-1001?_slice=tenant-a

POST /knowledge-chunks/_search?_slice=tenant-a
  {
    "knn": {
      "field": "embedding",
      "query_vector": [0.80, 0.12, 0.05, 0.03],
      "k": 10,
      "num_candidates": 100
    },
    "_source": ["document_id", "title", "content"]
  }

POST /_bulk
  { "index": { "_index": "knowledge-chunks", "_id": "chunk-1003", "_slice": "tenant-a" } }
  { "tenant_id": "tenant-a", "document_id": "doc-change-address", "title": "修改收货地址", "content": "订单发货前，可以在订单详情页修改收货地址。", "category": "orders", "updated_at": "2026-07-30T10:02:00Z", "embedding": [0.75, 0.16, 0.06, 0.03] }
  { "index": { "_index": "knowledge-chunks", "_id": "chunk-1004", "_slice": "tenant-b" } }
  { "tenant_id": "tenant-b", "document_id": "doc-invoice", "title": "申请电子发票", "content": "订单完成后，可以在发票管理页面申请电子发票。", "category": "billing", "updated_at": "2026-07-30T10:03:00Z", "embedding": [0.18, 0.70, 0.08, 0.04] }

GET /_cat/slice_collection/knowledge-chunks?v

GET /_cat/slice_collection/knowledge-chunks/slices?v

GET /_slice_collection/knowledge-chunks/slices?page_size=100

{
    "slices": [
      { "id": "tenant-a" },
      { "id": "tenant-b" }
    ]
  }

GET /_slice_collection/knowledge-chunks/slices?page_size=100&cursor=<next_cursor>

向量簇召回模式：自动选择候选 Slice

某电商搜索平台维护规模较大的商品向量库，并已通过离线聚类把商品划分为数千个向量簇。用户发起相似商品查询时，应用只有查询向量，无法预先确定目标簇。如果每次都查询全部商品数据，查询范围和资源开销会随数据规模增长。

该场景适合使用向量簇召回模式：每个 Slice 对应一个向量簇，并注册该簇的中心向量。执行 KNN 查询时，系统先计算查询向量与各簇中心的相似度，自动选择最相关的多个候选 Slice，再在这些 Slice 中并行执行 DiskBBQ 检索，从而缩小查询范围。

Collection 不负责训练聚类中心，也不会根据文档向量自动决定写入 Slice。应用需要提前计算并注册中心向量。

建议仅在同时满足以下条件时使用：

• 业务已经能够离线生成并持续维护聚类中心。

• 数据量和 Slice 数量较大，缩小查询范围能够带来实际收益。

• 业务允许先选候选簇再执行 KNN 查询，并已通过召回率测试确定合适的候选 Slice 数。

以下场景不建议使用：

• 数据没有稳定的聚类结构，无法提供可靠的中心向量。

• 数据量或 Slice 数量较小，直接查询的成本已经可接受。

• 查询必须覆盖全部向量数据，不能接受候选簇选择带来的召回范围变化。此时应使用命名空间模式，并显式指定 _slice 查询范围。

PUT /_slice_collection/products
  {
    "slice_strategy": "vector_cluster",
    "auto_create_slice": false,
    "settings": {
      "index.number_of_shards": 2,
      "index.number_of_replicas": 2
    },
    "mappings": {
      "properties": {
        "cluster_id": { "type": "keyword" },
        "name": { "type": "keyword" },
        "embedding": {
          "type": "dense_vector",
          "dims": 2,
          "index": true,
          "similarity": "cosine",
          "index_options": {
            "type": "bbq_disk"
          }
        }
      }
    },
    "config": {
      "routing_field": "cluster_id",
      "vector_dims": 2,
      "default_query_vector_path": "knn.query_vector",
      "default_query_slice_count": 128,
      "max_query_slice_count": 512
    }
  }

PUT /_slice_collection/products/slices/cluster-a
  {
    "vector": [0.9, 0.1]
  }

PUT /_slice_collection/products/slices
  {
    "slices": [
      {
        "slice_id": "cluster-b",
        "vector": [0.1, 0.9]
      },
      {
        "slice_id": "cluster-c",
        "vector": [0.6, 0.4]
      }
    ]
  }

PUT /products/_doc/product-1
  {
    "cluster_id": "cluster-a",
    "name": "example-product",
    "embedding": [0.92, 0.08]
  }

POST /products/_search?query_slice_count=64
  {
    "knn": {
      "field": "embedding",
      "query_vector": [0.91, 0.09],
      "k": 10,
      "num_candidates": 100
    }
  }

创建参数

创建 Collection 的接口为：

PUT /_slice_collection/{collection}

查询参数：

请求体参数如下。

如果一个 Backing Index 有 N 个主分片，仅按数量软上限计算时，可接收的 Slice 数为 N × max_slices_per_shard。max_slices_per_shard 和 max_storage_per_shard 只决定后续的新 Slice 是否继续分配到该 Backing：

• 达到任一阈值后，系统会选择或创建其他 Backing 来承载新 Slice。

• 已有 Slice 仍然可以继续写入。

• 修改阈值不会迁移已有 Slice，也不会重新平衡存量数据。

一般场景使用默认的 last 即可。只有在同时存在多个可接收新 Slice 的 Backing，并希望把新注册的 Slice 随机分散时，才使用 random。

查看 Collection

查看一个 Collection：

GET /_slice_collection/knowledge-chunks

查看全部 Collection：

GET /_slice_collection

该接口支持 master_timeout 查询参数。

{collection} 支持逗号分隔的名称和通配符。精确名称不存在时返回 HTTP 404；通配符没有匹配项时返回空对象。

响应示例：

{
  "slice_collections": {
    "knowledge-chunks": {
      "collection_uuid": "opaque-system-id",
      "lifecycle_state": "active",
      "max_slices_per_shard": 200,
      "max_storage_per_shard": "50gb",
      "backing_allocation_strategy": "last",
      "future_only_settings": {},
      "auto_create_slice": true,
      "slice_strategy": "exact",
      "max_managed_backing_generation": 0,
      "aliases": {}
    }
  }
}

响应还可能包含系统管理的标识和 generation 字段。应用应将其视为不透明信息，不要用于拼接 Backing 名或实现业务逻辑。

更新 Collection

该接口用于调整后续注册 Slice 的分配策略，不会移动已有 Slice。

更新可变配置：

POST /_slice_collection/knowledge-chunks/_update
{
  "max_slices_per_shard": 300,
  "max_storage_per_shard": "80gb",
  "backing_allocation_strategy": "last",
  "auto_create_slice": false,
  "settings": {
    "apack.slice_collection.future.index.number_of_shards": 4
  }
}

查询参数：

可更新字段包括：

• max_slices_per_shard

• max_storage_per_shard

• backing_allocation_strategy

• auto_create_slice

• settings 中允许的后续生效设置

后续生效设置只影响以后创建的 Backing，不修改现有 Backing。默认允许配置：

• index.number_of_shards

• index.routing_partition_size

• index.number_of_routing_shards

在 _update 请求中，后续生效设置需要使用 apack.slice_collection.future. 前缀。例如，index.number_of_shards 对应 apack.slice_collection.future.index.number_of_shards。写入时使用扁平前缀，通过 GET /_slice_collection/{collection} 回读时则以嵌套结构呈现，例如 "future_only_settings": {"index": {"number_of_shards": "4"}}。

成功响应为 {"acknowledged":true}。acknowledged=false 表示等待确认超时，不表示更新已经回滚。

更新 Mapping 和动态 Settings

使用 Collection 名更新 Mapping：

PUT /knowledge-chunks/_mapping
{
  "properties": {
    "channel": { "type": "keyword" }
  }
}

使用 Collection 名更新动态索引设置：

PUT /knowledge-chunks/_settings
{
  "index.refresh_interval": "5s"
}

Mapping 和动态索引设置会应用到当前所有 Backing，并成为后续 Backing 的统一配置。不要逐个修改 Backing Index。

注册 Slice

当 auto_create_slice=false，或希望在写入前完成资源准备时，可以显式注册 Slice：

PUT /_slice_collection/knowledge-chunks/slices/tenant-c

该接口支持 master_timeout 查询参数。

响应示例：

{
  "acknowledged": true,
  "errors": false,
  "items": [
    {
      "slice_id": "tenant-c",
      "result": "created",
      "backing_index": ".sc-knowledge-chunks-...-00000"
    }
  ]
}

backing_index 仅用于观察和排查，不应作为后续应用请求的目标。

一次最多注册 20480 个不重名的 Slice：

PUT /_slice_collection/knowledge-chunks/slices
{
  "slices": [
    "tenant-d",
    { "slice": "tenant-e" },
    { "slice_id": "tenant-f" }
  ]
}

该接口支持 master_timeout 查询参数。三种写法可以在同一请求中混用。

批量注册可能部分成功。每个 item 的 result 可能为 created、updated、noop 或 failed。只要存在失败 item，顶层 errors 就为 true。Slice 名不合法时（例如包含 :、首字符非字母数字、使用保留值 _all 或超过长度上限），注册接口同样返回 HTTP 200 并在对应 item 中给出 failed 和错误原因。

分页列出 Slice

GET /_slice_collection/knowledge-chunks/slices?prefix=tenant-&page_size=100

结果按 Slice 名升序返回。翻页期间如果并发新增或删除 Slice，分页结果为弱一致；继续翻页时应保持相同的 prefix。

删除 Slice

DELETE /_slice_collection/knowledge-chunks/slices/tenant-c

查询参数：

成功响应：

{
  "acknowledged": true
}

删除成功后，同名 Slice 可以重新注册，新数据与后台待清理的旧数据保持隔离。需要注意：

• Slice 删除后，指定该 Slice 名的查询返回 HTTP 404（resource_not_found_exception），而不是返回空结果。

• 物理清理完成前，使用 _slice=_all 的全量查询可能短暂看到旧数据。

• 删除响应不表示存储空间已经释放。

写入和读取

Collection 复用 Elasticsearch 标准文档 API，并通过 _slice 指定命名空间或向量簇。常用接口如下。

使用时请遵循以下规则：

• 单文档请求只能指定一个 Slice，不能使用逗号分隔或 _all。

• index、create 和 update 在 auto_create_slice=true 时可以自动注册不存在的 Slice；读取和删除不会自动注册，指定不存在的 Slice 时返回 HTTP 404。

• 部分文档和查询 API 可以使用 routing 表示逻辑 Slice，支持范围和冲突规则见“routing 兼容参数”。

• 每次 Bulk 最多自动注册 512 个不同的缺失 Slice。已存在的 Slice 不计入该限制。

• wait_for_active_shards 在 AI 引擎版写入链路中不作为等待副本的条件。需要等待文档可被搜索时，使用 refresh=wait_for。

• dense_vector 字段默认不包含在返回的 _source 中，GET /{collection}/_doc/{id} 和 GET /{collection}/_source/{id} 均不返回向量值；如需返回，请显式指定 _source_includes。

Refresh 与查询可见性

写入请求成功表示数据已经持久化，不表示数据已经可以被查询节点查询。AI 引擎版采用无状态架构，Refresh 需要由索引节点生成并发布新的 Commit，再由查询节点加载新的可搜索版本，因此是跨节点的分布式操作，开销高于传统有状态 Elasticsearch 的本地 Refresh。

您可以通过 Collection settings 查询和调整 index.refresh_interval，当前取值可通过 GET /{collection}/_settings 查看。较短的 Refresh 间隔会增加资源开销，生产环境建议设置为 5s 或更大；确有低延迟可见性需求时，可根据业务负载适当调小。具体生效值以当前 Collection 的 settings 为准。自动 Refresh 可以设置为 -1 关闭。缩短该间隔前，应先评估 Commit 发布频率、写入吞吐和对象存储 I/O。

根据业务对查询可见性的要求选择以下方式：

index.refresh_interval=-1 会关闭自动 Refresh。此时，使用 refresh=wait_for 的写入会持续等待，直到其他请求触发显式 Refresh，因此不能在没有显式刷新流程的情况下组合使用。生产环境需要读后写时，应根据业务时延要求选择等待自动 Refresh 或显式刷新，并评估分布式 Refresh 开销。Refresh 只解决查询可见性，不代表全部查询副本已经可用，也不能替代查询探针和高可用检查。

Bulk

每个 Bulk item 可以在 action metadata 中提供自己的 _slice，如快速入门中的示例。一个批次全部写入同一 Slice 时，也可以在 URL 上提供默认值：

POST /knowledge-chunks/_bulk?_slice=tenant-a
{ "index": { "_id": "chunk-2001" } }
{ "tenant_id": "tenant-a", "document_id": "doc-account-security", "title": "账号安全设置", "content": "管理员可以在安全设置页面启用多因素认证。" }

item 中的 _slice 可以覆盖 URL 默认值。命名空间模式不会从文档字段推导 Slice，即使文档体中包含 tenant_id 等字段，实际写入位置仍由 _slice 决定。错误处理方式见“API 通用约定”。

Multi Get

MGet 适合一次读取多个已知 ID；每个 item 可以访问不同的 Slice：

POST /knowledge-chunks/_mget
{
  "docs": [
    { "_id": "chunk-1001", "_slice": "tenant-a" },
    { "_id": "chunk-1002", "_slice": "tenant-b" }
  ]
}

URL 上的 _slice 可以作为默认值，每个 item 可以覆盖该默认值。每个 item 最终只能解析到一个 Slice。

Reindex

Reindex 适合在普通索引与 Collection 之间，或不同 Collection 之间迁移数据。在同一个 Collection 内复制一个 Slice 时，使用 Copy Slice。

当源端是 Collection 时，必须在请求体中显式指定 source._slice，否则返回 HTTP 400。当目标端是 Collection 时，只能指定一个目标 Slice，并且目标值必须采用 ={slice} 格式：

POST /_reindex
{
  "source": {
    "index": "source-knowledge-chunks",
    "_slice": "tenant-a,tenant-b"
  },
  "dest": {
    "index": "target-knowledge-chunks",
    "_slice": "=tenant-archive"
  }
}

目标 Slice 不存在时会自动注册。顶层 slices 参数表示 Elasticsearch Reindex 的并行度，与业务 Slice 数量无关。任一侧为 Collection 时，不支持 Reindex script；Collection 作为目标端时不支持显式 ingest pipeline。

指定查询范围

单次查询最多可以指定 1024 个 Slice。

除 Slice 数量上限外，还需要注意 HTTP 请求行的 4096 字节长度上限。使用较长的 Slice 名时，可能在达到 1024 个之前先返回 too_long_http_line_exception。此时可以缩短 Slice 名、拆分为多次查询，或改用 _slice=_all。

查询列表中可能包含不存在的 Slice 时，可以使用：

GET /knowledge-chunks/_search?_slice=tenant-a,tenant-b&ignore_missing_slice=true

不带该参数时，只要有一个 Slice 不存在，整个请求返回 HTTP 404。与 _slice=_all 同时使用时，ignore_missing_slice 无效，会被忽略且不报错。

以下查询接口也支持相同的 Slice 范围参数：

• Search 和 Count

• Multi search

• Search template

• Async search

• Validate query

• Search shards

• Update by query 和 Delete by query

Update by query、Delete by query 和 Reindex 会写入或删除数据，必须显式指定目标 Slice，未指定时请求会被拒绝并返回 HTTP 400。

省略 _slice 时查询全部 Slice

默认情况下，命名空间模式的查询需要显式指定 _slice。如果希望未传 _slice 的只读查询自动查询全部 Slice，可以开启以下集群设置：

PUT /_cluster/settings
{
  "persistent": {
    "apack.slice_collection.search.default_to_all_slices": true
  }
}

开启后，下面的请求等价于显式传入 _slice=_all：

GET /knowledge-chunks/_search

该设置为集群级设置，会影响所有 Collection，并且只适用于 Search、Count 等只读查询接口。全量查询的资源开销通常高于指定 Slice 查询；如果只有少量请求需要查询全部 Slice，建议继续显式使用 _slice=_all。

优化指定 Slice 内的文本检索

如果关键词或全文检索通常只查询指定的一个或少量 Slice，可以在创建 Collection 时开启 index.sliced_postings.enabled，减少查询需要访问的倒排数据范围：

PUT /_slice_collection/knowledge-chunks
{
  "settings": {
    "index.sliced_postings.enabled": true
  }
}

该设置默认为 false，只能在创建 Collection 时配置，创建后不能修改。开启后仍可使用 _slice=_all 查询全部 Slice，但无法获得限定 Slice 查询范围带来的主要优化收益。如果业务主要执行全局文本检索，建议保持默认关闭。

开启该设置后不支持 completion 字段，也不支持为 text 字段设置 fielddata=true。

查询最佳实践

• 使用命名空间模式时，或者请求不支持自动选择候选 Slice 时，应显式指定一个或少量 Slice，避免把 _slice=_all 作为默认访问方式。

• 使用向量簇召回模式时，应通过召回率和查询开销测试确定 query_slice_count，不要盲目增大候选 Slice 数量。

• _all 的查询开销会随 Backing 数量和分片数量增长。执行前应评估查询范围、超时时间和集群负载。

• 对可能不存在的可选 Slice 使用 ignore_missing_slice=true，不要因为单个缺失 Slice 重试整个批次。

• 应用写入、读取、更新和删除同一文档时必须使用一致的 Slice。

预热 Slice 缓存

_warm_slice API 将指定 Slice 后续查询可能访问的数据从对象存储预取到查询节点的共享缓存，从而降低冷数据的首次查询延迟。预热范围包括 DiskBBQ 向量、Slice 相关的倒排索引数据、doc values 和 stored fields，并覆盖该 Slice 所在分片的所有可搜索副本。

预热仅用于优化缓存，只影响后续访问速度，不改变查询结果，也不保证数据在缓存中的驻留时长。

• 用户即将打开一个长期未访问的知识库、代码仓库或 Agent 记忆空间，可以在首次查询前预热对应 Slice。

• 批量导入或数据迁移完成后，可以在切换查询流量前预热即将启用的 Slice。

• 已知某些命名空间将在固定时段出现访问高峰，可以提前预热这些 Slice。

数据访问不可预测、需要一次预热大量 Slice，或者目标 Slice 已经是热点数据时，不建议主动预热。大量预热会占用对象存储和查询节点的网络、缓存及计算资源，还可能淘汰已有热点数据。

POST /knowledge-chunks/_warm_slice?_slice=tenant-a

{
    "status": "ACCEPTED",
    "message": "cache warm hint accepted",
    "task": "<nodeId>:<taskId>"
  }

GET /_tasks/<nodeId>:<taskId>

POST /knowledge-chunks/_warm_slice?_slice=tenant-a&store_result=true

POST /knowledge-chunks/_warm_slice?_slice=tenant-a&wait_for_completion=true&timeout=60s

DiskBBQ 向量索引

DiskBBQ 对应 dense_vector 的 bbq_disk 索引类型，是分片内部使用的向量索引能力，不是第三种 Collection 模式。命名空间模式和向量簇召回模式都可以使用 DiskBBQ。本节介绍其配置和查询方法；AI 引擎版的性能参考见《什么是 AI 引擎版》。

• 向量规模较大，希望通过磁盘原生向量索引降低常驻内存压力。

• 能够使用业务评测集，在召回率、查询延迟和数据读取开销之间进行调优。

数据集较小、要求精确近邻结果，或尚未完成召回率评测时，不建议直接将 DiskBBQ 作为默认方案。

PUT /{collection}/_mapping
  {
    "properties": {
      "embedding": {
        "type": "dense_vector",
        "dims": 4,
        "index": true,
        "similarity": "cosine",
        "index_options": {
          "type": "bbq_disk"
        }
      }
    }
  }

{
    "index_options": {
      "type": "bbq_disk",
      "cluster_size": 384,
      "flat_index_threshold": -1,
      "default_visit_percentage": 0.0,
      "rescore_vector": { "oversample": 3.0 },
      "bits": 1
    }
  }

POST /knowledge-chunks/_search?_slice=tenant-a
  {
    "knn": {
      "field": "embedding",
      "query_vector": [0.80, 0.12, 0.05, 0.03],
      "k": 10,
      "visit_percentage": 10.0
    },
    "_source": ["document_id", "title", "content"]
  }

Collection Alias

Collection Alias 为应用提供稳定的访问名称，可用于统一查询多个 Collection 或切换写入目标。创建 Collection 时可以通过 aliases 字段添加 Alias，也可以使用标准 Elasticsearch _aliases API 管理。

• 版本迁移：应用始终访问固定 Alias，完成数据准备后把写入目标从旧 Collection 切换到新 Collection。

• 多 Collection 查询：通过一个 Alias 查询多个使用相同 slice_strategy 的 Collection。

• 应用解耦：业务配置只保存 Alias，不直接依赖带版本或日期的 Collection 名。

如果业务依赖 Alias filter 或 routing，或者希望把普通索引与 Collection 放入同一个 Alias，则不适用当前 Collection Alias。

以下示例假设 knowledge-chunks-v1 和 knowledge-chunks-v2 均为采用命名空间模式（exact）的 Collection。将它们加入同一个 Alias，并把 knowledge-chunks-v2 设置为写入目标：

POST /_aliases
{
  "actions": [
    {
      "add": {
        "index": "knowledge-chunks-v1",
        "alias": "knowledge-chunks-current"
      }
    },
    {
      "add": {
        "index": "knowledge-chunks-v2",
        "alias": "knowledge-chunks-current",
        "is_write_index": true
      }
    }
  ]
}

查看 Alias：

GET /_alias/knowledge-chunks-current

从 Alias 中移除一个成员：

POST /_aliases
{
  "actions": [
    {
      "remove": {
        "index": "knowledge-chunks-v1",
        "alias": "knowledge-chunks-current"
      }
    }
  ]
}

使用 Alias 时请注意：

• 同一个 Alias 的成员必须使用相同的 slice_strategy。采用向量簇召回模式（vector_cluster）的成员还必须使用相同的向量维度。

• 多成员 Alias 用于写入时，必须有且只有一个成员设置 is_write_index=true。

• Search、Count 和 Bulk 等接口可以按 Alias 语义访问多成员 Alias。

• 单文档 GET 和 MGet 中的每个 item 都必须唯一解析到一个 Collection，因此只能使用单成员 Alias。

• 当前不支持 Alias filter、routing、index_routing、search_routing、is_hidden 和 remove_index。

查询多成员 Alias 时，目标 Slice 必须在全部成员 Collection 中都存在，否则返回 HTTP 404。版本迁移期间新旧 Collection 的 Slice 集合通常不同，此时应显式携带 ignore_missing_slice=true，例如 GET /knowledge-chunks-current/_search?_slice=tenant-a&ignore_missing_slice=true，请求才会跳过缺失成员并正常返回。

Copy Slice 复制数据

Copy Slice 用于把同一 Collection 中一个 Slice 的可复制文档在线写入另一个 Slice。它适合数据搬运，不是时间点快照、备份或原子切流工具。

• 为某个租户复制一份测试或验证数据，同时保持与源 Slice 相同的 Collection Mapping。

• 在同一 Collection 内准备新的命名空间，Copy 完成并验证后由应用层切换访问名称。

• 对一个 Slice 做在线数据搬运，同时允许源 Slice 和目标 Slice 保持可读写。

Copy 期间写入仍可能发生，因此结果不是某个时间点的快照。需要备份、灾备、严格一致快照或原子切流时，不应使用 Copy Slice。

POST /_slice_collection/knowledge-chunks/slices/tenant-a/_copy/tenant-a-copy?wait_for_completion=false
  {
    "workers": 8,
    "batch_size": 5000,
    "requests_per_second": -1
  }

{
    "copy_id": "tenant-a-copy:1h",
    "completed": false,
    "timed_out": false,
    "state": "RUNNING",
    "source": "tenant-a",
    "target": "tenant-a-copy",
    "workers": 8,
    "progress": { "total": 0, "created": 0, "version_conflicts": 0 },
    "status_url": "/_slice_collection/knowledge-chunks/_copy/tenant-a-copy%3A1h",
    "cancel_url": "/_slice_collection/knowledge-chunks/_copy/tenant-a-copy%3A1h/_cancel"
  }

GET /_slice_collection/knowledge-chunks/_copy/<copy_id>

PUT /_cluster/settings
  {
    "persistent": {
      "apack.slice_collection.copy.reservation_retention": "1d"
    }
  }

POST /_slice_collection/knowledge-chunks/_copy/<copy_id>/_cancel

集群监控

在控制台实例详情页的左侧导航栏选择 监控与日志 > 集群监控，可以查看实例的运行指标。配置告警阈值时，应根据业务 SLO 和压测基线设置，具体指标名称和告警入口以控制台为准。

常用观测项与控制台指标的对应关系如下。

集群监控页面按指标类别分组，不提供索引节点和查询节点的角色分组。需要分别观察两类节点时，请将「资源类型」切换为指定节点，再根据节点名筛选：索引节点名包含 -index-，查询节点名包含 -search-。AI 引擎版没有 Warm 节点，只需关注索引节点、查询节点以及 AI 引擎版实际提供的监控指标。

CAT API

CAT API 适合人工观察和故障排查。日常总览先查看 Collection；容量或分片异常时再查看 Backing；定位特定命名空间的数据分布和文档数时查看 Slice。应用业务请求不应依赖 CAT 输出。

默认列：

通用查询参数：

Slice CAT 还支持 backing={backing} 按完整 Backing 名缩小范围。跨全部 Backing 按 docs.count 排序属于高开销查询，需要显式设置 allow_expensive_search=true。

面向程序处理时，建议使用 format=json 并显式指定列：

GET /_cat/slice_collection/knowledge-chunks?format=json&h=collection,state,backings,slices,docs.count,pri.store.size

CAT API 面向人工排查和有界运维查询：

• Slice CAT 最多返回 10000 行，超出时通过 HTTP Warning header 提示结果不完整。

• 需要完整、稳定分页的 Slice 名单时，使用 GET /_slice_collection/{collection}/slices。

• docs.count 是近实时数据，刚写入但尚未 refresh 的文档可能未被统计。

• pri.store.size 和 store.size 表示已索引数据大小，不等同于无状态节点的本地磁盘占用，也不包含对象存储中等待清理的历史数据。

删除 Collection

该接口适用于业务数据整体下线或清理本文示例。删除会移除 Collection 的配置和系统管理的数据，操作不可撤销；如果只需要清理某个 Slice，请使用删除 Slice API。

DELETE /_slice_collection/knowledge-chunks

查询参数：

成功响应：

{
    "acknowledged": true
  }

{collection} 支持逗号分隔的名称。默认配置下不允许使用通配符 * 和 _all，请求会返回 HTTP 400；如需使用，需要调整集群的 action.destructive_requires_name 设置。

存在正在运行或正在取消的 Copy Slice 时，删除返回 HTTP 409。取消 Copy 是异步操作，在 state 变为 CANCELLED 之前删除仍会被拒绝，应确认 state=CANCELLED 后再执行删除。

acknowledged=true 表示逻辑资源和元数据删除已确认；对象存储中的历史索引和 Translog 文件由后台流程异步回收，物理空间不保证在响应返回时立即释放。

Collection 权限

配置角色时，索引名称需要同时配置 Collection 名和对应的 Backing 通配符：

<collection>
  .sc-<collection>-*

例如 Collection 名为 knowledge-chunks 时，需要在角色中配置 knowledge-chunks 和 .sc-knowledge-chunks-*。只配置 Collection 名时，单文档读写、MGet、显式 Refresh 和 _update_by_query 等操作会返回 HTTP 403。

.sc-* 仅用于权限配置。应用仍应通过 Collection 名访问数据，不要直接访问或保存具体的 Backing Index 名称。

Slice 不是租户权限隔离边界。需要权限隔离时，应在应用层或其他受支持的 Elasticsearch 安全模型中实现。

与传统有状态 Elasticsearch 的常见差异

上表中标注为不适用的索引或集群设置，修改请求可能返回 HTTP 200，且回读时能看到新值。请勿据此判断功能已经启用。

此外，无状态架构中的副本主要用于查询和缓存，不等同于传统有状态 Elasticsearch 中可晋升为主分片的持久化副本。查询副本数量和查询节点共同决定查询容量与可用性；持久数据由对象存储保存，不能用增加副本数替代备份策略。

使用 Collection 和 Slice 时的限制

以下限制只针对 AI 引擎版中的 Collection 和 Slice 使用方式。它们不代表同名能力对普通索引也一定不可用。

名称和批量上限

Collection 和 Slice API 限制

以下为使用 Collection 和 Slice 时常见的 API 边界，不是 AI 引擎版全部功能的支持清单。

• DLS/FLS 不能用于 Collection。带 DLS/FLS 限制的角色可以创建成功，但该角色的用户访问 Collection 时会返回 HTTP 403。

• Collection 不支持跨集群搜索（CCS）。

• Point in Time（PIT）不能直接以 Collection 为目标。

• _graph/explore 和 _termvectors 不能以 Collection 为目标，_mtermvectors 也不能包含 Collection item。

• Collection 不支持已废弃的 _knn_search，请使用 _search 请求中的 knn。

• 向量簇召回模式只有在请求中提供内联查询向量时，才能自动选择候选 Slice。

• 配置 routing_field 后，不支持 scripted update。

• Collection Reindex 不支持 script；以 Collection 为目标时不支持显式 ingest pipeline；远程源端不支持 source._slice。

• Copy Slice 不支持跨 Collection、原子切流或在运行中动态调整 workers。

• 源 Slice 的 Mapping 包含 semantic_text 等推理字段时，不支持 Copy Slice。

• Slice CAT 不支持分页、按 Slice 统计存储大小或按 Slice 存储大小排序。

API 速查

以下汇总本文使用场景所需的 9.99.0 公开 API，不是 Elasticsearch 全量 API 清单，也不包含平台内部维护接口。