Day 16 混合检索 — 字段/名词/配置速查手册本文档是 Day 16day16-hybrid-rag项目中所有字段名、配置项、实体 DTO、技术术语的集中索引。每项按英文名 / 中文名 / 解释三栏组织。一、实体 DTO1.1 HybridSearchResult — 检索结果字段类型中文名解释idString文档唯一标识PGVector 表中的embedding_idUUID 格式textString文档原文片段向量库中存储的文档文本内容metadataString元数据JSON 字符串含source、page、filename等附加信息scoredouble相关性分数[0, 1] 区间1 表示最相关。向量阶段是余弦相似度Reranker 阶段是 relevance_scoresourceString来源标识取值vector向量检索/keyword关键词检索/rrfRRF 融合/rerankReranker 精排1.2 ApiResultT — 统一 API 响应体字段类型中文名解释codeint状态码200 成功500 失败messageString提示信息成功时为success失败时为错误描述dataT响应数据泛型具体类型由接口决定静态工厂方法方法解释ApiResult.ok(data)创建成功响应code200, message“success”ApiResult.fail(message)创建失败响应code500, datanull二、配置项application.yml2.1 硅基流动 API 配置配置键类型中文名取值解释siliconflow.api-keyStringAPI 密钥sk-xxx...硅基流动平台认证密钥siliconflow.base-urlStringAPI 基础地址https://api.siliconflow.cn/v1兼容 OpenAI 接口格式siliconflow.model-nameString对话模型deepseek-ai/DeepSeek-V3用于普通对话和流式对话的大语言模型siliconflow.embedding-modelStringEmbedding 模型BAAI/bge-large-zh-v1.5将文本转为 1024 维向量的模型siliconflow.rerank-modelStringReranker 模型BAAI/bge-reranker-v2-m3Cross-Encoder 重排序模型2.2 数据库配置配置键类型中文名取值解释server.portint服务端口8088Spring Boot 嵌入式 Tomcat 监听端口spring.datasource.urlString数据库连接地址jdbc:postgresql://localhost:5432/aidbPostgreSQL 连接串spring.datasource.usernameString数据库用户名aispring.datasource.passwordString数据库密码passwordspring.datasource.driver-class-nameStringJDBC 驱动类org.postgresql.DriverPostgreSQL 驱动spring.datasource.hikari.maximum-pool-sizeint连接池最大连接数10HikariCP 配置spring.datasource.hikari.minimum-idleint连接池最小空闲连接5HikariCP 配置spring.datasource.hikari.idle-timeoutint空闲超时毫秒3000005 分钟超时空闲连接被回收spring.datasource.hikari.connection-timeoutint连接超时毫秒1000010 秒等待连接池的最大时间三、服务层常量与参数3.1 HybridSearchService 参数常量值中文名解释RRF_K60RRF 平滑常数Reciprocal Rank Fusion 的 k 值k 越大曲线越平坦排名差异影响越小RECALL_TOP20单路召回上限向量检索和关键词检索各自最多返回的条数FINAL_TOP5最终输出条数Reranker 精排后输出的文档数NGRAM_MIN2N-gram 最小长度中文单字无意义2 字起步NGRAM_MAX4N-gram 最大长度4-gram 已覆盖绝大多数中文词组NGRAM_TOP8N-gram 词条上限控制 SQL CASE WHEN 数量同时覆盖问句关键词3.2 HybridSearchService 方法方法名可见性中文名解释search(query, tableName)public混合检索入口执行完整三阶段流水线返回 Top-5vectorSearch(query, tableName)private向量检索PGVector余弦距离查询Top-20keywordSearch(query, tableName)private关键词检索N-gram ILIKE 模糊匹配Top-20cleanQuery(query)private查询清理去标点、英文、数字、停用单字generateNgrams(text)privateN-gram 生成滑动窗口 2-4 字去重取前 8 个rrfFusion(listA, listB)privateRRF 融合双路排名→RRF 分数→合并排序accumulateRrf(scores, list)privateRRF 累加逐条累加1/(k排名)executeQuery(sql, source)privateSQL 执行JDBC 查询 ResultSet→HybridSearchResult 映射embeddingToPgVector(vec)private向量转换ListFloat→ PGVector 字面量字符串nvl(s, def)private空值处理字符串为空时返回默认值truncate(s, max)private日志截断截断长字符串尾部加 “…”3.3 RerankService 方法方法名可见性中文名解释rerank(query, candidates, topN)public重排序入口调硅基流动 API失败时降级parseResponse(candidates, body)private响应解析JSON → RerankResponse DTO → HybridSearchResult 列表truncate(s, max)private日志截断同 HybridSearchService 的工具方法3.4 RerankService 内部 DTO类名字段类型中文名解释RerankResponseresultsListRerankResult重排结果列表API 返回的顶层对象RerankResultindexint索引0 起始对应请求中 documents 数组的位置RerankResultrelevanceScoredouble相关性分数Cross-Encoder 输出区间 [0, 1]四、API 端点4.1 GET /search — 纯检索参数类型必填默认值解释queryString✅—用户问题文本tableString❌day4_rag_storePGVector 表名返回ApiResultListHybridSearchResultTop-5 文档含score和source。4.2 GET /rag/chat — RAG 对话参数类型必填默认值解释messageString✅—用户问题文本tableString❌day4_rag_storePGVector 表名返回ApiResultMapString, Object含 4 个键query— 用户原始问题documents—HybridSearchResult数组prompt— 组装好的 RAG Prompthint— 使用提示文字五、ChatModelConfig Bean 定义Bean 名称类型中文名解释openAiChatModelOpenAiChatModel普通对话模型同步阻塞式temperature0.3超时 60s重试 2 次openAiStreamingChatModelOpenAiStreamingChatModel流式对话模型SSE 逐 Token 输出temperature0.3超时 60sopenAiEmbeddingModelEmbeddingModelEmbedding 模型文本 → 1024 维向量重试 2 次参数说明参数值解释temperature0.3温度系数越低输出越确定适合事实性问答timeout60s请求超时防止线程长期阻塞maxRetries2失败自动重试次数流式模型不设此值六、Maven 依赖清单groupIdartifactIdversion作用org.springframework.bootspring-boot-starter-parent3.4.3Spring Boot 父 POM统一版本管理org.springframework.bootspring-boot-starter-web(继承自 parent)MVC 嵌入式 Tomcat 10.1org.springframework.bootspring-boot-starter-jdbc(继承自 parent)JDBC HikariCP 连接池org.springframework.bootspring-boot-starter-test(继承自 parent)JUnit 5 Mockito 测试框架dev.langchain4jlangchain4j1.13.1LangChain4j 核心库dev.langchain4jlangchain4j-open-ai1.13.1OpenAI 兼容接口适配硅基流动用此dev.langchain4jlangchain4j-pgvector1.13.1-beta23PGVector 集成支持org.postgresqlpostgresql(继承自 parent)PostgreSQL JDBC 驱动org.projectlomboklombok(由 SB 3.4.3 管理)编译期注解Data/Builder/Slf4j 等org.apache.httpcomponentshttpclient4.5.14HTTP 客户端Reranker API 直调用com.github.ulisesbocchiojasypt-spring-boot-starter3.0.5配置文件加密七、SQL 表与列7.1 day4_rag_storePGVector 表列名类型解释embedding_idtext/uuid主键文档唯一标识texttext文档原文片段metadatatext/jsonb元数据 JSONsource, page, filename 等embeddingvector(1024)1024 维向量BGE-large-zh-v1.5 输出维度7.2 SQL 关键技术点SQL 写法解释embedding [...]::vectorPGVector 余弦距离运算符返回值 [0, 2]0 完全相同2 完全相反1 - (embedding ...)将余弦距离转为相似度0 不相关1 完全相同text ILIKE %关键词%PostgreSQL 不区分大小写的模糊匹配CASE WHEN ... THEN 1 ELSE 0 END条件打分命中关键词 1 分1.0 / (1 length(text) / 500.0)长度惩罚长文档得分打折短精确片段得分更高八、技术术语速查8.1 检索相关术语英文全称解释混合检索Hybrid Search向量语义检索 关键词精确匹配双路召回互补短板双路召回Dual Recall同时跑向量检索和关键词检索各自返回 Top-20RRFReciprocal Rank Fusion排名融合算法不看绝对值只看排名score Σ 1/(krank)RRF_KRRF Smoothing ConstantRRF 平滑常数k60 是 TREC 论文经典取值RerankerCross-Encoder Reranker联合编码问句文档的二次排序模型精度远高于双塔模型Cross-Encoder—将 (query, document) 成对输入通过自注意力交互打分双塔模型Bi-Encoder / Dual Encoder分别编码问句和文档再算余弦相似度速度快但精度低于 Cross-Encoderrelevance_score—Reranker 输出的相关性分数区间 [0, 1]越高越相关8.2 向量相关术语英文全称解释Embedding—将文本映射为高维向量的过程/结果向量检索Vector Search计算问句向量与文档向量的余弦距离按相似度排序PGVector—PostgreSQL 的向量扩展插件支持向量存储和相似度查询余弦距离Cosine Distance运算符返回值0完全相同2完全相反余弦相似度Cosine Similarity1 - 余弦距离1完全相同0不相关BGEBAAI General Embedding北京智源研究院BAAI发布的 Embedding/Reranker 模型系列bge-large-zh-v1.5—BGE 中文 Embedding 模型输出 1024 维向量bge-reranker-v2-m3—BGE 多语言 Cross-Encoder Reranker 模型8.3 关键词检索相关术语英文全称解释N-gram—滑动窗口将文本切为连续 n 个字符的片段如 2-gram、3-gramILIKE—PostgreSQL 的不区分大小写 LIKE用于模糊匹配CASE WHEN—SQL 条件表达式用于构建打分逻辑长度惩罚Length Penalty1/(1len/500)短精确片段得分更高停用词Stop Words检索中无意义的中文单字如的“了”“是”检索前过滤掉8.4 AI 平台相关术语解释硅基流动SiliconFlow国内 AI 模型服务商提供 OpenAI 兼容接口DeepSeek-V3深度求索大语言模型通过硅基流动调用BAAI北京智源人工智能研究院BGE 系列模型的发布方OpenAI 兼容接口硅基流动的 API 格式兼容 OpenAILangChain4j 的OpenAiChatModel可直接对接8.5 框架与中间件术语解释Spring Boot 3.4.3Java 企业级应用框架LangChain4j 1.13.1Java 版 LangChainLLM 应用开发框架HikariCPSpring Boot 默认 JDBC 连接池高性能Apache HttpClient 4.5.14直接调 Reranker API 用的 HTTP 客户端绕过 LangChain4j 限制LombokJava 编译期注解处理器版本由 SB 3.4.3 管理JacksonJSON 序列化/反序列化库Spring Boot 默认集成Tomcat 10.1Spring Boot 3.x 内置的 Servlet 容器8.6 容错与降级术语解释降级策略Reranker API 调用失败时不抛异常返回 RRF 融合后的原始结果优雅降级Graceful Degradation部分功能不可用时整体服务仍可用try-with-resourcesJava 7 语法自动关闭 Connection / PreparedStatement / ResultSet重试机制ChatModel 配maxRetries2覆盖网络抖动导致的瞬时失败九、项目目录结构速查day16-hybrid-rag/ ├── pom.xml # Maven 依赖管理JDK 17, SB 3.4.3, LC4j 1.13.1 ├── README.md # 项目文档 └── src/ ├── main/ │ ├── java/com/day16/demo/ │ │ ├── Day16Application.java # SpringBootApplication 启动入口 │ │ ├── config/ │ │ │ ├── ChatModelConfig.java # 3 个 Bean 定义 │ │ │ └── DataInitializer.java # 启动时自动向量化知识库文档 │ │ ├── controller/ │ │ │ └── SearchController.java # /search /rag/chat │ │ ├── core/ │ │ │ └── HybridSearchResult.java # 检索结果实体 │ │ ├── dto/ │ │ │ └── ApiResult.java # 统一响应体 │ │ └── rag/ │ │ ├── HybridSearchService.java # 三阶段编排 │ │ └── RerankService.java # Reranker API 调用 │ └── resources/ │ ├── application.yml # 配置端口/API Key/数据源 │ ├── schema.sql # 建表 DDL │ ├── data.sql # 示例 SQL │ ├── docs/ # 知识库种子文档 │ └── static/ │ └── index.html # 检索前端 └── test/ # 未使用十、三阶段流水线示意用户 Query │ ├──→ [阶段 1: 双路召回] │ ├── 向量检索Embedding → PGVector → 余弦相似度排序 → Top-20 │ └── 关键词检索cleanQuery → N-gram 2-4 → ILIKE 打分 → Top-20 │ ├──→ [阶段 2: RRF 融合] │ 公式score 1/(60向量排名) 1/(60关键词排名) │ 输出去重后的候选集 │ └──→ [阶段 3: Reranker 精排] POST /v1/rerank → Cross-Encoder 联合编码 → relevance_score 排序 → Top-5文档版本v1.1 | 更新日期2026-06-26 | 对应代码day16-hybrid-rag