LangChain4j 集成 Voyage AI 嵌入模型：从文本嵌入到多模态向量化的完整实战指南

LangChain4j 集成 Voyage AI 嵌入模型从文本嵌入到多模态向量化的完整实战指南【免费下载链接】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 官方集成文档 docs/docs/integrations/embedding-models/voyage-ai.md系统讲解如何在 JVM 项目中通过 LangChain4j 使用 Voyage AI 嵌入Embedding模型从 Maven 依赖引入、VoyageAiEmbeddingModel的完整 Builder 配置到文本嵌入、批量嵌入、多模态文本 图片融合嵌入的实际用法。读完本文你将能够把 Voyage AI 的向量化能力无缝接入 LangChain4j 的 RAG 检索链路与向量存储体系并理解其底层请求/响应处理与路由机制。一、Voyage AI 集成概览Voyage AI 是提供文本与多模态嵌入Embedding服务的模型提供商。LangChain4j 通过独立模块langchain4j-voyage-ai将其封装为标准的 EmbeddingModel 实现使上层 RAG、向量检索代码完全复用 LangChain4j 统一的模型抽象无需关心 Voyage 的 HTTP API 细节。本模块的核心能力由官方文档与源码共同确认核心 APIVoyageAiEmbeddingModel实现类位于 VoyageAiEmbeddingModel.java多模态支持voyage-multimodal-3、voyage-multimodal-3.5可将交错排列的文本与图片融合为单一向量从模型名自动检测按调用参数支持input_typequery/document用于优化检索场景的向量质量可观测性支持通过listeners(...)配置EmbeddingModelListener接入 LangChain4j 的观测体系。该模块依赖langchain4j-core与langchain4j-http-client运行时默认使用 JDK 自带 HTTP 客户端langchain4j-http-client-jdk可参考 langchain4j-voyage-ai/pom.xml。二、添加 Maven 依赖在你的pom.xml中引入如下依赖dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-voyage-ai/artifactId version1.20.0-beta30/version /dependency说明上述版本来自官方集成文档。当前仓库主分支的模块版本为1.21.0-beta31-SNAPSHOT见 langchain4j-voyage-ai/pom.xml实际使用时请根据你的发布渠道选择正式发布的版本号。三、API 与构建方式VoyageAiEmbeddingModelVoyageAiEmbeddingModel是DimensionAwareEmbeddingModel的实现后者在 langchain4j-core 中提供维度感知能力它封装了 Voyage AI 的 Embedding API并通过链式 Builder 提供全部配置项。最简创建方式与集成测试 VoyageAiEmbeddingModelIT.java 中的用法一致import dev.langchain4j.model.embedding.EmbeddingModel; import dev.langchain4j.model.voyageai.VoyageAiEmbeddingModel; import dev.langchain4j.model.voyageai.VoyageAiEmbeddingModelName; EmbeddingModel model VoyageAiEmbeddingModel.builder() .apiKey(System.getenv(VOYAGE_API_KEY)) // 必填Voyage AI API Key .modelName(VoyageAiEmbeddingModelName.VOYAGE_3_LITE) .build();modelName既支持枚举VoyageAiEmbeddingModelName也支持任意字符串便于使用仓库枚举未收录的新模型名见 VoyageAiEmbeddingModel.java。Builder 配置项全解默认值来自源码配置项类型默认值说明apiKeyString无必填Voyage AI 的 API Key用于Authorization: Bearer apiKey请求头modelNameVoyageAiEmbeddingModelName/String无必填模型名见下文模型清单baseUrlStringhttps://api.voyageai.com/v1/API 基地址见 VoyageAiClient.javatimeoutDuration60 秒HTTP 连接/读取超时源码中同时将连接超时兜底为 15 秒maxRetriesInteger2对瞬时错误的最大重试次数通过withRetryMappingExceptions实现inputTypeStringnullquery/document/ null见下文专门说明truncationBooleantrue超长文本是否截断以适配上下文长度false 时超长会直接报错encodingFormatStringnull向量编码格式null浮点数列表或base64压缩为 Base64maxSegmentsPerBatchInteger128单次批量请求最多包含的文本段数量超出自动分批multimodalBoolean从模型名自动推断强制开启多模态路由命名含multimodal时自动为 truelogRequests/logResponsesBooleanfalse调试日志打印请求/响应体loggerorg.slf4j.Logger默认 Logger自定义请求/响应日志所用 LoggerhttpClientBuilderHttpClientBuilderSPI 加载自定义 HTTP 客户端超时、代理等customHeadersMap/SupplierMap无每次请求附加的自定义 HeaderSupplier 形式每次请求前调用适合动态令牌如 OAuth2 刷新listenersListEmbeddingModelListener空列表嵌入模型监听器用于观测与追踪以上默认值均可从 VoyageAiEmbeddingModel.java 的构造逻辑核实。内置模型清单与向量维度VoyageAiEmbeddingModelName.java 定义了仓库已知的模型与维度供knownDimension()做维度校验枚举值模型名输出维度VOYAGE_3voyage-31024VOYAGE_3_LITEvoyage-3-lite512VOYAGE_3_LARGEvoyage-3-large1024VOYAGE_FINANCE_2voyage-finance-21024VOYAGE_MULTILINGUAL_2voyage-multilingual-21024VOYAGE_LAW_2voyage-law-21024VOYAGE_CODE_2voyage-code-21536VOYAGE_CODE_3voyage-code-31024四、文本嵌入单条与批量单条文本嵌入import dev.langchain4j.model.output.Response; import dev.langchain4j.data.embedding.Embedding; ResponseEmbedding response model.embed(Hello World); int dimension response.content().dimension(); // 与模型维度一致批量文本段嵌入embedAll接收TextSegment列表返回值与输入顺序一一对应import dev.langchain4j.data.segment.TextSegment; import java.util.List; import static java.util.Arrays.asList; TextSegment segment1 TextSegment.from(hello); TextSegment segment2 TextSegment.from(hi); ResponseListEmbedding response model.embedAll(asList(segment1, segment2));从源码 doEmbed 可以看到内部处理逻辑分批按maxSegmentsPerBatch默认 128将输入切分为多个批次避免单请求过大并发串行请求逐批调用 Voyage API最后合并全部向量结果响应排序按响应的index字段排序保证输出与输入顺序一致见 EmbeddingResponse.javaToken 统计汇总每批的total_tokens以TokenUsage形式随响应返回。集成测试 VoyageAiEmbeddingModelIT.java 验证了 97 个文本段超过默认批大小 128 的一半场景用maxSegmentsPerBatch(96)强制分批依然能全部正确返回测试还断言了hello与hi两个段的余弦相似度大于 0.8使用CosineSimilarity可用于验证语义相关性的基本合理性。提示集成测试需要环境变量VOYAGE_API_KEY且测试类标注了EnabledIfEnvironmentVariable(named VOYAGE_API_KEY, matches .)未配置时自动跳过。五、input_type检索场景的优化参数Voyage AI 支持通过input_type参数对嵌入做检索场景优化LangChain4j 将其映射为EmbeddingInputType枚举QUERY/DOCUMENT映射逻辑见 VoyageAiEmbeddingModel.java取值语义来自源码 Javadocquery用于搜索或检索的查询文本。Voyage AI 会在嵌入前为查询场景前置优化提示prepend a promptdocument用于希望被检索到的文档/内容。Voyage AI 会为文档场景前置优化提示null默认直接编码原始文本不附加任何额外提示两种设置方式方式一全局配置构建时固定VoyageAiEmbeddingModel model VoyageAiEmbeddingModel.builder() .apiKey(System.getenv(VOYAGE_API_KEY)) .modelName(VoyageAiEmbeddingModelName.VOYAGE_3_LITE) .inputType(query) // 所有请求统一使用 query 模式 .build();方式二按请求配置per-callLangChain4j 的嵌入请求支持按调用传入参数。VoyageAiEmbeddingModel.supportedParameters()声明支持EmbeddingRequestParameters.INPUT_TYPE见 VoyageAiEmbeddingModel.java这也是官方文档强调的“Per-call parameters”能力import dev.langchain4j.model.embedding.request.EmbeddingInputType; import dev.langchain4j.model.embedding.request.EmbeddingRequest; model.embed(EmbeddingRequest.builder() .input(LangChain4j 是什么) .inputType(EmbeddingInputType.QUERY) // 本次请求按查询处理 .build());请求级参数优先于模型级配置——源码中getOrDefault(toVoyageInputType(request.inputType()), inputType)正是“先取请求参数、缺省时回退到 Builder 配置”的实现。典型用法RAG 系统中入库文档用DOCUMENT检索查询用QUERY两者在各自优化空间内编码可显著提升召回质量。六、多模态嵌入文本 图片融合为单一向量官方文档明确指出voyage-multimodal-3与voyage-multimodal-3.5可将文本和图片嵌入到共享向量空间且交错排列的文本 图片会被融合为一个嵌入向量。图片输入通过EmbeddingRequest中的ImageContentURL 或 Base64提供。自动检测与路由机制从源码 isMultimodalModel 可见模型名包含子串multimodal即自动判定为多模态例如voyage-multimodal-3.5。此时supportedContentTypes()返回TEXTIMAGE纯文本模型仅返回TEXT内部请求路由到/multimodalembeddings端点否则走/embeddings端点见 VoyageAiClient.java。路由测试 VoyageAiMultimodalRoutingTest.java 验证了以下关键行为voyage-multimodal-3/voyage-multimodal-3.5自动启用图文支持voyage-3纯文本模型请求图片会快速失败抛出UnsupportedFeatureException消息含IMAGEvoyage-multilingual-2不会被误判为多模态避免multilingual与multimodal混淆显式设置.multimodal(true)可覆盖自动检测例如使用自定义代理模型名时VideoContent输入同样会快速失败消息含VIDEO。图文混合嵌入示例import dev.langchain4j.data.message.TextContent; import dev.langchain4j.data.message.ImageContent; ResponseEmbedding response model.embed(EmbeddingRequest.builder() .input( TextContent.from(a photo of a cat), // 文本块 ImageContent.from(https://example.com/cat.png)) // 图片 URL .inputType(EmbeddingInputType.QUERY) .build());图片输入的两种形式图片使用ImageContent.from(...)创建常用重载见 ImageContent.java1. URL 形式ImageContent image ImageContent.from(https://example.com/cat.png);底层序列化为image_url内容块请求体会包含image_url与 URL。2. Base64 形式ImageContent image ImageContent.from(aGVsbG8, image/png); // Base64 数据 MIME 类型源码 toContentBlock 会将其拼装为data:mimeType;base64,data的 Data URL 发送MIME 缺省时默认为image/png。路由测试确认请求体形如data:image/png;base64,aGVsbG8。注意图片内容必须提供 URL 或 Base64 数据二者之一否则抛出UnsupportedFeatureException消息为 ImageContent must have either a URL or base64 data。多模态请求的底层结构多模态请求体由 MultimodalEmbeddingRequest.java 定义每个输入包含一个有序的内容块列表text/image_url/image_base64三种类型这些内容块被融合为单个嵌入向量。响应侧仍复用标准EmbeddingResponse可从中取回向量、模型名与 Token 用量。七、响应结构向量、Token 用量与 Base64 解码ResponseEmbedding/ResponseListEmbedding中除向量本身外还包含tokenUsage()Voyage 返回的total_tokens注意集成测试中的备注Voyage 有时会返回totalTokens0属正常现象outputTokenCount为 null嵌入无输出 tokenfinishReason()嵌入请求为 nullmetadata().modelName()实际响应模型名。encodingFormat(base64) 的底层解码当设置encodingFormat(base64)时Voyage 会以小端little-endian浮点字节的 Base64 字符串返回向量。响应解析器 EmbeddingResponse.java 负责透明解码VoyageAiEmbeddingModel model VoyageAiEmbeddingModel.builder() .apiKey(System.getenv(VOYAGE_API_KEY)) .modelName(VoyageAiEmbeddingModelName.VOYAGE_3_LITE) .encodingFormat(base64) // 服务端压缩返回减少传输体积 .build();对使用者而言response.content().vector()拿到的始终是float[]形式无需关心底层是否 Base64 编码——解码细节已被封装。八、监听器与观测Listeners官方文档强调可通过VoyageAiEmbeddingModel.builder().listeners(...)配置监听器。EmbeddingModelListener是 LangChain4j 观测体系的一部分可在嵌入请求发起前后、成功/失败时获得回调用于日志、指标与链路追踪。import dev.langchain4j.model.embedding.listener.EmbeddingModelListener; EmbeddingModelListener listener new EmbeddingModelListener() { Override public void onRequest(EmbeddingModelRequestContext context) { System.out.println(请求模型: context.request().modelName()); } // 其余回调按需覆写 }; VoyageAiEmbeddingModel model VoyageAiEmbeddingModel.builder() .apiKey(System.getenv(VOYAGE_API_KEY)) .modelName(voyage-multimodal-3.5) .listeners(List.of(listener)) .build();公共集成测试 common/VoyageAiEmbeddingModelIT.java 继承AbstractEmbeddingModelIT对监听器场景做了完整覆盖包括使用错误 API Keybanana且maxRetries(0)构造失败模型的监听器回调验证。九、错误处理与调试瞬时错误重试默认maxRetries 2由withRetryMappingExceptions统一处理源码 VoyageAiEmbeddingModel.java快速失败对不支持的内容类型如图片喂给纯文本模型、视频内容在本地立即抛出UnsupportedFeatureException避免无效的网络请求请求/响应日志logRequests(true)打印请求体logResponses(true)打印响应体——注意向量体积巨大集成测试中特别注释embeddings are huge in logs生产环境建议关闭响应日志或谨慎使用自定义 HTTP 客户端通过httpClientBuilder(...)注入自定义实现如代理、连接池配置模块默认通过 SPI 加载HttpClientBuilder并在 pom 中提供langchain4j-http-client-jdk作为运行时实现。十、与 LangChain4j RAG / 向量存储的衔接VoyageAiEmbeddingModel实现了统一的 EmbeddingModel 接口因此可以无缝替换 LangChain4j RAG 流程中的任意嵌入模型位置。典型接入方式使用TextSegment将文档切分为文本段调用embedAll(...)批量向量化将向量写入 LangChain4j 支持的向量存储如 langchain4j-pgvector、langchain4j-milvus 等模块检索时用embed(EmbeddingRequest.builder().input(query).inputType(EmbeddingInputType.QUERY).build())生成查询向量配合DOCUMENT入库向量做相似度检索。关于请求/响应 API 与多模态用法的更多通用说明可参考官方教程 Embedding Model 中的 embedding-model 章节。十一、参考资源仓库内官方集成文档voyage-ai.md核心实现VoyageAiEmbeddingModel.java模型与维度定义VoyageAiEmbeddingModelName.javaHTTP 客户端封装VoyageAiClient.java多模态请求模型MultimodalEmbeddingRequest.java实时集成测试需VOYAGE_API_KEYVoyageAiEmbeddingModelIT.java多模态路由单元测试VoyageAiMultimodalRoutingTest.java模块依赖定义langchain4j-voyage-ai/pom.xml【免费下载链接】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），仅供参考