Hazelcast

Hazelcast 是一个分布式内存数据网格与计算平台。 LangChain4j 通过两个模块与 Hazelcast 集成，拆分目的是让开源路径不依赖任何企业版/许可要求：

langchain4j-community-hazelcast（开源）— 提供 HazelcastChatMemoryStore，一种由 Hazelcast IMap 支持的 ChatMemoryStore。可在开源 Community Edition 上运行，无需许可证。
langchain4j-community-hazelcast-enterprise（需要 Hazelcast Enterprise）— 提供 HazelcastEmbeddingStore（通过 VectorCollection 进行向量搜索）以及 HazelcastCPMapChatMemoryStore（基于 CP Subsystem 的强一致聊天记忆存储）。该模块会再导出 langchain4j-community-hazelcast，因此企业版用户只需这一个依赖也能获得基于 IMap 的存储。

Maven 依赖

开源（聊天记忆存储）

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-community-hazelcast</artifactId>
    <version>${latest version here}</version>
</dependency>

Hazelcast 依赖的作用域为 provided，因此请添加你实际运行的版本。默认是开源 Community Edition：

<dependency>
    <groupId>com.hazelcast</groupId>
    <artifactId>hazelcast</artifactId>
    <version>5.7.0</version>
</dependency>

Hazelcast Enterprise（嵌入存储 + CP 聊天记忆）

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-community-hazelcast-enterprise</artifactId>
    <version>${latest version here}</version>
</dependency>

或者使用 BOM 统一管理版本：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-community-bom</artifactId>
            <version>${latest version here}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

备注

HazelcastEmbeddingStore 和 HazelcastCPMapChatMemoryStore 需要 Hazelcast Enterprise。 com.hazelcast:hazelcast-enterprise 不在 Maven Central 上 — 它会由 langchain4j-community-hazelcast-enterprise 传递引入，但你必须添加 Hazelcast release 仓库以及有效的企业版许可证密钥：

<repositories>
    <repository>
        <id>hazelcast-release</id>
        <name>Hazelcast Release Repository</name>
        <url>https://repository.hazelcast.com/release/</url>
    </repository>
</repositories>

通过 config.setLicenseKey(...) 或 HZ_LICENSEKEY 环境变量提供许可证密钥。 HazelcastCPMapChatMemoryStore 还额外要求启用 CP Subsystem；否则会快速失败。

聊天记忆存储

HazelcastChatMemoryStore（开源）将每条聊天记忆以 JSON 序列化的 ChatMessage 列表形式存储在 Hazelcast IMap 中。你提供的 HazelcastInstance 可以是嵌入式成员或瘦客户端 — builder 不做区分。

// Embedded member
HazelcastInstance hz = Hazelcast.newHazelcastInstance(new Config());

ChatMemoryStore store = HazelcastChatMemoryStore.builder()
        .hazelcastInstance(hz)
        .name("chatMemory") // optional, defaults to "chatMemory"
        .build();

// Client connecting to an external cluster
ClientConfig clientConfig = new ClientConfig();
clientConfig.getNetworkConfig().addAddress("hazelcast-host:5701");
HazelcastInstance hzClient = HazelcastClient.newHazelcastClient(clientConfig);

ChatMemoryStore store = HazelcastChatMemoryStore.builder()
        .hazelcastInstance(hzClient)
        .build();

也可以直接用 HazelcastChatMemoryStore.create(IMap<String, String>) 包装一个预先配置好的 IMap。

强一致变体（Enterprise）

HazelcastCPMapChatMemoryStore（Enterprise）是另一种实现，由 CP Subsystem 中的 CPMap 支持。它是 可线性化 的（强一致，基于 Raft），可避免同一 memoryId 被并发更新时丢失更新。实例上必须启用 CP Subsystem。

Config config = new Config();
config.getCPSubsystemConfig().setCPMemberCount(3); // CP Subsystem must be enabled
HazelcastInstance hz = Hazelcast.newHazelcastInstance(config);

ChatMemoryStore store = HazelcastCPMapChatMemoryStore.builder()
        .hazelcastInstance(hz)
        .name("chatMemory")
        .build();

相对 IMap 存储的权衡：CPMap 不可分区（必须装入每个 CP 成员的内存，默认总计 100 MB），并且 没有 TTL/淘汰。它适合大量小型对话；若用户规模极大且需要无界历史，请优先使用基于 IMap 的存储。

嵌入存储

HazelcastEmbeddingStore（Enterprise）由 Hazelcast VectorCollection 支持。向量索引维度必须与所用嵌入模型匹配；度量默认是 COSINE。

HazelcastInstance hz = Hazelcast.newHazelcastInstance(new Config());

EmbeddingStore<TextSegment> store = HazelcastEmbeddingStore.builder()
        .hazelcastInstance(hz)
        .collectionName("embeddings")   // optional, defaults to "embeddings"
        .dimension(384)                 // required, must match the embedding model
        .metric(Metric.COSINE)          // optional, defaults to COSINE
        .build();

也可以用 HazelcastEmbeddingStore.create(VectorCollection<String, TextSegmentDocument>) 包装预先配置好的 VectorCollection。search(...) 返回的相关性分数是 Hazelcast 已经归一化的 COSINE 分数，可直接使用。

限制

removeAll(Filter) 不受支持 — VectorCollection 没有服务端谓词删除；会抛出 UnsupportedFeatureException。按 id 删除、removeAll(Collection<String>) 以及 removeAll() 是支持的。
搜索期间的元数据过滤不会在服务端执行。如果 EmbeddingSearchRequest 带有过滤器，会在检索后于 客户端应用（并记录警告），这可能导致返回结果少于 maxResults。

API

HazelcastChatMemoryStore — 基于 IMap（AP），开源
HazelcastCPMapChatMemoryStore — 基于 CPMap（CP，可线性化），Enterprise
HazelcastEmbeddingStore — 基于 VectorCollection 的向量存储，Enterprise

Maven 依赖​

开源（聊天记忆存储）​

Hazelcast Enterprise（嵌入存储 + CP 聊天记忆）​

聊天记忆存储​

强一致变体（Enterprise）​

嵌入存储​

限制​

API​

示例​