> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 索引设置

> 选择 OpenSearch embedding 模型、规划安全的模型切换，并配置检索相关的索引能力。

索引设置用于控制 Standard 部署如何编码文档并为基于 OpenSearch 的检索准备数据。只有 Admin 应修改这些部署级设置，并且每次变更都应使用有代表性的索引内容进行测试。

## Embedding 模型

OpenCore 使用所选 embedding 模型编码文档 chunk 与查询。该页面提供已配置的云 Provider、支持的自托管模型和自定义 embedding 模型定义。

| 模型属性                       | 作用                             |
| -------------------------- | ------------------------------ |
| Model name                 | 选择 embedding 实现与 tokenizer。    |
| Dimension                  | 决定 OpenSearch 索引中的向量形状。        |
| Normalize                  | 控制写入索引和搜索前是否对 embedding 进行归一化。 |
| Query and passage prefixes | 对查询文本与文档文本应用模型特定前缀。            |

索引设置要求 Standard 模式。Lite 不启动 OpenSearch，因此不能运行连接器索引或 embedding 模型切换。在托管 Cloud 部署中，embedding 选择器及相关控制为只读，由服务统一管理。

选择云 embedding Provider 的模型前，先配置该 Provider 的凭据。定义自定义模型时确认 dimension、normalization 和 prefix；这些值会成为索引 contract 的一部分。

## 模型切换

修改 embedding 模型或 Contextual Retrieval 设置需要完整重新索引。OpenCore 会从当前 OpenSearch 索引读取已有 chunk，使用新设置重新生成 embedding，并将结果写入目标索引。

| 策略                                     | 重新索引期间的搜索                   | 切换行为                                       |
| -------------------------------------- | --------------------------- | ------------------------------------------ |
| Re-index All Connectors Then Switch    | 当前索引继续处理查询                  | port 所有可索引连接器内容，然后将新索引提升为当前索引              |
| Re-index Active Connectors Then Switch | 当前索引继续处理查询                  | 只 port 活跃连接器，然后将新索引提升为当前索引                 |
| Switch Before Re-index                 | 未来索引会立即成为当前索引；回填期间搜索结果可能不完整 | 立即提升未来索引，不删除原 OpenSearch 语料；后台 port 从原索引回填 |

第一种策略是默认值，也是最安全的选择。对于大型语料库，重新生成 embedding 可能需要数小时或数天。在普通切换或 active-only 切换期间，旧模型会持续可用，直到提升新索引。

当前实现会把 OpenSearch 中已存储的 chunk port 到新索引并重新计算 embedding；它不会通过连接器重新获取每一份源文档。复制 backlog 时，forward indexing 会继续保护更新的写入。

取消进行中的切换会停止 port，并放弃此次重建目标及其进度，同时保持旧 embedding 模型为当前模型。取消流程不保证删除物理 OpenSearch index。立即切换的 backfill 仍未完成时，不要开始另一轮切换。

## Reranking

Reranking 与 embedding 和 OpenSearch 索引构建相互独立。当前索引设置页面不显示 reranker 选择器，其 **Apply & Re-index** 请求也不发送 reranker 字段。

应把 embedding 模型切换视为 retrieval candidate 的变化，而不是 reranker 变化。新索引提升后需要验证回答质量，但不要预期该页面会修改部署中独立的 retrieval-time reranking 行为。

## Contextual Retrieval

Contextual Retrieval 会在 embedding 前为每个已索引 chunk 添加文档级 context，以改善 hybrid search 相关性。启用它可能显著增加 LLM 与 embedding 成本。

只有部署至少配置了一个语言模型时才能使用该控制。启用后必须选择 **Contextual Retrieval LLM**；如果开关已打开但未选模型，OpenCore 会阻止 **Apply & Re-index**。托管 Cloud 部署会禁用该设置。

修改 Contextual Retrieval 设置或模型会使用完整重新索引流程。当 contextual enrichment 发生变化时，OpenCore 会在目标 OpenSearch 索引中重建 chunk context 与 embedding，而不是复制旧向量。

## 高级设置

| 设置                          | 可用条件                 | 效果                                            |
| --------------------------- | -------------------- | --------------------------------------------- |
| Multipass Indexing          | 暂时不可用；开关已禁用          | 设计目标是按不同 chunk 大小建立索引，但当前无法从此页面启用             |
| Extract & Caption Images    | 要求已配置支持 vision 的语言模型 | 从支持的上传文件中提取图像，并在索引期间添加生成的描述                   |
| Captioning LLM              | 仅在启用图像处理后可用          | 选择为新图像生成 caption 的 vision-capable 模型          |
| Max Image Size for Analysis | 仅在启用图像处理后可用          | 跳过超过所选 5、10、20、50 或 100 MB 限制的图像；页面默认值为 20 MB |

Captioning model 与图像处理更新只影响后续建立索引的文档。已有 caption 已经进入先前的 embedding，因此只修改 captioning model 不会重写它们。

## 验证

1. 应用新设置，确认页面显示 **Re-indexing in progress** 并标明目标模型。
2. 监控连接器/索引状态。对于普通或 active-only 切换，确认查询会继续使用旧模型，直到新索引完成提升。
3. 完成提升后，针对[连接器与索引](/opencore/knowledge/connectors)中说明的内容执行有代表性的 keyword、semantic 和 hybrid 搜索。
4. 确认当前 embedding 模型已变化、预期文档可搜索，并且 contextual 或图像能力只在满足上述前置条件时生效。
5. 如果部署中没有基于 OpenSearch 的索引控制，请在[部署模式](/opencore/deployment-modes)确认当前模式，并先通过[语言模型](/opencore/models/language-models)配置模型，再重试依赖这些能力的功能。