Hazelcast

Hazelcast 是一个分布式内存数据网格与计算平台。 LangChain4j 通过两个模块与 Hazelcast 集成，如此拆分以使开源路径 不受任何企业版/许可要求约束：

• langchain4j-community-hazelcast（开源）—— 提供 HazelcastChatMemoryStore，一个以 Hazelcast IMap 为后端的 ChatMemoryStore。针对开源社区版运行，无需许可。
• langchain4j-community-hazelcast-enterprise（需要 Hazelcast Enterprise）—— 提供 HazelcastEmbeddingStore（经由 VectorCollection 的向量搜索）与 HazelcastCPMapChatMemoryStore（一个强一致、由 CP 子系统支撑的聊天记忆存储）。 该模块重新导出 langchain4j-community-hazelcast，因此企业版使用者仅凭这一个依赖也能获得 基于 IMap 的存储。

Maven 依赖

开源（聊天记忆存储）

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

Hazelcast 依赖是 provided 的，因此请添加你所针对的版本。默认是 开源社区版：

<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>

NOTE

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

<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 子系统；否则它会快速失败。

聊天记忆存储

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 子系统 中的 CPMap 支撑。它是线性一致的（强一致、由 Raft 支撑）， 从而在同一个 memoryId 被并发更新时避免丢失更新。实例上必须启用 CP 子系统。

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

示例

• HazelcastChatMemoryStoreExample
• HazelcastCPMapChatMemoryStoreExample
• HazelcastEmbeddingStoreExample