LangChain4j OceanBase 向量存储集成实战：从相似度检索到混合检索的完整指南-北京尧图网络

LangChain4j OceanBase 向量存储集成实战从相似度检索到混合检索的完整指南【免费下载链接】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/langchain4jOceanBase 是国内广泛使用的分布式关系型数据库自 4.3.5 版本起原生支持向量检索能力。LangChain4j 通过社区集成模块langchain4j-community-oceanbase将 OceanBase 接入其统一的EmbeddingStore抽象使 Java 开发者可以在不修改业务代码的前提下直接利用 OceanBase 完成向量相似度检索、元数据过滤与向量全文混合检索。本文将基于 OceanBase 集成文档结合 LangChain4j 核心源码完整讲解依赖引入、构建配置、三种距离度量、过滤表达式与 RRF 混合检索原理帮助你快速在 RAG 应用中落地 OceanBase。集成概览OceanBase Embedding Store 是 LangChain4j 官方集成列表中的一项社区集成。在嵌入存储总览表中它被标记为支持存储元数据、按元数据过滤以及删除嵌入三项核心能力能力矩阵与主流向量数据库对齐。该集成对外只暴露一个核心类OceanBaseEmbeddingStore它实现了 LangChain4j 统一的EmbeddingStore接口。这意味着你可以像使用其他向量库一样通过EmbeddingSearchRequest/EmbeddingSearchResult等通用 API 完成写入与检索后续若需切换存储后端业务代码几乎无需改动。前置要求项要求OceanBase 数据库实例版本4.3.5 或更高该版本起提供向量数据类型与距离函数支持JDKJava 17 或更高Maven 依赖在pom.xml中引入社区集成模块dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-community-oceanbase/artifactId version${latest version here}/version /dependency注意这是一个社区集成模块不属于本仓库主模块你可能需要在项目配置中额外添加 langchain4j-community 仓库才能解析该依赖。快速上手构建与基础检索下面是一个完整的写入检索示例。它先用 ONNX 本地量化嵌入模型生成向量再向 OceanBase 写入带元数据的文本段最后执行相似度检索import dev.langchain4j.data.document.Metadata; import dev.langchain4j.data.embedding.Embedding; import dev.langchain4j.data.segment.TextSegment; import dev.langchain4j.model.embedding.EmbeddingModel; import dev.langchain4j.model.embedding.onnx.allminilml6v2q.AllMiniLmL6V2QuantizedEmbeddingModel; import dev.langchain4j.store.embedding.EmbeddingSearchRequest; import dev.langchain4j.store.embedding.EmbeddingSearchResult; import dev.langchain4j.store.embedding.oceanbase.OceanBaseEmbeddingStore; // 1. 初始化嵌入模型本地量化版 all-MiniLM-L6-v2输出 384 维向量 EmbeddingModel embeddingModel new AllMiniLmL6V2QuantizedEmbeddingModel(); // 2. 创建向量存储指向 OceanBase 数据库 OceanBaseEmbeddingStore embeddingStore OceanBaseEmbeddingStore.builder() .url(jdbc:oceanbase://127.0.0.1:2881/test) .user(roottest) .password(password) .tableName(embeddings) .dimension(384) .build(); // 3. 写入带元数据的文本段返回生成的 UUID 主键 String id embeddingStore.add( embeddingModel.embed(Java is a programming language).content(), TextSegment.from(Java is a programming language, Metadata.from(category, programming).put(language, Java)) ); // 4. 构造检索请求并执行 Embedding queryEmbedding embeddingModel.embed(programming language).content(); EmbeddingSearchResultTextSegment results embeddingStore.search( EmbeddingSearchRequest.builder() .queryEmbedding(queryEmbedding) .maxResults(10) .build() ); // 5. 处理结果 results.matches().forEach(match - { System.out.println(Score: match.score()); System.out.println(Text: match.embedded().text()); System.out.println(Metadata: match.embedded().metadata()); });其中dimension(384)必须与所选嵌入模型的输出维度一致上文使用的AllMiniLmL6V2QuantizedEmbeddingModel见 langchain4j-embeddings-all-minilm-l6-v2-q 模块输出 384 维向量若更换模型需同步调整该值。理解检索请求参数检索请求由EmbeddingSearchRequest承载源码见 EmbeddingSearchRequest.java从源码注释可以确认以下默认行为queryEmbedding必填作为相似度检索的参照向量maxResults可选默认3返回的最大结果条数minScore可选默认0只返回相似度得分 minScore的结果filter可选默认不过滤作用于元数据query可选字符串查询供支持混合检索的EmbeddingStore实现使用——这正是 OceanBase 混合检索的入口。高级配置自定义字段名与距离度量除基础参数外构建器还暴露了完整的自定义能力OceanBaseEmbeddingStore embeddingStore OceanBaseEmbeddingStore.builder() .url(jdbc:oceanbase://127.0.0.1:2881/test) .user(roottest) .password(password) .tableName(embeddings) .dimension(384) .metricType(cosine) // 可选值: cosine、l2、ip .retrieveEmbeddingsOnSearch(true) .idFieldName(id_field) .textFieldName(text_field) .metadataFieldName(metadata_field) .vectorFieldName(vector_field) .build();配置项说明metricType向量距离度量类型决定底层距离函数与得分换算公式详见下一节retrieveEmbeddingsOnSearch(true)检索时是否回传原始向量供上层二次使用idFieldName/textFieldName/metadataFieldName/vectorFieldName自定义表列名适用于与已有表结构对齐的场景。此外存储会自动完成建表与向量索引的创建无需手工 DDL启用混合检索后还会自动在文本列上创建全文索引见混合检索一节。距离度量与得分换算OceanBase 向量存储支持三种距离度量。底层距离值会在 SQL 层被自动换算为[0, 1] 区间的相关性得分1 表示最相关。三种度量在 SQL 中的换算公式如下详见 oceanbase.md 的 Implementation Details 一节度量配置值距离范围得分公式Cosine默认cosine[0, 2]score (2 - distance) / 2L2 / Euclideanl2或euclidean[0, ∞)score 1 / (1 distance)Inner Productinner_product或ip归一化后 [-1, 1]score (inner_product 1) / 2Cosine 距离默认适用场景文本嵌入、语义相似度检索。结果不受向量模长影响。OceanBase 的cosine_distance返回 [0, 2] 区间0表示方向完全一致1表示正交垂直2表示方向完全相反换算为得分score (2 - distance) / 2。.metricType(cosine) // 默认值文本嵌入推荐L2 距离欧几里得适用场景同时关注向量方向与模长幅度的场景。度量向量之间的直线距离范围 [0, ∞)换算为得分score 1 / (1 distance)距离越近得分越接近 1。.metricType(l2) // 或 euclidean内积距离适用场景已归一化的向量、对性能敏感的应用。度量向量点积对归一化向量范围为 [-1, 1]换算为得分score (inner_product 1) / 2。.metricType(inner_product) // 或 ip关于 OceanBase 原生向量距离函数的更底层语义可查阅 OceanBase 官方向量距离函数文档原文档引用的 Reference 链接。过滤机制OceanBase 向量存储支持两种过滤途径按元数据字段过滤以及按表列直接过滤。按元数据字段过滤元数据过滤使用 LangChain4j 核心模块提供的MetadataFilterBuilder源码见 MetadataFilterBuilder.java与逻辑组合算子构造过滤作用于Metadataimport dev.langchain4j.store.embedding.filter.MetadataFilterBuilder; import static dev.langchain4j.store.embedding.filter.MetadataFilterBuilder.metadataKey; // 单个元数据字段等值过滤 Filter filter metadataKey(category).isEqualTo(programming); // 多条件组合逻辑与 Filter filter new And( metadataKey(category).isEqualTo(programming), metadataKey(language).isEqualTo(Java) ); // IN 操作符多值匹配 Filter filter metadataKey(language).isIn(Java, Python, C); // 带过滤的检索 EmbeddingSearchResultTextSegment results embeddingStore.search( EmbeddingSearchRequest.builder() .queryEmbedding(queryEmbedding) .filter(filter) .maxResults(10) .build() );按表列过滤也可以直接对表列id、text、metadata、vector构造过滤条件此时使用Filter的具体实现类import dev.langchain4j.store.embedding.filter.comparison.IsIn; import dev.langchain4j.store.embedding.filter.comparison.ContainsString; import dev.langchain4j.store.embedding.filter.comparison.IsEqualTo; // 按 ID 列过滤 Filter filter new IsIn(id, List.of(id1, id2, id3)); // 按文本列过滤LIKE 包含匹配 Filter textFilter new ContainsString(text, programming); // 文本列精确匹配 Filter exactTextFilter new IsEqualTo(text, Java programming);注意按表列过滤时字段名不区分大小写但必须与FieldDefinition中定义的实际列名或以下公认别名一致id→ id 字段text或document→ text 字段metadata→ metadata 字段vector或embedding→ vector 字段支持的过滤操作操作说明isEqualTo等值比较isNotEqualTo不等比较isGreaterThan大于isGreaterThanOrEqualTo大于等于isLessThan小于isLessThanOrEqualTo小于等于isInIN 操作多值isNotInNOT IN 操作containsStringLIKE 模式匹配And/Or/Not逻辑与 / 或 / 非从 Filter.java 的源码注释可以进一步了解底层语义Filter以存储无关的方式表达如type documentation AND year 2020的过滤表达式由各EmbeddingStore实现将其映射为原生过滤语句元数据值可为Float/Double其中NaN不可与任何值比较只有isNotEqualTo和isNotIn能匹配到NaN。混合检索Hybrid Search混合检索同时执行向量相似度检索与全文检索再通过RRFReciprocal Rank Fusion倒数排名融合算法融合结果兼顾语义相关性与关键词精确匹配。开启混合检索OceanBaseEmbeddingStore embeddingStore OceanBaseEmbeddingStore.builder() .url(jdbc:oceanbase://127.0.0.1:2881/test) .user(roottest) .password(password) .tableName(embeddings) .dimension(384) .enableHybridSearch(true) // 开启混合检索 .build();开启后存储会自动在 text 字段上创建全文索引。执行混合检索混合检索需要同时提供查询向量与查询文本EmbeddingSearchResultTextSegment results embeddingStore.search( EmbeddingSearchRequest.builder() .queryEmbedding(queryEmbedding) // 向量嵌入用于相似度检索 .query(search text) // 文本查询用于全文检索 .maxResults(10) .build() );这里的query(String)方法正是EmbeddingSearchRequest为混合检索预留的入口见 EmbeddingSearchRequest.java 中关于 support hybrid search 的说明。混合检索的工作原理向量检索使用查询向量执行相似度检索全文检索使用MATCH AGAINST在 text 字段上执行全文检索结果融合使用 RRF 算法融合两类结果——融合公式score Σ(1 / (k rank))其中k 60每次检索返回的结果按名次贡献得分名次越靠前贡献越大最终按融合后的 RRF 得分归一化排序。收益更好的召回同时覆盖语义相似与精确关键词两种命中方式更高的精度RRF 在两类检索间取得平衡关键词处理更强对精确关键词的匹配能力优于纯向量检索。实现细节元数据处理元数据以JSON格式存储于数据库超过2^53 - 1的Long值会被自动序列化为字符串以避免精度丢失过滤同时支持直接列过滤与 JSON 元数据过滤两条路径。默认表结构未自定义字段名时嵌入表默认包含以下列列名类型说明idVARCHAR(36)主键存储由向量存储生成的 UUID 字符串vectorJSON以 JSON 数组存储嵌入向量textTEXT文本段内容metadataJSON以 JSON 存储元数据已知限制removeAll(Filter)与removeAll()暂不支持请改用removeAll(CollectionString ids)按表列过滤时字段名不区分大小写但必须匹配实际列名或公认别名。小结OceanBase 4.3.5 提供了原生向量检索能力而 LangChain4j 的OceanBaseEmbeddingStore将其封装为标准的EmbeddingStore实现让你在享受统一 API 无缝切换的同时还能获得 JSON 元数据、三种距离度量、SQL 级得分换算、强大的过滤表达式以及基于 RRF 的向量全文混合检索能力。如果你正在构建 Java 生态的 RAG 应用且团队已有 OceanBase 运维体系这是一个值得优先评估的落地选项。更多扩展阅读OceanBase 集成文档嵌入存储能力总览表EmbeddingSearchRequest 源码Filter 过滤接口源码MetadataFilterBuilder 源码【免费下载链接】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 OceanBase 向量存储集成实战：从相似度检索到混合检索的完整指南

相关推荐

真机Canvas导出失败？用剪贴板文案替代canvasToTempFilePath

SkyPilot 大规模图片语义搜索实战：CLIP + ChromaDB 全链路构建图像向量数据库

AutoMQ（Apache Kafka Docker 镜像）使用指南：默认配置、文件输入与环境变量三种启动方式全解

更多资讯

基于Django的多媒体资料管理系统：从模型设计到部署实践

QMK 固件开发实战：4pplet Waffling60 Rev B（atmega32u2 60% 键盘）配置解析与编译指南

speech-to-speech 的 LLM 后端 transformers、mlx-lm 与 OpenAI 兼容 API 怎么选？

pypdf 中的 PDF 动作（Actions）机制：PageTrigger、JavaScript 与页面附加动作字典实战解析

HTML打包EXE全攻略：制作免安装绿色版与踩坑指南

OpenCreator：视频翻译配音一键出片的本地开源AI工作台

今日更新

基于高阶循环谱的MPSK载波频率估计与MATLAB实现

MiniPdf方：.NET开源Office转PDF的高效解决方案

Solon AI v3.10：Java全栈智能体开发框架解析

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？