分块与文档处理

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

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

分块按「字符」计数

分块大小与分块重叠的单位都是字符。界面展示的 Token 数只是粗略估算，用于判断上下文预算，不参与切割。中文与英文混排时两者比例差异很大，所以按 Token 调参时要留出余量。

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

Markdown 与纯文本走不同切分路径

系统先判断文本是否包含 Markdown 结构（标题、代码围栏、表格、列表是主要信号），再决定切分方式：

Markdown 模式：按结构块切分（标题、表格、代码块、列表、段落）。小表格整体保留，列表项不被拆散，未闭合的代码围栏会自动补全闭合。分块会记录所属章节（如 第一章 > 第二节）与类型（表格或代码），方便定位来源。
纯文本模式：按默认分隔符优先级依次尝试：段落空行、换行、中文句号、感叹号、问号、英文句末、分号、逗号、空格，最后才按单字符切分。

结构边界与重叠

Markdown 路径的切分规则比纯文本严格，调参前先了解这几条边界：

1–2 级标题是强制分块边界：当前分块已有内容时遇到一级或二级标题会先结束当前分块；三级及更深的标题不强制断开，只更新所属章节。
超大表格按行拆分：单个表格超过分块大小时逐行切分，每段都重复表头，检索命中续段时仍能读懂列含义。
超大代码块递归切分：代码块整体保留；超过上限时继续切分，并为每段补上语言标记与闭合围栏，避免出现半截围栏。
表格与代码块不加字符重叠：精确字符重叠只在相邻的文本/列表分块之间施加；只要相邻分块任一侧是表格或代码，就不前置重叠文本，防止表格行或代码被截断后混入上下文。
只有表格和代码有类型标记：普通文本与列表分块不写类型，因此不要指望用「列表」过滤列表分块。

重叠按精确字符数计算

分块重叠是精确的字符数，不是按句子或段落估算。中文句子常整段超过重叠值，按句子计算会得到远超预期的重叠量；精确字符重叠能保证中文内容得到你设定的重叠长度。

自定义分隔符是硬切分边界

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

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

预览

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

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

文本清理会折叠空行

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

处理

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

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

处理在后台执行：提取文本 → 清理 → 切分 → 生成嵌入 → 建立全文索引。完成后文档状态变为已完成，并更新分块数与 Token 数，以及知识库的总分块数与总 Token 数。

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

重新处理与重新分块

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

重新处理（界面）：已处理文档的分块设置为只读，界面会提示使用重新处理。它会取消进行中的任务、删除旧分块与其向量、清空计数，然后按新设置在预览页重新走一遍流程。所有手工编辑的分块内容都会丢失。
重新分块（通过程序提交）：语义与重新处理一致，直接提交新的分块大小、重叠和分隔符；文档正在处理时会被拒绝。

重新处理前先确认

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

编辑分块

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

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

失败处理

现象	可能原因	处理方式
文本提取失败	文件损坏、加密、纯图片（无 OCR）或格式不支持	转换格式或重新导出后重传
分块为零	提取结果为空或全是空白字符	确认文件含可提取文本
部分/全部嵌入失败	嵌入模型凭据、配额、维度不匹配	检查模型授权与向量维度，再重试失败分段
全文召回不可用	检索服务异常	联系管理员检查服务状态，确认文档已完成
任务堆积不结束	后台处理能力不足	联系管理员检查后台处理状态与日志

只有文档状态为失败且确实存在失败分块时，重试失败分段才可用。