KnowFlow Agent Day10：实现文档切片与数据保存

一、今天完成的内容今天继续开发 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 }四、为什么需要 overlapoverlap表示相邻切片之间重复保留的字符数。假设一句话刚好在切片边界处被截断切片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 Boot16个测试全部通过 FastAPI4个测试全部通过九、今天的总结通过今天的开发我理解了文档切片并不只是简单地把文章截成几段还要考虑切片大小、上下文重叠、重复切片和数据保存等问题。Day10 完成后项目已经能够把企业文档转换成适合检索的小段文本。下一步将学习 Embedding把这些切片转换成向量为真正的 RAG 相似度检索做准备。