一、今天完成的内容
今天继续开发 KnowFlow Agent，主要完成了文档切片功能。
前面的 Day08 和 Day09 已经实现了文档信息管理，以及 Spring Boot 调用 FastAPI 解析文档。今天在这个基础上，把解析后的长文本拆成多个较短的文本片段，并保存到系统中，为后续的 Embedding 和 RAG 检索做准备。
本次新增了以下接口：
POST /api/documents/{id}/chunks
GET /api/documents/{id}/chunks
POST /ai/documents/chunk其中，FastAPI 负责执行文本切片，Spring Boot 负责业务处理和保存切片数据。
二、什么是文档切片
文档切片就是把一篇较长的文档拆成多个较短的文本片段。
例如，一份企业售后手册可能包含退货、退款、维修和物流等内容。如果直接把整份文档交给大模型，不仅会浪费 Token，还可能让模型难以找到真正相关的信息。
切片之后，系统可以只查找与用户问题最相关的几个片段，再把这些内容交给大模型。
整体流程如下：
长文档
↓
拆分成多个切片
↓
保存切片
↓
根据用户问题查找相关切片
↓
交给大模型生成回答三、chunkSize 是什么
chunkSize 表示每个切片允许包含的最大字符数。
例如，一篇文档有1000个字符：
chunkSize = 500，大约拆成2个切片
chunkSize = 200，大约拆成5个切片chunkSize 不能设置得太大，否则一个切片中可能包含很多无关内容，影响检索准确率；也不能设置得太小，否则一句完整的话可能会被拆开。
项目当前默认值为：
{
"chunkSize": 500
}四、为什么需要 overlap
overlap 表示相邻切片之间重复保留的字符数。
假设一句话刚好在切片边界处被截断：
切片1：用户可以在收到商品七天内
切片2：申请退货，运费由商家承担这两个切片单独来看，表达的信息都不够完整。
加入重叠内容后：
切片1：用户可以在收到商品七天内
切片2：收到商品七天内申请退货，运费由商家承担第二个切片保留了前面的部分内容，语义会更加完整。
项目当前的默认配置为：
{
"chunkSize": 500,
"overlap": 50
}表示每个切片最多500个字符，相邻切片重复保留50个字符。
五、切片是一个一个查找吗
切片保存后，并不是每次都从第一条开始逐个查找。
后续系统会使用 Embedding，把每个切片转换成一组数字，也就是向量。用户的问题同样会被转换成向量，然后通过向量检索找到语义最相近的几个切片。
例如，用户询问：
质量问题退货时，运费由谁承担？系统会找到类似下面的内容：
Top 1：质量问题产生的退货运费由商家承担
Top 2：用户可以在签收后七天内申请退货
Top 3：退款将在审核通过后到账系统通常只把最相关的3到5个切片交给大模型，不需要把整份知识库都发送过去。
六、今天实现的业务流程
今天实现的完整流程是：
Spring Boot 接收文档内容
↓
调用 FastAPI 切片接口
↓
FastAPI 返回多个文本片段
↓
Spring Boot 保存切片
↓
更新文档切片数量和解析状态切片数据可以使用内存保存，也可以在启用 MySQL 后保存到 kf_document_chunks 表。
当同一份文档重新切片时，系统会先清除旧切片，再保存新的结果，避免产生重复数据。删除文档时，对应的切片也会一起删除。
七、接口请求示例
生成文档切片：
POST /api/documents/1/chunks
Content-Type: application/json请求内容：
{
"content": "这里是一段需要进行切片的企业售后知识文本......",
"chunkSize": 500,
"overlap": 50
}查询文档切片：
GET /api/documents/1/chunks系统会按照切片序号，从前到后返回该文档的所有切片。
八、测试结果
今天补充了切片生成、重叠内容和错误参数校验等测试。
Spring Boot：16个测试全部通过
FastAPI：4个测试全部通过九、今天的总结
通过今天的开发，我理解了文档切片并不只是简单地把文章截成几段，还要考虑切片大小、上下文重叠、重复切片和数据保存等问题。
Day10 完成后，项目已经能够把企业文档转换成适合检索的小段文本。下一步将学习 Embedding，把这些切片转换成向量，为真正的 RAG 相似度检索做准备。