Workbuddy 长文本 API 的预切分功能怎么开启，分块大小和重叠比例该怎么设？

Workbuddy 的长文本 API 预切分默认不开启，要让它在某一次调用里真正生效，需要同时满足三个条件：该 API Key 所属项目在控制台开启了长文本预处理开关、请求体里显式传入了分块参数、所用 SDK 版本支持并把参数透传到服务端；只传几百字的短文本时，即使三处都配好也不会触发切分，因为未超过单次上下文窗口的输入会走普通调用链路。 把预切分理解成“控制台里的一个开关”是最常见的误判，它实际是项目级授权加请求级声明的双层结构。项目级开关只回答“这个项目允许不允许切分”，请求级参数才回答“这一次调用切不切、按多大粒度切”，两者缺一，服务端都会按原始全文直送模型。所以排查“开了没反应”时，先看请求体有没有带参数，再回头看控制台，顺序反了会浪费很多时间。 开启之前要先量清楚三个量：待处理文本的实际长度、所选模型的单次上下文窗口、调用方式是流式还是一次性返回。文本长度超过模型窗口才需要预切分；接近但未超过窗口时，开切分反而增加调用次数和总 token；流式场景下切分会让分块边界出现在输出流中间，前端拼接逻辑必须一起改，否则会出现重复片段。 请求体里的分块参数是决定效果的核心，通常包含块大小和块间重叠两个字段。块大小按 token 计，应设成明显小于模型上下文窗口的值，给提示词和模型输出留出空间；重叠比例一般取块大小的百分之十到百分之十五，用来避免句子被从中间切断导致语义丢失。重叠设得过小会出现跨块的指代断裂，设得过大则同一段文字被重复送入模型，成本按比例上升。 控制台入口的命名在不同版本里并不统一，常见位置是项目设置下的长文本处理、文档预处理或上下文管理一类分组，开关旁边通常还有一个默认分块大小的输入框。这个输入框只提供默认值，一旦请求体里传了同名参数就会以请求体为准；如果只依赖控制台默认值而代码里又传了空值，部分版本会按“未声明”处理并退回整篇直送，这是配置看起来正确却不起作用的典型情形。 SDK 版本过低会静默丢弃分块参数，这是“参数明明传了却没生效”的第一嫌疑。老版本 SDK 在构造请求时只序列化白名单字段，新增的切分参数不在白名单里就被直接丢掉，HTTP 状态码依旧返回成功。做法是先升级到文档标注的最低支持版本，再在调试日志里打印实际发出的请求体，确认字段真的出现在网络上，而不是只出现在代码里。 验证预切分是否真的开启，不能看接口返回二百就下结论，要看响应结构里有没有分块元信息。启用后通常会在响应中附带分块数量的统计字段，或在分块模式下返回数组结构，每个元素对应一段的输入与输出。拿一段明显超过窗口的长文做对照实验，开启前后分别记录分块数量和总 token，数字一致就说明参数没落地，需要回到上一段查版本与请求体。 预切分只负责边界处理，不负责理解，它和分段摘要、分段检索是不同层级的能力。切分之后的每一块对模型来说是独立上下文，块与块之间不会自动共享记忆；如果任务本身要求跨全篇做归纳、比对或排序，切开再拼回来的结果往往不如一次直送。反过来，抽取条款、逐段校对、按章节生成摘要这类任务，切分带来的收益才明显。 成本上要算两笔账：切分动作本身在多数实现里不单独计费，但切分后每一块都要重新携带系统提示词和重叠内容，总输入 token 会随块数线性增长。块数等于文本长度除以有效块长，有效块长是块大小减去重叠部分，因此重叠比例翻倍会直接让总 token 明显上升。长文档批处理场景应先在小样本上算出单篇 token 与切分数，再决定批量任务的实际预算。 数据边界同样要在开启前想清楚，服务端切分意味着全文先进入对方处理链路再分段调用模型。对合同、病历、内部纪要这类文本，更稳妥的做法是在客户端按段落或章节自行切分，逐块发送并在本地维护块序，服务端只做单块推理。这样既保留了长文本处理能力，又把全文拼装的环节留在自己这一侧，审计时也更容易说明数据流向。 开启后可能遇到的报错有大致固定的排查顺序。返回参数校验类错误，多半是块大小超过模型允许的上限或小于最小值；输出被截断且末尾突然中断，通常是没算重叠导致某一块超窗；同一段内容重复出现，是重叠比例过大或前端流式拼接逻辑重复消费；完全没有分块痕迹，则回到 SDK 版本与请求体两个方向查。 一个可复用的判断清单是这样：文本是否真的超过模型窗口、任务是否需要跨段整体推理、项目开关是否对该 API Key 生效、请求体是否显式带了块大小与重叠、SDK 是否会丢弃未知字段、响应里有没有分块元信息、批量任务的 token 预算是否按有效块长算过。这七项里任何一项为否，先补那一项，再去调分块大小，否则参数怎么调都看不出差别。具体到某个版本的菜单命名与最低 SDK 版本号，以官方文档说明为准。