Qwen-Agent 文档切块阈值、重叠与缓存键【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent你往上传框拖进一份 200 页 PDFQwen-Agent 的文件解析只做三个决定要不要智能分块、每块多大、知识库缓存键怎么算。第一站这份 PDF 被拆成了几块进入 qwen_agent/tools/doc_parser.py 的DocParser.call后系统先把每一页每段落的 token 数累加出total_token再拿它和max_ref_token比。默认max_ref_token是 20000DEFAULT_MAX_REF_TOKEN你的 200 页 PDF 远超这个数所以走 else 分支交给split_doc_to_chunk按parser_page_size默认 500 token/块去切。为什么这样切20000 token 大致是一次模型调用能吃下的参考资料上限小文档塞进一个 chunk 就够了大文档必须切成 500 token 左右的小块每块都能独立塞进上下文。阈值分支tools/doc_parser.py:call()# tools/doc_parser.py:call() L128-141 if total_token max_ref_token: content [Chunk(contentget_plain_doc(doc), metadatameta, tokentotal_token)] cached_name_chunking f{hash_sha256(url)}_without_chunking else: content self.split_doc_to_chunk(doc, url, titletitle, parser_page_sizeparser_page_size)切块是贪心装箱available_token初始等于parser_page_size段落逐段塞进当前块、扣减预算扣不下就封块、开新块。每个块开头插一行[page: N]页码标记方便回原文定位封块前若块里只剩页码标记会pop掉避免空块。遇到一段太长先按.或。切成句子再装单句还超长就按available_token直接把句子截断。封块时_get_last_part从末尾取最多 150 字符作下一块开头且只取同一页need_page校验的内容让交界处的句子不被拦腰截断。200 页 PDF 大概会切成几百个 500 token 的 chunk。第二站拆完的块存到哪、怎么找回来分块结果不直接返回就丢而是写进磁盘。键只有一行缓存键怎么算tools/doc_parser.py:call()# tools/doc_parser.py:call() L106 cached_name_chunking f{hash_sha256(url)}_{str(parser_page_size)}Storageqwen_agent/tools/storage.py把每个键当一个文件名落在workspace/tools/doc_parser目录里put时os.makedirs建目录、再save_text_to_file写整段 JSON。同一份 PDF 第二次进来call开头就self.db.get(cached_name_chunking)命中直接json.loads返回跳过解析和切块日志打Read chunked ... from cache.。键里带了parser_page_size你换个 page_size 重跑键变了旧缓存不命中整份重新切一遍。整份不切块那条路会把键改写成{hash}_without_chunking所以「切过」和「没切过」两份结果互不覆盖。第三站提问时怎么从几百块里捞出答案最直接的入口是 examples/parallel_doc_qa.py。它先doc_parse把文件变成 chunk走上面那套缓存再调retrieval工具qwen_agent/tools/retrieval.py。Retrieval.call内部就两步先doc_parse再search两条路复用同一份 chunk 缓存。检索本身也只做两件事——先用GenKeyword让模型把问题抽成中英文关键词再把所有 chunk 摊平丢进 BM25rank_bm25的BM25Okapi算分、按分排序取 top-k 拼成参考资料喂给模型若整份文档 token 没超max_ref_tokenBaseSearch会直接返回全文、不进 BM25。parallel_doc_qa更狠一点按PARALLEL_CHUNK_SIZE1000切块给每个 chunk 起一个并行成员 Agent 去答答完再用retrieval在 4500 token 内召回资料做汇总。踩坑与调参⚠️parser_page_size— 默认 500 token/块调大到 1000parallel_doc_qa里PARALLEL_CHUNK_SIZE的值单块信息更完整但 BM25 命中变粗、单块更占上下文调小到 300RAG_CHUNK_SIZE的值块多、召回更细跨块语义断裂却更多。⚠️max_ref_token— 默认 20000调大让更多文档「不切块整份进」超长的会被模型上下文截断调小则分块更频繁、检索更准每块也更碎。缓存键里的parser_page_size— 换 page_size 重跑会生成新键、旧缓存失效整份重切一遍想复用缓存就保持同一 page_size。重叠字符数 — 硬编码在_get_last_part的available_len150且只取同页调大跨块信息多、相邻块重复 token 也多调成 0 则块边界句子可能被截断。想自己验分块数量改完parser_page_size跑python examples/parallel_doc_qa.py看日志里的 chunk 数参数细节见 README.md。【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
