为什么 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丢进去一份几十页的 PDF 直接提问Qwen-Agent 不会把全文塞给模型而是先把文件解析、智能分块、缓存成一批大小适中的文本块再拿去检索回答。这篇内容从一个真实提问流程讲起把文档解析、切块细节和缓存机制拆给你看你能明白为什么自己的文档会被从句子中间切开以及怎么改切块粒度。上传之后文档到底经历了什么入口是示例 parallel_doc_qa.py你把 PDF 链接交给 ParallelDocQA背后真正干活的是doc_parser这个工具。整个流程就四步文档解析器DocParser先用 SimpleDocParser 把文件按页、按段抽成结构化文本统计全文 token 总数和阈值max_ref_token比较没超阈值就整篇当一个 chunk超了就交给split_doc_to_chunk做智能分块把分块结果写入存储工具Storage落盘下次直接命中分支判断在 doc_parser.py 的call方法里if total_token max_ref_token: # 整篇文档当一个 chunk content [Chunk(contentget_plain_doc(doc), metadata{source: url, title: title, chunk_id: 0}, tokentotal_token)] else: # 智能分块 content self.split_doc_to_chunk(doc, url, titletitle, parser_page_sizeparser_page_size)小文件一次处理完厚文档则被切成若干页大小的块。两种分支产出的都是 Chunk 列表每个块带source、title、chunk_id元数据方便后续检索时回溯出处。为什么切块会把文档从句子中间切开分完块之后要考虑的不是快而是语义完整——把一段话拦腰截断模型对前后两半的理解都会打折。split_doc_to_chunk逐页遍历段落往当前块里填直到接近parser_page_size默认 500 token。单段超了剩余空间就先按句子\. |。切开单句还是太长就用 tokenizer 把句子按 token 硬切成若干片保证每块都能填满、且尽量不破坏语义单元。更隐蔽的细节在_get_last_part里一个块写满要交付时它会从末尾倒着取最多 150 个字符作为下一个块的开头。这样模型读到新块开头时还带着上文不会突然失忆def _get_last_part(self, chunk: list) - str: overlap available_len 150 # 最多取 150 个字符 for i in range(len(chunk) - 1, -1, -1): para chunk[i][0] if len(para) available_len: overlap f{para}{PARAGRAPH_SPLIT_SYMBOL}{overlap} available_len - len(para) ... return overlap所以你在分块结果里看到上一块的尾句出现在下一块开头时不是 bug是刻意保留的重叠。缓存没命中时怎么办块切好了数据去哪儿storage.py 是个基于文件系统的键值存储一个 key 对应磁盘上一个文件根目录默认在workspace/tools/doc_parser。缓存 key 的拼法是 URL 的 SHA-256 哈希加分块参数同一份文件用不同parser_page_size切出来的结果各占一个文件互不覆盖。每次调用先查磁盘查不到才真正解析cached_name_chunking f{hash_sha256(url)}_{str(parser_page_size)} try: record self.db.get(cached_name_chunking) return json.loads(record) except KeyNotExistsError: doc self.doc_extractor.call({url: url}) # 未命中开始解析改了分块参数觉得结果不对就进workspace/tools/doc_parser目录把对应文件删掉强制重新解析一次。get、delete这些操作落到磁盘上就是普通的读文件和删文件行为完全可预期。动手调这两个参数试试文件解析的行为主要由两个参数决定都能用环境变量覆盖参数作用默认值环境变量max_ref_token整篇文档直接当一个 chunk 的 token 阈值20000QWEN_AGENT_DEFAULT_MAX_REF_TOKENparser_page_size单个 chunk 的 token 上限500QWEN_AGENT_DEFAULT_PARSER_PAGE_SIZE文档长段落多、希望每次检索带更多上下文就把parser_page_size调到 800 或 1000模型上下文窗口小就调低max_ref_token让它更早切块QWEN_AGENT_DEFAULT_PARSER_PAGE_SIZE800 python examples/parallel_doc_qa.py参数改完记得先清掉workspace/tools/doc_parser下的旧文件否则拿到的还是旧的分块结果。跑一遍示例在 Web 界面上对着文档内容提问就能直观验证新的切块粒度合不合用。【免费下载链接】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），仅供参考
为什么 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丢进去一份几十页的 PDF 直接提问Qwen-Agent 不会把全文塞给模型而是先把文件解析、智能分块、缓存成一批大小适中的文本块再拿去检索回答。这篇内容从一个真实提问流程讲起把文档解析、切块细节和缓存机制拆给你看你能明白为什么自己的文档会被从句子中间切开以及怎么改切块粒度。上传之后文档到底经历了什么入口是示例 parallel_doc_qa.py你把 PDF 链接交给 ParallelDocQA背后真正干活的是doc_parser这个工具。整个流程就四步文档解析器DocParser先用 SimpleDocParser 把文件按页、按段抽成结构化文本统计全文 token 总数和阈值max_ref_token比较没超阈值就整篇当一个 chunk超了就交给split_doc_to_chunk做智能分块把分块结果写入存储工具Storage落盘下次直接命中分支判断在 doc_parser.py 的call方法里if total_token max_ref_token: # 整篇文档当一个 chunk content [Chunk(contentget_plain_doc(doc), metadata{source: url, title: title, chunk_id: 0}, tokentotal_token)] else: # 智能分块 content self.split_doc_to_chunk(doc, url, titletitle, parser_page_sizeparser_page_size)小文件一次处理完厚文档则被切成若干页大小的块。两种分支产出的都是 Chunk 列表每个块带source、title、chunk_id元数据方便后续检索时回溯出处。为什么切块会把文档从句子中间切开分完块之后要考虑的不是快而是语义完整——把一段话拦腰截断模型对前后两半的理解都会打折。split_doc_to_chunk逐页遍历段落往当前块里填直到接近parser_page_size默认 500 token。单段超了剩余空间就先按句子\. |。切开单句还是太长就用 tokenizer 把句子按 token 硬切成若干片保证每块都能填满、且尽量不破坏语义单元。更隐蔽的细节在_get_last_part里一个块写满要交付时它会从末尾倒着取最多 150 个字符作为下一个块的开头。这样模型读到新块开头时还带着上文不会突然失忆def _get_last_part(self, chunk: list) - str: overlap available_len 150 # 最多取 150 个字符 for i in range(len(chunk) - 1, -1, -1): para chunk[i][0] if len(para) available_len: overlap f{para}{PARAGRAPH_SPLIT_SYMBOL}{overlap} available_len - len(para) ... return overlap所以你在分块结果里看到上一块的尾句出现在下一块开头时不是 bug是刻意保留的重叠。缓存没命中时怎么办块切好了数据去哪儿storage.py 是个基于文件系统的键值存储一个 key 对应磁盘上一个文件根目录默认在workspace/tools/doc_parser。缓存 key 的拼法是 URL 的 SHA-256 哈希加分块参数同一份文件用不同parser_page_size切出来的结果各占一个文件互不覆盖。每次调用先查磁盘查不到才真正解析cached_name_chunking f{hash_sha256(url)}_{str(parser_page_size)} try: record self.db.get(cached_name_chunking) return json.loads(record) except KeyNotExistsError: doc self.doc_extractor.call({url: url}) # 未命中开始解析改了分块参数觉得结果不对就进workspace/tools/doc_parser目录把对应文件删掉强制重新解析一次。get、delete这些操作落到磁盘上就是普通的读文件和删文件行为完全可预期。动手调这两个参数试试文件解析的行为主要由两个参数决定都能用环境变量覆盖参数作用默认值环境变量max_ref_token整篇文档直接当一个 chunk 的 token 阈值20000QWEN_AGENT_DEFAULT_MAX_REF_TOKENparser_page_size单个 chunk 的 token 上限500QWEN_AGENT_DEFAULT_PARSER_PAGE_SIZE文档长段落多、希望每次检索带更多上下文就把parser_page_size调到 800 或 1000模型上下文窗口小就调低max_ref_token让它更早切块QWEN_AGENT_DEFAULT_PARSER_PAGE_SIZE800 python examples/parallel_doc_qa.py参数改完记得先清掉workspace/tools/doc_parser下的旧文件否则拿到的还是旧的分块结果。跑一遍示例在 Web 界面上对着文档内容提问就能直观验证新的切块粒度合不合用。【免费下载链接】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），仅供参考
)
