企业官网建设流程全解析

Redisson Spring AI Vector Store 的 HNSW 参数 m、ef-construction 与 ef-runtime 怎么选

【免费下载链接】redissonRedisson: Valkey & Redis Java Client and Real-Time Data Platform. Sync/Async/RxJava/Reactive API. Over 50 Valkey and Redis based Java objects and services: Set, Multimap, SortedSet, Map, List, Queue, Deque, Semaphore, Lock, AtomicLong, Map Reduce, Bloom filter, Spring, Tomcat, Scheduler, JCache API, Hibernate, RPC, local cache..项目地址: https://gitcode.com/GitHub_Trending/re/redisson

如果你的 Spring AI 应用使用 Redisson 的 Vector Store 做 RAG 或语义检索，索引默认采用 HNSW 算法，而m、ef-construction、ef-runtime三个参数直接决定检索召回率、建索引速度和内存占用。这篇文档给出 Redisson 官方文档中这三个参数的默认值、推荐范围和取舍方向，并说明如何在application.yaml或手动配置中调整它们，最后用add+similaritySearch验证配置生效。

开始前先确认前提条件，以下均来自 docs/spring-ai-vector-store.md：

• 该功能仅 Redisson PRO 版可用，需要按 License key configuration 配置 license key（Community Edition 不需要）；
• 需要Redis Stack或Redis 8.4+实例，且带 RediSearch 和 RedisJSON 模块；
• 需要一个EmbeddingModel实例（OpenAI、Ollama 等 Spring AI 支持的 provider）来计算文档向量。

先看懂三个参数的含义、默认值与推荐范围

文档同时说明 HNSW 是默认算法，"provides better search performance with slightly higher memory usage"，推荐用于大多数场景；如果数据集小且要求精确结果，可以改用FLAT（暴力算法，结果精确但大数据集上性能差），通过spring.ai.vectorstore.redisson.vector-algorithm: FLAT切换。

配置步骤

1. 引入依赖。Spring Boot 应用推荐用 Starter（xVERSIONx是官方文档中的版本号占位符，替换为你实际使用的 Redisson PRO 版本）：

<dependency> <groupId>pro.redisson</groupId> <artifactId>redisson-spring-ai-store-starter-10</artifactId> <version>xVERSIONx</version> </dependency>

非 Spring Boot 或需要手动装配的场景，改用redisson-spring-ai-store-10这个 artifact。

2. 在application.yaml中配置。以下是最短主路径配置，三个 HNSW 参数先保持默认值，验证检索行为后再按上一节的取舍方向调整：

spring: ai: vectorstore: redisson: index-name: my-index prefix: doc: initialize-schema: true vector-algorithm: HNSW distance-metric: COSINE hnsw: m: 16 ef-construction: 200 ef-runtime: 10

两个容易踩的边界：

• initialize-schema必须显式设为true才会自动创建索引。文档特别指出这是相对早期 Spring AI 版本的破坏性变更（旧版本默认执行 schema 初始化）；
• hnsw.*三个参数只在vector-algorithm: HNSW时有意义，改用FLAT后无对应参数。

可选分支：手动配置。不用 Spring Boot 自动装配时，等价写法是 builder 链：

return RedissonVectorStore.builder(redissonClient, embeddingModel) .indexName("custom-index") .prefix("custom-prefix") .vectorAlgorithm(Algorithm.HNSW) .distanceMetric(DistanceMetric.COSINE) .hnswM(16) .hnswEfConstruction(200) .hnswEfRuntime(10) .initializeSchema(true) .build();

builder 的hnswM/hnswEfConstruction/hnswEfRuntime与 yaml 中的hnsw.m/hnsw.ef-construction/hnsw.ef-runtime一一对应。

怎么选：文档给出的选择规则

文档没有提供基准测试数据，选择依据就是上表的范围与约束，可以按这个顺序收敛参数：

1. 先用默认值（16 / 200 / 10）跑通，确认similaritySearch返回的结果符合预期。
2. m只在建索引前定。它在推荐范围 12–48 内调整：召回率不足且内存有余量时往上调；内存紧张时往下调。
3. ef-construction受m约束：文档要求它至少为2 * m。例如m调到 48 后，ef-construction下限就是 96，仍在 100–500 推荐范围内。它决定的是索引本身的质量，调高换来更好的索引，代价是更长的构建时间——适合一次性灌入大量文档的场景按预算上调。
4. ef-runtime是唯一可以在线调节的召回/延迟旋钮。它影响的是查询时的精度：结果偏少或漏召回时，在 10–100 范围内上调并观察查询延迟；延迟敏感就回落到接近 10 的低位。
5. 如果数据集小且必须精确结果，直接换FLAT，不再涉及这三个参数。

验证配置生效

文档给出的使用方式本身就是验证路径：先写入文档，再做相似度检索。

@Autowired VectorStore vectorStore; List<Document> documents = List.of( new Document("Spring AI rocks!! Spring AI rocks!!", Map.of("category", "framework", "year", 2024)), new Document("The World is Big and Salvation Lurks Around the Corner"), new Document("You walk forward facing the past and you turn back toward the future.", Map.of("category", "philosophy", "year", 2023))); // Add the documents to Redis vectorStore.add(documents); // Retrieve documents similar to a query List<Document> results = vectorStore.similaritySearch( SearchRequest.builder() .query("Spring") .topK(5) .build());

判断依据来自文档中的两点说明：

• 每种距离度量（默认COSINE，另有L2、IP）的相似度得分都会归一化到 0–1，1 表示最相似，因此可以用similarityThreshold（如示例中的0.7）过滤低质量结果；
• 若调整ef-runtime前后用同一批查询和相同topK对比命中结果，可以直观看到"召回率 vs 延迟"的取舍是否如文档描述的方向变化。

限制与边界

• metadata-fields中用到的字段必须显式声明名称和类型（TAG、TEXT、NUMERIC），否则无法在filterExpression中过滤——调整 HNSW 参数时如果同时改过滤条件，注意这一点。
• distance-metric的选择与 HNSW 参数独立：文档给出COSINE适合文本 embedding，L2适合图像 embedding / 空间数据，IP适合已归一化向量；切换度量不需要动hnsw.*参数。
• 三个参数的调整没有文档承诺的量化收益（如召回率百分比），上文的范围和方向是官方文档全部给出的调参依据，具体数值仍以你自己语料上的similaritySearch结果为准。

更多细节（元数据过滤表达式到 Redis 查询的转换、RAG 集成示例、agent 记忆用法）见 docs/spring-ai-vector-store.md。

【免费下载链接】redissonRedisson: Valkey & Redis Java Client and Real-Time Data Platform. Sync/Async/RxJava/Reactive API. Over 50 Valkey and Redis based Java objects and services: Set, Multimap, SortedSet, Map, List, Queue, Deque, Semaphore, Lock, AtomicLong, Map Reduce, Bloom filter, Spring, Tomcat, Scheduler, JCache API, Hibernate, RPC, local cache..项目地址: https://gitcode.com/GitHub_Trending/re/redisson