FastGPT Embedding 输入超长治理token 预算分块与 maxToken 硬兜底机制解析【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT导读FastGPT 的知识库入库、检索召回与 query extension 等链路都依赖 embedding 模型生成向量。此前部分链路仅按字符长度或分块规则控制文本大小而 embedding provider 实际按 token 限制输入长度导致超长文本在建索引、检索或相似度计算时直接失败。本文基于 FastGPT 仓库中的 embedding-token-limit-guard 功能开发文档完整梳理token 预算分块 getVectors 硬兜底这套双层治理方案从分块函数引入 token 计数能力、入库建索引按 token 拆分、检索与相似度阶段只截断不扩增到 provider 调用入口的统一截断兜底并结合仓库源码给出可验证的实现证据与测试关注点。1. 问题背景与治理目标1.1 三类典型超长失败场景文档明确指出此前存在三类由 token 超限引发的失败场景失败位置根因知识库入库建索引失败某个 index 文本超过 embedding 模型maxToken知识库检索query embedding 失败用户 query 或扩展 query 过长query extension / 文本相似度相似度 embedding 失败原始文本或候选文本过长这些链路的共同问题是字符长度 ≠ token 数。中文、代码、符号密集文本在同样字符数下 token 数差异巨大按字符切出的分块可能在 token 维度轻松越界。1.2 本次治理目标与处理原则治理目标一句话概括让知识库文本索引按 token 预算分块并保证最终进入 embedding 的文本不超过模型maxToken原始数据内容保持不变索引数量和粒度随 token 计数结果变化。围绕这一目标功能文档确立了以下处理原则不改原文不改变DatasetData.q/DatasetData.a的原文内容拆分只作用于索引文本。不改交互与向量库结构新增内部 rawText 预览 API把浏览器内的分块计算迁到服务端。不做存量迁移存量超长索引不自动迁移。不专项优化语义分块质量Markdown 表格、代码块、PDF 等语义化拆分不在本次范围只处理 token 上限与 header-only 等安全性问题。入库可拆分允许把一条 index 拆成多条 index尽量保留原始内容。检索/相似度不扩增query 与相似度输入不拆分为多条统一由 embedding 调用入口截断到安全长度。getVectors是最后一道硬兜底所有 text input 在请求 provider 前按模型maxToken截断image input 不参与文本截断。2. 分块函数的 token 计数能力textSplitter 改造2.1lengthUnit双模式设计改造的核心文件是 packages/service/common/string/textSplitter.ts。splitText2Chunks新增可选参数lengthUnit: char | token默认仍按字符长度执行token模式统一走o200k_basetokenizerexport type SplitProps { text: string; chunkSize: number; paragraphChunkDeep?: number; paragraphChunkMinSize?: number; maxSize?: number; overlapRatio?: number; customReg?: string[]; lengthUnit?: char | token; // 新增长度计数单位 maxChunks?: number; // 新增预览等不可信输入的工作量上限 };在源码中长度计数器和分块策略都根据lengthUnit动态选择textSplitter.ts 对应实现const getTextLengthCounter (props: SplitProps): TextLengthCounter props.lengthUnit token ? countPromptTokensInWorker : getTextValidLength; const getSplitTextByLengthLimit (props: SplitProps): SplitTextByLengthLimit props.lengthUnit token ? splitTextByCounterLengthLimit : splitTextByCharLengthLimit;char模式使用getTextValidLength统计字符按splitTextByCharLengthLimit机械切分。token模式使用countPromptTokensInWorker统计 token按splitTextByCounterLengthLimit走指数探测 二分的智能边界查找。2.2 token 模式的核心算法指数探测 二分token 模式下字符数与 token 数没有固定比例不能直接用字符下标推算边界。源码中的getMaxPrefixEndByLengthtextSplitter.ts 实现采用了两段式策略指数探测从当前游标start出发以maxLength为初始跨度尝试探测未超限则按span * 2指数扩大直到找到一个超限的probeEnd。二分收敛在[bestEnd 1, probeEnd - 1]区间内二分找出不超过maxLength的最长前缀边界。关键实现细节代码注释与函数名均印证指针只在当前 chunk 附近做探测与二分避免每次重复 tokenize 完整剩余文本splitTextByCounterLengthLimit内循环复用该函数。使用Array.from(text)按Unicode code point切分避免把 astral 字符emoji、生僻汉字的代理对截断成非法字符串。getMaxPrefixByLength与getMaxSuffixByLength后者服务于 overlap都返回 well-formed 文本overlap在 token 模式下也按同一个 token 计数器计算不退回字符长度。maxChunks提供工作量上限预览等不可信输入传入了maxChunks后任何累积分块数超过上限都会直接抛错assertChunkLimit防止单请求耗尽 worker 内存。同时commonSplit对非法参数直接报错chunkSize非正、overlapRatio不在[0, 1)、自定义分隔符含空项、maxChunks非正整数都会 throw。2.3 边界决策tokenizer 常驻 worker不把 tokenizer 放进packages/global避免 global 包承担后端运行时依赖。前端预览迁移到服务端前端fileCustom分块预览改为调用后端 rawText 预览接口因此textSplitter.ts可以整体迁到packages/service。token 模式只用于后端场景知识库 index 分块这类后端链路。text2Chunksworker 承载 tokenizer 常驻内存。主 API 进程通过 packages/service/worker/function.ts 提交可序列化的lengthUnit等参数export const text2Chunks async (props: SplitProps) { if (isTestEnv) { const { splitText2Chunks } await import(../common/string/textSplitter); return splitText2Chunks(props); } return getWorkerControllerSplitProps, SplitResponse({ name: WorkerNameEnum.text2Chunks, ...getLightweightWorkerPoolOptionsSplitProps(), taskTimeoutMs: 300000, maxTasksPerWorker: 100 }).run(props); };worker 内部实现见 packages/service/worker/text2Chunks/index.ts它接收SplitProps后直接调用splitText2Chunks并回传结果。统一的 token 计数器定义在 packages/service/worker/countGptMessagesTokens/count.tsGPT_TOKENIZER_ENCODING o200k_base即FastGPT 的 worker token 计数统一使用 GPT 现代模型的 o200k_base 编码用于上下文预算与缺 usage 时的近似兜底供应商返回 usage 时仍以 usage 为准。2.4 Markdown 表格的 token 安全处理在 token 模式下markdownTableSplit做了额外防护表格按行拆分后要补回表头因此表头 行内容的最终文本可能重新超限。源码提供了splitTextWithHeaderLimittextSplitter.ts 实现按defaultChunk表头 分隔行 候选行内容的最终文本做二分兜底保证拼回表头后仍不超过 embedding 上限。若表头单独就耗尽 token 预算会直接抛错Markdown table header leaves no token budget for row content只有表头没有数据行的表格不生成分块避免无检索内容的空语义索引。3. 知识库入库建索引按 token 预算拆分3.1 核心流程与 helper入库建索引的核心文件是 projects/app/src/service/core/dataset/data/dataIndex.ts文档给出的核心流程为原始 q/a/index text - 系统 q/a index 直接调用 text2Chunks 的 token 模式 - 按 min(indexSize, embedding maxToken - prefixTokens) 生成 index - 外部 index 未超限时保持原文超限时按同一 token 模式拆分 - 再写入向量库对应两个核心 helper源码均已实现splitIndexTextByTokenLimit // 按 token 预算拆分索引正文并补前缀 buildEmbeddingSafeIndexTexts // 未超限保持原文超限时走 token-safe 二次拆分3.2splitIndexTextByTokenLimit正文预算 maxToken - 前缀源码实现dataIndex.ts 实现关键逻辑const prefixTokens indexPrefix ? await countPromptTokens(${indexPrefix}\n) : 0; const maxContentTokens maxToken - prefixTokens; if (maxContentTokens 0) { throw new Error(Dataset index prefix is too long for embedding token limit); } if (maxContentTokens minChunkSize) { throw new Error(Dataset index content token budget is smaller than minimum chunk size); } const normalizedIndexSize Math.max(indexSize, minChunkSize); const chunkTokenLimit Math.min(normalizedIndexSize, maxContentTokens); const chunks (await text2Chunks({ text: trimmedText, chunkSize: chunkTokenLimit, maxSize: chunkTokenLimit, lengthUnit: token })).chunks; return chunks .map((chunk) formatIndexTextWithPrefix(chunk, indexPrefix)) .filter((item) item.trim());要点前缀先扣预算如果存在indexPrefix先拼出前缀 正文的最终文本再计算 token正文预算为maxToken - prefixTokens保证最终送 embedding 的文本不超过模型上限。indexSize 下限保护indexSize下限沿用知识库分块最小值避免前缀挤压后传入过小 token 预算。minChunkSize 64定义在 packages/global/core/dataset/training/utils.ts。前缀幂等formatIndexTextWithPrefix只在文本未以indexPrefix开头时补前缀保证重复调用幂等dataIndex.ts 实现。3.3buildEmbeddingSafeIndexTexts未超限不重分为了不无谓重建向量未超限的既有索引保持原文dataIndex.ts 实现const formattedText formatIndexTextWithPrefix(text, indexPrefix); if ((await countPromptTokens(formattedText)) maxToken) { return [formattedText]; // 保持原文不重分 } return splitIndexTextByTokenLimit({ text: trimmedText, indexSize, maxToken, indexPrefix });3.4 系统索引与外部索引的处理在DatasetDataIndexOperation类中getSystemIndexesdataIndex.ts 实现系统默认索引直接按 token 模式和indexSize生成——q与a分别经splitIndexTextByTokenLimit生成多条default类型索引imageEmbedding类型索引由图片源生成且不参与文本 token 拆分。formatIndexesdataIndex.ts 实现系统索引复用上一步的安全结果外部文本索引通过buildEmbeddingSafeIndexTexts只在超过 embedding 上限时拆分拆出的新 index 保持原索引类型imageEmbedding索引直接返回不处理。拆分语义功能文档明确强调拆分只作用于indexes[].text不会改q/a原文。拆出来的新 index 都保持原索引类型。如果一条超长 index 被拆成多条新 index 会重新生成向量不复用旧dataId。文本未变化时会沿用已有 dataId避免重复重建向量mergeExistingSystemIndexIds按type:text匹配复用旧 dataId。3.5 人工维护索引的写入保护writeDatasetDataIndexdataIndex.ts 实现对人工维护的索引单独校验文本为空拒绝、系统索引类型不允许单独保存、textTokens this.maxToken时直接拒绝Dataset data index text is too long。内容与类型都没变化时复用旧索引避免重复消耗 embedding tokens。4. 检索阶段只截断不扩增4.1 embeddingRecall 的处理流程检索阶段的核心文件是 packages/service/core/dataset/search/defaultRecall/embeddingRecall.ts处理对象为textQueries与imageCaptionQueriesquery - trim/filter - 调用 getVectors - getVectors 内部按 embedding maxToken 截断 text inputbuildVectorRecallTasksembeddingRecall.ts 实现将文本 query 与图片描述 query 统一 trim 并过滤空项后以{ type: text, input: query }结构提交给getVectors图片 query 只有在当前 embedding 模型支持图片时才会转 base64 并作为{ type: image, input }进入单张图片解析失败会被跳过不影响其他任务。4.2 关键约束不把一个 query 拆成多个 query检索阶段的 query 数量在传入getVectors前后保持一致。图片 URL query 不走文本 token 截断以 image 类型进入 provider。下游逻辑不变检索结果合并、rerank、RRF、limit、similarity 等逻辑均不因本次改造变化。limit 0时直接返回空结果与 0 tokenembeddingRecall.ts 实现。5. 文本相似度 / query extensionlazy greedy 选择前的安全兜底5.1 useTextCosine 的调用链query extension / 文本相似度阶段的核心文件是 packages/service/core/ai/hooks/useTextCosine.ts处理对象为originalText与candidates[]originalText / candidates - 过滤空文本 - 调用 getVectors 计算向量 - getVectors 内部按 embedding maxToken 截断 text input - 继续执行原 lazy greedy selection 逻辑源码中lazyGreedyQuerySelectionuseTextCosine.ts 实现先对originalTexttrim、对 candidates trim 并过滤空项然后一次性把[query, ...normalizedCandidates]作为 text inputs 提交getVectors之后执行基于最大边际收益relevance diversityalpha 0.3的贪心选择。5.2 关键约束候选数量不扩增超长候选不会被拆成多条输入。展示内容不受截断影响返回的selectedData仍是原始候选文本的 trim 结果不因为 embedding 截断改变展示内容。空输入短路原始文本为空、无有效候选或k 0时直接返回{ selectedData: [], embeddingTokens: 0 }不调用 embeddinguseTextCosine.ts 实现。6. provider 调用入口getVectors 最后硬兜底6.1 统一截断流程embedding provider 调用的核心文件是 packages/service/core/ai/embedding/index.ts 与新增的 packages/service/core/ai/embedding/tokenLimit.tsgetVectors inputs - 校验输入结构和空输入 - 批量统计 text input token 数 - 只对超限 text input 按 model.maxToken 截断 - 按 text / image 组装 provider 请求 - 调用 embedding provider - provider 返回错误时按原错误链路抛出源码实现embedding/index.ts 实现const validatedInputs z .array(InputItemSchema) .parse(rawInputs) .map((item) ({ ...item, input: item.input.trim() })); if (validatedInputs.length 0 || validatedInputs.some((item) !item.input)) { return Promise.reject({ code: 500, message: input is empty }); } const textInputs validatedInputs.filter((item) item.type text).map((item) item.input); const textTokenCounts textInputs.length 0 ? await countPromptTokensBatch(textInputs) : []; // 只对超限 text 做单条截断兜底不做拆分 input: item.type text ? await truncateTextByFormattedTokenLimit({ text: item.input, maxToken: model.config.maxToken, currentTokens }) : item.input要点批量预判先countPromptTokensBatch批量统计所有 text input 的 token 数再只对超限的文本调用截断避免每个调用点重复写截断逻辑。image 保持原结构image input 以{ type: image_url, image_url: { url } }结构进入 provider不走文本 token 统计embedding/index.ts 实现。batchSize 分片请求按model.config.batchSize分片顺序提交单片内按retryFn重试provider 返回错误时沿用原错误链路抛出。向量格式化返回的 embedding 统一经formatVectors处理超过 1536 维截断并强制 L2 归一化不足 1536 维补零normalization开关控制是否归一化embedding/index.ts 实现。6.2 truncateTextByFormattedTokenLimit二分最长安全前缀packages/service/core/ai/embedding/tokenLimit.ts 中的truncateTextByFormattedTokenLimit是截断核心formatText 兜底formatText用于处理实际送入 embedding 的文本并不等于原文的场景例如知识库索引补集合标题前缀函数始终返回原文前缀由调用方决定如何组装最终文本。先判断再截断maxToken非有限或 0时原样返回formattedTokens maxToken时原样返回不产生任何截断。二分查找将文本按Array.from切成 code point 数组后二分找出不超过maxToken的最长前缀不会生成孤立 surrogate。只截断不拆分函数注释明确只做单条输入截断不会把一条文本拆成多条文本入库索引需要保留内容时应在分块阶段完成拆分。6.3 两层配合的完整语义阶段策略实现位置入库索引允许拆分为多条 token-safe indexdataIndex.ts检索 query只截断不扩增embeddingRecall.ts相似度输入只截断不扩增useTextCosine.tsprovider 入口单条截断硬兜底embedding/index.ts tokenLimit.ts注意provider 的 tokenizer 与本地 o200k_base tokenizer 可能存在差异如果 provider 仍返回超限错误继续沿用原错误链路抛出——最终是否超限以 provider 返回为准。7. rawText 预览 API分块计算迁到服务端7.1 新接口与权限校验前端fileCustom分块预览改为调用后端接口 projects/app/src/pages/api/core/dataset/file/getRawTextPreviewChunks.ts原 getPreviewChunks.ts 相应调整分块计算不再依赖浏览器端实现。接口安全设计权限校验authDataset要求WritePermissionVal写权限无知识库写权限时不执行分块。请求体限制bodyParser.sizeLimit 10mb防止超大请求体。工作量上限传入maxChunks: maxPreviewChunkCount值为 50,000见 packages/global/core/dataset/training/utils.ts超过上限返回分块错误避免单请求耗尽 worker 内存。非法参数拒绝自定义分隔符不允许空项、首尾|或连续||源码customReg.forEach校验空项overlapRatio、chunkSize必须落在安全业务范围overlapRatio ∈ [0,1)、chunkSize为正有限数。S3 key 预览化预览返回的图片等资源通过replaceS3KeyToPreviewUrl转换为带 1 天有效期的预览 URL。7.2 预览参数的标准化预览前会通过computedCollectionChunkSettings结合知识库的 agent 模型与 embedding 模型计算标准分块参数maxSize由getLLMMaxChunkSize(getDatasetAgentModel(dataset))得出默认defaultMaxChunkSize 8000见 packages/global/core/dataset/training/utils.ts保证预览与真实入库分块参数一致。8. 测试关注点与验收标准功能文档给出了四组单测与一组 API 测试的完整关注点全部有对应测试文件8.1 入库建索引测试测试文件projects/app/test/service/core/dataset/data/dataIndex.test.ts建议验证超长q/a生成多条 token-safe 默认索引超长自定义文本 index 拆成多条同类型 indeximageEmbeddingindex 不参与文本拆分短文本不额外拆分带indexPrefix时按前缀 正文的最终文本计算 token。验收标准每条最终写入向量库的文本 index token ≤ 当前 embedding model.maxToken8.2 检索阶段测试测试文件packages/service/test/core/dataset/search/defaultRecall.test.ts建议验证超长textQueries/imageCaptionQueries不扩增为多条 query图片 query 不受文本截断影响。验收标准检索阶段把有效文本 query 原样交给 getVectors最终截断由 getVectors 统一兜底8.3 文本相似度测试测试文件packages/service/test/core/ai/hooks/useTextCosine.test.ts建议验证originalText与超长candidates[]不扩增selectedData仍使用原候选文本k 0或无有效文本时不调用 embedding。验收标准useTextCosine 只做 trim/filter 和选择逻辑最终截断由 getVectors 统一兜底8.4 provider 调用入口测试测试文件packages/service/test/core/ai/embedding/index.test.ts建议验证空 inputs 或空文本 input 本地拒绝超长 text input 在请求 provider 前按model.maxToken截断image input 按 image_url 结构进入 providerprovider 错误沿原链路抛出包含 emoji、生僻汉字等 astral Unicode 字符时截断结果保持 well-formed。验收标准getVectors 是 embedding 超长文本的最后硬兜底provider 错误仍能正常透出8.5 rawText 预览 API 安全测试测试文件projects/app/test/pages/api/core/dataset/file/getRawTextPreviewChunks.test.ts 与 packages/service/test/common/string/textSplitter.test.ts建议验证无知识库写权限不执行分块自定义分隔符不允许空项、首尾|或连续||overlapRatio、chunkSize落在安全业务范围超过maxChunks的工作量会在继续分配大数组前终止。9. 手工测试步骤9.1 测试前准备由于改动在服务端逻辑手工测试前需要重启 app 服务。确认运行的是包含本次改动的分支。对已有数据测试时重新触发更新索引或重新上传文件。如果服务未重启或仍查看旧数据索引页面可能仍显示旧逻辑生成的索引数量。9.2 入库阶段手工验证操作创建/选择知识库 → 上传包含超长文本的文件 → 等待训练任务完成 → 打开数据详情查看数据索引。预期训练任务不应因为 embedding max-token 超限失败。数据可以正常完成索引生成。超长 index 可能被拆成多条默认索引。拆分结果不保证保持 Markdown 表格头、代码块边界或语义完整性。9.3 检索阶段手工验证操作在知识库检索测试或应用对话中输入超长 query → 触发语义检索。预期不应因为 query embedding 超长导致请求失败。检索会基于截断后的 query 执行。不会因为一个超长 query 扩增成多个 query。10. 非目标与风险注意事项10.1 非目标本次不解决Markdown 表格按行、列、单元格拆得更适合检索。PDF、Excel、代码块等内容的语义化分块质量。超长 query 摘要后再检索。存量超长索引的自动迁移。前端展示索引时的折叠、摘要或虚拟滚动体验。功能文档特别强调后续如果要优化索引质量应单独设计知识库分块质量优化方案不应混在 embedding max-token 兜底里。10.2 风险与注意事项token 消耗增加入库阶段超长 index 拆成多条后向量数量增加可能带来更多 embedding token 消耗。召回准确性风险query 截断会丢弃尾部信息极端情况下可能影响召回准确性。tokenizer 差异当前 token 统计使用 FastGPT 统一 token workero200k_base与具体 provider 的 tokenizer 可能存在轻微差异。预览工作量上限rawText 预览最多生成 50,000 个 chunk超过上限返回分块错误避免单请求耗尽 worker 内存。11. 验收结论本次功能验收只看一个核心结果FastGPT 已知上游入口会尽量把 text input 控制在对应 embedding model.maxToken 内最终是否超限以 provider 返回为准。整体策略总结为三层配合入库阶段允许拆分为多条 index 以尽量保留内容检索和相似度阶段只截断、不扩增 query 数量getVectors在 provider 入口批量预判 token 数并只截断超限文本作为最后硬兜底。相关修改涉及 packages/service/common/string/textSplitter.ts、packages/service/core/ai/embedding/index.ts、packages/service/core/ai/embedding/tokenLimit.ts、packages/service/core/ai/hooks/useTextCosine.ts、packages/service/core/dataset/search/defaultRecall/embeddingRecall.ts、projects/app/src/service/core/dataset/data/dataIndex.ts 及配套测试这一治理能力让知识库在混合多语言、超长文本场景下避免因 embedding 输入超限而中断建库与检索流程。【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考