PAYATHON 2026

Elasticsearch reindex 成功但 ELSER embeddings 不完整，如何排查？

排障赵师傅

结论

reindex 成功说明文档写入完成，failures: [] 表示任务没有收到未处理的失败。reindex 不会检查每个文档是否都生成了两个非空的 embeddings 字段。

目前还无法确定根因。建议先排除刷新延迟，核实缺失字段的统计方式，再用确认缺失的文档验证 pipeline：

  • updated: 977、created: 0 表明目标索引中已经存在这些 ID。刷新前，搜索可能读到尚未包含 embeddings 的旧版本。
  • 目标字段声明为 rank_features，需要确认当前版本是否支持对该类型使用 exists 查询，才能判断查询结果是否反映了 _source 中的字段缺失情况。
  • 如果刷新后仍确认字段缺失，再检查完整 pipeline 的条件、错误处理和输入值，以及后续处理器是否修改了输出。

任务 description 只是操作摘要，没有列出 pipeline 名称并不能说明 pipeline 未执行。reindex 支持 dest.pipeline，实际是否执行应结合执行统计和文档结果确认。官方 reindex 文档

1. 先排除刷新延迟

原请求没有指定 refresh。reindex 默认不会在结束时主动刷新，因此任务完成后，搜索结果可能还没有更新。Reindex API

任务完成后，执行刷新，再重新统计并抽查文档：

POST /v1214_test/_refresh

如果刷新后缺失数量归零，就可以确认是搜索可见性问题。以后需要在 reindex 完成后立即验收时，可以使用：

POST /_reindex?refresh=true
{
  "source": {
    "index": "v1214_test_staging_20260506_181845"
  },
  "dest": {
    "index": "v1214_test",
    "pipeline": "elser_double_embedding_pipeline"
  }
}

reindex 的 refresh 参数为布尔值，这里应使用 refresh=true，不要照搬普通写入 API 的 refresh=wait_for。

刷新只会让已有写入对搜索可见，不会重新生成 embeddings。如果刷新后字段仍然缺失，继续排查。

2. 核实“527 个文档缺失”的统计依据

先获取实际版本和 mapping：

GET /

GET /v1214_test/_mapping

确认 name_embedding 和 content_embedding 的完整路径、实际类型，以及查询是否指向预期的具体索引。

exists 判断字段是否具有可查询的索引值，不直接读取 _source。官方 rank_features 文档列出的查询方式是 rank_feature 和 term，Elastic 的相关 issue 也记录了该类型不支持 exists 查询的问题。因此，在版本未知的情况下，需要进一步核实查询返回的 527 是否代表字段缺失数量。rank_features 文档、相关 issue

即使请求没有报错，也要检查完整响应中的 _shards.failed 和错误信息，并用 _source 交叉验证。

对于约 1000 个文档，可以在刷新后遍历 _source，分别统计两个字段的缺失情况。下面假设 es 是已配置好连接和认证的 Elasticsearch Python 客户端：

from collections import Counter
from elasticsearch.helpers import scan

counts = Counter()
missing_ids = []

for hit in scan(
    es,
    index="v1214_test",
    query={
        "query": {"match_all": {}},
        "_source": ["name_embedding", "content_embedding"]
    }
):
    source = hit["_source"]

    name_value = source.get("name_embedding")
    content_value = source.get("content_embedding")

    name_ok = isinstance(name_value, dict) and bool(name_value)
    content_ok = isinstance(content_value, dict) and bool(content_value)

    counts[(name_ok, content_ok)] += 1

    if not (name_ok and content_ok):
        missing_ids.append(hit["_id"])

print(counts)
print(missing_ids)

这段代码将非空 token-weight 对象视为有效输出，适用于题目中的顶层 rank_features 字段。统计结果可分为四种情况：两个字段都有、仅缺少 name_embedding、仅缺少 content_embedding、两个字段都缺少。

如果 _source 配置了排除 embeddings 字段的存储规则，就不能通过这种方法判断推理是否执行，需要结合 simulation 和处理标记确认。

3. 用真实缺失文档做逐处理器 simulation

源文档中存在 name 和 content 这两个键，还不足以说明输入有效。需要检查它们的值是否为 null、空白字符串、数组或对象。inference 的每个输入字段应是单个字符串，推理会直接使用原始输入，不会先经过 mapping 中的 analyzer。Inference processor 文档

选择一个已确认缺失的 _id，读取它在源索引中的原始文档：

GET /v1214_test_staging_20260506_181845/_doc/REPLACE_WITH_ID

将返回的完整 _source 放入 simulation。下面的示例字符串需要替换为该文档的真实值：

POST /_ingest/pipeline/elser_double_embedding_pipeline/_simulate?verbose=true
{
  "docs": [
    {
      "_index": "v1214_test",
      "_id": "REPLACE_WITH_ID",
      "_source": {
        "name": "REPLACE_WITH_ACTUAL_NAME",
        "content": "REPLACE_WITH_ACTUAL_CONTENT"
      }
    }
  ]
}

verbose=true 会返回各处理器的执行结果，需要检查：

  • inference 是否执行，是否出现 skipped、error 或 error_ignored。
  • 两个输出字段是否都是非空对象，实际写入路径是否正确。
  • 是否有警告信息。
  • 后续 remove、rename、script 等处理器是否删除或覆盖了结果。

成功文档和缺失文档都应测试。手写一段正常文本并通过 simulation，只能证明这段文本能够通过 pipeline。Simulate pipeline API

