企业官网建设流程全解析

Qwen-Agent 文件解析实战指南：文件从上传到分块存储的完整链路，一次跑通你的知识库

【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen>=3.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.——这就是知识库 Chunk（chunk：把文档切出来的一小段文本，供模型逐段阅读）缓存机制的全部秘密。Storage 本身极简：每个 key 对应根目录下的一份纯文本文件，put是写，get在文件不存在时抛KeyNotExistsError，DocParser 正是拿这个异常当"缓存未命中"的信号。

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 个字开头，模型在块边界不会断上下文；代价只是重叠部分被重复计了一遍 token，150 字可以忽略。

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，目录会自动创建）控制，大规模知识库建议指到快的盘上。

参数速查表

【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen>=3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent