赵阳的技术博客

智枢项目复盘：从 0 到 1 构建 RAG 知识管理平台

Wed, 18 Feb 2026 00:00:00 +0000

项目背景

在企业场景中，知识分散在各种格式的文档中（PDF、Word、PPT 等），员工查找信息效率低下。传统的关键词搜索无法理解语义，经常找不到真正需要的内容。

智枢是一个基于 RAG（Retrieval-Augmented Generation）架构的企业级智能知识管理平台，支持多格式文档上传、解析与向量化，用户可以通过自然语言进行智能问答。

🔗 线上演示：rag.canggo.com

整体架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11



用户 → Nginx → Spring Boot Application
 ├── MinIO（对象存储）
 ├── Redis（缓存 / 分布式锁 / 会话管理）
 ├── Kafka（异步消息队列）
 │ └── 消费者 → Apache Tika（文档解析）
 │ → 通义千问 Embedding（向量化）
 │ → Elasticsearch（向量索引）
 ├── Elasticsearch（混合检索引擎）
 ├── DeepSeek API（大语言模型）
 └── WebSocket（流式对话推送）

核心技术难点

一、大文件异步处理流水线

用户上传的文档可能非常大（几百 MB 甚至 1GB），同步处理会直接阻塞请求。

解决方案：

基于 Redis BitMap 记录每个分片的上传状态，配合 MinIO 存储分片文件，实现断点续传
通过文件 MD5 实现秒传：相同文件直接复用，避免重复上传
采用 MinIO composeObject API 实现服务端零拷贝合并，文件数据完全不经过 Java 服务，1GB 文件合并耗时缩短至 3s 内
合并完成后通过 Kafka 异步解耦后续的解析与向量化流程

1
2
3
4
5
6
7
8


// Redis BitMap 标记分片状态
redisTemplate.opsForValue().setBit(
 "upload:chunks:" + md5, chunkIndex, true);

// 零拷贝合并
try (FileChannel source = FileChannel.open(chunkPath, READ)) {
 source.transferTo(0, source.size(), targetChannel);
}

关于大文件上传方案的完整设计，详见大文件断点续传方案设计

二、混合检索与 RAG 增强

单纯的向量检索在短查询场景下表现不佳，单纯的关键词检索又无法理解语义。

方案：KNN 向量召回 + BM25 关键词重排序

通过通义千问 Embedding 模型将文档和查询都转为 2048 维向量
KNN 余弦相似度召回语义相关的候选文档
BM25 对候选文档进行关键词相关性重排序
取 Top-K 结果拼接为上下文，构建增强 Prompt 送入大模型

1
2
3
4
5
6


// 混合检索：KNN 召回 + BM25 重排序
KnnSearchBuilder knn = new KnnSearchBuilder(
 "embedding_vector", queryVector, 10, 100, null);

Query bm25Query = QueryBuilders.match()
 .field("content").query(userQuery).build()._toQuery();

三、流式对话与服务降级

通过 WebSocket 长连接集成 DeepSeek Stream API，实现"打字机式"逐字生成体验。

关键设计 — 自动降级机制： 当向量 API 不可用时，自动降级至纯 BM25 文本搜索，保障服务可用性。

1
2
3
4
5
6


try {
 results = vectorSearch(query);
} catch (VectorApiException e) {
 log.warn("向量检索异常，降级为文本搜索", e);
 results = bm25Search(query); // 自动降级
}

四、细粒度权限管控

基于 Spring Security 实现 RBAC 权限模型，从角色、组织、文档多维度进行访问控制。

采用 JWT 双令牌架构（Access Token + Refresh Token），Access Token 短期有效（30 分钟），Refresh Token 长期有效（7 天），配合前端拦截器实现无感刷新。

收获与反思

异步设计是处理耗时任务的核心思路，Kafka 在解耦方面表现优秀
混合检索比单一检索方式效果好很多，融合策略的权重调优是关键
降级机制在依赖外部 API 的系统中必不可少
如果重新做，会考虑引入更细粒度的文本切分策略（如语义分段），提升长文档的检索精度

AI 智能体脚手架：多 Agent 编排框架的设计与实现

Sun, 15 Mar 2026 00:00:00 +0000

为什么要做这个框架？

随着大语言模型能力的提升，单个 Agent 已经无法满足复杂业务场景。多个 Agent 需要协同工作：一个负责意图理解，一个负责信息检索，一个负责内容生成…

目前主流的 Agent 框架（LangChain、AutoGen）大多基于 Python 生态，Java/Spring 生态缺乏成熟的多 Agent 编排方案。这个脚手架的目标是：通过 YAML 配置就能快速搭建多 Agent 协同应用。

🔗 线上演示：agent.canggo.com

整体架构（DDD 分层）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18



┌──────────────────────────────────────────────┐
│ Interface Layer（接口层） │
│ └── REST API / SSE 流式端点 │
├──────────────────────────────────────────────┤
│ Application Layer（应用层） │
│ └── 编排执行服务 / 会话管理 │
├──────────────────────────────────────────────┤
│ Domain Layer（领域层） │
│ ├── Agent 聚合根 │
│ ├── 编排策略（顺序 / 并行 / 路由） │
│ └── 工具 & 技能注册中心 │
├──────────────────────────────────────────────┤
│ Infrastructure Layer（基础设施层） │
│ ├── Spring AI 适配器 │
│ ├── Google ADK 适配器 │
│ └── MCP 工具连接器 │
└──────────────────────────────────────────────┘

核心设计

一、双框架协同：Spring AI + Google ADK

这是框架最核心的设计挑战 —— 如何抹平两个 AI 框架的差异：

Google ADK 提供了优秀的 Agent 编排引擎和会话管理
Spring AI 提供了丰富的模型接入能力和工具执行机制

设计了适配层来桥接两者，上层复用 ADK 编排能力，下层复用 Spring AI 模型接入：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


public class SpringAiLlmAdapter implements LlmClient {

 private final ChatModel chatModel;

 @Override
 public ChatResponse call(Prompt prompt) {
 return chatModel.call(toSpringAiPrompt(prompt));
 }

 @Override
 public Flux<ChatResponse> stream(Prompt prompt) {
 return chatModel.stream(toSpringAiPrompt(prompt));
 }
}

二、YAML 声明式编排

通过 YAML 配置文件定义 Agent 及其编排关系，框架读取配置后自动完成 Bean 装配：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


agents:
 - id: intent-analyzer
 model: deepseek-chat
 system-prompt: "你是一个意图分析器..."

 - id: knowledge-retriever
 model: deepseek-chat
 tools: [search-tool, database-tool]

orchestration:
 type: sequential
 steps:
 - agent: intent-analyzer
 - agent: knowledge-retriever
 condition: "#{intent == 'query'}"

基于策略路由树解析 YAML，编排节点通过计数器遍历、类型路由与动态 Bean 回跳实现逻辑循环，支持顺序、并行、路由三种编排类型的任意嵌套组合。

三、MCP 工具统一接入

基于工厂模式统一对接三类 MCP 工具源：

类型	说明	示例
Remote SSE	远程 MCP 服务	联网搜索、API 调用
Local CLI	本地命令行工具	代码执行、文件操作
Local Java	Java 组件	业务逻辑、数据查询

所有工具统一构建为技能列表注入模型，由框架自动完成多轮工具调用。

四、响应式流设计

流式模式：SSE + RxJava3 桥接 Reactor 响应式流，逐块推送
非流式模式：阻塞收集所有结果后统一返回
两种模式共享同一套装配产物，通过 Spring IOC 动态 Bean 注册实现装配与运行的解耦

1
2
3
4
5
6
7


@GetMapping(value = "/chat/stream",
 produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<ServerSentEvent<String>> streamChat(
 @RequestParam String message) {
 return agentService.streamExecute(message)
 .map(chunk -> ServerSentEvent.builder(chunk).build());
}

落地验证：AI + Draw.io

基于该脚手架落地了一个 AI + Draw.io 交互式绘图应用，用户通过自然语言描述即可生成流程图。只需编写新的 YAML 配置和绘图工具实现，无需修改框架代码。这验证了框架的扩展性。

总结

抽象是关键 — 好的适配层能让不同框架无缝协作
配置驱动 > 代码驱动 — YAML 声明式配置大幅降低接入成本
响应式编程 在流式对话场景下体验远优于传统阻塞式方案

你好世界 | 博客开张了

Sun, 01 Feb 2026 00:00:00 +0000

博客开张 🎉

你好！我是赵阳，一名 Java 后端开发者，目前就读于郑州轻工业大学计算机科学与技术专业（2027 届）。

这个博客主要用来记录我在后端开发和 AI 工程化方面的学习和实践，内容会围绕以下方向展开：

内容方向

项目实战总结 — 记录项目中的架构设计与技术难点
Java & Spring 生态 — 框架原理、源码分析
数据库 — MySQL 调优、Redis 原理与应用
中间件 — Kafka、Elasticsearch 实战经验
AI 工程化 — RAG、Agent 编排等 AI 应用落地
系统设计 — 高并发、高可用架构思考

我的项目

目前完成了两个比较完整的项目：

智枢 — 企业智能知识管理系统 — 基于 RAG 架构，支持多格式文档上传、向量化检索与智能问答
AI 智能体脚手架 — 基于 DDD 的多 Agent 编排框架，支持 YAML 声明式配置

持续更新中，欢迎交流 :)

AI 智能体脚手架：从 YAML 配置到多 Agent 协同的工程实践

Mon, 20 Apr 2026 00:00:00 +0000

这个项目要解决的问题是：怎么用一份 YAML 配置文件，就自动组装出一个能跑的、支持多智能体协同的 AI Agent？

听起来简单，实际做起来涉及两套框架的适配、多模态消息的格式转换、会话上下文的维持、流式传输……坑还挺多的。

本文把整个项目的核心设计从头到尾梳理一遍。

一、整体架构：DDD 分层

项目用的是 DDD 领域驱动设计，不是传统的 MVC。核心区别就一句话：MVC 里服务层依赖数据访问层，是正向依赖；DDD 里领域层定义接口，基础设施层去实现，是依赖倒置。

一共 6 个模块：

┌─────────────────────────────────────────────────────┐ │ 启动层（app） │ │ Spring Boot 启动入口 + 监听器 + 线程池配置 │ ├─────────────────────────────────────────────────────┤ │ 触发层（trigger） │ │ HTTP 控制器，接收前端请求，调用领域层 │ ├─────────────────────────────────────────────────────┤ │ 接口契约层（api） │ │ 只定义接口 + DTO，不写任何实现 │ ├─────────────────────────────────────────────────────┤ │ 领域层（domain）⭐ 核心 │ │ 装配链路、对话服务、适配器、消息转换器 │ ├─────────────────────────────────────────────────────┤ │ 基础设施层（infrastructure） │ │ 实现领域层定义的接口（数据库、外部API等） │ ├─────────────────────────────────────────────────────┤ │ 公共类型层（types） │ │ 枚举、异常类、常量 │ └─────────────────────────────────────────────────────┘

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15



为什么接口契约层和触发层要分开？因为接口契约层定义的是**对外的 API 契约**，将来如果要从 HTTP 换成 RPC，只需要新增一个触发层实现，接口契约层完全不动。而且其他服务要调用我们，只需要依赖这一个契约模块，不会碰到任何实现代码。

## 二、双框架适配：为什么要同时用两个框架

这个项目同时用了 Google ADK 和 Spring AI，各取所长：

| 框架 | 擅长的事 | 在项目中的角色 |
|------|---------|---------------|
| Google ADK | 多智能体编排、会话管理 | 上层，管调度 |
| Spring AI | 多模型接入、工具自动执行 | 下层，管调用 |

问题来了：两套框架的消息格式不一样。ADK 用的是 Content / Part 结构，Spring AI 用的是 Prompt / Message 结构。所以中间需要一个适配器来做转换。

这个适配器是整个项目的**枢纽**，它的核心方法做三件事：

SDK 格式的消息 ──→ 【消息转换器】 ──→ Spring AI 格式 ↓ 根据流式标志选择调用方式流式 → stream() 非流式 → call() ↓ Spring AI 格式的响应 ──→ 【消息转换器】 ──→ SDK 格式返回

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19



## MySpringAI 适配器

### 为什么需要它

`LlmAgent` 来自 Google ADK 框架，它要求的模型接口是 `LlmModel`（Google 自己定义的）。`ChatModel` 来自 Spring AI 框架，方法名、参数类型、返回类型全都不一样。直接把 `ChatModel` 塞给 `LlmAgent`，编译都过不了。

`MySpringAI` 就是一个翻译官（适配器），对上实现 Google ADK 的 `LlmModel` 接口，对下内部调用 Spring AI 的 `ChatModel` 方法：

```java
public class MySpringAI implements LlmModel {
 private final ChatModel chatModel; // 内部持有 Spring AI 的模型

 public LlmResponse generate(LlmRequest request) {
 Prompt springPrompt = convertToSpringPrompt(request); // Google格式 → Spring格式
 ChatResponse response = chatModel.call(springPrompt); // 用Spring AI真正调LLM
 return convertToAdkResponse(response); // Spring格式 → Google格式
 }
}

放在 patch 包里，说明是对 Google ADK 官方适配器 SpringAI 的补丁版本——可能修了 bug，可能加了自定义逻辑。

项目背景

这个项目要做的事情说起来就一句话：从一份 YAML 配置文件出发，自动组装出一台能让 20 个 AI 智能体协作运转的机器，然后注册到 Spring 容器里等着被调用。

听起来不复杂，但实际上组装过程涉及 API 连接创建、聊天模型构建、工具挂载、20 个基础 Agent 创建、8 个不同类型的工作流编排、还有嵌套引用……如果把这些逻辑全塞进一个大方法里，估计得写 500 行，改一个步骤就得在这 500 行里翻来翻去，以后想加个新步骤更是噩梦。

所以项目用了规则树这种设计模式，把整个组装过程拆成一个个独立的节点，像流水线一样一站接一站地执行。每个节点只管自己的事，干完活就告诉框架"下一站去哪"。

三、装配链路：从 YAML 到可运行的智能体

3.1 触发阶段

Spring Boot 启动时把 YAML 里的属性自动映射到配置类。启动完成后发出一个"应用就绪"事件，监听器捕获到后取出所有智能体的配置列表，传给装配服务。

3.2 责任链执行

装配链路是一条 6 节点的责任链，每个节点只做一件事，通过动态上下文对象传递中间产物：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30



根节点（空节点，哨兵）
 │
 ▼
API 节点
 │ 读取配置中的 URL 和密钥
 │ 创建 API 连接对象 → 存入上下文
 ▼
模型节点
 │ 取出 API 连接 + 模型名称
 │ 遍历 MCP 工具列表（远程SSE/本地命令行/本地JavaBean）
 │ 遍历 Skills 技能文件（文档+脚本）
 │ 所有工具统一构建为 ToolCallback → 放入同一个列表
 │ 创建 ChatModel 对象 → 存入上下文
 ▼
智能体节点
 │ 遍历配置中的每个智能体
 │ 取名称、描述、提示词、输出键
 │ 用适配器包装 ChatModel
 │ 创建 LLMAgent → 存入上下文的 Map 集合
 ▼
编排节点（1 主节点 + 3 子节点，逻辑循环）
 │ 详见 3.3 节
 ▼
运行器节点
 │ 取出配置指定的入口智能体
 │ 创建 InMemoryRunner
 │ 包装成注册对象 → 动态注册为 Spring Bean
 ▼
 装配完成 ✓

3.3 编排节点的逻辑循环

这是最复杂的节点。主节点和三个子节点之间形成了一种循环结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21



 ┌──────────────┐
 │ 主节点 │
 │ │
 │ 计数器 >= 总数?│──── 是 ────→ 运行器节点
 │ │
 │ 否，按类型 │
 │ 路由到子节点 │
 └──┬───┬───┬───┘
 │ │ │
 ┌──────┘ │ └──────┐
 ▼ ▼ ▼
 串行子节点 并行子节点 循环子节点
 │ │ │
 └──────┬───┘──────────┘
 │
 │ 创建完 → 存入集合 → 路由回主节点
 ▼
 ┌──────────────┐
 │ 主节点 │ ← 继续循环
 └──────────────┘

三个子节点的路由方法都指回主节点，但这里有个工程细节——子节点不能用字段注入来引用主节点，否则会和主节点形成循环依赖，Spring 启动直接报错。所以子节点用的是运行时动态获取：

1
2
3
4
5
6
7


// 子节点的路由方法
@Override
public StrategyHandler get(...) {
 // 不用 @Resource 注入，而是运行时从容器取
 // 因为主节点持有子节点引用，子节点再注入主节点就循环了
 return getBean("agentWorkflowNode");
}

字段注入在 Bean 初始化阶段就要拿到引用，此时对方可能还没创建完；动态获取是在运行时去容器里取，这时候所有 Bean 早就创建好了。

另外，编排智能体和普通的 LLM 智能体实现了同一个接口，所以可以放在同一个 Map 里。先创建的编排智能体可以被后创建的引用——这就是嵌套编排的实现原理。比如先创建一个并行编排，后面的串行编排可以把它当子节点用。

3.4 动态上下文里装了什么

1
2
3
4
5
6
7



DynamicContext（共享黑板）
├── API 连接对象 ← API 节点写入，模型节点读取
├── ChatModel 对象 ← 模型节点写入，智能体节点读取
├── 智能体 Map 集合 ← 智能体节点 + 编排节点共同写入
├── 编排步骤计数器 ← 编排节点用来控制循环
└── 当前编排配置 ← 编排节点用来判断类型和路由

每个智能体的装配都用一个全新的空上下文，多个智能体之间完全隔离。

3.5 为什么用责任链而不是写一个大方法

四个字：开闭原则。

想在装配流程中加一个新的处理步骤？新建一个节点类，改一下前后节点的路由指向，原有节点一行不动。如果是大方法，要在几百行代码中间找位置插入，还得处理变量作用域冲突。

还有一个很实际的好处：如果第 5 个节点需要第 2 个节点产生的数据，直接从上下文里读就行。如果用节点间传参，这个数据就得在第 3、第 4 个节点一路透传过去，中间节点被迫携带自己根本不需要的参数。

谁是 Bean 谁不是

这个点特别容易混淆，单独拎出来说清楚：

是 Bean 的：

AiAgentAutoConfigProperties（@EnableConfigurationProperties 注册的）
所有 @Service 标记的节点类（RootNode、AiApiNode 等等）
AiAgentRegisterVO（RunnerNode 里手动 registerBean() 注册的，整条流水线唯一一次手动注册）

不是 Bean 的：

AiAgentConfigTableVO（只是配置类 Bean 里的一个字段值，不能被 @Resource 注入）
ArmoryCommandEntity（每次调用时 new 出来的参数"信封"）
DynamicContext（每次调用时 new 出来的上下文"托盘"）
流水线中间创建的所有对象（OpenAiApi、ChatModel、LlmAgent、LoopAgent 等等）

一句话记：配置类（Properties）生出配置数据（TableVO），配置数据装进信封（CommandEntity），信封送进流水线。

MCP/Skills 工具创建细节

为什么需要工具

模型只会"说话"，不会"做事"。工具让模型能调用外部能力——搜索网页、读取文件、调用本地 Java 方法等等。不管工具从哪来，最终都要变成 Spring AI 统一的 ToolCallback 类型。

三种 MCP 工具类型

类型	通信方式	比喻
SSE	HTTP 长连接到远程服务器	打电话给远程专家
Stdio	启动本地子进程，通过标准输入输出通信	在电脑上开一个助手程序
Local	直接从 Spring 容器取 Bean	找身边的同事帮忙

工厂 DefaultMcpClientFactory 判断 ToolMcp 对象里 sse/local/stdio 三个字段哪个不为 null，就返回对应的创建服务——因为 YAML 的结构决定了每个 MCP 配置只会有一个子字段有值。

Skills 工具

Skills 是写在文件里的工具描述（比如 Markdown 格式），有两种加载方式：

1
2
3
4
5
6
7
8


if ("directory".equals(type)) {
 // 从文件系统绝对路径加载——适合本地开发
 SkillsTool.builder().addSkillsDirectory(path).build();
}
if ("resource".equals(type)) {
 // 从 classpath 资源路径加载——适合打包部署
 SkillsTool.builder().addSkillsResource(new ClassPathResource(path)).build();
}

一个 Java 小知识：`toArray(new ToolCallback[0])`

这是 Java 里把 List 转成指定类型数组的惯用写法。传 new ToolCallback[0] 不是为了用这个空数组装东西，纯粹是告诉 Java “我要的数组类型是 ToolCallback”——因为泛型在运行时会被擦除，List 不知道自己装的是什么类型。

直觉上传正确大小的 new ToolCallback[list.size()] 应该更快，但实际上传空数组反而更快：JIT 编译器能识别出 toArray 内部"创建数组后立刻被完全覆盖"的模式，直接跳过无意义的零初始化。而外部创建的数组 JIT 不敢优化，零初始化白白浪费了。

装配流水线的完整链路

整体结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26



YAML（原材料）
 │
 ▼
第1站 RootNode → 纯入口，像链表头指针，什么都不做
 │
 ▼
第2站 AiApiNode → 创建 OpenAiApi（API连接对象）
 │
 ▼
第3站 ChatModelNode → 创建 ChatModel（聊天模型 + MCP/Skills工具）
 │
 ▼
第4站 AgentNode → 创建 20 个基础 LlmAgent，全部放入 agentGroup 货架
 │
 ▼
第5站 AgentWorkflowNode → 循环处理 8 个工作流配置，每次根据类型分发到子节点
 │ ├── LoopAgentNode → 处理 loop 类型 → 回到 AgentWorkflowNode
 │ ├── ParallelAgentNode → 处理 parallel 类型 → 回到 AgentWorkflowNode
 │ └── SequentialAgentNode → 处理 sequential 类型 → 回到 AgentWorkflowNode
 │
 ▼
第6站 RunnerNode → 取出最终入口 Agent，包装成 InMemoryRunner，注册到 Spring
 │
 ▼
成品：AiAgentRegisterVO（包着 runner 的信封）

启动入口

Spring Boot 启动完成后，AiAgentAutoConfig 监听到 ApplicationReadyEvent 事件，自动触发装配：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@Configuration
@EnableConfigurationProperties(AiAgentAutoConfigProperties.class)
public class AiAgentAutoConfig implements ApplicationListener<ApplicationReadyEvent> {

 @Override
 public void onApplicationEvent(ApplicationReadyEvent event) {
 // 从配置类（Bean）里取出配置数据（不是Bean，只是普通Java对象）
 // 传给装配服务开始组装
 armoryService.acceptArmoryAgents(
 new ArrayList<>(aiAgentAutoConfigProperties.getTables().values()));
 }
}

这里有个容易混淆的点：AiAgentAutoConfigProperties 是 Bean（被 @EnableConfigurationProperties 注册的），但它里面的 AiAgentConfigTableVO 不是 Bean——只是 Spring Boot 用 new 创建出来填充字段的普通 Java 对象。就像"箱子在货架上有登记，但箱子里的东西没有单独登记"。

上下文：DynamicContext

上下文是自己定义的，不是框架提供的。它就是一个跟着流水线走的"托盘"，每个节点都能往上面放东西、从上面拿东西：

1
2
3
4
5
6
7


public static class DynamicContext {
 private OpenAiApi openAiApi; // 第2站放入
 private ChatModel chatModel; // 第3站放入
 private Map<String, BaseAgent> agentGroup = new HashMap<>(); // 第4站开始持续放入
 private AtomicInteger currentStepIndex = new AtomicInteger(0); // 第5站的循环计数器
 private AgentWorkflow currentAgentWorkflow; // 第5站每次循环覆盖写入
}

第5站：最复杂的 AgentWorkflowNode

这个节点是整棵规则树里最精妙的部分。前面 4 站都是直线走下去，到这里开始出现循环 + 分支。

循环不是用 for/while 实现的，而是通过 currentStepIndex 计数 + 子节点回指自身来形成逻辑上的循环：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// AgentWorkflowNode.doApply() 核心逻辑
if (dynamicContext.getCurrentStepIndex() >= agentWorkflows.size()) {
 // 全部处理完了，跳到 RunnerNode
 dynamicContext.setCurrentAgentWorkflow(null);
 return router(requestParameter, dynamicContext);
}
// 取出当前索引对应的 workflow，放入上下文
dynamicContext.setCurrentAgentWorkflow(agentWorkflows.get(dynamicContext.getCurrentStepIndex()));
dynamicContext.addCurrentStepIndex(); // 索引 +1
return router(requestParameter, dynamicContext);

get() 方法根据 workflow 的 type 字段决定分支走向：

1
2
3
4
5
6


return switch (node) {
 case "loopAgentNode" -> loopAgentNode;
 case "parallelAgentNode" -> parallelAgentNode;
 case "sequentialAgentNode" -> sequentialAgentNode;
 default -> runnerNode;
};

三个子节点处理完后都回到 AgentWorkflowNode——它们的 get() 都写的 return getBean("agentWorkflowNode")。用 getBean() 而不是 @Resource 是为了避免循环依赖。

嵌套的秘密：agentGroup

所有 Agent（不管是基础的 LlmAgent 还是组装好的 LoopAgent/ParallelAgent/SequentialAgent）都放在同一个 agentGroup 这个 Map 里。后面的 workflow 可以通过名字引用前面已经组装好的 workflow，因为它们继承自同一个父类 BaseAgent，类型是兼容的。

这就是为什么 YAML 里 workflow 的声明顺序必须正确——先被引用的必须先创建。如果顺序乱了，queryAgentList() 按名字去 agentGroup 里取的时候会取不到，被直接跳过，导致组装出来的 Agent 树缺胳膊少腿。

规则树到底是什么

一句话定义

规则树 = 策略模式 + 责任链模式 + 组合模式的混合体。每个节点是一个独立策略，节点之间通过路由串成链，某些节点还能根据条件分叉出不同的分支，形成树形结构。

为什么叫"树"不叫"链"

如果每个节点的下一站都是固定的，那就是一条链。但这个项目里有一个关键节点 AgentWorkflowNode，它会根据工作流的类型动态决定下一站去哪——是 loop 就去 LoopAgentNode，是 parallel 就去 ParallelAgentNode，是 sequential 就去 SequentialAgentNode。这就产生了分支，画出来就是一棵树。

为什么不写一个大方法

不是做不到，是做完之后没法维护。任何用规则树实现的逻辑，用一个大方法都能实现，甚至可能 200 行就写完了。但规则树的价值不在于"能不能实现"，而在于"实现之后好不好改"。每个步骤独立成类，想改某一步就只改那一个类，想插入新步骤就写个新类改一下前后节点的指向，想删掉某个步骤就删类改指向——团队协作时多人改不同的节点类也不会冲突。

四、装配与运行的衔接

装配阶段的最终产物是一个注册对象，里面包含智能体 ID、名称、描述和内存运行器。

内存运行器持有四样东西：

1
2
3
4
5
6



InMemoryRunner
├── 入口智能体 （可以是 LLMAgent 也可以是编排智能体）
├── 智能体名称
├── 工具列表 （所有 MCP + Skills）
└── 会话服务 （管理用户会话的生命周期和对话历史）

装配链路最后一个节点通过 Spring 动态 Bean 注册，以 agentId 为名称把注册对象注册到 IOC 容器：

1
2
3
4
5


// 注册逻辑（伪代码）
if (容器中已存在同名 Bean) {
 先移除旧的; // 支持热替换
}
注册新的 Bean(agentId, 注册对象);

运行时用户请求过来，对话服务通过 agentId 从容器里取出注册对象，拿到运行器就能执行。装配不需要知道谁会调用，运行不需要知道怎么装配的——完全解耦。

为什么不直接用一个 Map 存？当然也行，但 Spring 容器帮你管理了对象的生命周期，全局可访问不需要到处传 Map 引用，热更新时"先移除再注册"的逻辑也更自然。

InMemoryRunner 的内部结构

装配流水线的最终产物就是这个 runner。它里面装着 4 样东西：

组成部分	装配阶段放进去的	运行阶段动态产生的	作用
Agent 树	✅		固定不变的执行蓝图
Session 管理器		✅	管理每个用户的对话状态
应用名	✅		日志标识 + Session 隔离
插件列表	✅		扩展 runner 的能力（demo 里为空）

“InMemory"指的是 Session 数据存在内存里，应用重启后对话历史会丢失。

Session 里的 outputKey 机制

这是 Agent 之间传递数据的核心机制。每个 Agent 配置了 outputKey 后，执行完毕的输出会被存到 session.state 这个 Map 里。后续 Agent 的 instruction 里写 {request_brief} 这样的占位符，ADK 框架会自动从 session.state 里查找对应的 key 并替换：

1
2
3
4
5
6
7



InputEchoAgent 执行完 → session.state.put("request_brief", "目标：分析AI趋势...")

QuestionDecomposerAgent 即将执行：
 instruction 里有 {request_brief}
 → 从 session.state 取出 "request_brief" 的值
 → 替换占位符后发给 LLM

五、会话机制：两层管理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25



我们代码管理的（外层）：
┌────────────────────────────────────┐
│ ConcurrentHashMap<用户ID, 会话ID> │
│ │
│ "xiaofuge" → "a3f6-..." │
│ "admin" → "b7e2-..." │
└────────────────────────────────────┘
 ↑ 作用：快速查找用户有没有会话
 ↑ 只存映射关系，不存聊天内容

SDK 内部管理的（内层）：
┌────────────────────────────────────┐
│ SessionService │
│ │
│ Session "a3f6-..." { │
│ events: [ │
│ { role: user, text: "你好" } │
│ { role: model, text: "你好！" }│
│ { role: user, text: "1+1" } │
│ { role: model, text: "等于2" } │
│ ] │
│ } │
└────────────────────────────────────┘
 ↑ 作用：存储真正的对话历史

上下文维持的原理：每次发起对话传入用户 ID 和会话 ID，SDK 内部根据会话 ID 找到对应的会话对象，取出历史记录和新消息拼在一起发给大模型。大模型的 API 本身是无状态的——所谓的"记忆"就是每次把完整历史重新发一遍。

外层 Map 创建会话时用的是原子操作，保证同一用户并发到达时只创建一次。

当前方案的局限：全在内存里，服务一重启就丢了。生产环境需要外层映射换 Redis（高频键值查询），内层会话历史存 MySQL（访问频率不高但数据重要）。还有个隐患是 Map 没有容量上限，用户越来越多会持续膨胀，长时间运行可能 OOM。

六、工具调用：注入、触发、执行

三个环节，我们代码只负责第一个：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16



【注入】我们的代码 ──────────────────────────────────
 装配时遍历 MCP + Skills
 构建 ToolCallback 列表
 注入到 ChatModel 对象中

【触发】Spring AI 自动完成 ──────────────────────────
 调用大模型时，把工具描述一起发过去
 大模型自己决定是否调用
 如果要调用，返回工具名称 + 参数

【执行】Spring AI 自动完成 ──────────────────────────
 从 ToolCallback 列表中匹配对应工具
 执行工具，拿到结果
 把结果连同之前的消息再发给大模型
 ↑ 这个过程可能多轮循环，直到大模型返回最终回答

MCP 和 Skills 的区别

触发机制完全一样——都是构建 ToolCallback，大模型根据描述决定调用，Spring AI 自动执行。区别在于回调内部做的事：

	MCP	Skills
本质	通过协议调用独立服务	读取本地文件返回内容
工具逻辑在哪	远程服务 / 本地子进程 / JavaBean	文档 + 脚本，由大模型理解后使用
类比	给智能体配了个能干活的助手	给智能体发了本操作手册
适用场景	重量级（数据库操作、代码执行）	轻量级（知识注入、简单脚本）

有个容易误解的点：Skills 里的脚本不是大模型自己执行的。大模型读到"你需要执行某个脚本"后，如果有代码执行类的 MCP 工具，它会再发一次工具调用让 MCP 去执行。大模型自己执行不了任何东西。

七、多模态：消息构建与格式转换修复

7.1 消息构建

用户发多模态消息时，接收到的不再是字符串，而是一个实体类，里面三个列表：

1
2
3
4
5
6
7



ChatCommandEntity
├── texts: ["请分析这张图片"] → 转为文本类型 Part
├── inlineDatas: [{bytes, mimeType}] → 转为内联数据类型 Part
└── fileUris: [{url, mimeType}] → 转为 URI 类型 Part
 ↓
 合并为一个 Content 消息体

Content 和 Part 是包含和被包含的关系。Part 一共 5 种类型：

Part 类型	携带数据	谁创建的
文本	纯文本字符串	我们的代码
内联数据	字节数组 + 类型标识	我们的代码
URI	远程地址 + 类型标识	我们的代码
函数调用	工具名称 + 参数	大模型返回的
函数响应	工具执行结果	Spring AI 自动生成的

Content 有 3 种角色：user（用户消息）、model（模型回复）、system（系统指令/提示词）。

7.2 消息转换器的修复

框架默认的消息转换器有个 bug——转换时只处理文本，直接跳过了多媒体数据。强行转换会丢失全部图片信息。

我们的修复策略是最小侵入——继承框架的转换器，只重写有问题的那一步：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11



原始消息（包含文本 + 图片）
 │
 ├──① 先把多媒体数据提取出来暂存
 │
 ├──② 调用父类的转换方法（多媒体会丢失）
 │
 ├──③ 把暂存的多媒体数据补回到转换结果的媒体字段
 │
 ▼
Spring AI 格式的消息（文本 + 图片都在）

为什么不完全重写？因为父类的转换方法还处理了很多其他逻辑（角色映射、系统指令、历史拼接），全部复制一遍工作量大，而且父类更新时我们不会自动同步。只修复有问题的部分，其他完全复用父类，这样改动范围最小。

规则树的四个核心方法

整棵规则树能自动一站接一站跑起来，全靠这 4 个方法的配合。这是最底层的机制，必须先搞明白这个，后面的所有代码才看得懂。

StrategyHandler 接口（框架层）

框架提供了一个接口，定义了每个节点必须具备的能力：

1
2
3
4
5
6
7


public interface StrategyHandler<T, D, R> {
 // 对外暴露的执行入口——外界调用这个来启动节点
 R apply(T requestParameter, D dynamicContext) throws Exception;

 // 获取下一个节点——每个节点必须告诉框架"下一站是谁"
 StrategyHandler<T, D, R> get(T requestParameter, D dynamicContext) throws Exception;
}

三个泛型参数：T 是输入参数类型，D 是上下文类型，R 是返回结果类型。

AbstractMultiThreadStrategyRouter 抽象类（框架层）

接口只说了"要做什么”，这个抽象类实现了通用逻辑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


public abstract class AbstractMultiThreadStrategyRouter<T, D, R>
 implements StrategyHandler<T, D, R> {

 // 子类必须实现的"干活"方法
 protected abstract R doApply(T requestParameter, D dynamicContext) throws Exception;

 // apply() 的实现——框架帮你写好了
 @Override
 public R apply(T requestParameter, D dynamicContext) throws Exception {
 return doApply(requestParameter, dynamicContext);
 }

 // ★ router()——找到下一个节点并执行它
 protected R router(T requestParameter, D dynamicContext) throws Exception {
 StrategyHandler<T, D, R> nextHandler = get(requestParameter, dynamicContext);
 if (nextHandler != null) {
 return nextHandler.apply(requestParameter, dynamicContext);
 }
 return null;
 }
}

四个方法的关系

方法	谁定义的	谁实现的	做什么	一句话记忆
`apply()`	接口定义	框架实现	启动一个节点的执行	“启动这个节点”
`doApply()`	抽象类定义	你实现	这个节点的具体业务逻辑	“这个节点干什么”
`get()`	接口定义	你实现	返回下一个节点是谁	“下一站去哪”
`router()`	抽象类定义	框架实现	调用 get() 获取下一站，再调用它的 apply()	“帮我跳到下一站”

所以写一个节点只需要写两个方法：doApply()（干活）和 get()（指路）。在 doApply() 的最后一行调用 return router(参数, 上下文) 就能自动跳到下一站。如果是最后一个节点，直接 return 结果就行，不调 router()。

八、流式与非流式

8.1 三个层面的区别

层面	非流式	流式
前端体验	等几秒后一次显示全部内容	文字像打字机一样逐步出现
控制器返回	普通 JSON 响应	ResponseBodyEmitter 流式发射器
底层调用	Spring AI 同步方法 call()	Spring AI 流式方法 stream()

8.2 流式发射器的作用

正常的 HTTP 接口 return 之后连接就关闭了。流式发射器告诉 Spring 框架：“这个连接先别关，后面还有数据要推”。框架会设置响应头为流式传输格式，保持连接。

超时时间设 3 分钟，是整个连接的总生存上限。复杂的智能体可能要多轮工具调用，一两分钟很正常，3 分钟给了比较宽裕的余量。超过就强制关闭，防止异常情况导致连接资源永远不释放。

8.3 runner.runAsync() 的行为

返回的是事件流对象，延迟执行——调用后不会立即开始与大模型通信，只有对这个事件流进行订阅时才真正开始。不订阅就不执行，这是响应式编程的特点。

还有个容易混淆的点：控制层的流式/非流式和底层调用 LLM 的流式/非流式是独立的。控制层流式指的是返回给前端的方式，底层流式指的是调用大模型 API 的方式。底层大部分情况调的是流式，但也可能是同步——这也是为什么适配器内部即使底层是非流式，也要把响应包装成只有一个事件的事件流来返回，保持接口统一。

九、错误处理的现状与不足

当前的错误处理是基础的捕获与传递模型：

1
2
3
4
5
6
7
8
9



LLM 调用异常
 │
 ├── 记录到监控组件
 ├── 错误映射（统一格式）
 ├── 包装成 RuntimeException 向上抛
 │
 ├── 非流式 → 返回错误 JSON
 └── 流式 → emitter.completeWithError() 中断连接

能用，但在生产环境中有三个明显的不足：

缺乏重试机制。网络抖动、大模型限流（429）这些很常见，当前失败一次就直接报错。应该针对可恢复异常做指数退避重试（隔 1s、2s、4s 重试 3 次）。

缺乏主备降级。主模型挂了就服务不可用。应该配备用模型，重试无果后自动切换。

工具调用失败会中断整个对话。MCP 远程服务挂了，异常一路向上抛，用户直接看到报错。更好的做法是拦截工具异常，把错误信息作为工具的返回值发给大模型，让大模型自己决定是换个工具还是告诉用户"这个服务暂时不可用"——这才是智能体该有的行为。

十、多模态 HTTP 接口设计

当前 Controller 层的 chat 和 chatStream 两个接口，入参 ChatRequestDTO 只有纯文本字段。Service 层的多模态方法没有暴露出来。

如果要设计多模态接口，推荐先上传后引用的方案：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15



步骤 1：前端调用文件上传接口
POST /api/v1/files/upload (multipart/form-data)
返回：{ "fileUri": "https://oss.xxx/dog.png", "mimeType": "image/png" }

步骤 2：前端调用对话接口（JSON，不变）
POST /api/v1/chat
{
 "agentId": "100003",
 "userId": "admin",
 "message": "请分析这张图片",
 "files": [
 { "fileUri": "https://oss.xxx/dog.png", "mimeType": "image/png" }
 ]
}

为什么不把图片 Base64 编码塞进 JSON？体积膨胀 33%，大 JSON 解析吃内存容易 OOM。为什么不用 multipart 表单？因为现有的 chat 和 chatStream 两个接口都是 JSON 格式，如果其中一个改成表单格式，前端就要写两套请求逻辑，流式接口（SSE）配合表单上传更是别扭。

先上传后引用的好处是：两个现有接口都不需要破坏，只在 DTO 里加一个 files 字段就完成升级，依然是干净的 JSON。大文件传输压力可以剥离给 OSS，不拖垮智能体服务。

方案总结

设计点	解决的问题
DDD 分层 + 依赖倒置	业务逻辑不受技术实现变化影响
双框架适配器	ADK 管编排 + Spring AI 管调用，各取所长
6 节点责任链	装配流程可扩展、可测试、可并行开发
编排节点逻辑循环 + 动态获取	支持嵌套编排，避免循环依赖
动态 Bean 注册	装配与运行完全解耦，支持热替换
两层会话管理	外层快速索引 + 内层存储历史
消息转换器重写	最小侵入修复多模态丢失
流式发射器 + 事件流	打字机效果 + 统一的异步执行模型

智能体脚手架的核心思路：配置驱动 + 职责分离。把复杂的装配过程拆成独立节点（责任链），把异构框架的差异封装在适配器里（桥接），把运行时的状态交给容器管理（IOC）。每一层只关心自己的事，加起来就是一个完整的智能体。

智枢项目 — 大文件异步流水线与 RAG 检索架构全拆解

Tue, 14 Apr 2026 00:00:00 +0000

写在前面

这篇文章是对我个人项目**「智枢 — 企业智能知识管理系统」中大文件异步流水线**模块的深度复盘。

这个模块要解决的核心问题是：用户上传一个 1GB 的大文件（PDF / Word / Excel 等），系统要完成分片上传 → 合并 → 解析 → 智能分块 → 向量化入库这整条链路，并且全程不能卡住用户、不能撑爆内存、不能丢数据。

下面的内容，我会按照数据流经过系统的真实顺序，一步步拆解每个环节的设计思路和踩过的坑。

一、1GB 文件上传从 15s 优化到 3s

1.1 前端怎么切片？

前端拿到文件后，利用 HTML5 的 Blob.slice() 方法，按照固定大小（默认 5MB）进行循环切割。1GB 的文件会被切成大约 200 个分片。

切片前，前端会开一个 Web Worker（浏览器提供的后台独立线程），在后台计算整个文件的 MD5 值。这样做是为了不阻塞主线程，否则计算 1GB 文件的 MD5 会直接让网页卡死、失去响应。

为什么固定 5MB？

因为 MinIO 兼容的 S3 协议有硬性要求：分片上传时，除了最后一个分片，其余分片不能小于 5MB。同时 5MB 也是一个很好的平衡点——太小会导致 HTTP 请求过于频繁，太大则一旦网络波动重传成本太高。

1.2 后端怎么接收？

后端的 /api/v1/upload/chunk 接口接收到分片后，不会把数据落到应用服务器的本地磁盘，而是直接通过流（Stream）透传写入 MinIO 对象存储的临时目录 chunks/{fileMd5}/{chunkIndex} 中。

写入成功后，做两件事：

在 Redis BitMap 中标记该分片已完成
在 MySQL 的 chunk_info 表中记录分片的存储路径和 MD5

另外，在接收第一个分片时，系统会调用秒传检测：查数据库和 MinIO，如果已经存在完全相同 MD5 的完整文件，直接复制元数据、返回 100% 进度，耗时接近 0 秒。

1.3 后端怎么合并？（核心优化点）

传统合并方案是：后端把 200 个分片从 MinIO 全部下载到 JVM 内存里拼接成一个 1GB 的大文件，再重新上传回 MinIO。在千兆内网下，这个"一下一上"的双向传输至少要 15 秒，还伴随着巨大的内存压力。

智枢的破局方案：MinIO 服务端零拷贝合并。

系统使用了 MinIO 的 composeObject API，本质上只是发送一条指令给 MinIO：“请把这 200 个分片在你内部拼成一个新文件”。MinIO 在自己的磁盘阵列上直接执行数据块的链接，文件数据完全不经过我们的 Java 服务。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


List<ComposeSource> sources = partPaths.stream()

 .map(path -> ComposeSource.builder().bucket(bucketName).object(path).build())

 .collect(Collectors.toList());

minioClient.composeObject(

 ComposeObjectArgs.builder()

 .bucket(bucketName)

 .object("merged/" + fileMd5)

 .sources(sources)

 .build()

);

砍掉了 1GB 数据的内网双向传输开销后，合并耗时直接降到了 3 秒以内。

二、Redis BitMap —— 1000 个分片仅占 125 字节

2.1 为什么用 BitMap？

断点续传需要高频地记录和查询"哪个分片传了，哪个没传"。如果用 Redis 的 List 或 Set 来存，每个分片序号至少占几十字节，1000 个分片可能要占好几 KB。

而 BitMap 的思路极其简洁：一个分片的状态 = 一个 Bit。0 表示未上传，1 表示已上传。

2.2 具体怎么记录？

Key 的设计是 upload:{userId}:{fileMd5}，确保每个用户每个文件的状态独立。

1
2
3


// 标记第 5 号分片已上传

redisTemplate.opsForValue().setBit("upload:user123:abc123", 5, true);

2.3 “125 字节"怎么算的？

1000 个分片 = 1000 个 Bit。

1 Byte = 8 Bits。

1000 ÷ 8 = 125 Bytes。

这个空间压缩是恐怖的——相比用 Set 存 1000 个整数（大约几 KB），BitMap 把内存占用压缩了上百倍。

2.4 查询进度时怎么高效解析？

系统不会循环发起 1000 次 Redis 请求。而是一次性把整个 BitMap 的字节数组拉取到 JVM 本地，然后通过位运算解析：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// 一次性获取整个 BitMap

byte[] bitmapData = redisTemplate.execute((RedisCallback<byte[]>) connection -> {

 return connection.get(redisKey.getBytes());

});

// 在本地通过位运算检查每一位

private boolean isBitSet(byte[] bitmapData, int bitIndex) {

 int byteIndex = bitIndex / 8;

 int bitPosition = 7 - (bitIndex % 8);

 return (bitmapData[byteIndex] & (1 << bitPosition)) != 0;

}

CPU 指令级别的位运算，能在零点几毫秒内解析出所有分片的状态。

二、断点续传：Redis BitMap

使用 Redis BitMap 记录每个分片的上传状态。空间效率极高 —— 1000 个分片只需 125 字节。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// 标记分片已上传
public void markChunk(String md5, int index) {
 redisTemplate.opsForValue()
 .setBit("upload:chunks:" + md5, index, true);
}

// 检查所有分片是否上传完毕
public boolean allUploaded(String md5, int total) {
 Long count = redisTemplate.execute(
 (RedisCallback<Long>) conn ->
 conn.bitCount(("upload:chunks:" + md5).getBytes())
 );
 return count != null && count == total;
}

网络中断后，客户端重新上传时，服务端返回已上传的分片列表，客户端只需补传缺失部分。

三、Redis 挂了怎么办？三重保障机制

Redis 在这个系统里只是加速缓存层，不是数据安全的依赖。真正的数据安全靠的是 MySQL 和 MinIO 的双重持久化。

3.1 Redis 数据丢了会怎样？

前端查不到进度，会以为文件没传过，从第 0 个分片重新上传。但后端是幂等的——它会去查 MySQL 和 MinIO，发现分片已经存在，就跳过真实的存储上传，只在 Redis 里补上标记。用户只会感觉进度条"闪退"了一下又迅速跑满，并没有产生冗余的网络传输。

3.2 合并时怎么保证不损坏？

合并接口完全不信任 Redis。它直接去 MySQL 查所有分片记录，然后逐个调用 MinIO 的 statObject 做物理探查，确认每个分片文件真实存在。只有 100% 确认后才执行合并。

3.3 修复孤儿记录

代码中有一段自愈逻辑：如果 Redis 说"已上传"但 MySQL 没记录（或者反过来），系统会去 MinIO 确认真相，然后补齐缺失的那一方记录。

四、Kafka 异步解耦全流程

4.1 消息是什么时候发的？

这里有一个很容易搞混的细节。Kafka 消息不是合并后立刻发的，真实的顺序是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10



① 合并分片 → 获得 1 小时有效的预签名下载链接

② 重新读取合并后的文件 → 预估向量化消耗 → 写入数据库

③ 构建 FileProcessingTask（把预签名链接塞进去）

④ 通过 Kafka 事务性发送消息

⑤ 返回响应给前端

4.2 为什么用事务性发送？

普通的异步发送没有原子性保证。可能出现"数据库更新了但消息没发出去"的半成品状态。

事务性发送（executeInTransaction）保证闭包内的所有发送操作要么全部成功提交（消费者才能看到消息），要么全部回滚（消息被丢弃）。

在智枢这种场景下，如果消息丢了但数据库标记为"已完成”，用户会看到文件上传成功了，但永远无法做问答检索——这种"静默失败"比直接报错更严重。

4.3 消费者处理流程

消费者从 Kafka 拉取到消息后，通过预签名链接从 MinIO 下载文件（流式下载，不是一次性加载到内存），然后依次执行：

文件解析（Tika / PDFBox 提取纯文本）
智能分块（四级语义切分）
写入 MySQL（document_vectors 表）
调用向量化模型（生成高维向量）
写入 Elasticsearch（knowledge_base 索引）
回写实际消耗量（更新 file_upload 表的 actualEmbeddingTokens）

4.4 消费失败了消息会丢吗？

不会。消费者处理异常时会主动向上抛出，触发两道防线：

自动重试： 默认最多重试 10 次，每次间隔递增
死信队列： 重试耗尽后，消息被转移到 原始主题名.DLT 的死信主题中，并且保持与原始消息相同的分区编号（方便排查来源）

死信消息不会被自动消费，需要人工排查修复后手动重新投递。

4.5 那个 1 小时的预签名链接是为消费者准备的

消费者通过这个临时链接下载文件，不需要知道 MinIO 的账号密码，降低了模块间的耦合。但如果 Kafka 消息积压超过 1 小时，链接就会过期，消费者会因为 403 而下载失败——这也是为什么需要合理设置 Kafka 分区数和消费者并发度。

五、向量化消耗预估与预扣费

5.1 为什么要预估？

因为 Kafka 消息是异步消费的，从发送到处理完成可能需要几分钟。如果不预扣，用户可能在这个时间窗口内连续上传 10 个大文件，每个都通过余额检查，但实际累计消耗远超余额。

5.2 怎么实现的？

合并完成后、发 Kafka 之前，系统会重新读取合并后的文件流，走一遍与正式解析完全相同的分块算法，但只统计不存储：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


private class StreamingEstimateHandler extends BodyContentHandler {

 private long estimatedTokens = 0L;

 private int estimatedChunkCount = 0;

 private void processParentChunk() {

 List<String> childChunks = splitTextIntoChunksWithSemantics(buffer.toString(), chunkSize);

 estimatedChunkCount += childChunks.size();

 estimatedTokens += usageQuotaService.estimateEmbeddingTokens(childChunks);

 buffer.setLength(0);

 }

}

预估完成后，系统先预扣用户余额。等消费者实际处理完成后，再用真实消耗量"多退少补"。

如果预估消耗超过用户余额，合并接口会直接拒绝，Kafka 消息根本不会被发送。

三、零拷贝合并

传统方案的问题： 读取所有分片到内存 → 写入目标文件。1GB 文件意味着至少 1GB 内存占用。

零拷贝方案： 利用 FileChannel.transferTo() 在内核态完成数据拷贝，不经过用户态缓冲区：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


public void mergeChunks(String md5, int totalChunks, Path target) {
 try (FileChannel dest = FileChannel.open(target,
 CREATE, WRITE, TRUNCATE_EXISTING)) {

 for (int i = 0; i < totalChunks; i++) {
 Path chunk = getChunkPath(md5, i);
 try (FileChannel src = FileChannel.open(chunk, READ)) {
 src.transferTo(0, src.size(), dest);
 }
 }
 }
}

效果：1GB 文件合并耗时从 15s+ 降至 3s 内，且内存占用几乎为零。

一、秒传：文件 MD5 去重

客户端上传前先计算文件 MD5，服务端检查是否已存在相同文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public UploadResult checkFile(String md5) {
 String existingId = redisTemplate.opsForValue()
 .get("file:md5:" + md5);

 if (existingId != null) {
 return UploadResult.secondPass(existingId); // 秒传
 }

 Set<Integer> uploaded = getUploadedChunks(md5);
 return UploadResult.needUpload(uploaded); // 返回待上传分片
}

六、JVM 内存熔断机制

6.1 为什么需要？

对于 PDF 文件，PDFBox 需要把整个文档树加载到内存中（为了按页提取和去页眉页脚），一个 500 页的 PDF 可能吃掉几百 MB 内存。如果同时处理多个大 PDF，堆内存很容易被撑爆。

另外，即使是普通文档走 Tika 路线，底层的 POI 库在解析几十万行 Excel 时，也可能在内部缓存大量对象。

6.2 怎么实现的？

在所有解析任务的入口处，有一道"内存安全门卫"：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


private void checkMemoryThreshold() {

 Runtime runtime = Runtime.getRuntime();

 long usedMemory = runtime.totalMemory() - runtime.freeMemory();

 double memoryUsage = (double) usedMemory / runtime.maxMemory();

 if (memoryUsage > 0.8) { // 超过 80%

 System.gc(); // 尝试 GC 自救

 // 重新检测

 usedMemory = runtime.totalMemory() - runtime.freeMemory();

 memoryUsage = (double) usedMemory / runtime.maxMemory();

 if (memoryUsage > 0.8) { // 回收后依然超标

 throw new RuntimeException("内存不足，拒绝处理");

 }

 }

}

三步走：探测 → 自救（GC）→ 果断拒绝。宁可让一条消息进入重试/死信，也绝不冒 OOM 崩溃的风险。

七、双轨解析架构（核心设计）

这是整个大文件流水线中我最满意的一块设计。

7.1 为什么 PDF 不能用 Tika？

Tika 当然能处理 PDF，但会引发两个灾难性后果：

页眉页脚污染语义： Tika 分不清正文和页眉，它会把"内部机密"、“第三章架构设计"这种页眉页脚文本夹杂在正文中间，导致向量化后的数据质量极差。
丢失页码信息： 企业知识库场景下，用户提问后系统必须告诉他"答案来自第 15 页”。Tika 的流式处理是一条线读到底的，根本不知道当前读到了第几页。

所以我专门引入了 PDFBox，为 PDF 开辟了一条独立的精细化处理路线。

7.2 双轨是怎么分的？

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


public void parseAndSave(String fileMd5, InputStream fileStream, ...) {

 checkMemoryThreshold(); // 先做内存体检

 if (isPdfDocument(bufferedStream)) {

 parsePdfAndSave(...); // PDF 专属路线

 return; // 直接 return，不走 Tika！

 }

 // 非 PDF → Tika 通用路线

 StreamingContentHandler handler = new StreamingContentHandler(...);

 parser.parse(bufferedStream, handler, metadata, context);

}

两条路线的核心区别：

维度	PDF 路线（PDFBox）	非 PDF 路线（Tika）
解析方式	加载完整文档树，按物理页遍历	流式读取，1MB 缓冲区
页码信息	✅ 精准保留每页页码	❌ 无页码，存 null
页眉页脚处理	✅ 专属去噪逻辑	❌ 不需要
内存占用	较高（需要加载文档树）	极低（永远只有 1MB）
OOM 风险	有，靠内存熔断兜底	几乎没有

7.3 PDF 的页眉页脚是怎么去除的？

思路非常巧妙：如果某行文本在很多页的顶部或底部都重复出现，那它大概率就是页眉或页脚。

具体步骤：

逐页提取文本，把每页按行切割
收集每页顶部前 3 行和底部后 3 行的有效文本
对这些边界行做归一化处理——关键操作是把所有数字替换为 #（这样"第 1 页"和"第 37 页"都变成"第 # 页"，被识别为同一行）
统计归一化后的行在所有页中出现的次数，超过阈值（2~3 次）的判定为页眉/页脚
从每页中剔除这些行

7.4 非 PDF 的流式处理具体怎么工作？

Tika 的工作模式是**“推送模型”**：它每次从输入流中读取几 KB 的原始数据，解码后提取出纯文本，然后调用我们自定义的 characters 回调方法。

我们在回调方法里把文本累积到一个 StringBuilder 缓冲区中，当缓冲区达到 1MB 时，就触发一次分块处理，然后立刻清空缓冲区：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


@Override

public void characters(char[] ch, int start, int length) {

 buffer.append(ch, start, length);

 if (buffer.length() >= parentChunkSize) { // 1MB

 processParentChunk();

 }

}

所以 JVM 内存中任何时刻最多只有约 1MB 的文本数据，无论原始文件是 100MB 还是 10GB。数据像流水一样经过 JVM，处理完就释放，永远不会蓄积。

八、四级语义分块算法

PDF 和非 PDF 在前半段的"解析"走的是两条不同的路，但在后半段的"分块和入库"时，它们殊途同归，汇聚到同一个方法：splitTextIntoChunksWithSemantics。

8.1 为什么不直接按固定字数切？

固定切分（比如每 500 字一刀）极容易把完整的句子甚至专有名词拦腰截断，导致向量化后的语义是破碎的。比如"中华人民共和国"可能被切成"中华人民共"和"和国"。大模型拿到这种上下文，回答质量会严重下降。

8.2 四级递进式切分

我按语义边界的优先级进行层层降级：

第一级 — 段落切分（最高优先级）：

1

String[] paragraphs = text.split("nn+");

段落是最天然的语义单元。优先在段落边界处切割，能最大程度保持语义的内聚性。

第二级 — 句子切分（处理超长段落）：

1

String[] sentences = paragraph.split("(?<=[。！？；])|(?<=[.!?;])s+");

如果单个段落超过块大小限制，就降级到按中英文标点符号切割。

第三级 — HanLP 智能分词（处理超长句子）：

1

List<Term> termList = StandardTokenizer.segment(sentence);

如果连单个句子都超长，调用 HanLP 自然语言处理模型按词语边界切分，确保"中华人民共和国"这样的专有名词不会被破坏。

第四级 — 字符切分（终极保底）：

1
2
3
4
5


catch (Exception e) {

 chunks = splitByCharacters(sentence, chunkSize);

}

如果 HanLP 异常，退化为最原始的逐字符切分。只是保底，正常情况下不会触发。

8.3 页码是怎么附加的？

分块方法本身完全不关心页码，它只负责切字符串。页码是在外层的调用方控制的：

PDF 路线调用时，传入真实的 pageNumber（比如 5）
非 PDF 路线调用时，传入 null

保存方法 saveChildChunks 收到什么页码就存什么页码，不做任何分类判断：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


private int saveChildChunks(..., Integer pageNumber) {

 for (String chunk : chunks) {

 vector.setPageNumber(pageNumber); // PDF 传 5 就存 5，非 PDF 传 null 就存 null

 documentVectorRepository.save(vector);

 }

}

这种设计遵循了高内聚、低耦合的原则：分块算法是纯粹的、无状态的文本处理函数。未来如果要支持新格式（比如 PPT 按幻灯片页切分），核心分块算法一行代码都不用改。

九、混合检索（KNN + BM25）

9.1 为什么必须混合？

只用 BM25（关键词检索）的问题：

用户问"怎么请假"，但文档里写的是"员工带薪休假管理办法"。BM25 匹配不到任何关键词，直接返回空。

只用 KNN（向量检索）的问题：

用户搜"RFC 7519"，KNN 返回一堆跟"网络协议"语义相关但完全不包含"RFC 7519"这个关键词的文档，答非所问。

混合检索让两种能力互补： KNN 负责语义召回（把所有可能相关的候选都捞上来），BM25 负责精准排序（确保最终结果包含用户的原始关键词）。

9.2 两阶段架构与打分权重

第一阶段 — KNN 粗召回 + 关键词硬过滤：

先用 KNN 在向量空间中大范围召回 topK × 30 个语义相近的候选文档，然后用 must 子句强制要求候选文档必须包含用户查询中的关键词。语义再相似但不含关键词的，直接淘汰。

第二阶段 — BM25 精排（Rescore 重打分）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


s.rescore(r -> r

 .windowSize(recallK)

 .query(rq -> rq

 .queryWeight(0.2d) // KNN 分数权重：20%

 .rescoreQueryWeight(1.0d) // BM25 分数权重：100%

 .query(rqq -> rqq.match(m -> m

 .field("textContent")

 .query(query)

 .operator(Operator.And)

 ))

 )

);

最终得分 = 0.2 × KNN 分 + 1.0 × BM25 分。BM25 主导最终排序，KNN 只作为辅助信号。

在企业知识库场景中，用户提问通常已经包含了比较明确的关键词，关键词的精确匹配度对结果质量的影响远大于语义相似度。

9.3 向量化失败时的自动降级

如果向量模型接口异常（比如网络超时），系统不会直接报错，而是自动降级为纯 BM25 文本搜索：

1
2
3
4
5
6
7
8
9


final List<Float> queryVector = embedToVectorList(query, userId);

if (queryVector == null) {

 logger.warn("向量生成失败，仅使用文本匹配进行搜索");

 return textOnlySearchWithPermission(query, userDbId, userEffectiveTags, topK);

}

这保证了即使外部依赖出问题，用户的搜索功能也不会完全不可用。

十、动态上下文增强策略

10.1 什么是长文本限制？

大语言模型有固定的上下文窗口（比如 8K / 32K / 128K 个 Token）。企业文档动辄几万字甚至几十万字，直接塞给模型要么超限报错，要么注意力分散、回答质量暴跌。

10.2 怎么突破？

核心思路：不把整本书塞给模型，只把最相关的几页纸递给它。

文档上传时，就按四级分块算法切成一个个小型文本块，向量化后存入 Elasticsearch
用户提问时，通过混合检索精准找出最相关的 5~10 个文本块
将这些块动态拼接成上下文，注入大模型的提示词中

“动态"体现在：每次用户问的问题不同，检索到的块也不同，上下文是实时组装的。并且系统可以根据模型的窗口大小，动态调整召回的块数量。

四、异步处理

合并完成后通过 Kafka 异步触发后续流程，客户端无需等待：

1
2
3
4
5
6
7
8


kafkaTemplate.send("file-process-topic",
 new FileProcessMessage(fileId, md5, filePath));

// 消费者异步执行：
// 1. Apache Tika 解析文档内容
// 2. 文本分段
// 3. 通义千问 Embedding 向量化
// 4. 写入 Elasticsearch 索引

写在最后

回顾整个大文件异步流水线，最让我有成就感的，不是某一个单独的技术点，而是整条链路的协同设计：

前端切片 + 后端 MinIO 零拷贝合并 → 解决传输瓶颈
Redis BitMap + MySQL + MinIO 三重保障 → 解决数据可靠性
Kafka 事务性发送 + 重试 + 死信 → 解决异步可靠性
内存熔断 + 双轨解析 + 流式缓冲 → 解决稳定性
四级语义分块 + 混合检索 → 解决 RAG 质量
预估消耗 + 预扣费 → 解决计费准确性

每个环节都不是孤立的炫技，而是为了整条链路的最终目标——让用户上传任意格式的大文件后，能通过自然语言高质量地找到他想要的答案。

方案总结

技术点	解决的问题
文件 MD5 + Redis	秒传，避免重复上传
Redis BitMap	断点续传，记录分片状态
FileChannel.transferTo	零拷贝合并，消除内存瓶颈
Kafka	异步解耦上传与处理

大文件处理的核心思路：分而治之 + 异步解耦。把大问题拆成小问题（分片），把慢操作放到后台（Kafka 异步）。

整体流程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14



客户端 服务端 存储
 │ │ │
 ├── 1. 计算文件 MD5 ────────>│ │
 │ ├── 2. Redis 查是否秒传 │
 │<── 3. 返回已上传分片列表 ──│ │
 │ │ │
 ├── 4. 上传缺失分片 ────────>│── 5. 存入 MinIO ──────>│
 │ ├── 6. BitMap 标记分片 │
 │ │ │
 ├── 7. 全部分片完毕 ────────>│ │
 │ ├── 8. 零拷贝合并 │
 │ ├── 9. Kafka 异步处理 │
 │<── 10. 返回成功 ──────────│ │

Java 集合框架深度笔记：HashMap、ConcurrentHashMap 与 ArrayList

Wed, 08 Apr 2026 00:00:00 +0000

这是我花了几个小时死磕 Java 集合底层源码后的总结。不是背的八股文，是我自己一行行推演出来的理解。以后面试前翻一遍这个就够了。

一、HashMap（面试出现率最高的集合，没有之一）

1.1 整体结构

HashMap 的底层说白了就是一个数组，数组里每个格子叫"桶"。往里面放数据的时候，先算出 key 的 hash 值，然后用这个 hash 值去决定放在哪个桶里。如果两个 key 算出来的桶位置一样（哈希冲突），就在那个桶后面挂一条链表。链表太长了（达到 8 个节点），再升级成红黑树。

所以本质就是：数组 + 链表 + 红黑树。

1.2 hash 怎么算的？为什么要搞个"扰动函数"？

HashMap 不是直接拿 key 的 hashCode 去用的。它多做了一步：把 hashCode 的高 16 位和低 16 位做了一次异或运算（hash ^ (hash >>> 16)）。

为什么要多此一举？因为算桶位置的时候用的是 hash & (n-1)，实际上只有 hash 值的最后几位在起作用，高位的特征全被浪费了。扰动函数就是把高位的信息"混"到低位里去，让散列更均匀，减少冲突。

至于为什么用异或而不是用与（&）或者或（|）？因为异或是唯一一个输出 0 和 1 概率各占 50% 的运算，最大程度保留了随机性。与运算会偏向 0，或运算会偏向 1，都不行。

1.3 为什么容量必须是 2 的 n 次方？

这个是 HashMap 最精妙的设计之一。

算桶位置的公式是 hash & (n-1)。当 n 是 2 的幂次方时，n-1 的二进制全是 1（比如 16-1=15，二进制是 1111）。这样做 & 运算的结果完全取决于 hash 值本身，每个桶都有可能被分配到。

但如果 n 不是 2 的幂，比如 n=10，那 n-1=9，二进制是 1001，中间两位永远是 0。不管你 hash 值是啥，算出来的桶位置中间两位永远是 0，大量桶位置永远用不上，哈希冲突会极其严重。

而且位运算（&）比取模运算（%）快几十倍。所以这个设计既保证了散列均匀，又保证了极致的性能。

如果你 new HashMap<>(10)，底层会通过 tableSizeFor() 方法自动向上取到最近的 2 的幂，也就是 16。它用了一串连续的无符号右移和按位或操作来实现，全程位运算，极快。

1.4 put 的完整流程

这个是面试被问到最多的，我自己推演了一遍源码：

先看 table 数组是不是空的。第一次 put 的时候 table 还是 null（懒加载），会先调 resize() 初始化一个默认长度 16 的数组。
用 (n-1) & hash 算出桶下标。
如果那个桶是空的，直接创建新节点放进去，完事。
如果桶不为空（哈希冲突了）：
- 先看桶里第一个节点的 key 是不是跟要放的 key 相同（先比 hash，再比 equals）。相同就准备覆盖旧值。
- 如果第一个不是，看这个桶是不是已经变成红黑树了。是的话走红黑树的插入逻辑。
- 如果还是链表，就一个个遍历下去。遍历过程中找到相同的 key 就覆盖；遍历到尾部还没找到，就在尾部追加新节点（JDK 8 是尾插法，JDK 7 是头插法）。
- 插入后检查链表长度有没有到 8。到了的话调 treeifyBin()。
treeifyBin() 里面还会再判断一次：数组长度有没有到 64。如果数组太短（不到 64），说明冲突是因为容量不够导致的，优先扩容而不是转树。只有链表长度 ≥ 8 且数组长度 ≥ 64，才会真正转红黑树。
最后检查 size 有没有超过阈值（容量 × 0.75），超过了就扩容。

为什么先比 hash 再比 equals？因为 hash 是 int 比较，一条 CPU 指令就搞定了。equals 可能要比较好多个字段，很慢。先用便宜的操作排除掉大部分不匹配的，再用昂贵的操作做精确确认。

1.5 get 的流程

get 比 put 简单多了：

算 hash，定位桶。
检查桶里第一个节点是不是目标（大多数情况一次命中）。
不是的话，看是红黑树还是链表，分别用对应的方式遍历查找。
找不到就返回 null。

1.6 扩容机制（JDK 8 的平移魔法）

触发扩容的条件：元素个数 > 容量 × 0.75。

扩容时数组容量翻倍（左移 1 位）。重点是数据怎么迁移。

JDK 7 的做法是对每个元素重新算一遍 hash & (newCap-1)，很慢。JDK 8 巧妙地利用了一个数学规律：扩容后 n-1 的掩码只是在高位多了一个 1。所以只需要看每个元素的 hash 值在那个新增的高位上是 0 还是 1。

具体做法是用 hash & oldCap 来判断：

结果为 0：留在原来的桶位置。
结果不为 0：搬到 原位置 + 旧容量 的新位置。

这样一条链表会被拆成高低两条链表，分别放到新数组的两个位置上。全程不需要重新计算 hash，一次位运算搞定，极致优雅。

而且 JDK 8 扩容拆链表用的是尾插法，保持了原来的顺序。JDK 7 用的头插法会把顺序反过来，多线程下会形成环形链表导致死循环（经典面试题）。

1.7 链表转红黑树的那些细节

为什么阈值是 8？ JDK 源码注释里直接引用了泊松分布的数据。在负载因子 0.75 的情况下，一个桶里挂到 8 个节点的概率是千万分之六，几乎不可能。所以树化只是极端情况的安全兜底。

为什么退化阈值是 6 而不是 8？ 为了防止反复横跳。如果转换和退化都用 8，当链表长度在 7 和 8 之间来回波动时，就会不停地转树、退回链表、转树、退回链表，白白浪费性能。中间留出 6 到 8 的缓冲区。

为什么用红黑树不用 AVL 树？ 红黑树是弱平衡的，插入删除时旋转次数少（最多 3 次），综合读写性能更好。AVL 树严格平衡，查找快一丢丢，但插入删除时旋转次数多。HashMap 的场景是读写都频繁，红黑树更合适。

1.8 负载因子为什么是 0.75？

0.75 是空间利用率和哈希冲突概率之间的最佳平衡点。

太大（比如 1.0）：数组装满才扩容，冲突严重，链表很长，查询变慢。太小（比如 0.25）：浪费大量空间。 0.75 刚好：75% 使用率，根据泊松分布计算，每个桶的平均元素数约 0.5，链表超过 8 的概率只有千万分之六。

1.9 存 20 个元素扩容几次？

初始容量 16，阈值 12。存到第 13 个时触发扩容，容量变 32，阈值变 24。之后存到 20 都不会再扩容。答案是 1 次。

如果提前知道要存 1000 个元素，应该 new HashMap<>(1334)，底层会向上取到 2048，阈值是 1536，永远不会扩容。

1.10 为什么推荐用 String 做 Key？

三个原因：

不可变：hashCode 算一次就缓存起来了，后续调用直接用缓存，不用重新算。
天然重写了 equals 和 hashCode：直接能用，不用操心。
不会被修改：不存在 hash 值变了但数据还在旧桶里的内存泄漏问题。

如果用可变对象做 Key，put 之后又改了那个对象的属性，它的 hashCode 就变了。再去 get 的时候，根据新 hashCode 去别的桶找，当然找不到。而旧数据还死死卡在原来的桶里，GC 也回收不了（因为 HashMap 的 table 数组还持有它的强引用），这就是经典的内存泄漏。

1.11 HashMap 的线程安全问题

HashMap 绝对不是线程安全的。

JDK 7 的致命问题：多线程并发扩容时，头插法会导致链表形成环，后续 get 操作会陷入死循环，CPU 直接飙到 100%。

JDK 8 改成了尾插法，解决了死循环。但依然有两个致命问题：

数据覆盖：两个线程同时往一个空桶里 put，都判断桶是空的，后放的直接把先放的覆盖了。
size 不准：size++ 不是原子操作，两个线程同时加，可能只加了 1。

多线程环境下必须用 ConcurrentHashMap。

1.12 HashMap 的 key 可以为 null 吗？

可以，而且只能有一个 null key。源码里对 null 的处理是直接返回 hash 值 0，所以 null key 永远放在 table[0] 这个桶里。

但是 ConcurrentHashMap 和 Hashtable 的 key 和 value 都不能为 null。

二、ConcurrentHashMap（并发面试必考）

2.1 JDK 7 的分段锁

JDK 7 的思路是把一个大 HashMap 切成 16 个小 HashMap，每个小的叫 Segment。Segment 直接继承了 ReentrantLock，所以它天生就是可重入锁。

写数据的时候只锁对应的那个 Segment，其他 15 个不受影响。最多允许 16 个线程同时写。

问题在于：并发度被固定死了（默认 16），而且每个 Segment 对象本身很重，浪费内存。

2.2 JDK 8 的 CAS + synchronized

JDK 8 把分段锁整个推翻了。数据结构回归为和 HashMap 一样的数组+链表+红黑树。但锁的粒度细化到了每一个桶的头节点。

put 的时候分两种情况：

桶是空的：用 CAS 直接塞进去。因为是一步操作，CAS 硬件指令就能保证原子性，全程无锁，极快。
桶不为空（有冲突）：用 synchronized 锁住这个桶的头节点，在锁里面安心地遍历链表或红黑树。

如果 CAS 失败了（说明有人抢先把桶占了），不会抛异常，而是进入下一次 for 循环重试。这次发现桶不为空了，就会自动切换到 synchronized 分支。

为什么 JDK 8 又把 synchronized 请回来了？ 因为从 JDK 6 开始，JVM 对 synchronized 做了史诗级优化（偏向锁、轻量级锁、锁升级）。在竞争不激烈时性能和 ReentrantLock 不相上下，而且不用创建锁对象，省内存。

2.3 读操作全程无锁

get 方法不需要加任何锁。这是因为 Node 节点的 val 和 next 都被 volatile 修饰了。

volatile 保证了内存可见性：一个线程改了值，会立刻强制刷新到主内存，其他线程的 CPU 缓存里的旧值自动失效。所以读线程永远能看到最新的数据。

就算某个桶正在被 synchronized 锁住做写操作，读线程依然可以毫无阻塞地读，因为 volatile 保证了可见性，不需要锁来保护。

2.4 size 的极致统计（LongAdder 思想）

如果用一个 AtomicInteger 来统计 size，高并发下所有线程都去 CAS 争抢同一个变量，大量线程 CAS 失败后疯狂自旋，CPU 直接被榨干。

ConcurrentHashMap 学了 LongAdder 的思路：化整为零。

内部有一个 baseCount 和一个 CounterCell 数组。平时没竞争就直接 CAS 加 baseCount。一旦 CAS 失败（有竞争了），线程就用自己的随机 hash 值，分散到 CounterCell 数组的不同格子里去加。

统计 size 的时候，把 baseCount 和所有格子的值加起来就行了。

但这个 size 是弱一致性的。遍历数组求和的过程中没有加锁，其他线程可能还在往里面加数据。所以拿到的值可能不是绝对精准的。在高并发场景下，绝对不能用 map.size() 来做库存拦截或者秒杀判断。

CounterCell 上面还加了个 @sun.misc.Contended 注解，是为了解决 CPU 缓存的伪共享问题。CPU 缓存是按缓存行（64字节）读取的，如果多个 CounterCell 挤在同一个缓存行里，一个被改了整个缓存行都失效，其他格子也得跟着重新从主内存读。这个注解会在对象前后填充空白字节，把不同的 Cell 强行挤到不同的缓存行里。

2.5 为什么不允许 null？

为了避免二义性。在单线程的 HashMap 里，get 返回 null 后可以用 containsKey 去证伪。但在 ConcurrentHashMap 里，你 get 到 null 还没来得及 containsKey，别的线程可能已经把数据改了。你永远无法证明这个 null 到底是"值就是 null"还是"key 不存在"。

2.6 复合操作的陷阱

虽然 ConcurrentHashMap 内部是线程安全的，但 get 之后判断 if null 再 put，这三步合在一起不是原子的。高并发下依然会丢数据。

普通场景可以用 merge 或 putIfAbsent。但如果是热点 Key 的高并发累加（比如统计播放量），用 merge 所有线程都在一个桶的头节点上排队，性能很差。终极方案是用 ConcurrentHashMap<String, LongAdder>，把累加操作下沉到 LongAdder 内部的分散格子里。

三、volatile（JUC 并发编程的灵魂基石）

volatile 有两个超能力和一个致命弱点。

3.1 超能力一：内存可见性

一个线程改了 volatile 变量，JVM 会强制把新值刷到主内存，并且让其他线程 CPU 缓存里的旧值失效。其他线程读的时候，跳过本地缓存直接从主内存拿最新值。

经典案例：一个 while(isRunning) 循环，如果 isRunning 没加 volatile，另一个线程把它改成 false，循环线程可能永远看不到，因为它一直读的是自己 CPU 缓存里的旧值 true，死循环。

3.2 超能力二：禁止指令重排

CPU 为了优化性能会重排指令顺序。volatile 会在变量的读写前后插入内存屏障，禁止跨过屏障的指令重排。

经典案例就是双重检查锁（DCL）单例模式。new Singleton() 在底层分三步：分配内存、初始化对象、赋值引用。CPU 可能重排成分配内存、赋值引用、初始化对象。这样别的线程看到引用不是 null 就直接用了，但对象还没初始化完，直接空指针。加了 volatile 就能强制这三步严格按顺序执行。

3.3 致命弱点：不保证原子性

volatile 只能保证读到最新值，但 count++ 这种操作（读、加、写三步），两个线程可能同时读到同一个值，各自加 1 后写回去，结果只加了 1。

解决办法：用 AtomicInteger（底层是 CAS），或者加 synchronized。

四、ArrayList

4.1 底层结构

就是一个 Object 数组（elementData），外加一个 size 记录实际元素个数。

注意 size 和 capacity 的区别：size 是实际装了多少个，capacity 是数组的物理长度。

4.2 扩容机制

默认初始容量是 10，但用了懒加载。new 的时候底层数组是空的，第一次 add 时才扩容到 10。

每次扩容新容量 = 旧容量 × 1.5（用位运算 oldCapacity + (oldCapacity >> 1) 实现）。

扩容后通过 Arrays.copyOf 创建新数组，底层调的是 System.arraycopy 这个 native 方法，C++ 级别的内存块拷贝，极快。

为什么是 1.5 倍不是 2 倍？ HashMap 必须 2 倍是因为要保证 2 的幂做位运算。ArrayList 没这个限制，1.5 倍更省内存。

边界防御：如果 oldCapacity 是 1，1 + (1>>1) = 1，等于没扩。但源码里有双重保险：算完 1.5 倍后还会跟最低需求值比较，取大的那个。所以不会出问题。

如果提前知道要存多少数据，直接指定初始容量，比如 new ArrayList<>(1000)，避免反复扩容的性能损耗。

4.3 为什么不是线程安全的？

两个致命场景：

size++ 不是原子操作：两个线程同时读到 size=5，都往下标 5 放数据，后放的覆盖先放的，数据丢失。
扩容判断不安全：两个线程同时判断不需要扩容，然后同时 add，数组空间不够，ArrayIndexOutOfBoundsException。

4.4 序列化的骚操作

底层数组 elementData 被 transient 修饰，意思是默认不序列化。但 ArrayList 依然能被序列化，因为它自己写了 writeObject 和 readObject 方法。

为什么要这么做？因为数组的 capacity 通常远大于 size。如果直接序列化整个数组，后面一堆 null 全跟着走了，白白浪费带宽和空间。自定义序列化只写前 size 个有效元素，反序列化时也只创建刚好够用的数组。

五、LinkedList

5.1 底层结构

标准的双向链表，每个 Node 包含 item（数据）、prev（前驱指针）、next（后继指针）。整个 LinkedList 维护了 first 和 last 两个指针。

它还实现了 Deque 接口，所以可以当队列、栈、双端队列用。

5.2 中间插入真的比 ArrayList 快吗？

不一定，大部分情况下并不快。 这是一个经典的认知误区。

LinkedList 修改指针确实是 O(1)，但在调 add(index, e) 的时候，得先调 node(index) 找到那个位置。node 方法虽然做了个小优化（index 在前半段从头找，后半段从尾找），但本质还是逐个节点遍历，O(n)。

所以中间插入两者都是 O(n)。而且 ArrayList 的数组搬运用的是 System.arraycopy（native 方法，整块内存拷贝），实测往往比 LinkedList 的链表遍历还快。

LinkedList 唯一有优势的场景是纯粹的头部或尾部操作（addFirst/addLast/removeFirst/removeLast），因为有 first 和 last 指针可以 O(1) 直达。

六、ArrayList vs LinkedList 的硬件级性能差异

6.1 遍历性能：ArrayList 碾压

理论上遍历都是 O(n)，但实测 ArrayList 比 LinkedList 快 10 倍以上。

原因是CPU 缓存行（Cache Line）和空间局部性（Spatial Locality）。

CPU 每次从主内存读数据是按缓存行（64 字节）整块加载的。ArrayList 底层是连续数组，读第 1 个元素时顺便就把后面十几个元素一起拉进了高速缓存。后续访问直接缓存命中（Cache Hit），纳秒级。

LinkedList 的节点在堆内存中随机分布，物理地址天南地北。每访问一个节点，CPU 缓存里的数据大概率用不上（Cache Miss），只能重新去主内存捞。主内存的延迟是 L1 缓存的 100 倍以上。

而且绝对不能用普通 for 循环遍历 LinkedList！ list.get(i) 每次都从头重新找，O(n²) 复杂度。必须用 Iterator 或 foreach。

6.2 内存占用：LinkedList 浪费严重

在 64 位 JVM（开启指针压缩）下，一个 LinkedList.Node 占 24 字节（对象头 12 + 三个引用 12）。

存 100 万个 Integer：

ArrayList：数组引用约 4MB。
LinkedList：Node 对象约 24MB。

光维护数据结构的开销，LinkedList 就是 ArrayList 的 6 倍。如果对内存极度敏感，直接用 int[] 基本类型数组，100 万个 int 只要 4MB。

6.3 队列选型：ArrayDeque 碾压 LinkedList

如果要用队列或栈，别用 LinkedList，用 ArrayDeque。

ArrayDeque 底层是首尾相接的环形数组，头尾操作通过位运算移动指针，绝对 O(1)。不用创建 Node 对象，没有 GC 压力。内存连续，CPU 缓存友好。

ArrayDeque 不能存 null，因为底层用 elements[head] == null 来判断队列是否为空。允许 null 的话就有二义性了。

七、集合遍历的那些坑

7.1 Fail-Fast 机制

ArrayList 内部有个 modCount（修改计数器），每次 add/remove 都会加 1。迭代器创建时会拍一个快照 expectedModCount。

每次调 next() 都会对比这两个值。如果你在 foreach 里直接调 list.remove()，modCount 变了但 expectedModCount 没变，不一致就抛 ConcurrentModificationException。

漏网之鱼：删除倒数第二个元素时可能不报错。因为删除后 size 减 1，恰好等于 cursor，hasNext() 返回 false，循环正常结束，next() 里的校验根本没机会执行。但最后一个元素会被跳过，数据遗漏。

Fail-Fast 不能作为可靠的并发检测手段。modCount 没有 volatile 修饰，多线程下有可见性问题。

7.2 普通 for 循环正序删除的坑

普通 for 循环没有 Fail-Fast，不会抛异常。但正序遍历删除会静默跳过元素。

因为删除一个元素后，后面的元素全部前移。但 i 继续递增，直接跳过了前移过来的那个元素。

解决方案：倒序遍历（从后往前删），或者用 Java 8 的 removeIf。

7.3 安全删除元素的三种正确姿势

iterator.remove()：迭代器自己的 remove 方法会同步更新 expectedModCount。
倒序 for 循环：后面的元素前移不影响前面还没遍历的元素。
list.removeIf(predicate)：底层做了严格的边界控制，最安全最优雅。

八、SubList 的视图陷阱

subList 不是创建新集合！它返回的内部类持有原 ArrayList 的引用，只是加了 offset 和 size 做可视窗口。

改 sub → 原 list 跟着变。
改原 list → 再访问 sub 直接报 ConcurrentModificationException（版本校验失败）。

正确做法：如果需要独立副本，套一层 new ArrayList<>(list.subList(2, 5))。

subList 最优雅的用法是范围清除：list.subList(2, 5).clear()。

九、Arrays.asList 的三个致命坑

坑一：不能增删

返回的不是 java.util.ArrayList，而是 Arrays 类的内部类。这个内部类没有重写 add 和 remove，调了直接 UnsupportedOperationException。

坑二：引用传递后门

底层直接 this.a = array 持有了原数组的引用。改原数组，List 跟着变；改 List，原数组也变。

坑三：基础类型泛型灾难

泛型只能是引用类型。传入 int[] arr，整个数组被当成一个 Object 塞进去，得到 List<int[]>，size 永远是 1。

正确做法：

对象数组：new ArrayList<>(Arrays.asList(arr))
基础类型数组：Arrays.stream(arr).boxed().collect(Collectors.toList())

List.of()（JDK 9+）创建的是完全不可变集合，add/set/remove 全部报错，连 null 都不能存。

十、Java 集合 vs Redis 数据结构

它们在逻辑模型上高度一致（List、Set、Map），但底层实现天差地别，因为运行环境不同。

哈希冲突：Java HashMap 用红黑树优化查询；Redis Hash 只有链表没有树（省内存、单线程维护树太复杂）。

扩容机制：Java 一次性全量搬运（多线程环境扛得住瞬间卡顿）；Redis 用渐进式 Rehash 分批搬运（单线程不能卡，每次只搬一个桶）。

有序集合：Java TreeSet 用红黑树；Redis ZSet 用跳表（范围查找更快、实现更简单）。

并发安全：Java 需要 ConcurrentHashMap 用 CAS+锁来保证；Redis 天然安全（单线程执行命令）。

脱离运行环境谈数据结构选型就是耍流氓。底层设计的本质就是空间与时间、并发与单线程的极限取舍。

Redis 持久化机制：RDB 与 AOF 的深入对比

Thu, 02 Apr 2026 00:00:00 +0000

Redis 作为内存数据库，进程退出后数据就会丢失。持久化是保证数据安全的核心能力。Redis 提供了两种持久化方式：RDB（快照） 和 AOF（追加日志）。

在我的项目中，Redis 同时承担了缓存、分布式锁和会话存储的角色，选择合适的持久化策略直接影响数据安全性和性能。

RDB（Redis Database）

原理

RDB 通过生成某个时间点的全量数据快照来实现持久化。Redis fork 一个子进程，子进程遍历内存数据写入临时文件，完成后原子替换旧文件。

1
2
3
4
5
6
7
8



主进程 子进程
 │ │
 ├── fork() ────────────────>│
 │ ├── 遍历内存数据
 │ 继续处理客户端请求 ├── 写入临时 rdb 文件
 │ ├── 替换旧 rdb 文件
 │ └── 退出

fork 使用操作系统的 Copy-on-Write 机制：子进程与父进程共享内存页，只有当父进程修改某页数据时才会复制该页。因此 fork 本身很快，但如果在快照期间有大量写入，内存占用会显著上升。

触发方式

1
2
3
4
5
6
7
8


# 手动触发
SAVE # 同步阻塞，生产环境禁用
BGSAVE # 异步 fork 子进程

# 自动触发（redis.conf）
save 900 1 # 900 秒内至少 1 次修改
save 300 10 # 300 秒内至少 10 次修改
save 60 10000 # 60 秒内至少 10000 次修改

优缺点

✅ 优点	❌ 缺点
文件紧凑，适合备份和灾难恢复	两次快照之间的数据可能丢失
恢复速度快（直接加载二进制）	数据量大时 fork 耗时较长
对主线程影响小	fork 瞬间内存可能翻倍（COW）

AOF（Append Only File）

原理

AOF 记录每一条写命令，追加到文件末尾。重启时重放所有命令来恢复数据。

同步策略

1
2
3


appendfsync always # 每条命令都同步，最安全，性能最差
appendfsync everysec # 每秒同步（推荐，最多丢 1 秒数据）
appendfsync no # 由 OS 决定，性能最好，可靠性最差

AOF 重写

AOF 文件会不断膨胀，Redis 通过重写机制压缩文件体积：

1
2
3
4
5
6



原始 AOF: 重写后:
SET counter 1 SET counter 4
INCR counter ← 等效合并
INCR counter
INCR counter

重写同样通过 fork 子进程执行，不阻塞主线程。

优缺点

✅ 优点	❌ 缺点
数据安全性高（最多丢 1 秒）	文件体积通常比 RDB 大
可读性好，便于分析和调试	恢复速度慢（重放命令）
重写机制控制文件大小	持续写入有 I/O 压力

对比总结

维度	RDB	AOF
数据安全	可能丢失分钟级数据	最多丢失 1 秒
文件大小	小（二进制压缩）	大（文本命令）
恢复速度	快	慢
性能影响	fork 时短暂影响	持续写入
适用场景	定期备份、容灾	数据安全要求高

生产环境推荐：混合持久化

Redis 4.0+ 支持 RDB + AOF 混合持久化：

1

aof-use-rdb-preamble yes

重写时先以 RDB 格式写入全量数据，再追加增量 AOF 命令。兼顾恢复速度和数据安全。

追求性能用 RDB，追求安全用 AOF，生产环境开混合持久化。

赵阳的技术博客

智枢项目复盘：从 0 到 1 构建 RAG 知识管理平台

项目背景

整体架构

核心技术难点

一、大文件异步处理流水线

二、混合检索与 RAG 增强

三、流式对话与服务降级

四、细粒度权限管控

收获与反思

AI 智能体脚手架：多 Agent 编排框架的设计与实现

为什么要做这个框架？

整体架构（DDD 分层）

核心设计

一、双框架协同：Spring AI + Google ADK

二、YAML 声明式编排

三、MCP 工具统一接入

四、响应式流设计

落地验证：AI + Draw.io

总结

你好世界 | 博客开张了

博客开张 🎉

内容方向

我的项目

AI 智能体脚手架：从 YAML 配置到多 Agent 协同的工程实践

一、整体架构：DDD 分层

项目背景

三、装配链路：从 YAML 到可运行的智能体

3.1 触发阶段

3.2 责任链执行

3.3 编排节点的逻辑循环

3.4 动态上下文里装了什么

3.5 为什么用责任链而不是写一个大方法

谁是 Bean 谁不是

MCP/Skills 工具创建细节

为什么需要工具

三种 MCP 工具类型

Skills 工具

一个 Java 小知识：toArray(new ToolCallback[0])

装配流水线的完整链路

整体结构

启动入口

上下文：DynamicContext

第5站：最复杂的 AgentWorkflowNode

嵌套的秘密：agentGroup

规则树到底是什么

一句话定义

为什么叫"树"不叫"链"

为什么不写一个大方法

四、装配与运行的衔接

InMemoryRunner 的内部结构

Session 里的 outputKey 机制

五、会话机制：两层管理

六、工具调用：注入、触发、执行

MCP 和 Skills 的区别

七、多模态：消息构建与格式转换修复

7.1 消息构建

7.2 消息转换器的修复

规则树的四个核心方法

StrategyHandler 接口（框架层）

AbstractMultiThreadStrategyRouter 抽象类（框架层）

四个方法的关系

八、流式与非流式

8.1 三个层面的区别

8.2 流式发射器的作用

8.3 runner.runAsync() 的行为

九、错误处理的现状与不足

十、多模态 HTTP 接口设计

方案总结

智枢项目 — 大文件异步流水线与 RAG 检索架构全拆解

写在前面

一、1GB 文件上传从 15s 优化到 3s

1.1 前端怎么切片？

1.2 后端怎么接收？

1.3 后端怎么合并？（核心优化点）

二、Redis BitMap —— 1000 个分片仅占 125 字节

2.1 为什么用 BitMap？

2.2 具体怎么记录？

2.3 “125 字节"怎么算的？

2.4 查询进度时怎么高效解析？

一个 Java 小知识：`toArray(new ToolCallback[0])`