Qwen-Agent 文档分块实战：3 个参数让 RAG 知识库从上传到问答一次跑通

Qwen-Agent 文档分块实战3 个参数让 RAG 知识库从上传到问答一次跑通【免费下载链接】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 丢给 AI它却答非所问多半是文档太长超出了模型窗口。Qwen-Agent 的文档解析加本地缓存机制负责把它切成可控的文本块并反复复用是搭建 RAG 知识库的地基。️ 一张图看懂文件从上传到被问答的旅程读法很简单doc_parser管切Storage管存两者在 qwen_agent/tools/ 下各占一个文件。文件第一次进来时走解析分块之后同一文件、同一参数组合直接命中缓存问答 Agent 拿到的永远是结构一致的 Chunk。✂️ 大文档怎么切阈值判断与句子级分块先建立一个直觉切块前先问一句这文档值不值得切。DocParser.call会遍历每一页、每个段落累加 token得到total_token再和max_ref_token比大小if total_token max_ref_token: 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保留全部上下文检索时不会因为切得太碎而丢失前后关系大文档才交给split_doc_to_chunk逐页逐段装桶。split_doc_to_chunk的装桶规则分三层段落 token 小于当前块的剩余空间available_token就整段放入放不下且块里已有内容时收桶并开新块段落本身超长则退到句子级切分——按\. |。把中英文句子拆开逐句填充单句仍超长的按 token 边界硬切。每个块头部还会写入[page: 页码]标记方便追溯出处。语义连贯靠_get_last_part保住收桶时从块末尾回取最多 150 个字符按句为界作为新块的开头并同步扣减available_token。重叠不是可选项它让跨块的句子和指代不至于被拦腰截断检索命中边界块时仍带得上前文。 切好的块存到哪基于 SHA256 哈希的本地缓存缓存键由文件标识和分块粒度拼成两个分量缺一不可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})同一条 URL 哈希相同parser_page_size不同则键不同——换个粒度重切不会污染旧缓存。走不切整篇分支时键会改用{hash}_without_chunking后缀。存储层就是本地文件系统一条记录一个文件默认落在workspace/tools/doc_parser/可用storage_root_path配置挪走。第二次解析同一文件时直接get返回日志里那句Read chunked ... from cache.就是省掉了一次完整解析。 跑起来看效果路径一多文档问答git clone https://gitcode.com/GitHub_Trending/qw/Qwen-Agent后安装依赖运行 examples/parallel_doc_qa.py 的test()把一条 PDF 链接放进消息ParallelDocQA会并行解析多份材料再召回作答。路径二Web 界面上传运行同文件的app_gui()浏览器里直接上传 PDF / Word / PPT / TXT / HTML提问后就能看到文档被消化成什么内容。️ 三个参数调对知识库更好用参数默认行为适用场景调整建议parser_page_size每块 500 token 上限普通技术文档、手册长句密集可调至 800~1000块更少短条目文档调小以提升检索精度max_ref_token20000 token 以内不切整篇中小文档整体入窗口按模型上下文留足对话余量后设定窗口小就调小storage_root_pathworkspace/tools/doc_parser/个人单机使用知识库规模大时迁到 I/O 更快的磁盘缓存随键保留提醒一点改parser_page_size会换缓存键同一文件首次请求会重新切一遍这是预期行为。一句话收束阈值判断、句子级分块、SHA256 缓存三件事就是 Qwen-Agent 把一份文件变成一套可问答文本块的全部家底也是开源 RAG 知识库搭建里最省心的起点。机制细节可对照 qwen_agent/tools/doc_parser.py 与 qwen_agent/tools/storage.py 源码阅读。【免费下载链接】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），仅供参考