Qwen-Agent 本地化部署实战指南1 小时跑通内网私有文档问答助手【免费下载链接】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你公司数据合规文档不能出内网。这篇文章带你在一台 GPU 机器上完成 Qwen-Agent 的本地化部署起本地模型服务、接入 Agent 框架、做文档问答和自定义工具最后得到一个能直接上生产的私有助手。选型按显存定模型按并发定服务这节做完你手上会有三个结论模型规格、量化方案、推理服务框架。显存决定上限。先记住几个数字7B 模型 4-bit 量化显存约 6GBRTX 3090/4090 都装得下14B 4-bit约 10GB单张 A100-40G 或 2 张消费级卡32B 8-bit约 20GB需要 A100-80G 或多卡量化怎么选纯问答场景 4-bit 够用。如果助手要频繁调用工具、生成长代码工具调用对指令遵循要求高建议 8-bit 起步4-bit 偶尔会丢参数。推理服务框架按用户规模挑维度vLLMOllamaLM Studio对外接口OpenAI 兼容 /v1OpenAI 兼容 /v1本地 OpenAI 兼容端点并发能力高多用户共享中偏单机低偏试用函数调用稳定性好社区用得最多看模型本身看模型本身典型角色内网多人服务单机快速验证挑量化模型做对比7B-4bit 最低显存约 6GB约 6GB约 6GB结论很直接给团队用选 vLLM先在自己笔记本上验证选 Ollama。两者接口一致后面切 Qwen-Agent 时只改一个地址不用改代码。用 vLLM 起一个本地模型服务这节做完你能在浏览器里访问http://127.0.0.1:8000/v1并且收到模型的正常回复。三步装框架、装 vLLM、拉服务起来。pip install -U qwen-agent[gui,rag] pip install vllm vllm serve Qwen/Qwen2.5-7B-Instruct \ --served-model-name qwen25-local \ --max-model-len 8192 \ --port 8000几个参数值得解释一下--served-model-name定义了对外暴露的模型名。内网环境模型文件通常放在私有镜像或本地目录这个别名是后面 Qwen-Agent 配置里要填的值--max-model-len 8192限制上下文长度。文档问答时检索片段 系统提示 历史消息都占这个额度8K 是问答场景的甜点值内网机器拉不了 HuggingFace 时用HF_ENDPOINT指向内部镜像源或者提前把权重拷到本地路径服务起来后用 curl 打一次chat/completions接口确认能通。如果超时先看 vLLM 日志里的显存占用多数情况是--max-model-len或gpu-memory-utilization开得太大。把 Qwen-Agent 接到本地模型上这节做完你有一个能对话的 Assistant背后跑的是你自己的 GPU不经过任何云端。关键点只有一个Qwen-Agent 的模型接口是统一的。你在 模型抽象层 里能看到oai类型负责所有 OpenAI 兼容端点。配置里只要model_server以http开头框架就自动按 OpenAI 协议处理vLLM、Ollama、TGI 全都适用。换模型 换配置不动一行代码。from qwen_agent.agents import Assistant llm_cfg { model: qwen25-local, model_server: http://127.0.0.1:8000/v1, generate_cfg: {top_p: 0.8, max_input_tokens: 4000}, } bot Assistant(llmllm_cfg, system_message你是公司内网文档助手只依据提供的文件回答。) for rsp in bot.run([{role: user, content: 新人入职流程是什么}]): print(rsp)max_input_tokens别照抄云端习惯的 128K。本地推理时输入越长、KV 缓存越占显存问答场景 4000 左右足够也省了截断报错的概率。扩展本地能力给 Agent 加一个目录统计工具内置工具不够用时自己写一个。Qwen-Agent 的工具体现在 内置工具目录 里自定义工具继承BaseTool、用register_tool注册三样东西description告诉模型什么时候调你parameters定义入参call里写逻辑。以统计文件目录为例import json from pathlib import Path from qwen_agent.tools.base import BaseTool, register_tool register_tool(dir_report) class DirReport(BaseTool): description 目录统计工具返回文件数量和总大小MB。 parameters [{name: path, type: string, description: 要扫描的目录绝对路径, required: True}] def call(self, params: str, **kwargs) - str: files [p for p in Path(json.loads(params)[path]).rglob(*) if p.is_file()] return json.dumps({count: len(files), size_mb: round(sum(f.stat().st_size for f in files) / 2**20, 2)})写完后把dir_report加进Assistant的function_list就能用。注意call的返回值必须能被json.loads解析模型要读这个结果来组织回答。让代码解释器在 Docker 沙箱里跑如果你的助手要帮员工跑数据分析别让它直接exec。Qwen-Agent 的code_interpreter工具自带隔离每次执行起一个独立的 Jupyter kernel容器模式下代码跑在 Docker 里文件落在独立的work_dir执行超过timeout秒会被强制中断进程退出时容器自动清理。内网部署时的两个注意点一是机器上要装 Docker构建镜像需要能访问内部镜像源二是图表里出现中文乱码时检查一下宿主机字体工具内置了中文字体文件但自定义镜像里要自己带上。把本地 PDF 接进文档问答这节做完你手里是一个真正的私有文档问答助手。用法比想象中省事Assistant原生支持files参数文件路径传进去框架自动完成解析、分块、检索不需要你单独部署向量库。bot Assistant(llmllm_cfg, files[./docs/handbook.pdf], rag_cfg{max_ref_token: 2000, parser_page_size: 400}) for rsp in bot.run([{role: user, content: 报销审批找哪个部门}]): print(rsp)rag_cfg里两个旋钮parser_page_size控制切块的粒度默认 500扫描件多的文档可以调小max_ref_token控制每次检索塞回提示词的上限本地 7B 模型建议 2000 以内检索质量靠的是检索策略rag_searchers默认关键词 首段匹配而不是堆料。支持的文件类型包括 PDF、Word、PPT、TXT、CSV、Excel、HTML具体以官方仓库为准。调优与避坑这几条都是内网上线前会撞上的按现象 → 原因 → 处理看⚠️ 现象工具调用时参数缺字段或 JSON 截断。原因4-bit 量化伤指令遵循。处理换 8-bit 权重或在提示词里明确参数必须完整。⚠️ 现象长对话越聊越慢最后报Model context length错误。原因max-model-len和max_input_tokens没对齐历史消息撑爆上下文。处理把max_input_tokens设成小于服务端上限 512 的值。⚠️ 现象同一问题检索到的片段答非所问。原因PDF 是扫描件解析出的是空文本。处理先确认解析质量扫描件走 OCR 通道别硬调parser_page_size。⚠️ 现象多人同时用响应从 1 秒变 30 秒。原因vLLM 默认并发下单卡排队。处理加--max-num-seqs限制单批请求数或扩第二张卡。✅ 现象换 Ollama 做备份节点时全链路零改动。原因接口统一。处理只改model_server地址即可这套架构本身就是为多后端准备的。跑通之后顺着这两个示例文件看能复现本文的全部环节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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考