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 页的 PDF 手册丢给客服机器人问它任何条款都能答出出处背后就是 Qwen-Agent 文件解析在做的事解析、分块、落盘加缓存。本文讲清它怎么运转以及你拿到项目后第一步该干什么。喂进手册之后文件去哪了真实客服场景里你不会希望机器人每次被提问都把整份文档塞给模型——200 页、几万个 token又长又贵。Qwen-Agent 的办法是提前加工文件doc_parser.py 负责切storage.py 负责存simple_doc_parser.py 负责读文件。你往 DocParser 里传一个url本地路径或 http 链接它先查一次分块缓存没命中才调用 SimpleDocParser 解析产出页 段落结构每个段落都附带 token 数。解析结果本身也会缓存键是文件哈希 _ori所以下次再处理同一个文件不会重新读一遍 PDF。分块完成后内容被装进一个 Record包含文件来源、标题和全部切片的 JSON 壳写成单个 JSON 文件落盘再返回。下次调用只要文件和分块参数不变直接命中缓存日志会打印Read chunked ... from cache.——这就是知识库 Chunkchunk把文档切出来的一小段文本供模型逐段阅读缓存机制的全部秘密。Storage 本身极简每个 key 对应根目录下的一份纯文本文件put是写get在文件不存在时抛KeyNotExistsErrorDocParser 正是拿这个异常当缓存未命中的信号。Qwen-Agent 文件解析的数据流解析、分块、落盘三步走整条链路只有三步解析、分块、落盘需要做决定的地方只有两个。文档分块阈值配置20000 token 以下不切整篇解析完先累加所有段落的 token 得到total_token。只要total_token max_ref_token默认 20000可用环境变量QWEN_AGENT_DEFAULT_MAX_REF_TOKEN覆盖整篇文档就只生成 1 个 Chunk超过才进入split_doc_to_chunk。换句话说你的手册如果只有 3000 token分块没有意义模型一次就读完了。切好的结果长这样字段只有三个class Chunk(BaseModel): content: str # 切片正文 metadata: dict # source、title、chunk_id token: int # 该切片占用的 token 数你该盯的是token这一行整个分块算法都由它驱动——解析阶段先给每个段落数 token分块阶段再把它们从预算里逐段扣掉。跨块重叠_get_last_part 只取末尾 150 个字符split_doc_to_chunk按页遍历段落每放下一个段落就从parser_page_size默认 500即一块预算 500 token里扣掉对应 token扣不下的段落封块新块从_get_last_part截出的尾巴开始。单个段落超预算时先按.和。拆成句子句子仍超长按 token 硬切。_get_last_part负责截这个尾巴倒序累计、上限 150 字符def _get_last_part(self, chunk: list) - str: overlap need_page chunk[-1][1] # 只取同一页的内容 available_len 150 # 重叠预算只有 150 字符 for i in range(len(chunk) - 1, -1, -1): # …省略… 段落页码与 need_page 不一致时直接返回 # …省略… 按 . /。 拆句倒序累加, 凑满 150 字符即返回 return overlap该盯的是need_page这行重叠绝不跨页遇到翻页立即返回空新块就从干净页头开始。下一个 Chunk 以这 150 个字开头模型在块边界不会断上下文代价只是重叠部分被重复计了一遍 token150 字可以忽略。doc_parser 使用教程三步跑通拿到项目第一步是装 RAG 相关依赖pip install -U qwen-agent[rag]想要网页界面就装[gui,rag]再配置DASHSCOPE_API_KEY环境变量走 DashScope 服务或自部署模型服务。然后跑下面三行把 PDF 路径换成你自己的from qwen_agent.tools.doc_parser import DocParser parser DocParser() # 也可在 cfg 里传 max_ref_token / parser_page_size record parser.call({url: ./manual.pdf}) print(len(record[raw]), record[raw][0][content][:80])第二行不传 cfg 时两个参数取默认值 20000 和 500。跑完去workspace/tools/doc_parser/找应该多出一个 JSON 文件再跑一次日志出现Read chunked ... from cache.即缓存生效。想看完整效果examples/parallel_doc_qa.py 给了多文档问答加 WebUI 的例子python examples/parallel_doc_qa.py即可在网页里上传 PDF 提问参数细节可查官方文档指南。参数调优max_ref_token 与 parser_page_size 何时改两个参数都支持构造时经cfg传入优先级高于默认值也可用环境变量全局设定。max_ref_token决定要不要切同时也是 RAG 引用窗口的 token 预算。调小更多文件会走分块流程索引更细调大单次回答能带更多引用材料。模型上下文小就调小它。parser_page_size决定怎么切单个 Chunk 的 token 预算。合同、产品手册这类长句密集文档建议调到 1000条款不容易被拦腰截断想要更细的粒度就降到 200但切片数量变多每块还有 150 字重叠开销。注意缓存键和参数的联动分块缓存的键包含分块参数改完parser_page_size后同一个文件会重新分块并写入新的缓存文件旧的仍留在原地占空间可手动删。存储位置由 DocParser 的cfg里的path参数即 Storage 的storage_root_path目录会自动创建控制大规模知识库建议指到快的盘上。参数速查表参数默认值调大还是调小一句话理由max_ref_token20000模型上下文小就调小想少切就调大决定切不切、单次回答能带多少引用材料parser_page_size500长条款调大到 1000要细粒度调小到 200单个 Chunk 的 token 预算越小块越碎path存储路径workspace/tools/doc_parser换到更快的盘所有分块结果都落在这里QWEN_AGENT_DEFAULT_WORKSPACEworkspace按需改位置默认工作空间与存储根目录的父目录【免费下载链接】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），仅供参考