LangChain4j 集成 Jlama 本地 Embedding 模型基于 BERT 的纯 JVM 向量化实战指南【免费下载链接】langchain4jLangChain4j is an idiomatic, open-source Java library for building LLM-powered applications on the JVM. It offers a unified API over popular LLM providers and vector stores, and makes implementing tool calling (including MCP support), agents and RAG easy. It integrates seamlessly with enterprise Java frameworks like Quarkus and Spring Boot.项目地址: https://gitcode.com/GitHub_Trending/la/langchain4j本篇技术指南讲解如何在 LangChain4j 项目中接入 Jlama Embedding 模型以纯 JVM 方式完成文本向量化与语义检索从 Maven/Gradle 依赖配置、JlamaEmbeddingModel构建与参数调优到结合InMemoryEmbeddingStore完成写入-检索闭环并串联 RAG 场景。读完本文你将掌握本地化、零外部 API 依赖的 Embedding 方案并能从源码层面理解模型下载、加载与池化pooling的底层机制。Jlama 与 langchain4j-jlama 概览Jlama 是一个纯 Java 实现的 LLM 推理引擎基于 Java 20 构建利用 JDK 孵化中的 Vector APIjdk.incubator.vector加速推理并直接加载 HuggingFace 上以 safetensors 格式发布的模型。langchain4j-jlama 模块langchain4j-jlama/pom.xml将其封装为 LangChain4j 统一模型接口让 Java 开发者无需任何外部推理服务即可在 JVM 内完成 Embedding、对话生成与流式输出。从该模块的源码结构langchain4j-jlama/src/main/java/dev/langchain4j/model/jlama可以看到它提供五类模型入口模型类能力说明JlamaEmbeddingModel文本向量化仅支持 BERT 架构模型JlamaLanguageModel文本补全LLM实现LanguageModel接口JlamaChatModel多轮对话含工具调用实现ChatModel接口JlamaStreamingLanguageModel流式文本补全逐 token 输出JlamaStreamingChatModel流式对话逐 token 输出同时模块基于 SPIServiceLoader提供了对应 Builder 工厂见 spi便于与 Quarkus / Spring Boot 等框架的扩展机制整合。本文聚焦其中的 Embedding 部分。需要特别强调的是运行环境前提Jlama 依赖 Java 21该模块pom.xml中java.version为 21且推理过程依赖 Vector API 等 JVM 内部能力运行测试时需要在 JVM 参数中加入--add-modulesjdk.incubator.vector --enable-preview --enable-native-accessALL-UNNAMED等选项参见 pom.xml。这同样适用于你在自己的应用里以java -jar或 IDE 方式启动时的情况。项目依赖配置Maven 与 Gradle要使用 Jlama Embedding需要在项目中同时引入 LangChain4j 核心模块与 Jlama 集成模块。下面是 Mavenpom.xml的完整配置dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version1.20.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-jlama/artifactId version1.20.0-beta30/version /dependency dependency groupIdcom.github.tjake/groupId artifactIdjlama-native/artifactId !-- for faster inference. supports linux-x86_64, macos-x86_64/aarch_64, windows-x86_64 Use https://github.com/trustin/os-maven-plugin to detect os and arch -- classifier${os.detected.name}-${os.detected.arch}/classifier version${jlama.version}/version !-- Version from langchain4j-jlama pom -- /dependency关键点说明langchain4j-jlama是集成模块其版本与核心模块的正式版本/里程碑版本可能不同步请以 Maven Central 上实际发布的版本为准。jlama-native提供面向特定平台的本地加速能力支持linux-x86_64、macos-x86_64/aarch_64、windows-x86_64必须通过classifier指定平台。${jlama.version}对应langchain4j-jlama内部使用的 Jlama 版本当前仓库中为0.8.4见 pom.xml可用 os-maven-plugin 自动探测当前操作系统与架构并生成os.detected.name/os.detected.arch属性。若你的项目使用 Gradlebuild.gradle中对应的写法为implementation dev.langchain4j:langchain4j:1.20.0 implementation dev.langchain4j:langchain4j-jlama:1.20.0-beta30从源码角度看pom.xml 中langchain4j-jlama直接依赖jlama-core并将jlama-native作为测试依赖scopetest/scope也就是说纯 Java 推理路径只需要jlama-core而追求更快推理速度时才需要按平台引入jlama-native原生库。使用 JlamaEmbeddingModel 实现语义检索核心示例Embedding 内存向量库Jlama Embedding 模型的使用非常直接构建JlamaEmbeddingModel指定一个 HuggingFace 上基于 safetensors 格式的BERT 架构模型owner/model-name格式即可对文本做向量化并配合 LangChain4j 的EmbeddingStore完成语义检索。完整可运行示例import dev.langchain4j.data.embedding.Embedding; import dev.langchain4j.data.segment.TextSegment; import dev.langchain4j.model.jlama.JlamaEmbeddingModel; import dev.langchain4j.model.embedding.EmbeddingModel; import dev.langchain4j.store.embedding.EmbeddingMatch; import dev.langchain4j.store.embedding.EmbeddingStore; import dev.langchain4j.store.embedding.inmemory.InMemoryEmbeddingStore; import java.util.List; public class HelloWorld { public static void main(String[] args) { EmbeddingModel embeddingModel JlamaEmbeddingModel .modelName(intfloat/e5-small-v2) .build(); // For simplicity, this example uses an in-memory store, but you can choose any external compatible store for production environments. EmbeddingStoreTextSegment embeddingStore new InMemoryEmbeddingStore(); TextSegment segment1 TextSegment.from(I like football.); Embedding embedding1 embeddingModel.embed(segment1).content(); embeddingStore.add(embedding1, segment1); TextSegment segment2 TextSegment.from(The weather is good today.); Embedding embedding2 embeddingModel.embed(segment2).content(); embeddingStore.add(embedding2, segment2); String userQuery What is your favourite sport?; Embedding queryEmbedding embeddingModel.embed(userQuery).content(); EmbeddingSearchRequest searchRequest EmbeddingSearchRequest.builder() .queryEmbedding(queryEmbedding) .maxResults(1) .build(); EmbeddingSearchResultTextSegment searchResult embeddingStore.search(searchRequest); EmbeddingMatchTextSegment embeddingMatch searchResult.matches().get(0); System.out.println(Question: userQuery); // What is your favourite sport? System.out.println(Response: embeddingMatch.embedded().text()); // I like football. } }程序输出Question: What is your favourite sport? Response: I like football.示例中intfloat/e5-small-v2是仓库测试用例实际使用的模型见 JlamaEmbeddingModelIT.java你也可以替换为 HuggingFace 上任意 BERT 架构的 safetensors 模型只要以owner/model-name格式指定即可。流程上示例完成了三步向量化写入对两个TextSegment分别调用embeddingModel.embed(...)得到Embedding与原文一起存入InMemoryEmbeddingStore查询向量化对用户问题做同样的embed()得到查询向量相似度检索用EmbeddingSearchRequestmaxResults1检索最相似的片段返回EmbeddingMatchTextSegment通过embedded().text()拿到原文。这里为了演示简单使用了内存向量库生产环境可以替换为 LangChain4j 支持的任何外部向量存储如 pgvector、Milvus、Qdrant、Weaviate 等。更真实的文档级流程多来源加载与多格式解析在真实业务中文本往往不是手动构造的两个字符串而是来自文档。LangChain4j 提供了内置的文档加载器DocumentLoader支持文件系统、URL、Amazon S3、Azure Blob Storage、GitHub、Tencent COS 等来源对应仓库中的 document-loaders 目录同时支持多种文档格式解析DocumentParser涵盖 text、pdf、doc、xls、ppt 等类型对应 document-parsers 目录。典型的流程是加载文档 → 解析为Document→ 切分为多个TextSegment→ 批量embedAll写入向量库之后查询时复用同一套检索逻辑。需要注意的是JlamaEmbeddingModel.embedAll(ListTextSegment)的实现见 JlamaEmbeddingModel.java是逐段调用底层model.embed(text, poolingType)的因此在处理大规模语料时建议结合批量提交与持久化向量库并评估推理耗时。深入源码模型加载与构建参数全解JlamaEmbeddingModel继承自DimensionAwareEmbeddingModel其构建器builder暴露了全部可调参数。下表综合 JlamaEmbeddingModel.java 的 Builder 定义整理Builder 方法类型作用与默认值modelName(String)StringHuggingFace 模型标识owner/model-name格式必填modelCachePath(Path)Path模型缓存目录默认为~/.jlama/models见 JlamaModelRegistry.javaauthToken(String)String访问私有/受限模型时所需的 HuggingFace Token可选threadCount(Integer)Integer推理线程数控制 CPU 并行度quantizeModelAtRuntime(Boolean)Boolean是否在运行时做量化Q4以降低内存占用poolingType(Generator.PoolingType)枚举句向量池化策略默认MODEL采用模型自带池化workingDirectory(Path)Path推理工作目录用于存放工作张量/临时文件模型类型强制校验构造JlamaEmbeddingModel时JlamaEmbeddingModel.java源码会校验下载模型的类型if (jlamaModel.getModelType() ! ModelSupport.ModelType.BERT) { throw new IllegalArgumentException(Model type must be BERT); }也就是说Embedding 场景下只接受 BERT 架构模型若指定了其他架构如 Llama 系列构建阶段会直接抛出IllegalArgumentException。这一点在选择模型时必须留意。加载链路下载 → 缓存 → 加载JlamaEmbeddingModel的构造函数展示了完整的模型准备链路JlamaEmbeddingModel.java通过JlamaModelRegistry.getOrCreate(modelCachePath)获取或创建本地模型注册表若缓存目录不存在会先创建目录见 JlamaModelRegistry.java调用registry.downloadModel(modelName, authToken)若本地缓存缺失则通过SafeTensorSupport.maybeDownloadModel从 HuggingFace 下载 safetensors 权重与config.json下载失败时由JlamaExceptionMapper做重试与 HTTP 状态码映射见 JlamaExceptionMapper.java依据quantizeModelAtRuntime、threadCount、workingDirectory等参数配置Loader并强制设置inferenceType(AbstractModel.InferenceType.FULL_EMBEDDING)JlamaEmbeddingModel.java加载为BertModel并从model.getConfig().embeddingLength读取向量维度dimension供dimension()查询使用。从JlamaModel.LoaderJlamaModel.java还可看到两个底层细节运行时量化目前仅支持 Q4DType.Q4工作量化类型workingQuantizationType默认DType.I8即推理过程中的中间张量默认以 INT8 工作以平衡精度与内存。池化策略poolingpoolingType决定如何将 BERT 输出的 token 级向量聚合成一个句向量默认MODEL表示使用模型自带的池化逻辑通常是 CLS token 或 mean pooling由模型实现决定你也可以显式传入Generator.PoolingType的其他取值来覆盖。每次embed/embedAll调用都会携带该池化类型JlamaEmbeddingModel.java。与 RAG 的集成及参数显式控制接入 RAG 流程Jlama Embedding 天然适合作为 RAGRetrieval-Augmented Generation流程中的向量化组件先用JlamaEmbeddingModel将知识库文档切分后的片段写入EmbeddingStoreingestion 阶段检索时再对用户问题向量化并在向量库中召回相关片段retrieval 阶段最后把召回内容交给JlamaChatModel或其他对话模型生成回答。关于 LangChain4j 中 RAG 的 ingestion、retrieval 与高级检索Advanced Retrieval的完整实践参见 RAG 教程。参数显式控制默认情况下JlamaEmbeddingModel会在后台使用一组内置参数例如上述默认池化策略MODEL、默认缓存路径、模型自身的上下文与嵌入维度等。当你需要精确控制 temperature、maxTokens 等模型参数或希望对齐不同模型的推理行为时可以在 模型参数教程 中了解 LangChain4j 统一参数体系ChatRequestParameters等的用法。类似的显式配置模式也体现在JlamaChatModel的构造逻辑中temperature 默认0.3f、maxTokens 默认取模型上下文长度JlamaChatModel.javaJlamaLanguageModel则默认 temperature0.7fJlamaLanguageModel.java。测试验证与常见问题排查仓库中的集成测试仓库在 JlamaEmbeddingModelIT.java 中提供了可复现的验证用例should_embed对hello world调用model.embed(text)断言返回向量非空且tokenUsage、finishReason为 null本地推理不产生计费 Token 统计should_return_correct_dimension断言model.dimension()与实际返回向量的dimension()一致验证维度信息与模型配置对齐。测试使用intfloat/e5-small-v2并将模型缓存到系统临时目录java.io.tmpdir/jlama_tests。你可以参考该写法在本地 CI 或开发环境快速验证 Jlama Embedding 是否可用。常见问题现象原因与对策构建时报Model type must be BERT指定了非 BERT 架构的模型换成 BERT 架构的 safetensors 模型首次运行下载缓慢或失败模型权重需从 HuggingFace 下载到缓存目录默认~/.jlama/models可预先手动下载或配置镜像并通过modelCachePath指向已有缓存私有模型 401/403通过authToken(...)传入 HuggingFace 访问 TokenJVM 启动报java.lang.UnsupportedOperationException或 Vector API 相关错误确认 JDK 版本满足 21并按 pom.xml 中所示添加--add-modulesjdk.incubator.vector --enable-preview --enable-native-accessALL-UNNAMED等启动参数大模型内存占用过高开启quantizeModelAtRuntime(true)Q4 量化降低内存占用更多参考更多可直接运行的示例代码可以查看 LangChain4j 官方的langchain4j-examples示例工程。结合本文的源码解析你可以继续深入 langchain4j-jlama 模块或对比阅读仓库中其他 Embedding 模型集成如 langchain4j-embeddings 目录下的本地轻量模型来选择最适合你场景的向量化方案。【免费下载链接】langchain4jLangChain4j is an idiomatic, open-source Java library for building LLM-powered applications on the JVM. It offers a unified API over popular LLM providers and vector stores, and makes implementing tool calling (including MCP support), agents and RAG easy. It integrates seamlessly with enterprise Java frameworks like Quarkus and Spring Boot.项目地址: https://gitcode.com/GitHub_Trending/la/langchain4j创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考