Qwen-Agent 文档解析完整指南9 种格式分块、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 报告时多数人的第一步是手动翻找、复制粘贴结果既慢又容易漏行漏段。Qwen-Agent 的文档解析模块DocParser把这件事变成了一次函数调用传入文件路径它自动识别格式、抽取文本与表格、按 token 预算切块并缓存结果为后续检索和问答提供干净的语料。本文沿解析什么 → 怎么调 → 分块原理 → 接问答 → 调参避坑五步走全部示例可直接运行。先看它能啃下哪 9 种文件Qwen-Agent 的解析能力集中在 简单解析器支持.pdf、.docx、.pptx、.txt、.html、.csv、.tsv、.xlsx、.xls共 9 种格式覆盖办公场景里最常见的文档类型。每种格式走独立的解析分支PDF 用pdfminer抽文本、pdfplumber抽表格Word 读段落和表格Excel/CSV 经pandas转成 Markdown 管道表格。输出是统一的分页结构文本和表格混排、按页组织[{page_num: 1, content: [{text: 一段正文}, {table: | 列A | 列B |\n|---|---|}]}]有两点需要提前知道目前不支持从 PDF 里抽图extract_imageTrue会直接抛错纯扫描件这类以图片为主的文件也解析不出文字。这类文件建议先走 OCR再交给 Qwen-Agent。3 行代码跑通解析与分块真正给上层用的入口是 DocParser它在抽内容的同时负责分块。安装依赖后两行就能拿到一个文档的全部 chunkfrom qwen_agent.tools.doc_parser import DocParser parser DocParser() record parser.call({url: ./report.pdf}) print(record[title], len(record[raw]))url既可以是本地路径也可以是可下载的http(s)链接远程文件会被自动拉到本地临时目录再解析。返回的record含三块文件标题title、来源url以及分块列表raw每个 chunk 带正文content、token 数token和元数据来源、标题、chunk_id。分块行为由两个参数控制不传就用默认值parser_page_size单个 chunk 的目标 token 数默认 500。max_ref_token整份文档 token 数低于该阈值时全文合并为一个 chunk 不再切分默认 20000。record parser.call({url: ./report.docx}, parser_page_size300, max_ref_token10000)分块算法拆解token 预算、句子切分与重叠理解split_doc_to_chunk的内部逻辑调参时心里才有底。它的目标不是按固定字数硬切而是让每个 chunk 在 token 预算内尽量保持语义完整三个细节值得记住。其一长段落会先按.或。拆成句子再装填而不是在词中间截断。其二单个句子仍超预算时才按 token 逐段硬切。其三每个新 chunk 开头会带上上一块末尾约 150 个字符作为重叠区_get_last_part避免跨块的关键信息被切断。解析和分块结果都会按sha256(url)写入本地缓存workspace/tools下同一个文件二次调用直接读缓存不再重复解析这也是批量处理时省时间的关键。从解析到问答接上 BM25 检索光有分块还不够问答要经过一层检索。Qwen-Agent 内置 retrieval 工具默认用keyword_searchBM25front_page_search的混合策略把与问题最相关的 chunk 捞出来再交给大模型。可以直接调用它看召回内容from qwen_agent.tools.retrieval import Retrieval tool Retrieval() hits tool.call({query: 产品保修期, files: [./manual.pdf]})更省事的用法是走Assistant消息里带上fileRAG 会在后台自动完成解析 → 检索 → 作答整条链路无需手动编排。对应官方 RAG 文档 和 示例脚本from qwen_agent.agents import Assistant bot Assistant(llm{model: qwen-plus-latest}) msgs [{role: user, content: [{text: 保修期多长}, {file: ./manual.pdf}]}] print(list(bot.run(msgs))[-1])若问题需要定位到具体段落可换成 BasicDocQA文档很大时ParallelDocQA 会把每个 chunk 并行提问再汇总换取更快的响应。RAG 依赖pdfminer、rank_bm25等额外包用pip install qwen-agent[rag]一次性装齐。调参与落地几个真实会踩到的点上手之后真正影响效果的是这几个旋钮和环境行为chunk 粒度parser_page_size太小如 200会把一句话拆散检索召回零碎太大如 1000则单块信息过载、相关性下降。一般从默认 500 起步再按文档长短微调。召回窗口max_ref_token控制塞进上下文的总 token默认 20000。文档多、答案分散时可适当调大但受模型上下文窗口约束。缓存复用同一文件、同一分块参数走同一缓存键。想强制重解析改一下参数值如parser_page_size即可换键不同path配置可把缓存隔离到独立目录。改默认值用环境变量QWEN_AGENT_DEFAULT_PARSER_PAGE_SIZE、QWEN_AGENT_DEFAULT_MAX_REF_TOKEN、QWEN_AGENT_DEFAULT_RAG_SEARCHERS都能在不改代码的前提下覆盖默认行为便于在不同环境间切换。格式兜底.csv解析失败会自动退回按 Excel 处理Word 因页边界不固定整篇视为单页返回。把分块和检索调顺之后再叠加ParallelDocQA或WebUI图形界面就是一条从原始文档到可追问知识库的完整链路。解析、分块、缓存、检索四块各司其职按需拼装即可。【免费下载链接】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 文档解析完整指南：9 种格式分块、RAG 问答与落地调参
Qwen-Agent 文档解析完整指南9 种格式分块、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 报告时多数人的第一步是手动翻找、复制粘贴结果既慢又容易漏行漏段。Qwen-Agent 的文档解析模块DocParser把这件事变成了一次函数调用传入文件路径它自动识别格式、抽取文本与表格、按 token 预算切块并缓存结果为后续检索和问答提供干净的语料。本文沿解析什么 → 怎么调 → 分块原理 → 接问答 → 调参避坑五步走全部示例可直接运行。先看它能啃下哪 9 种文件Qwen-Agent 的解析能力集中在 简单解析器支持.pdf、.docx、.pptx、.txt、.html、.csv、.tsv、.xlsx、.xls共 9 种格式覆盖办公场景里最常见的文档类型。每种格式走独立的解析分支PDF 用pdfminer抽文本、pdfplumber抽表格Word 读段落和表格Excel/CSV 经pandas转成 Markdown 管道表格。输出是统一的分页结构文本和表格混排、按页组织[{page_num: 1, content: [{text: 一段正文}, {table: | 列A | 列B |\n|---|---|}]}]有两点需要提前知道目前不支持从 PDF 里抽图extract_imageTrue会直接抛错纯扫描件这类以图片为主的文件也解析不出文字。这类文件建议先走 OCR再交给 Qwen-Agent。3 行代码跑通解析与分块真正给上层用的入口是 DocParser它在抽内容的同时负责分块。安装依赖后两行就能拿到一个文档的全部 chunkfrom qwen_agent.tools.doc_parser import DocParser parser DocParser() record parser.call({url: ./report.pdf}) print(record[title], len(record[raw]))url既可以是本地路径也可以是可下载的http(s)链接远程文件会被自动拉到本地临时目录再解析。返回的record含三块文件标题title、来源url以及分块列表raw每个 chunk 带正文content、token 数token和元数据来源、标题、chunk_id。分块行为由两个参数控制不传就用默认值parser_page_size单个 chunk 的目标 token 数默认 500。max_ref_token整份文档 token 数低于该阈值时全文合并为一个 chunk 不再切分默认 20000。record parser.call({url: ./report.docx}, parser_page_size300, max_ref_token10000)分块算法拆解token 预算、句子切分与重叠理解split_doc_to_chunk的内部逻辑调参时心里才有底。它的目标不是按固定字数硬切而是让每个 chunk 在 token 预算内尽量保持语义完整三个细节值得记住。其一长段落会先按.或。拆成句子再装填而不是在词中间截断。其二单个句子仍超预算时才按 token 逐段硬切。其三每个新 chunk 开头会带上上一块末尾约 150 个字符作为重叠区_get_last_part避免跨块的关键信息被切断。解析和分块结果都会按sha256(url)写入本地缓存workspace/tools下同一个文件二次调用直接读缓存不再重复解析这也是批量处理时省时间的关键。从解析到问答接上 BM25 检索光有分块还不够问答要经过一层检索。Qwen-Agent 内置 retrieval 工具默认用keyword_searchBM25front_page_search的混合策略把与问题最相关的 chunk 捞出来再交给大模型。可以直接调用它看召回内容from qwen_agent.tools.retrieval import Retrieval tool Retrieval() hits tool.call({query: 产品保修期, files: [./manual.pdf]})更省事的用法是走Assistant消息里带上fileRAG 会在后台自动完成解析 → 检索 → 作答整条链路无需手动编排。对应官方 RAG 文档 和 示例脚本from qwen_agent.agents import Assistant bot Assistant(llm{model: qwen-plus-latest}) msgs [{role: user, content: [{text: 保修期多长}, {file: ./manual.pdf}]}] print(list(bot.run(msgs))[-1])若问题需要定位到具体段落可换成 BasicDocQA文档很大时ParallelDocQA 会把每个 chunk 并行提问再汇总换取更快的响应。RAG 依赖pdfminer、rank_bm25等额外包用pip install qwen-agent[rag]一次性装齐。调参与落地几个真实会踩到的点上手之后真正影响效果的是这几个旋钮和环境行为chunk 粒度parser_page_size太小如 200会把一句话拆散检索召回零碎太大如 1000则单块信息过载、相关性下降。一般从默认 500 起步再按文档长短微调。召回窗口max_ref_token控制塞进上下文的总 token默认 20000。文档多、答案分散时可适当调大但受模型上下文窗口约束。缓存复用同一文件、同一分块参数走同一缓存键。想强制重解析改一下参数值如parser_page_size即可换键不同path配置可把缓存隔离到独立目录。改默认值用环境变量QWEN_AGENT_DEFAULT_PARSER_PAGE_SIZE、QWEN_AGENT_DEFAULT_MAX_REF_TOKEN、QWEN_AGENT_DEFAULT_RAG_SEARCHERS都能在不改代码的前提下覆盖默认行为便于在不同环境间切换。格式兜底.csv解析失败会自动退回按 Excel 处理Word 因页边界不固定整篇视为单页返回。把分块和检索调顺之后再叠加ParallelDocQA或WebUI图形界面就是一条从原始文档到可追问知识库的完整链路。解析、分块、缓存、检索四块各司其职按需拼装即可。【免费下载链接】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），仅供参考