如果同一个缺失文档在 simulation 中始终正常，就应继续检查实际写入链路、目标索引配置、并发覆盖，以及批量运行时的状态。

4. 检查完整 pipeline 和错误处理

题目中的 pipeline 配置有所省略，需要读取完整定义及目标索引设置：

GET /_ingest/pipeline/elser_double_embedding_pipeline

GET /v1214_test/_settings?include_defaults=true

重点检查以下配置：

检查项可能出现的结果
processor 的 if条件为假时跳过 inference，写入仍可成功
ignore_missing: true忽略缺少的输入字段
ignore_failure: true忽略处理器异常，继续执行
processor 或 pipeline 的 on_failure异常被处理后，文档仍可能写入成功
嵌套 pipeline、后续脚本改写输入、输出路径或 embeddings
index.final_pipeline在请求指定的 pipeline 之后继续处理文档

显式指定 dest.pipeline 时，需要检查请求指定的 pipeline 和目标索引的 final pipeline。index.default_pipeline 只在请求未指定 pipeline 时作为默认值使用。Pipeline 执行与错误处理文档

普通 inference 异常如果没有配置忽略或恢复处理，通常会导致写入失败。若 failures 始终为空，应重点检查是否存在条件跳过、异常已被处理、输出检查方式有误，或写入结果随后被覆盖等情况。

Inference 文档还提醒：当 output_field 已有值时，推理结果可能追加到已有字段中，而非覆盖。反复执行 _update_by_query 前，需要检查已有输出，不能将重复运行视为可靠的修复办法。Inference 输出字段说明

5. 如何确认每个文档都经过了 pipeline

在一次受控测试前后，分别读取 ingest 统计：

GET /_nodes/stats/ingest?filter_path=nodes.*.ingest.pipelines.elser_double_embedding_pipeline

汇总所有节点的数据，比较该 pipeline 及 inference processor 的 count、failed 增量。这些增量可以帮助确认是否发生调用和失败，但统计值是累计的，可能包含其他写入、simulation 或重试，不能直接当作独立文档数量。Nodes stats 文档

如果需要逐文档确认，可以复制一份 pipeline 用于诊断，在开头记录本次运行标记，并在 inference 后检查输出。对于题目中的两个顶层字段，可在 inference 后追加以下处理器：

{
  "fail": {
    "tag": "check_embedding_outputs",
    "if": "!(ctx.name_embedding instanceof Map) || ctx.name_embedding.isEmpty() || !(ctx.content_embedding instanceof Map) || ctx.content_embedding.isEmpty()",
    "message": "Missing or empty ELSER embedding output"
  }
}

检查通过后，再追加完成标记：

{
  "set": {
    "field": "embedding_diagnostic.completed_run",
    "value": "elser-debug-run-001"
  }
}

使用时注意：

  1. 诊断输入不能带有旧 embeddings，否则旧值可能让检查误通过。可以在诊断副本中、推理前删除两个输出字段。
  2. 每次运行使用新的标记值，避免读到上一次留下的标记。
  3. 如果希望缺失输出直接进入 reindex 的 failures，就不要用 pipeline 级 on_failure 将检查异常处理成正常写入。
  4. 如果 mapping 为 dynamic: strict，需要先声明诊断字段类型。

如果业务允许保留失败文档，也可以在 on_failure 中记录 _ingest.on_failure_message 和处理器 tag。这样错误会保存在文档中，但 reindex 仍可能成功，因此需要单独查询这些错误记录。

6. 确认真实缺失后，再检查模型负载

读取模型和部署统计：

GET /_ml/trained_models/.elser_model_2_linux-x86_64/_stats

根据实际版本返回的字段，查看推理错误、超时、待处理请求和部署状态，同时核对对应时间段的节点日志。模型统计 API

retries.bulk: 2 只说明发生过 bulk 重试，无法据此判断有 527 个文档被跳过，也不能单独证明 ELSER 资源不足。有队列、超时或拒绝的证据后，再尝试减小 source.size、降低请求速率或调整模型部署资源。

ELSER 的长文本截断需要与字段缺失分开排查。官方说明 ELSER 编码字段的前 512 个 tokens，但这一限制本身无法解释为什么整份文档没有 embeddings。ELSER 文档

7. 是否需要“强制处理所有文档”

原请求没有源端过滤条件，也已经指定 dest.pipeline，无需额外的“强制推理”参数。再次执行 reindex 仍会受到 processor 的 if、错误处理和输入值的影响。

建议先在新的诊断索引中处理少量已确认缺失的 ID。提前配置相同的 embeddings mapping，并使用带输出检查的诊断 pipeline：

POST /_reindex?refresh=true
{
  "source": {
    "index": "v1214_test_staging_20260506_181845",
    "query": {
      "ids": {
        "values": ["REPLACE_WITH_ID_1", "REPLACE_WITH_ID_2"]
      }
    }
  },
  "dest": {
    "index": "v1214_test_embedding_debug",
    "pipeline": "elser_double_embedding_pipeline_debug"
  }
}

确认输出、运行标记和失败记录符合预期后，再补跑已记录的缺失 ID。两边的文档状态可能不同，因此目标索引中用于查询缺失字段的条件不能直接照搬到源索引。

仅凭“每次约 46%”无法确定故障原因。还需要比较多次运行中缺失的是否为同一批 ID：如果总是固定的 ID，优先检查输入和处理分支；如果缺失 ID 随运行变化，则重点检查负载、并发写入和结果覆盖。

备注：内容仅供参考。