05.6.11.3 Spring AI 与 Java 生态集成
所属:全栈开发面试题库 / 05 数据库与存储 / 05.6 向量数据库与语义检索 / 05.6.11 向量检索工程化与生态集成
覆盖范围
- Spring AI 的 VectorStore 抽象与各向量库适配实现
- EmbeddingModel 配置、文档切分与 ETL 流水线
- RAG Advisor 与 ChatClient 结合、检索参数与过滤表达式
- 向量库连接配置、Bean 与 properties、多环境与凭据管理
- 事务边界、检索的非事务属性、线程池与异步模型
- 向量维度与模型一致性校验、多数据源路由、可观测与超时
- 依赖版本与冲突、增量更新、常见接入坑
集成链路主线
配置属性(endpoint / 凭据 / 模型)
↓ 构造 EmbeddingModel 与 VectorStore Bean
ETL:Reader → Transformer(切分)→ Writer(向量化入库)
在线:ChatClient + RAG Advisor → VectorStore 检索(filter / topK)
→ 上下文组装 → 模型生成
高频题速览
| 编号 | 题目 | 难度 | 频率 |
|---|---|---|---|
| 05.6.11.3-002 | VectorStore 接口核心方法 | 基础 | ★★★★★ |
| 05.6.11.3-007 | RAG Advisor 的作用与挂载位置 | 进阶 | ★★★★★ |
| 05.6.11.3-011 | 检索为什么不放在数据库事务里 | 高级 | ★★★★☆ |
| 05.6.11.3-015 | 向量维度与模型一致性校验 | 高级 | ★★★★★ |
| 05.6.11.3-017 | SearchRequest 的 filter 表达式 | 进阶 | ★★★★★ |
| 05.6.11.3-020 | 多 VectorStore 路由与按租户选择 | 高级 | ★★★★☆ |
| 05.6.11.3-023 | 批量入库与分批写入节奏 | 进阶 | ★★★★☆ |
| 05.6.11.3-034 | 多 VectorStore 注入歧义 | 高级 | ★★★★☆ |
| 05.6.11.3-036 | 维度不一致在写入期才暴露 | 进阶 | ★★★☆☆ |
| 05.6.11.3-048 | 一套 Spring AI RAG 接入清单 | 高级 | ★★★★★ |
05.6.11.3-001 Spring AI 在 Java 生态中的定位与抽象层是什么?
频率 ★★★☆☆ | 难度 基础
一句话结论
Spring AI 在 Spring 体系内提供模型调用、向量存储、文档处理与 RAG 编排的抽象,把不同大模型与向量库的差异收敛到统一接口,便于在 Spring 应用中装配与替换。
概念解释
- 抽象层:模型接口、Embedding 接口、VectorStore 接口、Advisor 编排。
- 适配层:各厂商与向量库提供具体实现,通过自动装配或显式 Bean 接入。
- 边界:抽象解决统一接入,底层库高级能力仍可能需要原生客户端补充。
原理流程
引入 Spring AI 依赖 → 配置模型与向量库 → 抽象接口注入业务代码
→ 具体适配实现完成调用 → 上层链路编排 RAG
代码 / 命令
# 面试表达:先讲抽象接口分层,再讲适配实现,最后讲与 Spring 容器的装配关系
# 待确认:当前版本模块划分与自动装配条件以官方参考文档为准
常见误区
- 误区:Spring AI 自带向量数据库。正解:它是集成抽象,底层仍需接入 Milvus、pgvector、Qdrant 等独立存储。
- 误区:抽象层覆盖所有底层特性。正解:高级索引参数与运维能力常需原生 SDK 补充。
追问
- 问:Spring AI 与直接用各厂商 SDK 的取舍?答:抽象降低换库成本,直接 SDK 获得全部特性,按团队维护需求选择。
- 问:抽象层性能损失在哪?答:主要在接口转换与额外封装,需在压测中对比原生调用。
05.6.11.3-002 VectorStore 接口的核心方法有哪些?
频率 ★★★★★ | 难度 基础
一句话结论
VectorStore 抽象通常覆盖文档写入、相似度检索、带分数检索、删除与按 id 查询这组方法,具体方法签名以当前版本官方文档为准。
概念解释
- 写入:接收 Document 列表完成向量化与入库。
- 检索:按查询与检索参数返回候选 Document,部分方法附带分数。
- 维护:删除、点查等生命周期方法。
- 一致性:接口行为由具体适配实现翻译为底层 SDK 调用。
原理流程
业务调用抽象方法 → 适配实现翻译 → 底层向量库 SDK → 结果回填 Document
代码 / 命令
# 方法类别:add / similaritySearch / similaritySearchWithScore / delete / get
# 待确认:各方法确切签名、参数名与返回结构以 Spring AI 当前版本文档为准
常见误区
- 误区:所有适配实现方法签名完全一致。正解:能力差异可能通过可选参数或扩展方法体现。
- 误区:抽象接口包含混合检索与重排。正解:这些通常是独立组件或链路环节,不在基础 VectorStore 接口内。
追问
- 问:方法返回的 Document 带不带原文?答:取决于底层库存储内容与适配实现,需核对结果结构。
- 问:检索参数从哪里传?答:通过检索请求对象或方法参数传入 topK、过滤条件等,具体形态以文档为准。
05.6.11.3-003 各向量库适配实现的差异点在哪里?
频率 ★★★★☆ | 难度 进阶
一句话结论
适配实现的差异体现在过滤语法、标量字段类型、批量写入能力、索引参数暴露程度与分数口径,接入前要对照目标库能力逐项核对。
概念解释
- 差异维度:条件表达式支持、metadata 类型、批量接口、特有参数。
- 屏蔽风险:抽象层未暴露的底层能力需原生客户端访问。
- 验证方式:用同一组写入与检索用例在目标库跑通。
原理流程
列出需求能力 → 对照官方适配说明 → 补齐原生调用 → 写入 / 检索 / 过滤 / 删除回归
代码 / 命令
# 核对表:写入、检索、带分数、过滤、删除、批量、特有参数、分数方向
# 待确认:各适配当前能力清单以 Spring AI 参考文档与对应仓库为准
常见误区
- 误区:换适配实现只改依赖即可。正解:过滤语法与字段类型差异需要业务侧调整。
- 误区:适配实现与底层库版本天然兼容。正解:需核对适配包与服务端版本的兼容范围。
追问
- 问:某库特性抽象层不支持怎么办?答:在业务服务内封装原生客户端调用,与抽象接口分层共存。
- 问:怎么评估适配成熟度?答:看官方维护状态、方法覆盖、文档完整度与社区问题反馈。
05.6.11.3-004 EmbeddingModel 抽象与模型配置包含哪些内容?
频率 ★★★★☆ | 难度 基础
一句话结论
EmbeddingModel 抽象负责把文本转为向量,配置包含模型标识、连接、维度与调用参数;入库与查询必须共用同一模型实例与版本。
概念解释
- 配置项:模型标识、端点 / 凭据、批次与超时参数。
- 一致性:同一集合内向量来自同一模型,维度与归一化口径一致。
- 复用:Bean 单例化,避免重复初始化与连接浪费。
原理流程
读取配置 → 构造 EmbeddingModel Bean → 注入 VectorStore 与检索链路
→ 写入与查询统一调用该实例
代码 / 命令
# 核对:模型标识、输出维度、归一化方式与存量向量一致
# 待确认:具体配置属性前缀与参数名以官方文档为准
常见误区
- 误区:入库与查询可用不同模型分别优化。正解:向量空间不同,混用检索无意义。
- 误区:模型配置只在检索侧声明。正解:入库向量化同样依赖该配置。
追问
- 问:模型版本怎么留痕?答:在入库记录或 metadata 中保存模型标识,便于回溯与切换。
- 问:配置缺失如何快速发现?答:启动期校验必填项,缺失则初始化失败并给出明确提示。
05.6.11.3-005 文档切分器在 Spring AI 中处于什么环节?
频率 ★★★☆☆ | 难度 基础
一句话结论
文档切分属于 ETL 流水线中的转换环节,在读取文档之后、向量化入库之前完成切块,控制块大小、重叠与结构边界。
概念解释
- 位置:Reader 读取 → Transformer 切分 → Writer 写入。
- 产出:带 metadata 的 Document 片段列表。
- 质量影响:切块直接决定召回粒度与上下文完整性。
原理流程
原始文档 → 读取组件 → 切分转换(大小 / 重叠 / 边界)→ metadata 补充 → 向量化入库
代码 / 命令
# 配置关注点:块大小、重叠、分隔符层级
# 验证:抽样审阅句子完整与实体连贯
# 待确认:切分组件类名与参数以当前版本文档为准
常见误区
- 误区:切分由向量库完成。正解:切分在应用侧 ETL 环节完成,向量库只接收片段。
- 误区:默认参数适配所有文档类型。正解:中文、表格、代码需分别调整。
追问
- 问:结构化文档怎么切?答:按标题、段落边界切分,层级信息写入 metadata。
- 问:切块后还能加工吗?答:可在转换链中接入清洗、摘要或上下文补充步骤。
05.6.11.3-006 ETL 流水线:Reader、Transformer、Writer 如何分工?
频率 ★★★★☆ | 难度 进阶
一句话结论
Reader 负责从数据源读取原始文档,Transformer 负责清洗、切分与 metadata 加工,Writer 负责向量化并写入 VectorStore,三段解耦便于替换数据源与存储。
概念解释
- Reader:文件、数据库、对象存储等来源接入。
- Transformer:切分、过滤、补充元数据。
- Writer:调用 EmbeddingModel 并批量写入向量库。
- 优势:各段可独立测试与替换,便于离线批处理组织。
原理流程
Reader 取文档 → Transformer 切块加工 → 校验非空与类型 → Writer 批量向量化入库 → 登记台账
代码 / 命令
# 流水线记录:来源标识、片段数、批次状态、失败条目
# 分段测试:Reader 抽样核对原文,Transformer 抽样核对切块,Writer 对账入库数量
常见误区
- 误区:ETL 必须在线请求期执行。正解:入库链路应离线或异步批量完成,在线只做检索。
- 误区:三段耦合在一个方法里更好维护。正解:解耦后便于对账、重试与替换组件。
追问
- 问:大文档怎么进流水线?答:Reader 流式读取,分批切块写入,避免一次性加载全文到内存。
- 问:ETL 失败怎么续跑?答:记录处理水位与批次状态,重启后从断点继续并对账。
05.6.11.3-007 RAG Advisor 的作用与挂载位置是什么?
频率 ★★★★★ | 难度 进阶
一句话结论
RAG Advisor 在对话链路中介入检索增强:按问题检索上下文、组装进提示词,再交给模型生成;它挂在 ChatClient 链路之上,与模型调用解耦。
概念解释
- 职责:触发检索、拼接上下文、约束模型基于上下文回答。
- 挂载方式:作为 Advisor 接入 ChatClient 或对话链路,具体装配形态以版本为准。
- 分离:检索配置与模型调用分开,便于替换检索策略。
原理流程
用户问题 → Advisor 检索 VectorStore → 组装上下文 → 填入 Prompt → ChatClient 调用模型 → 回答
代码 / 命令
# 链路核对:检索参数(topK / filter)、上下文模板、来源标注
# 待确认:Advisor 具体接口名与装配方式以 Spring AI 当前版本文档为准
常见误区
- 误区:Advisor 直接包含向量数据库。正解:它调用注入的 VectorStore,存储是独立依赖。
- 误区:挂上 Advisor 就自动解决检索质量。正解:切块、模型、过滤与阈值仍需单独调优。
追问
- 问:检索为空时 Advisor 怎么表现?答:应走无依据兜底提示,不使用空上下文让模型自由发挥。
- 问:多个 Advisor 如何排序?答:按链路职责顺序组合,具体顺序与可组合性以官方文档为准。
05.6.11.3-008 ChatClient 与 Advisor 结合做检索增强的链路是什么?
频率 ★★★★☆ | 难度 进阶
一句话结论
ChatClient 负责模型对话调用,Advisor 在调用前完成检索与上下文注入,两者组合成完整 RAG 链路;检索结果与历史对话共享上下文长度预算。
概念解释
- ChatClient:模型调用入口,管理提示词与对话上下文。
- Advisor:检索与上下文组装环节。
- 预算:系统指令、历史、检索上下文、生成预留共同占用模型窗口。
原理流程
构造 ChatClient → 注册 RAG Advisor → 传入问题
→ Advisor 检索并注入上下文 → 模型生成 → 结果返回
代码 / 命令
# 上下文预算:窗口 - 指令 - 历史 - 生成预留 = 可用检索上下文
# 观测:分段记录检索条数、组装长度、生成耗时
常见误区
- 误区:检索上下文不受窗口限制。正解:超长会被截断或报错,需显式长度控制。
- 误区:Advisor 会自动保留来源标注。正解:来源与引用需在上下文模板中显式组装。
追问
- 问:多轮对话历史挤占上下文怎么办?答:历史做摘要或裁剪,与检索上下文共享预算。
- 问:如何替换检索策略?答:更换 Advisor 内的检索配置或 VectorStore 实现,ChatClient 链路保持稳定。
05.6.11.3-009 向量库连接配置:properties 与 Bean 如何组织?
频率 ★★★★☆ | 难度 基础
一句话结论
连接端点、凭据与参数从配置属性读取,自动装配或显式 Bean 构造底层客户端与 VectorStore;配置与代码分离,按环境注入不同值。
概念解释
- 配置层:endpoint、凭据、集合 / 命名空间、超时、批次参数。
- 装配层:客户端 Bean 与 VectorStore Bean 生命周期受 Spring 容器管理。
- 环境隔离:开发、预发、生产使用独立配置与凭据。
原理流程
配置属性加载 → 条件满足时装配客户端 / VectorStore Bean → 业务注入使用
→ 容器关闭时释放资源
代码 / 命令
# 检查:必填配置校验、凭据不进代码仓库、Bean 单例复用
# 待确认:自动装配条件与属性前缀以官方文档为准
常见误区
- 误区:在业务代码里硬编码连接地址。正解:连接信息走配置注入,便于环境切换。
- 误区:每次请求新建客户端。正解:客户端与 VectorStore 应容器内单例复用。
追问
- 问:Bean 初始化失败怎么处理?答:启动期快速失败并告警,不要带病进入请求阶段。
- 问:多套向量库配置怎么管理?答:按环境或业务域注册命名 Bean,显式取用。
05.6.11.3-010 多环境配置差异如何管理?
频率 ★★★☆☆ | 难度 基础
一句话结论
环境差异通过配置模板 + 环境变量 / 配置中心注入解决,代码与默认值保持中性,测试数据不复制到生产,凭据各环境独立。
概念解释
- 隔离项:连接地址、集合名、凭据、超时与批参数。
- 原则:代码不写环境特定值,配置可渲染。
- 数据:生产数据不进测试环境,测试用脱敏样本。
原理流程
配置模板 → 各环境渲染 → 独立装配 → 独立监控与配额 → 变更走评审
代码 / 命令
# 检查:生产凭据不出现在测试配置;集合命名带环境前缀避免误连
常见误区
- 误区:共用一套配置只改集合名。正解:凭据、网络与配额也需隔离。
- 误区:测试配置留生产 key 方便复用。正解:混用凭据扩大泄露面。
追问
- 问:如何防止应用误连生产?答:网络隔离 + 凭据分离 + 启动期环境标识校验。
- 问:配置变更怎么回滚?答:配置版本化管理,保留上一可用版本。
05.6.11.3-011 事务边界:检索为什么不放在数据库事务里?
频率 ★★★★☆ | 难度 高级
一句话结论
向量检索是独立存储的只读查询,不参与业务数据库事务的 ACID 边界;把检索挂在数据库事务内会拉长事务时长、占用连接,且向量库本身不服从本地事务。
概念解释
- 存储独立:向量库与业务库是两个系统,没有跨库事务协议。
- 检索性质:在线只读近邻查询,不需要事务隔离语义。
- 风险:事务内远程调用增加锁持有时间与连接占用,放大故障面。
原理流程
业务事务:写业务库 → 提交事务 → 事务外调用向量检索
(检索与业务数据一致性通过应用层补偿 / 对账保证)
代码 / 命令
# 边界原则:向量库读写不纳入 @Transactional 范围
# 一致性手段:业务记录状态 + 向量库幂等写入 + 定时对账
常见误区
- 误区:事务内调用向量库能保证强一致。正解:向量库不参与本地事务,跨库一致性只能靠补偿机制。
- 误区:检索放在事务里不影响性能。正解:远程调用拉长事务,占用业务库连接与行锁。
追问
- 问:业务写库后向量必须立即可搜怎么办?答:写后按幂等流程写入向量库,必要时读强一致链路并容忍窗口,而不是靠数据库事务。
- 问:跨库一致性怎么兜底?答:事件 / 消息同步 + 对账任务 + 差异补偿队列。
05.6.11.3-012 向量库写入与业务库写入的一致性问题怎么处理?
频率 ★★★★☆ | 难度 高级
一句话结论
两个存储无法单事务提交,需按业务重要性选择「先写业务库再同步向量库」或事件驱动最终一致,并配合幂等、重试与对账补偿。
概念解释
- 顺序:业务库为权威数据源,向量库为派生索引。
- 保证:幂等写入、失败重试、对账发现差异并补偿。
- 取舍:强一致要求高的场景缩短同步窗口并监控延迟。
原理流程
写业务库提交 → 发变更事件 / 直接调用 → 幂等写向量库
→ 记录同步状态 → 对账任务扫描差异 → 补偿写入 / 删除
代码 / 命令
# 幂等键:业务文档 id;重复写入按覆盖语义处理
# 对账:比对业务库文档状态与向量库标识集合,输出差异清单
常见误区
- 误区:先写向量库再写业务库更稳妥。正解:权威源应先落业务库,避免向量残留无主数据。
- 误区:同步成功一次就长期一致。正解:异步链路可能失败,必须有对账兜底。
追问
- 问:同步失败怎么补偿?答:失败条目进重试队列,对账任务二次发现差异并补写。
- 问:文档下线如何级联清理向量?答:业务状态变更后触发向量删除,对账复核残留命中。
05.6.11.3-013 线程池配置与阻塞调用隔离怎么做?
频率 ★★★☆☆ | 难度 高级
一句话结论
阻塞型向量库与 Embedding 调用应通过独立线程池隔离,按下游连接与配额定并发上限,避免阻塞业务主线程池并防止相互拖累。
概念解释
- 隔离对象:检索调用、批量入库、Embedding 计算。
- 上限依据:下游连接数、速率限制、单任务耗时。
- 观测:线程池队列水位、活跃线程、排队等待时长。
原理流程
识别阻塞调用 → 配置独立线程池(核心 / 最大 / 队列)→ 任务提交
→ 监控水位与拒绝策略 → 超限降级或排队
代码 / 命令
# 配置核对:池大小与下游连接匹配;队列有界;拒绝策略明确
# 待确认:异步执行器配置方式以 Spring 版本与框架文档为准
常见误区
- 误区:复用业务 Tomcat / 公共线程池跑批量入库。正解:批量任务会挤占在线请求线程。
- 误区:线程池越大吞吐越高。正解:下游连接与配额决定上限,过大并发触发限流。
追问
- 问:线程池满了怎么办?答:有界队列 + 拒绝策略,配合限流与降级,而不是无限排队。
- 问:CPU 密集切分放哪个池?答:不应占用 IO 线程池,必要时独立隔离并限并发。
05.6.11.3-014 异步调用与 Future / 响应式的边界在哪里?
频率 ★★★☆☆ | 难度 高级
一句话结论
异步模型要与底层客户端能力匹配:同步阻塞客户端用线程池并发,非阻塞客户端才适合响应式链路;混用会导致阻塞事件循环或线程失控。
概念解释
- 同步客户端:阻塞 IO,靠线程池提升并发。
- 非阻塞客户端:可接入响应式 / 异步链路。
- 边界:以底层 SDK 是否提供异步接口为准,不凭框架名判断。
原理流程
确认客户端类型 → 同步走线程池 / 异步走非阻塞调用 → 结果汇聚
→ 超时与并发控制统一配置
代码 / 命令
# 检查:调用是否阻塞;异步链路中是否混入同步 SDK
# 待确认:Spring AI 各适配提供的异步支持以官方文档为准
常见误区
- 误区:响应式链路里直接调用同步 SDK 也不影响。正解:会阻塞事件循环,需切换非阻塞或线程池隔离。
- 误区:Future 编排等于响应式。正解:线程池并发与事件循环模型不同,资源模型要分清。
追问
- 问:底层只有同步客户端怎么办?答:线程池隔离执行,控制池大小,避免阻塞主链路。
- 问:异步批量怎么控并发?答:信号量 / 分批并发限制,配合退避重试与下游配额。
05.6.11.3-015 向量维度与 Embedding 模型一致性如何校验?
频率 ★★★★★ | 难度 高级
一句话结论
写入前校验向量维度与集合定义、模型版本一致;维度不符会被底层拒绝或污染索引,模型切换后存量向量不可直接混用。
概念解释
- 校验项:向量非空、长度等于集合维度、模型标识匹配记录。
- 风险:历史向量与新模型向量混在同一集合导致检索失真。
- 切换:换模型需全量重建,过渡期双写并按标识隔离。
原理流程
调用 Embedding → 校验维度与模型标识 → 写入集合
→ 抽样点查核对长度 → 模型变更走双写影子读 → 灰度切流重建
代码 / 命令
# 校验:输出长度 == 集合维度;metadata / 台账记录模型版本
# 待确认:维度约束的报错形式以底层库与适配实现为准
常见误区
- 误区:维度不一致向量库会自动兼容。正解:通常写入报错,或在部分实现中污染索引。
- 误区:换模型追加旧集合即可。正解:空间不可比,必须重建。
追问
- 问:怎么发现历史维度不一致?答:抽样点查向量长度,对照集合 schema 与模型记录。
- 问:双写过渡期如何隔离新旧向量?答:按模型标识分集合 / 命名空间或 metadata 过滤隔离。
05.6.11.3-016 切换模型导致存量向量不可用怎么过渡?
频率 ★★★☆☆ | 难度 高级
一句话结论
模型切换采用「新模型验证 → 双写新向量 → 影子读对比 → 灰度切流 → 清理旧向量」的步骤,旧向量保留至切换稳定后再删除。
概念解释
- 前提:新模型在标注集上召回达标。
- 过渡:双写期间两套向量并存,按模型标识隔离。
- 回滚:保留旧向量与配置版本,异常时可切回。
原理流程
评估集验证新模型 → 离线重建 / 增量双写 → 影子读对比新旧结果
→ 按租户 / 比例切流 → 观察指标 → 清理旧向量
代码 / 命令
# 记录:模型标识、集合 / 命名空间、切换时间与指标
# 回滚路径:旧模型配置与旧向量保留一个观察周期
常见误区
- 误区:切换模型只改配置。正解:存量数据必须重算,配置变更不迁移历史向量。
- 误区:双写期间无需隔离。正解:新旧向量混杂会让检索结果不可解释。
追问
- 问:双写写入放大怎么控制?答:离线批处理重建为主,在线增量双写为辅,监控 Embedding 配额。
- 问:怎么确认新模型更优?答:同一标注集对比召回、排序与人工评价,达标后再切。
05.6.11.3-017 SearchRequest 的 filter 表达式怎么使用?
频率 ★★★★★ | 难度 进阶
一句话结论
检索请求对象携带 topK、相似度阈值与过滤表达式,filter 由适配层翻译为底层向量库标量条件;表达式语法与支持操作符以适配实现为准。
概念解释
- 组成:查询、候选条数、过滤条件、分数阈值等检索参数。
- 翻译:框架表达式 → 底层原生查询条件。
- 兼容:框架支持的操作符不一定被目标库全部支持。
原理流程
业务构造检索请求(query / k / filter)→ 适配翻译 → 底层标量过滤 + 向量排序
→ 候选回填 Document
代码 / 命令
# 条件类型:等值、集合包含、范围、布尔组合
# 验证:样本条件核对底层查询是否下推、命中集合是否符合预期
# 待确认:表达式确切语法与字段名以当前版本文档为准
常见误区
- 误区:filter 传入方法就一定生效。正解:需确认翻译与底层字段支持,否则可能被忽略。
- 误区:嵌套 metadata 可直接过滤。正解:复杂结构需展平为底层支持的标量字段。
追问
- 问:权限过滤怎么强制?答:在检索请求中注入用户可见范围条件,不能依赖结果展示前剔除。
- 问:过滤字段未索引影响多大?答:低选择率条件退化为扫描,需核对底层索引支持。
05.6.11.3-018 filter 与底层向量库条件下推的兼容性如何核对?
频率 ★★★☆☆ | 难度 高级
一句话结论
逐项核对操作符、字段类型、数组包含与空值处理在目标库的支持情况,用样本查询验证条件确实下推;不支持的条件要显式报错而非静默忽略。
概念解释
- 核对项:等值 / 范围 / 包含 / 布尔组合 / 空值。
- 验证方式:对照底层查询日志或执行结果确认过滤生效。
- 防护:适配层对未知操作符抛错,避免线上误召回。
原理流程
列出过滤需求 → 对照目标库能力 → 编写样本用例 → 检查命中集合 → 记录不兼容项
代码 / 命令
# 兼容性检查:每种条件类型跑一条写入 + 过滤查询
# 不支持项:在适配层明确提示,或改用业务侧后置过滤(注明性能代价)
常见误区
- 误区:抽象表达式处处等价。正解:各库语法与类型约束不同,迁移需重新核对。
- 误区:翻译失败会抛异常。正解:部分实现静默丢弃条件,需测试拦截。
追问
- 问:跨库迁移过滤怎么改?答:先梳理条件清单,按目标库语法重写并回归命中结果。
- 问:后置过滤有什么代价?答:先召回全量候选再剔除,选择率低时性能差且可能超 topK。
05.6.11.3-019 topK、相似度阈值等检索参数如何设置?
频率 ★★★☆☆ | 难度 基础
一句话结论
topK 决定召回宽度,相似度阈值过滤低相关候选;两者按业务样本分布标定,显式设置而不依赖框架默认值。
概念解释
- topK:候选条数,大则召回全但噪声多,小则精准但可能漏召回。
- 阈值:按度量方向设上限或下限,需结合分数分布标定。
- 链路位置:召回后可再经重排截断,最终上下文条数可小于 topK。
原理流程
标注样本 → 跑召回记录分数分布 → 定 topK 与阈值 → 接入链路 → 上线后复核趋势
代码 / 命令
# 注意:默认值以当前版本实现为准,不要在代码中假定固定数值
# 度量方向:相似度越高越相关,距离越低越相关,阈值方向先确认
常见误区
- 误区:topK 越大检索越准。正解:大 K 引入低相关候选,占用上下文并干扰生成。
- 误区:阈值可跨模型 / 跨库复用。正解:分数口径变化后需重新标定。
追问
- 问:K 怎么取值?答:从个位数起步,按召回率与噪声平衡调整,用标注集对比。
- 问:过滤后不足 K 条怎么办?答:属正常现象,业务容忍空结果与低分结果,不强行凑数。
05.6.11.3-020 多 VectorStore 路由与按租户选择怎么做?
频率 ★★★★☆ | 难度 高级
一句话结论
按租户、业务域或文档类型注册多个 VectorStore Bean,业务层依据路由维度选择对应实例;多路检索时合并候选并注意分数口径差异。
概念解释
- 路由依据:租户标识、产品线、文档类型、权限范围。
- 实现:条件选择 Bean,或封装路由服务。
- 合并:多路结果去重,分数不可直接比较时先归一化。
原理流程
请求携带路由维度 → 校验访问权 → 选择对应 VectorStore → 检索
→ 多路合并去重 / 归一化 → 后处理返回
代码 / 命令
# 单路由:按维度取已注册命名 Bean
# 多路:并发检索后按文档标识合并,分数口径分别记录
常见误区
- 误区:一个集合存所有业务最简单。正解:混存导致过滤复杂、权限隔离弱、参数无法分别优化。
- 误区:多路分数可直接合并排序。正解:不同库 / 模型口径不同,需归一化或分阶段排序。
追问
- 问:路由规则放哪一层?答:业务服务层决定目标存储,检索组件只执行,便于测试与替换。
- 问:跨集合权限怎么控制?答:路由前校验访问权,检索 filter 再补行级条件。
05.6.11.3-021 可观测:检索埋点、耗时与召回数记录什么?
频率 ★★★☆☆ | 难度 进阶
一句话结论
在检索链路记录请求标识、耗时、召回条数、分数分布、过滤条件摘要与错误分类,区分检索阶段与生成阶段指标。
概念解释
- 指标:检索 P50/P99、召回条数、空结果率、分数区间、错误率。
- 标签:场景、租户、模型版本、集合。
- 采样:慢查询与异常查询保留摘要样本,便于复盘。
原理流程
请求进入 → 记录开始时间与标识 → 检索执行 → 记录条数 / 分数 / 耗时 → 上报指标与日志
代码 / 命令
# 埋点字段:trace 标识、query 摘要、集合、K、filter 摘要、hit_count、score 分布、latency、error
# 看板:延迟趋势、空结果率、低分占比、错误分类
常见误区
- 误区:只记录成功率。正解:空结果与低分结果不报错,却是检索质量主要信号。
- 误区:日志落原始 query 与原文。正解:做摘要脱敏,避免敏感信息进入日志。
追问
- 问:怎么发现召回退化?答:对比上线前后召回条数、分数分布与人工抽样命中率。
- 问:指标按什么维度聚合?答:至少按场景与租户拆分,避免平均掩盖个别问题。
05.6.11.3-022 超时、重试与熔断配置放在哪一层?
频率 ★★★★☆ | 难度 高级
一句话结论
超时分层设置(客户端、检索链路、接口总时长),重试只针对可重试错误并加退避,熔断保护下游;配置与向量库调用绑定,避免整体超时被拉长。
概念解释
- 超时层级:连接 / 请求超时、检索调用超时、接口总超时逐级收紧。
- 重试范围:网络抖动、临时限流可重试;参数错误、权限失败不重试。
- 联动:重试幂等,配合限流与熔断。
原理流程
请求进入 → 各层超时配置 → 调用检索 → 失败分类 → 可重试退避重试 → 仍失败走熔断降级
代码 / 命令
# 超时:连接 / 请求 / 接口总时长分开配置
# 重试:次数上限、退避间隔、错误类型白名单
常见误区
- 误区:客户端超时设长就不会超时。正解:超时过长堆积请求,拖垮下游。
- 误区:所有错误都重试。正解:不可重试错误反复重试只会放大压力。
追问
- 问:超时后返回什么?答:走降级结果或明确错误提示,由业务 SLA 决定,不静默成功。
- 问:重试如何避免重复 Embedding?答:按文本哈希缓存 Embedding 结果,检索重试复用已算向量。
05.6.11.3-023 批量入库与分批写入节奏怎么控制?
频率 ★★★★☆ | 难度 进阶
一句话结论
批量入库按 Embedding 上限、向量库写入上限与内存承受能力分别设批大小,控制并发与间隔,失败批次隔离重试并登记水位。
概念解释
- 约束来源:模型单次输入、底层批量接口、进程内存。
- 节奏:批间隔、并发度、速率按下游承载设定。
- 台账:批次状态、失败原因、重试次数可追踪。
原理流程
文档切块 → 分批向量化 → 批量写入 → 成功登记水位 / 失败隔离 → 限速推进
代码 / 命令
# 配置:Embedding 批大小、写入批大小、并发数、批间隔
# 压测:逐步放大批次与并发,观察两侧延迟与错误率
常见误区
- 误区:批越大吞吐越高。正解:超上限整批失败,内存压力也上升。
- 误区:在线检索与入库共享配额。正解:离线批量应限速错峰,避免挤占在线查询。
追问
- 问:历史大批量数据怎么导?答:离线分批、断点续跑、错峰执行。
- 问:部分条目失败怎么处理?答:定位失败条目小批重试,记录隔离队列,不整批重跑。
05.6.11.3-024 增量更新与去重在 Spring AI 链路如何落地?
频率 ★★★☆☆ | 难度 高级
一句话结论
以业务文档标识做幂等键,结合内容哈希判断新增、更新或跳过;更新时先清理旧节点再写新节点,配合水位与对账防止重复与残留。
概念解释
- 去重键:doc_id 稳定标识,content_hash 标识内容版本。
- 更新流程:点查存在性 → 比对版本 → 新增 / 覆盖 / 跳过。
- 对账:定时统计每文档节点数量,发现残留与缺失。
原理流程
增量文档 → 取 doc_id / hash → 点查比对 → 新增 / 删旧写新 / 跳过
→ 登记水位 → 对账复核
代码 / 命令
# metadata 记录:doc_id、parent_id、content_hash、模型标识
# 对账:每个 doc_id 节点数量、向量库标识与业务库状态比对
常见误区
- 误区:按文本相似度自动去重。正解:近似不等于相同,去重必须用业务标识或哈希。
- 误区:更新直接追加新节点。正解:不清旧节点会导致新旧内容同时被召回。
追问
- 问:内容小改要不要全量重切?答:整文变更重切替换;局部变更可定位受影响块,按实现能力选择。
- 问:增量中断怎么续跑?答:保存水位与处理状态,重启后从断点继续,失败批次单独重试。
05.6.11.3-025 依赖管理:BOM 与版本对齐要注意什么?
频率 ★★★☆☆ | 难度 进阶
一句话结论
Spring AI 相关依赖通过统一 BOM 管理版本,主框架、适配包与模型客户端版本需成对兼容;升级前核对兼容范围并在预发回归。
概念解释
- BOM 作用:统一各模块版本,避免手工逐个指定。
- 兼容范围:适配包与主框架、底层 SDK 之间存在版本约束。
- 风险:版本错配出现类缺失、签名变更或行为漂移。
原理流程
引入 BOM → 锁定版本 → 预发安装 → 导入与构造检查 → 写入 / 检索回归 → 观察线上
代码 / 命令
# 待确认:BOM 坐标、版本兼容范围以官方发布说明为准
# 检查:依赖树中是否存在版本冲突或被仲裁到意外版本
常见误区
- 误区:只升级主框架即可。正解:适配包与客户端需同步到兼容版本。
- 误区:版本报错是偶发环境问题。正解:版本错配通常稳定复现,先查依赖组合。
追问
- 问:怎么排查依赖冲突?答:分析依赖树,定位被仲裁版本与冲突来源。
- 问:版本怎么锁定?答:构建清单固定版本号,升级走预发验证,不跟随最新版盲目更新。
05.6.11.3-026 Spring Boot 自动装配在向量库接入中起什么作用?
频率 ★★★☆☆ | 难度 基础
一句话结论
满足条件时自动装配底层客户端与 VectorStore Bean,业务侧注入即可使用;接入重点是核对装配条件、配置属性与多实现共存时的选择规则。
概念解释
- 触发条件:类路径存在对应依赖、配置属性满足要求。
- Bean 产物:客户端、EmbeddingModel、VectorStore。
- 注意:多个适配实现共存时,注入歧义需要显式指定。
原理流程
引入适配依赖 → 配置属性满足 → 自动装配 Bean → 业务注入 → 启动期校验连接
代码 / 命令
# 待确认:各适配的装配条件与属性前缀以官方文档为准
# 检查:启动日志中 Bean 装配情况与配置绑定是否正确
常见误区
- 误区:自动装配无需核对配置。正解:属性缺失或前缀错误会导致 Bean 未按预期创建。
- 误区:所有适配默认参与装配。正解:条件不满足时 Bean 不生效,需核对触发条件。
追问
- 问:不想用自动装配怎么办?答:排除对应自动配置类,显式声明 Bean。
- 问:装配失败怎么定位?答:看启动报错与条件评估报告,核对依赖与属性。
05.6.11.3-027 凭据管理:环境变量与密钥如何规范使用?
频率 ★★★☆☆ | 难度 基础
一句话结论
凭据从环境变量或配置中心注入,不写入代码与仓库;按环境独立授权、最小权限,日志与错误信息中不泄露密钥。
概念解释
- 管理项:api key、账号密码、连接令牌。
- 原则:最小权限、分环境、可轮换。
- 泄露防护:异常日志只记连接标识,不打印凭据。
原理流程
凭据注入运行环境 → 客户端构造时读取 → 运行期使用 → 轮换时更新配置
代码 / 命令
# 禁止入库:密钥、令牌、内部地址
# 检查:错误堆栈与日志不输出 Authorization 类信息
常见误区
- 误区:代码里留默认密钥兜底。正解:缺失配置应启动失败,不提供硬编码默认密钥。
- 误区:一个超级账号走所有环境。正解:分环境凭据与最小权限授权。
追问
- 问:密钥轮换怎么衔接?答:客户端支持刷新或滚动重启更新,双凭据兼容窗口需确认。
- 问:密钥泄露如何止损?答:立即轮换、排查使用范围、审计访问记录。
05.6.11.3-028 metadata 字段如何映射到向量库 schema?
频率 ★★★☆☆ | 难度 进阶
一句话结论
业务 metadata 按底层库标量约束展平并统一类型,参与过滤的字段要确认索引支持;写入前做类型校验,避免序列化失真与过滤不命中。
概念解释
- 类型梳理:标量字段、列表元素类型、空值处理。
- 一致性:同字段不混用字符串与数值。
- 过滤核对:过滤字段确认底层索引与查询支持。
原理流程
梳理 metadata → 对照 schema 约束 → 展平 / 清洗 → 写入抽样 → 过滤验证
代码 / 命令
# 检查:嵌套对象展平、空值策略、列表可过滤性、类型统一
# 样本:每个过滤字段跑等值 / 范围查询确认命中
常见误区
- 误区:框架传什么类型底层都接受。正解:类型不符被拒绝或序列化失真。
- 误区:写入成功即过滤可用。正解:需单独验证过滤命中行为。
追问
- 问:存量类型混乱怎么修?答:按目标 schema 清洗,必要时重建集合与索引。
- 问:复杂业务对象怎么存?答:序列化字符串或拆标量字段,按检索需求选择。
05.6.11.3-029 扩展自定义 VectorStore 实现要做什么?
频率 ★★★☆☆ | 难度 高级
一句话结论
自定义实现需完成写入、检索、带分数检索、删除与点查方法的翻译,注入 EmbeddingModel 与底层客户端,并补齐 metadata 映射与错误处理。
概念解释
- 方法集合:与抽象接口对齐的写入 / 检索 / 维护方法。
- 依赖:EmbeddingModel 负责向量化,底层客户端负责调用。
- 契约:参数类型、返回 Document 结构与抽象基类一致。
原理流程
实现抽象接口 → 注入模型与客户端 → 逐方法翻译原生调用
→ 回填 metadata 与 id → 单测覆盖全方法
代码 / 命令
# 自检清单:写入、相似度检索、带分数检索、删除、点查
# 待确认:抽象基类方法签名以当前版本官方文档为准
常见误区
- 误区:只实现写入与检索即可接入。正解:删除、点查缺失会让增量维护与对账断裂。
- 误区:适配层重做业务模型。正解:适配只做翻译,业务编排留在服务层。
追问
- 问:抽象方法未全实现会怎样?答:调用到未实现方法时报未实现错误,开发期用单测暴露。
- 问:底层独有能力怎么暴露?答:扩展方法透传原生参数,保持抽象签名稳定。
05.6.11.3-030 Document 与 metadata 的结构是什么?
频率 ★★★☆☆ | 难度 基础
一句话结论
Document 由文本内容与 metadata 字典组成,metadata 承载来源、租户、时间、文档 id 等标量字段,供过滤、回溯与结果展示使用。
概念解释
- 内容:可被向量化与展示的正文片段。
- metadata:轻量标量字段,不放大对象。
- 关联:父子层级通过 id 类字段在 metadata 中关联。
原理流程
业务字段 → 挂到 Document.metadata → 写入向量库标量列
→ 检索命中 → 结果回填 metadata
代码 / 命令
# metadata 示例:doc_id、tenant、source、updated_at、chunk_index
# 注意:敏感原文不进入 metadata
常见误区
- 误区:metadata 可放任意嵌套 JSON。正解:受底层标量约束,复杂结构需展平。
- 误区:metadata 不会随结果暴露。正解:命中文档 metadata 会返回,敏感字段不要写入。
追问
- 问:同一文档多块怎么标识?答:文档级 id 加块级位置字段,便于聚合与更新。
- 问:metadata 过大有什么问题?答:标量冗余存储,影响写入与过滤性能,只留必要字段。
05.6.11.3-031 检索结果与 Prompt 拼接的长度如何控制?
频率 ★★★☆☆ | 难度 进阶
一句话结论
按模型窗口预留指令、历史与生成空间,召回块按相关度排序后截断;超长时分批摘要或保留高相关段落,避免超出上下文窗口。
概念解释
- 预算划分:系统指令、历史对话、检索上下文、生成预留。
- 截断依据:分数、顺序、来源优先级。
- 兜底:超预算时优先保高相关块,不随机丢弃。
原理流程
召回排序 → 计算可用上下文预算 → 顺序填充块 → 超预算截断 / 摘要 → 填入 Prompt
代码 / 命令
# 预算 = 模型窗口 - 指令与历史占用 - 生成预留
# 待确认:模型窗口与 token 计算方式以所用模型文档为准
常见误区
- 误区:检索多少块塞多少块。正解:需长度控制与去重,避免超出窗口。
- 误区:token 长度等于字符数。正解:不同分词口径不同,按模型 token 方式估算。
追问
- 问:历史对话占用怎么办?答:历史摘要或裁剪,与检索上下文共享预算。
- 问:截断后如何保证依据完整?答:保留段落标题与来源,引导模型基于可见内容回答。
05.6.11.3-032 混合检索与重排在 Spring AI 链路中怎么接入?
频率 ★★★☆☆ | 难度 高级
一句话结论
混合检索可组合向量召回与关键词召回,重排作为召回后的精排环节接入链路;具体组件与编排方式以当前版本官方文档为准,分数口径需分别处理。
概念解释
- 多路:向量语义召回 + 词项精确召回。
- 融合:按标识去重,统一排序或加权融合。
- 重排:精排模型对候选打分,收紧最终 TopK。
原理流程
查询 → 多路召回 → 合并去重 / 归一化 → 融合排序 → 重排精排 → 上下文组装
代码 / 命令
# 记录:各路召回条数、重叠文档、融合候选、重排 TopK
# 待确认:混合检索与重排组件的可用形态以官方文档为准
常见误区
- 误区:不同路分数直接相加。正解:口径分布不同,需归一化或分阶段排序。
- 误区:重排替代向量检索。正解:重排是召回后环节,候选仍来自检索。
追问
- 问:一路召回失败怎么降级?答:单路返回并记录失败路,不阻塞主链路。
- 问:重排超时怎么办?答:跳过重排用召回排序兜底,保证主链路可用。
05.6.11.3-033 缓存检索结果有什么取舍?
频率 ★★☆☆☆ | 难度 进阶
一句话结论
热门相同问题可缓存检索结果降低重复 Embedding 与检索开销,但需控制过期与一致性,文档更新后失效缓存,避免返回旧上下文。
概念解释
- 收益:降低重复调用、缩短延迟。
- 风险:文档变更后缓存陈旧;多租户结果不可混存。
- 要点:按查询与过滤条件组合做键,设置 TTL 与失效策略。
原理流程
查询 + filter 组合成缓存键 → 命中返回缓存 → 未命中检索后写入
→ 文档更新触发相关缓存失效
代码 / 命令
# 缓存键:查询归一化 + 过滤条件 + 模型 / 集合标识
# 失效:文档更新删除相关条目;设置合理 TTL 兜底
常见误区
- 误区:缓存只按问题文本。正解:过滤条件与租户不同结果不同,必须纳入键。
- 误区:缓存永久有效。正解:语料变更后陈旧缓存会污染回答。
追问
- 问:缓存粒度怎么选?答:热门重复问题命中缓存,长尾问题直接检索。
- 问:缓存击穿怎么处理?答:热点键互斥重建,避免同一查询并发重复回源。
05.6.11.3-034 常见坑:多个 VectorStore 实现导致注入歧义怎么办?
频率 ★★★★☆ | 难度 高级
一句话结论
类路径存在多个适配实现时,按类型注入会出现候选歧义;需通过命名 Bean、显式限定或装配条件指定目标 VectorStore,并在启动期验证注入结果。
概念解释
- 成因:多个适配依赖共存,容器内存在多个同类型 Bean。
- 解决:显式 Bean 名 / 限定符选择,或排除不需要的自动装配。
- 验证:启动后核对注入实例对应的集合与配置。
原理流程
梳理类路径适配 → 确认需要的实现 → 显式指定 Bean / 排除多余装配
→ 启动核对注入实例 → 检索链路回归
代码 / 命令
# 检查:依赖树中适配包清单;注入处是否显式指定目标 Bean
# 待确认:限定符与装配排除方式以 Spring 版本文档为准
常见误区
- 误区:框架自动选第一个实现即可。正解:歧义可能导致注入非预期集合。
- 误区:排除自动装配后无需核对。正解:需确认所需 Bean 仍被正确创建。
追问
- 问:多业务域需要多个 VectorStore 怎么办?答:注册命名 Bean 按路由注入,避免单类型歧义。
- 问:怎么验证注入正确?答:启动日志或测试中核对 Bean 名称、集合名与连接配置。
05.6.11.3-035 常见坑:阻塞 SDK 用在响应式链路有什么问题?
频率 ★★★☆☆ | 难度 高级
一句话结论
响应式链路中直接调用同步阻塞 SDK 会阻塞事件循环,表现为整体延迟抖动、并发上不去;需切换非阻塞客户端或用线程池隔离阻塞调用。
概念解释
- 信号:事件循环线程占满、无关请求同时变慢。
- 根因:阻塞调用占住循环线程。
- 解法:非阻塞客户端,或将同步调用放入隔离线程池。
原理流程
接口延迟抖动 → 排查协程 / 循环内调用 → 确认同步 SDK 阻塞
→ 线程池隔离 / 换异步客户端 → 压测回归
代码 / 命令
# 检查:响应式链路内是否出现同步 SDK 与同步 Embedding 调用
# 处置:阻塞操作隔离执行,限制并发,优先评估官方异步支持
常见误区
- 误区:异步框架里所有调用自动异步。正解:只有非阻塞客户端不占事件循环。
- 误区:加线程池就解决了。正解:池大小失控会带来新的资源瓶颈。
追问
- 问:怎么确认是事件循环阻塞?答:看循环线程占用与请求排队时长,区分下游慢与循环被卡住。
- 问:线程池并发怎么定?答:按下游连接与配额反推,不让线程数超过承载能力。
05.6.11.3-036 常见坑:维度不一致在写入期才暴露怎么预防?
频率 ★★★☆☆ | 难度 进阶
一句话结论
维度问题常在写入或检索阶段才集中暴露;预防靠启动期核对模型与集合维度、写入前校验向量长度、抽样点查历史数据。
概念解释
- 暴露时机:写入被拒、检索结果异常、历史数据混维度。
- 预防:配置校验、写入校验、抽样巡检。
- 记录:模型标识与维度写入台账便于比对。
原理流程
启动期核对模型维度与集合定义 → 写入前校验向量长度 → 抽样点查历史
→ 发现不一致隔离问题批次
代码 / 命令
# 校验:向量非空、长度等于集合维度、模型标识匹配记录
# 巡检:定期抽样点查向量长度与 metadata 模型标识
常见误区
- 误区:接入时跑通一条样例就代表维度没问题。正解:需覆盖模型、集合与历史数据核对。
- 误区:维度不一致是底层库的问题。正解:多为模型配置或切换未重建导致。
追问
- 问:发现混维度怎么修复?答:定位问题批次,按正确模型重建受影响集合或分片。
- 问:如何防止新模型误写旧集合?答:写入前校验模型标识与集合配置匹配。
05.6.11.3-037 常见坑:filter 字段在向量库无索引会怎样?
频率 ★★★☆☆ | 难度 进阶
一句话结论
过滤字段缺少索引或类型不匹配时,条件不生效或退化为扫描,表现为过滤结果不符预期、检索延迟升高;需核对底层支持并验证命中集合。
概念解释
- 表现:条件被忽略、命中范围过大、慢查询。
- 原因:字段未索引、操作符不支持、类型不一致。
- 验证:样本条件对比实际命中结果。
原理流程
带过滤慢查询 → 检查字段索引支持 → 核对类型与操作符 → 优化 schema / 条件 → 回归延迟
代码 / 命令
# 记录:过滤字段、扫描候选量、命中量、耗时
# 对照:底层库官方文档对过滤字段索引的说明(待确认具体类型)
常见误区
- 误区:metadata 字段都能高效过滤。正解:是否走索引取决于底层实现。
- 误区:条件写对结果就一定对。正解:需实际命中集合验证。
追问
- 问:多过滤字段怎么优化?答:高选择率条件前置,确认组合条件可下推。
- 问:过滤不命中怎么排查?答:先放宽条件看基础召回,再逐字段叠加定位问题字段。
05.6.11.3-038 常见坑:长事务内调用向量库拉低吞吐怎么识别?
频率 ★★☆☆☆ | 难度 高级
一句话结论
事务内远程调用拉长事务时长、占用业务库连接与行锁,识别信号是事务耗时与连接占用升高;修复是把向量调用移出事务并改补偿一致性。
概念解释
- 信号:事务平均时长上升、业务库连接紧张、锁等待增加。
- 根因:事务边界内嵌入向量库 / 模型远程调用。
- 修复:缩短事务,远程调用移到事务提交后。
原理流程
慢事务排查 → 拆分事务内调用环节 → 定位远程向量调用 → 移出事务
→ 补偿 / 对账保证一致性 → 回归连接与延迟指标
代码 / 命令
# 检查:事务方法内是否存在 VectorStore / Embedding / 模型调用
# 原则:远程检索与写入不纳入本地事务边界
常见误区
- 误区:事务内调用向量库更安全。正解:跨系统无本地事务,反而拉长锁持有。
- 误区:连接占用高是连接池太小。正解:先排查事务内远程调用拉长占用时间。
追问
- 问:移出事务后一致性怎么保证?答:业务库提交后异步写向量库,幂等 + 对账补偿。
- 问:必须写后立即可搜怎么办?答:同步等待向量写入确认,但仍不放在数据库事务内。
05.6.11.3-039 常见坑:Embedding 批大小超出模型上限怎么处理?
频率 ★★☆☆☆ | 难度 进阶
一句话结论
超出模型单次条数或 token 上限会整批或部分失败;应按上限切小批,失败条目隔离重试,记录原因与原始文本便于补写。
概念解释
- 上限:单次条数、token 总量、单条长度限制。
- 失败类型:整批拒绝、部分截断、单条超长。
- 处置:小批重试、超长拆分、隔离不可重试条目。
原理流程
待向量化列表 → 按上限切批 → 调用模型 → 成功收集 / 失败记录 → 隔离队列补写
代码 / 命令
# 配置:批大小、单条长度上限、重试次数与退避
# 记录:失败标识、原因、时间,供后续补写
常见误区
- 误区:整批失败全部重跑。正解:定位失败条目小批重试,避免重复向量化。
- 误区:超长文本静默截断即可。正解:截断破坏语义,需评估或拆分后入库。
追问
- 问:模型限流返回 429 怎么办?答:退避降速、缩小批大小,不持续重打。
- 问:怎么统计 Embedding 失败率?答:按批次记录成功 / 失败条数,纳入入库指标。
05.6.11.3-040 常见坑:版本冲突导致类加载错误如何排查?
频率 ★★★☆☆ | 难度 高级
一句话结论
版本冲突表现为类缺失、方法签名不符或加载错误,排查从依赖树入手定位被仲裁版本,核对 BOM 与适配包兼容范围,预发回归后再上线。
概念解释
- 表现:NoSuchMethod 类错误、类找不到、签名不匹配。
- 来源:主框架、适配包、底层 SDK 版本错配。
- 处理:对齐兼容版本,清理冲突依赖。
原理流程
报错信息定位类 / 方法 → 分析依赖树与仲裁版本 → 对齐 BOM 与适配版本
→ 预发回归 → 观察线上
代码 / 命令
# 待确认:当前版本兼容范围以官方发布说明为准
# 检查:依赖树中同一构件是否存在多版本
常见误区
- 误区:报错是运行环境偶发问题。正解:版本冲突通常稳定复现,先查依赖组合。
- 误区:只看编译通过即可。正解:兼容问题常在运行期反射 / 动态调用时暴露。
追问
- 问:如何锁定兼容组合?答:跟随官方 BOM 版本,适配包不单独随意升级。
- 问:升级后行为变化怎么排查?答:跑标准写入 / 检索用例,对比返回结构与召回结果。
05.6.11.3-041 与 MyBatis / JPA 业务数据如何联动?
频率 ★★★☆☆ | 难度 进阶
一句话结论
业务数据由 ORM 持久化到业务库,向量库保存派生索引;联动通过业务文档 id 关联,业务状态变更驱动向量写入与删除,两边对账兜底。
概念解释
- 权威源:业务库保存完整业务记录与状态。
- 派生索引:向量库保存片段、向量与 metadata 关联。
- 关联键:doc_id 贯穿两侧。
原理流程
ORM 写业务库 → 提交后取文档 id → 构造片段写向量库
→ 状态下线触发删除 → 对账比对两侧标识
代码 / 命令
# 关联字段:业务主键 / 文档 id 写入向量 metadata
# 对账:业务库有效文档集合与向量库标识集合求差集
常见误区
- 误区:向量库保存业务主数据。正解:业务记录以 ORM 库为准,向量库可重建。
- 误区:ORM 事务内同步写向量库。正解:跨库一致性靠提交后补偿,不用本地事务。
追问
- 问:业务字段更新如何同步向量?答:按变更字段判断是否影响片段内容,必要时重建对应文档向量。
- 问:ORM 模型里要不要存向量字段?答:通常不存,向量在专用库;业务库只保留关联 id 与版本。
05.6.11.3-042 多模态向量(如有)的配置边界是什么?
频率 ★★☆☆☆ | 难度 进阶
一句话结论
多模态向量化能力取决于所用 Embedding 模型与底层向量库支持;接入前核对模型输入类型、向量维度与库的多模态存储能力,不在文档中假设无条件支持。
概念解释
- 前提:模型支持图片 / 文本等多模态输入,目标库可存对应向量。
- 边界:不同适配对多模态的覆盖程度不同。
- 验证:用真实多模态样本跑通写入与检索。
原理流程
核对模型输入类型 → 核对底层库多模态能力 → 构造多模态 Document
→ 写入检索验证 → 记录维度与模型标识
代码 / 命令
# 待确认:当前 Spring AI 版本与目标库支持的多模态形态以官方文档为准
# 不假设:未验证前不写入多模态混合方案结论
常见误区
- 误区:文本向量方案可直接套用于图片。正解:模型与存储能力都需单独核对。
- 误区:多模态向量与文本向量可同集合混用。正解:维度与空间不同,需隔离存储。
追问
- 问:多模态检索怎么评估?答:按对应模态标注样本验证召回,不套用文本指标口径。
- 问:能力不足时怎么降级?答:退回文本模态,图片信息经描述文本入库。
05.6.11.3-043 灰度切换向量库或模型的 Bean 方案怎么做?
频率 ★★★☆☆ | 难度 高级
一句话结论
灰度通过可切换的 Bean 路由实现:新旧两套 VectorStore / 模型并存,按租户或比例路由,影子读对比结果,验证后逐步切流并保留回滚路径。
概念解释
- 双实例:新旧配置各自构造 Bean,按标识注册。
- 路由:业务层按规则选择实例,支持比例与维度切流。
- 回滚:旧 Bean 与配置保留观察周期。
原理流程
装配新旧 Bean → 影子读旁路对比 → 按租户 / 比例切流 → 指标观察 → 全量切换 → 下线旧实例
代码 / 命令
# 路由记录:命中实例、版本标识、对比指标
# 回滚:配置切回旧 Bean 标识,旧向量保留至稳定
常见误区
- 误区:灰度直接全量切换再回滚。正解:向量重建成本高,应小流量验证后逐步切。
- 误区:只看接口成功率判断灰度。正解:检索质量差异不一定报错,需对比召回与排序。
追问
- 问:双写期间如何保证一致?答:按文档标识幂等写入,定时对账两侧数量与版本。
- 问:灰度指标看什么?答:召回命中、排序质量、P99 延迟、错误率与成本。
05.6.11.3-044 压测要点:JVM、连接池与慢查询如何观测?
频率 ★★★☆☆ | 难度 进阶
一句话结论
压测覆盖检索 QPS、延迟分布、连接池水位与 JVM 指标,使用与真实分布一致的数据集,记录 P99 而非只看平均值。
概念解释
- 数据集:规模、维度、分布与真实语料一致。
- 资源指标:连接池、线程池、CPU、内存、GC。
- 延迟口径:P50/P99/错误率,分场景与租户。
原理流程
构造压测数据集 → 阶梯加压 → 采集延迟 / 资源 / 池水位 → 定位瓶颈 → 调参回归
代码 / 命令
# 观测:检索 P99、连接池活跃 / 等待、线程队列、CPU 与 GC
# 标准:目标 QPS 下 P99 与召回达标,资源有余量
常见误区
- 误区:用随机向量压测即可。正解:分布与维度不符,压测结论不可靠。
- 误区:平均延迟达标即可上线。正解:P99 才反映真实体验,需单独关注。
追问
- 问:连接池瓶颈怎么判断?答:看等待队列与获取连接耗时,池不足时延迟随并发上升。
- 问:JVM 哪些指标要看?答:堆使用、GC 频次与停顿、线程数,定位内存与停顿问题。
05.6.11.3-045 错误分类:连接失败、写入失败、检索超时如何区分?
频率 ★★☆☆☆ | 难度 基础
一句话结论
错误按连接、写入、检索三类分别识别:连接问题看端点与凭据,写入问题看批次与 schema,检索超时看候选规模与资源;分类后分别重试或降级。
概念解释
- 连接失败:端点不可达、凭据失效、网络策略。
- 写入失败:维度不符、字段类型、批量超限、主键冲突。
- 检索超时:候选过大、过滤低效、资源饱和。
原理流程
捕获异常 → 归类错误类型 → 匹配可重试性 → 重试 / 隔离 / 降级 → 记录错误指标
代码 / 命令
# 分类记录:错误类型、发生环节、请求标识、下游错误码
# 处置:可重试错误退避重试;不可重试进隔离队列
常见误区
- 误区:所有异常走同一重试逻辑。正解:错误类型决定是否可重试与处置方式。
- 误区:错误信息直接暴露给用户。正解:对外返回兜底提示,细节进内部日志。
追问
- 问:连接失败怎么快速验证?答:用同凭据在运行环境直连端点做小请求测试。
- 问:写入部分失败怎么对账?答:按返回 id 与入参比对,缺失条目进入补写批次。
05.6.11.3-046 降级策略:检索不可用时的兜底怎么做?
频率 ★★★☆☆ | 难度 进阶
一句话结论
检索不可用时按级别降级:放宽参数、跳过重排、返回缓存或热门内容、明确无依据提示,保证主链路不被拖垮。
概念解释
- 降级层级:缩小候选、关闭重排、缓存兜底、静态内容、提示转人工。
- 保护目标:避免下游雪崩,保留基本可用。
- 开关:降级策略可配置并定期演练。
原理流程
压力 / 故障触发 → 降级开关生效 → 逐级降级 → 恢复后逐级放开 → 记录降级事件
代码 / 命令
# 客户端配合:超时 + 熔断 + 退避重试
# 兜底结果:缓存答案、热门文档、无依据提示、工单入口
常见误区
- 误区:降级会伤害体验所以不做。正解:整体超时比降级结果更差。
- 误区:只在服务端限流。正解:客户端重试不节制会放大压力,需两侧配合。
追问
- 问:降级开关怎么验证有效?答:定期故障演练,确认降级路径真实生效。
- 问:检索结果质量下降时是否降级?答:低分 / 空结果先走兜底提示,不强行喂噪声上下文。
05.6.11.3-047 配置校验在启动期如何快速暴露问题?
频率 ★★☆☆☆ | 难度 进阶
一句话结论
启动期校验必填配置、维度与模型标识、集合连通性,非法配置直接初始化失败并给出明确提示,避免问题推迟到请求阶段暴露。
概念解释
- 校验项:连接配置、模型与维度、凭据非空、必填属性。
- 连通性:启动时轻量探测目标库可达性(按环境决定是否启用)。
- 失败表现:明确错误信息与缺失项,便于排障。
原理流程
应用启动 → 配置绑定 → 校验必填与一致性 → 探测连通 → 装配 Bean
→ 校验失败终止启动并提示
代码 / 命令
# 校验清单:端点、凭据、集合名、模型标识、维度、超时与批参数
# 待确认:框架内置校验能力以当前版本文档为准
常见误区
- 误区:配置缺失留空运行即可。正解:启动期失败优于线上请求报错。
- 误区:启动探测影响冷启动。正解:可按环境开关,生产保留必要连通校验。
追问
- 问:校验失败怎么提示?答:指出缺失项与期望格式,不打印敏感值。
- 问:多套配置如何分别校验?答:按环境 / 业务域分组校验对应配置项。
05.6.11.3-048 一套 Spring AI RAG 接入清单是什么?
频率 ★★★★★ | 难度 高级
一句话结论
按「模型与向量库选型 → ETL 入库 → 检索与 Advisor 编排 → 配置与生命周期 → 增量对账与观测 → 灰度兜底」推进,每步有验证指标与回滚路径。
概念解释
- 输入:语料规模、语种、过滤与权限维度、QPS 与 SLA。
- 关键决策:Embedding 模型、VectorStore 适配、切分策略、检索参数、重排方式。
- 交付物:入库流水线、检索链路、配置 Bean、增量对账、观测看板、降级与回滚方案。
原理流程
1) 梳理语料与 SLA 2) 验证模型与后端召回 3) 切块 / metadata / 批量入库
4) 配置检索参数、filter 与 Advisor 5) 接入观测与超时熔断
6) 增量更新与对账 7) 评估集回归与灰度切流 8) 备份回滚与成本监控
代码 / 命令
# 面试表达:先讲假设与规模 → 各环节选型理由 → 指标与验证方式 → 运维兜底
# 验收用例:写入、检索、过滤、删除、增量更新、空结果、超时降级 各跑通一条
常见误区
- 误区:接入就是调通检索接口。正解:入库质量、增量维护、观测与兜底才是工程主体。
- 误区:框架默认配置可直接上生产。正解:切块、批大小、阈值与并发都需自有样本验证。
追问
- 问:上线后召回退化怎么响应?答:核查入库量、模型与配置变更,跑评估集回归,必要时回滚版本。
- 问:成本怎么控制?答:监控 Embedding 调用量、向量存储与检索 QPS,按访问频率分层存储。
参考来源
- Spring AI 官方参考文档:https://docs.spring.io/spring-ai/reference/
- Spring AI 官方仓库:https://github.com/spring-projects/spring-ai
- Spring AI VectorStore 抽象说明:https://docs.spring.io/spring-ai/reference/api/vectordbs.html
- Spring AI Advisors 文档:https://docs.spring.io/spring-ai/reference/api/advisors.html