分块与文档处理

预览分块、处理待处理文档，并在不丢失手工修改的前提下应用新分块策略

分块决定知识库召回的粒度：分块太大，召回内容里混着无关信息、挤占上下文预算；分块太小，单条分块缺少完整语义，检索命中后也读不出完整答案。因此先预览、再处理，不要在未验证结果的情况下直接放大分块或重叠。

分块是「字符」不是「Token」

chunk_size 与 chunk_overlap 的单位都是字符。Token 数只是用 字符数 ÷ 4 粗略估算后展示（界面上标注为 tokens），用于判断上下文预算，不参与切割。中文与英文混排时两者比例差异很大，所以按 Token 调参时要留出余量。

参数	默认值	最小值	界面建议上限	说明
分块大小 `chunk_size`	`1000` 字符	`100`	`2000`	单个分块的目标长度
分块重叠 `chunk_overlap`	`100` 字符	`0`	`500`	相邻分块保留的上下文长度
自定义分隔符 `separator`	空	—	—	可写转义序列，见下
文本清理 `clean_text`	开启	—	—	关闭可保留原始格式

系统先判断文本是否包含 Markdown 结构（# 标题、代码围栏、表格、列表是主要信号），再决定切分方式。两条路径都由同一个入口 chunk_text(text, chunk_size, chunk_overlap, separators, is_markdown) 选择：

Markdown 模式：按结构块切分。小表格整体保留，超大表格按行拆分并重复表头；列表项不被拆散；未闭合的代码围栏会自动补全闭合。分块还会带上 section（第一章 > 第二节 形式的面包屑）和 chunk_type（table/code/list/text）元数据，方便定位来源。
纯文本模式：使用递归字符切分器，按默认分隔符优先级依次尝试：段落空行、换行、中文句号 。、中文感叹号 ！、中文问号 ？、英文句末 . 、! 、? 、中文分号 ；、英文分号 ; 、中文逗号 ，、英文逗号 , 、空格、单字符。

为什么重叠用字符精确实现

切分器本身以 overlap = 0 运行，之后再把上一分块末尾的精确 N 个字符前置到当前分块。原因是切分器自带的重叠按「切分单元」计算，中文句子常整段超过重叠值，会得到远超预期的重叠量。精确字符重叠还能保证中文内容得到你要求的重叠长度。

把 separator 填成 \n\n、--- 之类的字符串后，系统会先按该分隔符把原文切开，再对每段继续切分。即使原文本来能装进一个分块，也会在分隔符处断开——这是它和「默认分隔符」最大的区别（默认分隔符只在需要缩短超长文本时才生效）。

输入框里的 \n、\r、\t、\\ 会被还原成真正的换行/制表符/反斜杠，因此可以放心直接写 \n\n。

在文档操作中选择预览分块（或从待处理文档进入批量预览页），配置分块大小、重叠、自定义分隔符和文本清理。预览会真的读取并解析文档，但不会写入索引。

预览结果给出总览（分块数 / 总 Token / 总字符）与每个分块的 chunk_index、内容、token_count、char_count、overlap_length；重叠前缀在界面上以黄色高亮，便于确认重叠是否落在合理位置。预览页还支持直接编辑或删除单个分块。

文本清理会折叠空行

文本清理默认开启：它会把连续空行折叠成单个换行（\n\n → \n）、压缩行内多余空格并去掉每行首尾空白。对于靠空行划分段落的 Markdown，这会改变分块边界。如果文档结构依赖空行，先在预览中关闭文本清理再对比结果。

对待处理（pending）文档有两种启动方式，区别在于是否使用你确认过的分块内容：

操作	行为	适用场景
开始处理（预览页）	把预览中当前的分块内容原样提交，在服务端生成嵌入与全文索引	你已检查/编辑过预览分块
快速处理	按文档元数据或知识库设置直接重新提取与切分	内容干净、信任默认参数

处理是后台任务：提取文本 → 清理 → 切分 → 生成嵌入 → 建立全文索引。完成后文档状态变为 completed、写入 chunk_count/token_count，并更新知识库的总分块数与总 Token 数。

分块设置的有效来源优先级是：文档级设置（预览/处理时提交）> 知识库设置 > 内置默认值 1000/100。

两者都会替换原有分块，但入口不同：

重新处理（界面）：已处理文档的分块设置为只读，界面会提示使用重新处理。它会取消进行中的任务、删除旧分块与其向量、清空计数，然后按新设置在预览页重新走一遍流程。所有手工编辑的分块内容都会丢失。
重新分块（API/管理端）：POST /api/v1/knowledge-bases/{kb_id}/documents/{doc_id}/rechunk 直接提交新的 chunk_size/chunk_overlap/separator，语义与重新处理一致；文档处于 processing 时会被拒绝（document_processing）。

重新处理前先确认

重新处理不可撤销：旧分块、旧向量和全部手工修改都会被替换。文档在处理期间不能视为可检索完整；大批量重新处理会占用 Worker 队列，建议分批进行。

在文档详情页或预览页可以修改分块内容、在其后新增分块或删除分块：

分块内容不能为空。
保存时会剥离 HTML 标签（防 XSS），因此粘贴 <div> 之类的原始 HTML 会只剩文本内容，Markdown 语法（**加粗**、表格、围栏代码）不受影响。
保存后会重算该分块 Token 数（字符数 ÷ 4），并同步修正文档与知识库的 Token 统计。
保存会重新生成该分块的嵌入，并更新全文索引；任一步失败则回滚内容，提示 vector_update_failed。
单条分块嵌入失败时，用重试此分段；整篇失败时用重试失败分段。

现象	可能原因	处理方式
文本提取失败	文件损坏、加密、纯图片（无 OCR）或格式不支持	转换格式或重新导出后重传
分块为零	提取结果为空或全是空白字符	确认文件含可提取文本
部分/全部嵌入失败	嵌入模型凭据、配额、维度不匹配	检查模型授权与 `embedding_dimension`，再重试失败分段
全文召回不可用	PostgreSQL / `pg_search` 异常	检查数据库与扩展状态，文档需为 `completed`
任务堆积不结束	Worker 未运行或队列积压	查看 Worker 队列与 API 日志

只有文档状态为 error 且确实存在 failed 分块时，重试失败分段才可用；否则接口会返回 document_not_in_error_state 或 no_failed_chunks。