Spring Data ES中Dense_Vector配置similarity遇映射解析异常

问题描述 #

使用org.springframework.boot:spring-boot-starter-data-elasticsearch:3.1.2时，为Dense_Vector类型字段配置similarity = "cosine"，启动应用触发mapper_parsing_exception，提示Field [similarity] requires field [index] to be configured。实体类中认为已通过@Field注解配置index=true，但错误依然存在；通过IndexOperations手动配置索引与相似度则可正常运行。

核心原因 #

1. @Field注解默认值问题：对于FieldType.Dense_Vector类型，Spring Data Elasticsearch 3.1.x中index属性默认值为false，若未显式声明index=true，框架不会将该属性传递到Elasticsearch的mapping中。而Elasticsearch要求设置similarity时必须同时开启index=true（相似度计算依赖索引化的向量）。
2. 框架映射bug：部分3.1.x版本存在Dense_Vector类型的index属性未被正确解析并生成到ES mapping的问题，即使显式声明index=true也无法被正确传递。

解决方案 #

方案1：显式声明index=true #

修改实体类中embedding字段的@Field注解，明确添加index = true：

@Field(name = "embedding", type = FieldType.Dense_Vector, dims=768, index = true, similarity = "cosine")
double[] embedding;

这是最直接的修复方式，确保框架将index=true传递到Elasticsearch的mapping定义中。

方案2：自定义Mapping文件 #

如果方案1无效，可通过@Mapping注解指定自定义JSON mapping文件，确保embedding字段配置完全符合要求：

1. 在resources/mappings目录下创建spare_parts-mapping.json文件：

{
  "properties": {
    "embedding": {
      "type": "dense_vector",
      "dims": 768,
      "index": true,
      "similarity": "cosine"
    }
    // 其他字段配置可省略，框架会自动补充
  }
}

2. 在实体类的@Document注解中引入该mapping：

@Data
@Document(indexName = "spare_parts", mappingPath = "/mappings/spare_parts-mapping.json")
public class SparePartsDoc {
    // 实体类字段定义...
}

方案3：启动时自动配置Mapping #

若需要动态调整mapping，可通过ApplicationListener在应用启动时自动配置，替代手动测试代码：

@Component
public class ElasticsearchMappingInitializer implements ApplicationListener<ContextRefreshedEvent> {

    private final ElasticsearchOperations elasticsearchOperations;

    public ElasticsearchMappingInitializer(ElasticsearchOperations elasticsearchOperations) {
        this.elasticsearchOperations = elasticsearchOperations;
    }

    @Override
    public void onApplicationEvent(ContextRefreshedEvent event) {
        IndexOperations indexOperations = elasticsearchOperations.indexOps(SparePartsDoc.class);
        if (!indexOperations.exists()) {
            indexOperations.create();
            Document mapping = indexOperations.createMapping(SparePartsDoc.class);
            if (mapping.get("properties") instanceof LinkedHashMap<?, ?> properties) {
                if (properties.get("embedding") instanceof LinkedHashMap<?, ?> embedding) {
                    embedding.put("index", true);
                    embedding.put("similarity", "cosine");
                    indexOperations.putMapping(mapping);
                }
            }
        }
    }
}

应用启动时会自动检查并修复embedding字段的mapping配置。

验证 #

重启应用后，通过Elasticsearch API查看索引mapping：

GET /spare_parts/_mapping

确认embedding字段配置包含"index": true和"similarity": "cosine"，即可解决该异常。

内容的提问来源于stack exchange，提问作者Rodrick Zadrozny