LangChain4j 集成 Jina Embedding 模型实战指南文本/多模态嵌入、query/passage 非对称检索与监听器配置【免费下载链接】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/langchain4jLangChain4j 的langchain4j-jina集成模块为 JVM 开发者提供了访问 Jina Embeddings API 的统一入口通过JinaEmbeddingModel一个类即可完成文本嵌入、多模态文本图片嵌入、面向检索的非对称 query/passage 编码以及嵌入请求监听等能力。本文基于仓库中的官方集成文档与源码实现完整讲解依赖引入、Builder 参数、多模态与输入类型task的自动检测机制、RAG 场景接入方式并给出可直接复制运行的 Java 示例。模块概览langchain4j-jinalangchain4j-jina是 LangChain4j 官方提供的一个独立 Maven 模块位于仓库 langchain4j-jina 目录下。其核心公开 API 只有一个类JinaEmbeddingModel位于 JinaEmbeddingModel.java它实现了 LangChain4j 核心模块中的EmbeddingModel接口dev.langchain4j.model.embedding.EmbeddingModel因此可以无缝用于 RAG 流水线、EmbeddingStore写入与检索等场景。从模块的 pom.xml 可以看到它仅依赖langchain4j-core与langchain4j-http-client运行时默认携带langchain4j-http-client-jdk作为 HTTP 客户端实现模块轻量、无外部服务端依赖只有调用 Jina API 时需要网络与 API Key。引入 Maven 依赖在项目的pom.xml中添加如下依赖即可开始使用dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-jina/artifactId version1.20.0-beta30/version /dependency说明当前仓库快照版本为1.21.0-beta31-SNAPSHOT见 langchain4j-jina/pom.xml正式发布版以 Maven Central 上最新的稳定版本为准。由于该模块依赖langchain4j-core建议通过 LangChain4j 官方 BOMlangchain4j-bom统一管理版本避免核心库与集成模块版本不一致。构建 JinaEmbeddingModelBuilder 全参数解析JinaEmbeddingModel通过流式 Builder 构建源码见 JinaEmbeddingModel.java最小配置只需要apiKey和modelNameimport dev.langchain4j.model.embedding.EmbeddingModel; import dev.langchain4j.model.jina.JinaEmbeddingModel; EmbeddingModel model JinaEmbeddingModel.builder() .apiKey(System.getenv(JINA_API_KEY)) .modelName(jina-embeddings-v3) .build();Builder 支持的全部配置项及其默认值如下表默认值均来自源码构造函数配置项类型默认值说明apiKeyString无必填Jina API Key可通过环境变量注入modelNameString无必填模型名称如jina-embeddings-v3、jina-embeddings-v4、jina-clip-v2baseUrlStringhttps://api.jina.ai/Jina API 服务地址一般无需修改见源码DEFAULT_BASE_URLtimeoutDuration60 秒HTTP 请求超时时间maxRetriesInteger2失败自动重试次数配合RetryUtils.withRetryMappingExceptions实现lateChunkingBooleanfalse是否启用 Jina 的 late chunking 特性见下文logRequestsBooleanfalse是否记录请求日志logResponsesBooleanfalse是否记录响应日志嵌入向量数据量大测试代码中特意建议关闭loggerorg.slf4j.Logger默认 Logger自定义请求/响应日志的 LoggerhttpClientBuilderHttpClientBuilder默认自定义底层 HTTP 客户端超时、代理等精细控制listenersListEmbeddingModelListener空列表嵌入模型监听器见监听器一节其中lateChunking是 Jina 的特色参数。仓库测试 JinaEmbeddingModelIT.java 验证了开启lateChunking(true)后对同一批文本片段产生的向量与关闭时显著不同余弦相似度数值、token 统计均发生变化说明该参数会实质影响嵌入结果适合对整篇长文档先整体编码、再按块检索的场景。文本嵌入embed 与 embedAll单条文本嵌入import dev.langchain4j.model.output.Response; import dev.langchain4j.data.embedding.Embedding; ResponseEmbedding response model.embed(hello); Embedding embedding response.content(); System.out.println(维度: embedding.dimension()); // jina-embeddings-v3 为 1024 System.out.println(Token 使用: response.tokenUsage()); // totalTokenCount 4批量文本嵌入import dev.langchain4j.data.segment.TextSegment; import java.util.List; ResponseListEmbedding response model.embedAll(List.of( TextSegment.from(hello), TextSegment.from(hi), TextSegment.from(there)));从 JinaEmbeddingModelIT.java 的断言可以确认以下实现事实jina-embeddings-v3返回的向量维度为1024每个输入项对应一个嵌入批量输入返回结果顺序与输入一致语义相近的文本hello / hi余弦相似度大于 0.85关闭 late chunking 时或大于 0.9开启时TokenUsage中outputTokenCount恒为 0totalTokenCount等于输入 token 数源码 JinaEmbeddingModel.java 将 Jina 响应的usage.promptTokens或usage.totalTokens映射为 LangChain4j 的输入 token 数。底层请求/响应结构文本嵌入走JinaEmbeddingRequest见 JinaEmbeddingRequest.java请求体包含四个字段model、task可选见下文输入类型、lateChunking、input字符串数组。响应JinaEmbeddingResponse则包含model、data嵌入列表与usagepromptTokens/totalTokens由 JinaEmbeddingModel.doEmbed 统一映射为 LangChain4j 的EmbeddingResponse。多模态嵌入文本与图片langchain4j-jina支持多模态嵌入但仅限特定模型。源码中的模型能力自动检测逻辑如下见 JinaEmbeddingModel.javaprivate static boolean isMultimodalModel(String modelName) { return modelName ! null (modelName.contains(clip) || modelName.contains(embeddings-v4)); }即模型名包含clip如jina-clip-v2或embeddings-v4如jina-embeddings-v4时supportedContentTypes()返回TEXT与IMAGE两种内容类型其余模型如jina-embeddings-v3仅支持文本。多模态请求通过JinaMultimodalEmbeddingRequest发送见 JinaMultimodalEmbeddingRequest.java每个输入项只能是单个文本或单张图片JinaMultimodalInput.text(...)/JinaMultimodalInput.image(...)。重要限制Jina 不融合交错图文与部分多模态模型不同Jina 每个输入项只嵌入一种模态不会把一段文本和一张图片融合进同一个向量。源码 toMultimodalInput 明确做了两处校验并抛出UnsupportedFeatureException一个输入项中出现多张图片 → Jina embeds one image per input每输入仅一张图片同一输入项中同时出现文本和图片 → Jina embeds a single text or image per input; interleaved textimage is not supported不支持交错图文。因此向EmbeddingRequest传输入时每个输入项只能是单独的TextContent或单独的ImageContent。图片支持两种形式URLImageContent.from(url)直接传图片 URLBase64源码会将 base64 数据编码为data:mimeType;base64,data形式的 data URI 发送mimeType 默认image/png。使用方式示例通过EmbeddingRequest显式构造多模态输入import dev.langchain4j.model.embedding.EmbeddingModel; import dev.langchain4j.model.embedding.request.EmbeddingRequest; import dev.langchain4j.model.embedding.request.EmbeddingInput; import dev.langchain4j.data.message.ImageContent; import dev.langchain4j.data.message.TextContent; import dev.langchain4j.model.output.Response; import dev.langchain4j.data.embedding.Embedding; EmbeddingModel multimodalModel JinaEmbeddingModel.builder() .apiKey(System.getenv(JINA_API_KEY)) .modelName(jina-clip-v2) .build(); // 每个输入只放一个 TextContent 或一个 ImageContent EmbeddingRequest request EmbeddingRequest.builder() .input(TextContent.from(A red car on the highway)) .input(ImageContent.from(https://example.com/car.jpg)) // URL 形式 .input(ImageContent.from(base64Bytes, image/jpeg)) // base64 形式 .build(); ResponseEmbedding response multimodalModel.embed(request);关于 LangChain4j 的请求/响应 API 与多模态用法的完整说明可参考仓库教程文档 rag.md。输入类型Input Typequery 与 document 非对称编码这是 Jina 提升检索质量的关键能力。jina-embeddings-v3、jina-embeddings-v4、jina-embeddings-v5这几个模型会把搜索查询和被检索的文档用不同的方式编码即非对称编码canonical RAG 中的 query vs passage通常能显著改善检索效果。能力自动检测源码 isTaskAwareModel 按模型名自动判断是否支持输入类型参数private static boolean isTaskAwareModel(String modelName) { return modelName ! null (modelName.contains(embeddings-v3) || modelName.contains(embeddings-v4) || modelName.contains(embeddings-v5)); }支持的模型jina-embeddings-v3 / v4 / v5supportedParameters()返回INPUT_TYPE不支持的模型如jina-clip-v2会直接拒绝该参数而不是静默忽略——这是supportedParameters()声明机制的作用调用方可以在发送前通过能力探测避免请求失败。枚举值与 Jina task 的映射LangChain4j 核心定义了统一的EmbeddingInputType枚举见 EmbeddingInputType.java自 1.18.0 引入标注为Experimental仅包含两个值QUERY搜索查询与DOCUMENT待索引检索的文档/段落。JinaEmbeddingModel通过 toJinaTask 将其映射为 Jina API 的task参数EmbeddingInputTypeJina task 值用途QUERYretrieval.query编码查询侧文本DOCUMENTretrieval.passage编码文档/段落侧文本未设置null省略 task 字段由 Jina 应用其默认行为在 EmbeddingRequest 中按调用设置import dev.langchain4j.model.embedding.request.EmbeddingInputType; // 文档侧写入 EmbeddingStore 时标记为 DOCUMENT EmbeddingRequest docRequest EmbeddingRequest.builder() .input(LangChain4j is a Java library for LLM-powered applications.) .inputType(EmbeddingInputType.DOCUMENT) .build(); ResponseEmbedding docResponse model.embed(docRequest); // 查询侧检索时标记为 QUERY EmbeddingRequest queryRequest EmbeddingRequest.builder() .input(Java LLM library) .inputType(EmbeddingInputType.QUERY) .build(); ResponseEmbedding queryResponse model.embed(queryRequest);在 RAG 检索器中设置如果使用 LangChain4j 的EmbeddingStoreContentRetriever做 RAG 检索可以通过embeddingInputType(...)直接配置该配置项定义于 EmbeddingStoreContentRetriever.javaimport dev.langchain4j.rag.content.retriever.EmbeddingStoreContentRetriever; import dev.langchain4j.model.embedding.request.EmbeddingInputType; EmbeddingStoreContentRetriever retriever EmbeddingStoreContentRetriever.builder() .embeddingStore(embeddingStore) .embeddingModel(model) .embeddingInputType(EmbeddingInputType.QUERY) // 检索查询按 QUERY 编码 .maxResults(5) .build();测试验证仓库中的公共嵌入测试基类AbstractEmbeddingModelIT包含should_embed_query_and_document_differently用例它通过 JinaV3EmbeddingModelIT.java 在jina-embeddings-v3上实际运行验证同一文本作为 QUERY 与作为 DOCUMENT 编码会得到不同向量。同时该测试类明确标注了两个能力边界supportsImageInput() falsejina-embeddings-v3纯文本多模态需用jina-clip-v2/jina-embeddings-v4supportsDimensionsParameter() falseJinaEmbeddingModel目前尚未映射 Jina 的 Matryoshkadimensions参数即暂不支持在请求中自定义输出维度。监听器ListenersJinaEmbeddingModel支持通过 Builder 配置EmbeddingModelListener用于观测嵌入请求的发起、成功与失败事件import dev.langchain4j.model.embedding.listener.EmbeddingModelListener; import java.util.List; EmbeddingModel model JinaEmbeddingModel.builder() .apiKey(System.getenv(JINA_API_KEY)) .modelName(jina-embeddings-v3) .listeners(List.of(myListener)) .build();从 JinaV3EmbeddingModelIT.java 可以看到监听器在成功请求与失败请求使用无效 Key、maxRetries(0)关闭重试两种路径下都会被触发可用于指标采集、日志记录或链路追踪。监听器列表在构造时经copy(builder.listeners)保存模型实例构建后不可变更。完整可运行示例下面把以上能力整合为一个完整的、可直接运行的 Java 示例需要环境变量JINA_API_KEYimport dev.langchain4j.data.embedding.Embedding; import dev.langchain4j.data.segment.TextSegment; import dev.langchain4j.model.embedding.EmbeddingModel; import dev.langchain4j.model.embedding.request.EmbeddingInputType; import dev.langchain4j.model.embedding.request.EmbeddingRequest; import dev.langchain4j.model.jina.JinaEmbeddingModel; import dev.langchain4j.model.output.Response; import java.util.List; public class JinaEmbeddingExample { public static void main(String[] args) { // 1) 文本嵌入模型jina-embeddings-v3text-only、支持 input type EmbeddingModel textModel JinaEmbeddingModel.builder() .apiKey(System.getenv(JINA_API_KEY)) .modelName(jina-embeddings-v3) .maxRetries(2) .timeout(java.time.Duration.ofSeconds(60)) .logRequests(true) .logResponses(false) // 嵌入向量很大避免日志爆炸 .build(); // 2) 批量文本嵌入写入 EmbeddingStore 的文档侧 ResponseListEmbedding docResponse textModel.embed( EmbeddingRequest.builder() .inputs(List.of( TextSegment.from(LangChain4j makes RAG easy in Java.), TextSegment.from(Jina embeddings support query/passage asymmetry.))) .inputType(EmbeddingInputType.DOCUMENT) .build()); System.out.println(文档嵌入数量: docResponse.content().size()); System.out.println(向量维度: docResponse.content().get(0).dimension()); // 3) 查询侧嵌入检索时使用 QUERY 类型 ResponseEmbedding queryResponse textModel.embed( EmbeddingRequest.builder() .input(Java RAG framework) .inputType(EmbeddingInputType.QUERY) .build()); System.out.println(查询向量维度: queryResponse.content().dimension()); System.out.println(Token 使用: queryResponse.tokenUsage()); // 4) 多模态嵌入jina-clip-v2 / jina-embeddings-v4支持文本与图片 EmbeddingModel multimodalModel JinaEmbeddingModel.builder() .apiKey(System.getenv(JINA_API_KEY)) .modelName(jina-clip-v2) .build(); ResponseEmbedding imageResponse multimodalModel.embed( EmbeddingRequest.builder() .input(dev.langchain4j.data.message.ImageContent.from(https://example.com/car.jpg)) .build()); System.out.println(图片嵌入维度: imageResponse.content().dimension()); } }使用注意事项与边界综合文档与源码使用JinaEmbeddingModel时有几点需要特别留意多模态不融合交错图文每个输入项只能是一个TextContent或一个ImageContent混用会抛UnsupportedFeatureException每输入最多一张图片输入类型的能力边界只有jina-embeddings-v3/v4/v5接受INPUT_TYPE参数jina-clip-v2等模型会拒绝该参数建议依赖supportedParameters()能力探测而不是硬编码维度参数暂未映射Jina 的 Matryoshkadimensions参数尚未在JinaEmbeddingModel中实现见 JinaV3EmbeddingModelIT.java因此输出维度由模型决定如jina-embeddings-v3为 1024Token 统计口径outputTokenCount恒为 0总 token 数以 Jina 返回的 prompt/total tokens 为准集成测试中还注释了 Jina 侧输入 token 统计疑似存在偏差的观察见 JinaEmbeddingModelIT.java自定义 HTTP 客户端如需代理、TLS 等精细控制可通过httpClientBuilder(...)注入自定义的HttpClientBuilder。参考与深入阅读集成文档原文jina.md核心实现JinaEmbeddingModel.java请求/响应 DTOinternal/apiHTTP 客户端封装JinaClient.java集成测试JinaEmbeddingModelIT.java、JinaV3EmbeddingModelIT.javaRAG 教程请求/响应 API 与多模态用法rag.md核心枚举与请求模型EmbeddingInputType.java、EmbeddingRequest.java【免费下载链接】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），仅供参考 LangChain4j 集成 Jina Embedding 模型实战指南：文本/多模态嵌入、query/passage 非对称检索与监听器配置
LangChain4j 集成 Jina Embedding 模型实战指南文本/多模态嵌入、query/passage 非对称检索与监听器配置【免费下载链接】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/langchain4jLangChain4j 的langchain4j-jina集成模块为 JVM 开发者提供了访问 Jina Embeddings API 的统一入口通过JinaEmbeddingModel一个类即可完成文本嵌入、多模态文本图片嵌入、面向检索的非对称 query/passage 编码以及嵌入请求监听等能力。本文基于仓库中的官方集成文档与源码实现完整讲解依赖引入、Builder 参数、多模态与输入类型task的自动检测机制、RAG 场景接入方式并给出可直接复制运行的 Java 示例。模块概览langchain4j-jinalangchain4j-jina是 LangChain4j 官方提供的一个独立 Maven 模块位于仓库 langchain4j-jina 目录下。其核心公开 API 只有一个类JinaEmbeddingModel位于 JinaEmbeddingModel.java它实现了 LangChain4j 核心模块中的EmbeddingModel接口dev.langchain4j.model.embedding.EmbeddingModel因此可以无缝用于 RAG 流水线、EmbeddingStore写入与检索等场景。从模块的 pom.xml 可以看到它仅依赖langchain4j-core与langchain4j-http-client运行时默认携带langchain4j-http-client-jdk作为 HTTP 客户端实现模块轻量、无外部服务端依赖只有调用 Jina API 时需要网络与 API Key。引入 Maven 依赖在项目的pom.xml中添加如下依赖即可开始使用dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-jina/artifactId version1.20.0-beta30/version /dependency说明当前仓库快照版本为1.21.0-beta31-SNAPSHOT见 langchain4j-jina/pom.xml正式发布版以 Maven Central 上最新的稳定版本为准。由于该模块依赖langchain4j-core建议通过 LangChain4j 官方 BOMlangchain4j-bom统一管理版本避免核心库与集成模块版本不一致。构建 JinaEmbeddingModelBuilder 全参数解析JinaEmbeddingModel通过流式 Builder 构建源码见 JinaEmbeddingModel.java最小配置只需要apiKey和modelNameimport dev.langchain4j.model.embedding.EmbeddingModel; import dev.langchain4j.model.jina.JinaEmbeddingModel; EmbeddingModel model JinaEmbeddingModel.builder() .apiKey(System.getenv(JINA_API_KEY)) .modelName(jina-embeddings-v3) .build();Builder 支持的全部配置项及其默认值如下表默认值均来自源码构造函数配置项类型默认值说明apiKeyString无必填Jina API Key可通过环境变量注入modelNameString无必填模型名称如jina-embeddings-v3、jina-embeddings-v4、jina-clip-v2baseUrlStringhttps://api.jina.ai/Jina API 服务地址一般无需修改见源码DEFAULT_BASE_URLtimeoutDuration60 秒HTTP 请求超时时间maxRetriesInteger2失败自动重试次数配合RetryUtils.withRetryMappingExceptions实现lateChunkingBooleanfalse是否启用 Jina 的 late chunking 特性见下文logRequestsBooleanfalse是否记录请求日志logResponsesBooleanfalse是否记录响应日志嵌入向量数据量大测试代码中特意建议关闭loggerorg.slf4j.Logger默认 Logger自定义请求/响应日志的 LoggerhttpClientBuilderHttpClientBuilder默认自定义底层 HTTP 客户端超时、代理等精细控制listenersListEmbeddingModelListener空列表嵌入模型监听器见监听器一节其中lateChunking是 Jina 的特色参数。仓库测试 JinaEmbeddingModelIT.java 验证了开启lateChunking(true)后对同一批文本片段产生的向量与关闭时显著不同余弦相似度数值、token 统计均发生变化说明该参数会实质影响嵌入结果适合对整篇长文档先整体编码、再按块检索的场景。文本嵌入embed 与 embedAll单条文本嵌入import dev.langchain4j.model.output.Response; import dev.langchain4j.data.embedding.Embedding; ResponseEmbedding response model.embed(hello); Embedding embedding response.content(); System.out.println(维度: embedding.dimension()); // jina-embeddings-v3 为 1024 System.out.println(Token 使用: response.tokenUsage()); // totalTokenCount 4批量文本嵌入import dev.langchain4j.data.segment.TextSegment; import java.util.List; ResponseListEmbedding response model.embedAll(List.of( TextSegment.from(hello), TextSegment.from(hi), TextSegment.from(there)));从 JinaEmbeddingModelIT.java 的断言可以确认以下实现事实jina-embeddings-v3返回的向量维度为1024每个输入项对应一个嵌入批量输入返回结果顺序与输入一致语义相近的文本hello / hi余弦相似度大于 0.85关闭 late chunking 时或大于 0.9开启时TokenUsage中outputTokenCount恒为 0totalTokenCount等于输入 token 数源码 JinaEmbeddingModel.java 将 Jina 响应的usage.promptTokens或usage.totalTokens映射为 LangChain4j 的输入 token 数。底层请求/响应结构文本嵌入走JinaEmbeddingRequest见 JinaEmbeddingRequest.java请求体包含四个字段model、task可选见下文输入类型、lateChunking、input字符串数组。响应JinaEmbeddingResponse则包含model、data嵌入列表与usagepromptTokens/totalTokens由 JinaEmbeddingModel.doEmbed 统一映射为 LangChain4j 的EmbeddingResponse。多模态嵌入文本与图片langchain4j-jina支持多模态嵌入但仅限特定模型。源码中的模型能力自动检测逻辑如下见 JinaEmbeddingModel.javaprivate static boolean isMultimodalModel(String modelName) { return modelName ! null (modelName.contains(clip) || modelName.contains(embeddings-v4)); }即模型名包含clip如jina-clip-v2或embeddings-v4如jina-embeddings-v4时supportedContentTypes()返回TEXT与IMAGE两种内容类型其余模型如jina-embeddings-v3仅支持文本。多模态请求通过JinaMultimodalEmbeddingRequest发送见 JinaMultimodalEmbeddingRequest.java每个输入项只能是单个文本或单张图片JinaMultimodalInput.text(...)/JinaMultimodalInput.image(...)。重要限制Jina 不融合交错图文与部分多模态模型不同Jina 每个输入项只嵌入一种模态不会把一段文本和一张图片融合进同一个向量。源码 toMultimodalInput 明确做了两处校验并抛出UnsupportedFeatureException一个输入项中出现多张图片 → Jina embeds one image per input每输入仅一张图片同一输入项中同时出现文本和图片 → Jina embeds a single text or image per input; interleaved textimage is not supported不支持交错图文。因此向EmbeddingRequest传输入时每个输入项只能是单独的TextContent或单独的ImageContent。图片支持两种形式URLImageContent.from(url)直接传图片 URLBase64源码会将 base64 数据编码为data:mimeType;base64,data形式的 data URI 发送mimeType 默认image/png。使用方式示例通过EmbeddingRequest显式构造多模态输入import dev.langchain4j.model.embedding.EmbeddingModel; import dev.langchain4j.model.embedding.request.EmbeddingRequest; import dev.langchain4j.model.embedding.request.EmbeddingInput; import dev.langchain4j.data.message.ImageContent; import dev.langchain4j.data.message.TextContent; import dev.langchain4j.model.output.Response; import dev.langchain4j.data.embedding.Embedding; EmbeddingModel multimodalModel JinaEmbeddingModel.builder() .apiKey(System.getenv(JINA_API_KEY)) .modelName(jina-clip-v2) .build(); // 每个输入只放一个 TextContent 或一个 ImageContent EmbeddingRequest request EmbeddingRequest.builder() .input(TextContent.from(A red car on the highway)) .input(ImageContent.from(https://example.com/car.jpg)) // URL 形式 .input(ImageContent.from(base64Bytes, image/jpeg)) // base64 形式 .build(); ResponseEmbedding response multimodalModel.embed(request);关于 LangChain4j 的请求/响应 API 与多模态用法的完整说明可参考仓库教程文档 rag.md。输入类型Input Typequery 与 document 非对称编码这是 Jina 提升检索质量的关键能力。jina-embeddings-v3、jina-embeddings-v4、jina-embeddings-v5这几个模型会把搜索查询和被检索的文档用不同的方式编码即非对称编码canonical RAG 中的 query vs passage通常能显著改善检索效果。能力自动检测源码 isTaskAwareModel 按模型名自动判断是否支持输入类型参数private static boolean isTaskAwareModel(String modelName) { return modelName ! null (modelName.contains(embeddings-v3) || modelName.contains(embeddings-v4) || modelName.contains(embeddings-v5)); }支持的模型jina-embeddings-v3 / v4 / v5supportedParameters()返回INPUT_TYPE不支持的模型如jina-clip-v2会直接拒绝该参数而不是静默忽略——这是supportedParameters()声明机制的作用调用方可以在发送前通过能力探测避免请求失败。枚举值与 Jina task 的映射LangChain4j 核心定义了统一的EmbeddingInputType枚举见 EmbeddingInputType.java自 1.18.0 引入标注为Experimental仅包含两个值QUERY搜索查询与DOCUMENT待索引检索的文档/段落。JinaEmbeddingModel通过 toJinaTask 将其映射为 Jina API 的task参数EmbeddingInputTypeJina task 值用途QUERYretrieval.query编码查询侧文本DOCUMENTretrieval.passage编码文档/段落侧文本未设置null省略 task 字段由 Jina 应用其默认行为在 EmbeddingRequest 中按调用设置import dev.langchain4j.model.embedding.request.EmbeddingInputType; // 文档侧写入 EmbeddingStore 时标记为 DOCUMENT EmbeddingRequest docRequest EmbeddingRequest.builder() .input(LangChain4j is a Java library for LLM-powered applications.) .inputType(EmbeddingInputType.DOCUMENT) .build(); ResponseEmbedding docResponse model.embed(docRequest); // 查询侧检索时标记为 QUERY EmbeddingRequest queryRequest EmbeddingRequest.builder() .input(Java LLM library) .inputType(EmbeddingInputType.QUERY) .build(); ResponseEmbedding queryResponse model.embed(queryRequest);在 RAG 检索器中设置如果使用 LangChain4j 的EmbeddingStoreContentRetriever做 RAG 检索可以通过embeddingInputType(...)直接配置该配置项定义于 EmbeddingStoreContentRetriever.javaimport dev.langchain4j.rag.content.retriever.EmbeddingStoreContentRetriever; import dev.langchain4j.model.embedding.request.EmbeddingInputType; EmbeddingStoreContentRetriever retriever EmbeddingStoreContentRetriever.builder() .embeddingStore(embeddingStore) .embeddingModel(model) .embeddingInputType(EmbeddingInputType.QUERY) // 检索查询按 QUERY 编码 .maxResults(5) .build();测试验证仓库中的公共嵌入测试基类AbstractEmbeddingModelIT包含should_embed_query_and_document_differently用例它通过 JinaV3EmbeddingModelIT.java 在jina-embeddings-v3上实际运行验证同一文本作为 QUERY 与作为 DOCUMENT 编码会得到不同向量。同时该测试类明确标注了两个能力边界supportsImageInput() falsejina-embeddings-v3纯文本多模态需用jina-clip-v2/jina-embeddings-v4supportsDimensionsParameter() falseJinaEmbeddingModel目前尚未映射 Jina 的 Matryoshkadimensions参数即暂不支持在请求中自定义输出维度。监听器ListenersJinaEmbeddingModel支持通过 Builder 配置EmbeddingModelListener用于观测嵌入请求的发起、成功与失败事件import dev.langchain4j.model.embedding.listener.EmbeddingModelListener; import java.util.List; EmbeddingModel model JinaEmbeddingModel.builder() .apiKey(System.getenv(JINA_API_KEY)) .modelName(jina-embeddings-v3) .listeners(List.of(myListener)) .build();从 JinaV3EmbeddingModelIT.java 可以看到监听器在成功请求与失败请求使用无效 Key、maxRetries(0)关闭重试两种路径下都会被触发可用于指标采集、日志记录或链路追踪。监听器列表在构造时经copy(builder.listeners)保存模型实例构建后不可变更。完整可运行示例下面把以上能力整合为一个完整的、可直接运行的 Java 示例需要环境变量JINA_API_KEYimport dev.langchain4j.data.embedding.Embedding; import dev.langchain4j.data.segment.TextSegment; import dev.langchain4j.model.embedding.EmbeddingModel; import dev.langchain4j.model.embedding.request.EmbeddingInputType; import dev.langchain4j.model.embedding.request.EmbeddingRequest; import dev.langchain4j.model.jina.JinaEmbeddingModel; import dev.langchain4j.model.output.Response; import java.util.List; public class JinaEmbeddingExample { public static void main(String[] args) { // 1) 文本嵌入模型jina-embeddings-v3text-only、支持 input type EmbeddingModel textModel JinaEmbeddingModel.builder() .apiKey(System.getenv(JINA_API_KEY)) .modelName(jina-embeddings-v3) .maxRetries(2) .timeout(java.time.Duration.ofSeconds(60)) .logRequests(true) .logResponses(false) // 嵌入向量很大避免日志爆炸 .build(); // 2) 批量文本嵌入写入 EmbeddingStore 的文档侧 ResponseListEmbedding docResponse textModel.embed( EmbeddingRequest.builder() .inputs(List.of( TextSegment.from(LangChain4j makes RAG easy in Java.), TextSegment.from(Jina embeddings support query/passage asymmetry.))) .inputType(EmbeddingInputType.DOCUMENT) .build()); System.out.println(文档嵌入数量: docResponse.content().size()); System.out.println(向量维度: docResponse.content().get(0).dimension()); // 3) 查询侧嵌入检索时使用 QUERY 类型 ResponseEmbedding queryResponse textModel.embed( EmbeddingRequest.builder() .input(Java RAG framework) .inputType(EmbeddingInputType.QUERY) .build()); System.out.println(查询向量维度: queryResponse.content().dimension()); System.out.println(Token 使用: queryResponse.tokenUsage()); // 4) 多模态嵌入jina-clip-v2 / jina-embeddings-v4支持文本与图片 EmbeddingModel multimodalModel JinaEmbeddingModel.builder() .apiKey(System.getenv(JINA_API_KEY)) .modelName(jina-clip-v2) .build(); ResponseEmbedding imageResponse multimodalModel.embed( EmbeddingRequest.builder() .input(dev.langchain4j.data.message.ImageContent.from(https://example.com/car.jpg)) .build()); System.out.println(图片嵌入维度: imageResponse.content().dimension()); } }使用注意事项与边界综合文档与源码使用JinaEmbeddingModel时有几点需要特别留意多模态不融合交错图文每个输入项只能是一个TextContent或一个ImageContent混用会抛UnsupportedFeatureException每输入最多一张图片输入类型的能力边界只有jina-embeddings-v3/v4/v5接受INPUT_TYPE参数jina-clip-v2等模型会拒绝该参数建议依赖supportedParameters()能力探测而不是硬编码维度参数暂未映射Jina 的 Matryoshkadimensions参数尚未在JinaEmbeddingModel中实现见 JinaV3EmbeddingModelIT.java因此输出维度由模型决定如jina-embeddings-v3为 1024Token 统计口径outputTokenCount恒为 0总 token 数以 Jina 返回的 prompt/total tokens 为准集成测试中还注释了 Jina 侧输入 token 统计疑似存在偏差的观察见 JinaEmbeddingModelIT.java自定义 HTTP 客户端如需代理、TLS 等精细控制可通过httpClientBuilder(...)注入自定义的HttpClientBuilder。参考与深入阅读集成文档原文jina.md核心实现JinaEmbeddingModel.java请求/响应 DTOinternal/apiHTTP 客户端封装JinaClient.java集成测试JinaEmbeddingModelIT.java、JinaV3EmbeddingModelIT.javaRAG 教程请求/响应 API 与多模态用法rag.md核心枚举与请求模型EmbeddingInputType.java、EmbeddingRequest.java【免费下载链接】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），仅供参考