这次我们直接进入主题Agent 部署而且是一套零基础、小白也能照做的完整流程。Agent 不是一个固定软件更准确的说法是「大模型 工具调用 流程编排」的组合。你要先想清楚自己搭 Agent 是想聊天、想接入知识库、还是想让它调用外部工具干活不同目标决定了不同的部署路径。本文把一条完整路线拆成三层Ollama 本地模型服务、Dify 可视化编排平台、以及一个最简 Python Agent 实例方便你理解 Agent 底层到底在做什么。先说这套方案的优点不用写复杂的前端不用从零训练模型整体部署以 Docker 和命令行为主只要把环境准备好照着命令执行就能跑通。最终你会得到两个可用的东西一个可视化 Agent 应用能对话、能挂工具、能接知识库、能发 API 请求另一个是你自己写的最小 Agent 脚本方便理解模型如何决定调用哪个工具。本文会依次覆盖环境准备、Ollama 部署、Dify 部署、Agent 功能测试、API 调用、批量任务、资源占用观察和常见问题排查。如果你之前只听说过 Agent 但没动手搭过这篇可以直接收藏作为起步材料。1. 核心能力速览能力项说明项目类型Agent 部署搭建教程本地模型服务 可视化编排 Python 最小实现组件清单Ollama、Dify、Python 脚本、可选云模型 API主要功能对话、工具调用、知识库问答、API 服务、批量任务推荐硬件有 NVIDIA GPU 优先显存 6G 以上体验更好没有 GPU 也能用 CPU 跑小模型显存占用取决于模型大小和并发数需按实际部署版本测试观察支持平台Windows / macOS / LinuxDocker 环境即可启动方式命令启动、Docker Compose 启动、Python 脚本启动是否支持 API支持Dify 提供应用 APIOllama 提供本地模型 API是否支持批量任务支持可通过 API 循环调用或编写批处理脚本适合人群零基础小白、需要快速搭建 Agent 的开发者、想学习 Agent 原理的读者从材料可以确定这条路线没有苛刻的硬件要求关键是把软件环境理顺。显存的具体数值取决于你选择什么模型、多少并发、上下文多长不要听别人说“8G 就能跑”就直接照搬最好以本机测试为准。2. 适用场景与使用边界这套部署方案适合三类诉求。第一类是产品验证你想快速做一个能回答领域问题的机器人先看效果再决定要不要开发。第二类是工具集成你已经有大模型 API但希望有一个可视化界面来控制提示词、知识库和工具调用流程。第三类是学习原理你想知道 Agent 是怎么决定调用工具的Python 最小实现会让你看得更清楚。也有几类场景不适合用这条路线。如果你的目标是上线到线上生产环境、支撑大量用户访问那么本地单机部署的 Dify 和 Ollama 需要重构为分布式架构。如果你的需求只是简单问答不需要工具调用和知识库直接用大模型聊天界面会更轻。如果你完全不想碰命令行和 Docker那么当前方案对你来说仍有门槛需要先补基础。使用边界必须说清楚部署 Agent 不意味着可以为所欲为。如果你接入外部工具、搜索、文档处理能力必须确认数据来源合法不能抓取未授权内容不能处理未经同意的人脸、声音、隐私信息。使用开源模型要遵守对应许可证。调用云模型 API 要注意费用和内容合规商用前必须做评估。构建知识库时只放有授权的文档和数据。Agent 生成的内容不能自动发布到公开渠道需要先审核。3. 环境准备与前置条件开始之前先把机器环境检查一遍。建议至少准备这样一套环境。检查项建议操作系统Windows 10/11、macOS 12、Ubuntu 22.04 均可Docker建议安装 Docker Desktop 或 Docker EngineDocker ComposeDify 部署需要Docker Desktop 一般自带Python3.9 以上用于运行最小 Agent 脚本Git用于克隆 Dify 仓库命令行工具Windows 用 PowerShell 或 CMDmacOS/Linux 用 Terminal显卡驱动如果要本地 GPU 跑模型需要装好 NVIDIA 驱动和 CUDA 环境磁盘空间部署镜像加模型文件至少预留 20G 以上网络环境能正常访问 Docker Hub 和模型下载源环境检查可以直接在终端执行python --version git --version docker --version docker compose version如果命令能正常输出版本号说明基础环境没问题。如果docker compose提示找不到命令在 Windows 上重新安装 Docker Desktop在 Linux 上安装 docker-compose-plugin。硬件这块我的建议是不要被“必须多少 G 显存”的说法劝退。本地模型有许多尺寸和量化版本小模型用 CPU 也能跑只是速度慢。真正要留意的是显存不足时程序可能直接崩溃或自动退回到 CPU表现为响应非常慢。你可以先部署完再根据实际观察调整模型大小。端口方面要提前注意Ollama 默认占用 11434Dify 默认通过 80 端口访问如果本机已经跑了 Nginx、Apache 或其它 Web 服务先停掉或改端口。后面排错时我也会把端口问题列在常见问题里。4. 方案一Ollama 本地大模型部署4.1 安装 OllamaOllama 是一个本地大模型运行工具它帮我们把模型下载、启动、API 暴露都简化了。对小白来说这是最省事的模型层方案。去 Ollama 官网下载对应系统的安装包Windows 和 macOS 都有安装器Linux 可以用安装脚本。安装完成后终端执行ollama --version能输出版本号就说明安装成功。Windows 下安装好后Ollama 通常会作为后台服务常驻不需要每次都手动启动。4.2 拉取模型拉取模型使用ollama pull命令。模型名称由命名空间、模型名和标签组成不同标签对应不同参数量和量化版本。比如ollama pull qwen2.5:7b执行后会在后台下载模型文件。下载完成后可以查看本地已有哪些模型ollama list如果你的电脑配置不高可以选更小的模型标签比如qwen2.5:3b或更小的量化版本。这里不要死记某个具体模型而是根据本机内存和显卡情况选择。在本地跑一个 7B 模型通常需要 8G 左右内存或显存具体占用以实际观察为准。4.3 验证 Ollama APIOllama 启动后默认会监听http://localhost:11434并且提供 OpenAI 兼容接口。先用 curl 验证是否可用curl http://localhost:11434/api/generate -d {model:qwen2.5:7b,prompt:你好,stream:false}如果返回包含response字段的 JSON说明模型服务已经正常。这一步很重要后面 Dify 或 Python 脚本都要通过这个 API 与模型通信。5. 方案二Dify 可视化 Agent 搭建5.1 拉取并启动 DifyDify 是一个开源的可视化 AI 应用平台支持 Agent、知识库、工作流编排和 API 发布。它尤其适合不想从零写代码的人把 Agent 的大部分交互都做成了可视化操作。先克隆 Dify 仓库git clone https://github.com/langgenius/dify.git cd dify/docker在docker目录下复制环境变量文件cp .env.example .env然后启动服务docker compose up -d第一次启动会拉取镜像耗时取决于网络情况。启动完成后查看容器状态docker compose ps如果所有容器状态都是Up说明服务已经起来。默认情况下Dify 会映射 80 端口本地直接访问http://localhost即可。如果 80 端口被占用需要在.env或docker-compose.yaml中调整端口映射。5.2 初始化管理员账号第一次访问 Dify 页面会进入初始化页面需要设置管理员邮箱和密码。这一步很直接填完后进入 Dify 工作台。这里要记住Dify 的数据都保存在 Docker 卷里如果你之后重置容器数据不会自动清除需要手动清理卷。对测试环境来说重置麻烦一点但不会丢数据。5.3 添加模型供应商进入 Dify 后点击右上角头像进入「设置」找到「模型供应商」。这里可以添加两种模型来源Ollama选择 Ollama填写 Base URL。如果 Dify 跑在 Docker 容器里访问宿主机的 Ollama 需要使用http://host.docker.internal:11434在 Windows 和 macOS 的 Docker Desktop 下有效。如果无效可以填写宿主机局域网 IP。OpenAI 兼容 API如果你用的是云服务商或其它本地推理框架选择 OpenAI-API-compatible填写 Base URL、API Key 和模型名称。模型名称必须和 Ollama 里ollama list显示的完全一致否则调用时会报模型不存在。5.4 创建 Agent 应用回到工作台点击「创建空白应用」选择 Agent 类型。在 Agent 编辑页面你可以编写系统提示词告诉 Agent 自己是什么角色、应该怎么回答问题。添加工具。Dify 自带一些工具比如计算器、天气查询等也可以定义 OpenAPI 工具把外部 HTTP 服务包装成 Agent 可调用的能力。添加知识库。如果有需要问答的文档可以创建知识库并上传文件Dify 会做分段和向量化之后 Agent 就能基于文档内容回答。开启对话历史让 Agent 记住上下文。编排完成后在右侧对话框测试。输入“今天天气怎么样”或者“帮我算一下 23 乘以 45”如果 Agent 调用了工具并返回结果说明编排链路已经通了。5.5 发布与访问Dify 应用可以发布为 Web App也可以发布为 API。点击页面右上角的「发布」再在「访问 API」面板中查看 API 密钥和调用地址。发布后别人可以通过 Web 页面访问你做的 Agent也可以通过 API 集成到自己的系统里。到这里你已经完成了一个可视化的 Agent 搭建。整个过程不涉及修改代码适合作为团队内部原型或者个人项目的第一版。6. 方案三最简 Python Agent 实现可视化平台能让人快速上手但它隐藏了很多细节。如果你想知道 Agent 到底是什么我建议再动手写一个最简 Python 脚本。这里用 requests 直接调用 Ollama 的接口不依赖 Dify。先安装依赖pip install requests然后创建minimal_agent.pyimport requests import json OLLAMA_URL http://localhost:11434/api/chat MODEL_NAME qwen2.5:7b def calculator(expression: str) - str: # 仅用于本地测试不要对不可信表达式使用 eval try: return str(eval(expression)) except Exception as e: return f计算失败: {e} def get_weather(city: str) - str: # 这是一个演示工具实际要接真实天气 API return f{city} 今日天气多云气温 20-28℃仅供参考 TOOLS { calculator: { desc: 计算数学表达式例如 12*13, func: calculator, }, get_weather: { desc: 查询一个城市的天气参数是城市名称, func: get_weather, }, } def build_tool_schema(): tools [] for name, info in TOOLS.items(): tools.append({ type: function, function: { name: name, description: info[desc], parameters: { type: object, properties: {}, }, }, }) return tools def run_agent(user_input: str, max_rounds: int 5): messages [{role: user, content: user_input}] for _ in range(max_rounds): payload { model: MODEL_NAME, messages: messages, stream: False, tools: build_tool_schema(), } resp requests.post(OLLAMA_URL, jsonpayload, timeout120) data resp.json() message data.get(message, {}) tool_calls message.get(tool_calls) if not tool_calls: return message.get(content, ) messages.append(message) for call in tool_calls: fn call.get(function, {}) name fn.get(name) args fn.get(arguments, {}) if args is None: args {} if name in TOOLS: result TOOLS[name][func](**args) else: result f未找到工具: {name} messages.append({ role: tool, content: json.dumps(result, ensure_asciiFalse), }) return 超过最大调用轮数 if __name__ __main__: question input(请输入你的问题) answer run_agent(question) print(Agent 回答, answer)运行脚本python minimal_agent.py输入“帮我算一下 12*13顺便看看北京的天气”如果模型支持 tool calling它会先调用计算器再调用天气工具最后汇总回答。要注意不是所有模型都支持 tool calling。如果模型不理解工具参数脚本会返回普通回答而不是调用工具。遇到这种情况可以换一个对工具调用支持更好的模型或者检查 Ollama 版本是否满足要求。这个脚本的作用是演示 Agent 的最底层逻辑模型输出工具调用意图程序解析并执行工具再把结果重新交给模型循环直到完成。7. 接口 API 与批量任务测试部署 Agent 不只是为了在页面上聊天很多时候你要把它接入自己的系统。Dify 发布后的应用提供 HTTP API这是最常用的集成方式。7.1 Dify API 调用示例首先在 Dify 应用的「访问 API」页面复制 API 密钥格式一般是app-xxxxx。然后使用 curl 调用curl -X POST http://localhost/v1/chat-messages \ -H Authorization: Bearer app-xxxxxx \ -H Content-Type: application/json \ -d {query:帮我出一道 Python 练习题,response_mode:blocking,user:test-user}response_mode可以设置为blocking阻塞返回完整回答或streaming流式返回。user是用户标识用于区分不同会话。如果返回的 JSON 中包含answer字段说明 API 调用成功。这里的 API 路径要以 Dify 页面上显示的信息为准不同版本可能会有调整。7.2 Python 批量任务脚本有了 API批量任务就很简单了。这里给出一个通用模板遍历问题列表逐个调用 Dify API 并保存结果import requests import time url http://localhost/v1/chat-messages headers { Authorization: Bearer app-xxxxxx, Content-Type: application/json, } questions [ 用一句话介绍 Python, 用一句话介绍 Docker, 用一句话介绍 Dify, ] for i, q in enumerate(questions, 1): payload { query: q, response_mode: blocking, user: fbatch-user-{i}, } try: resp requests.post(url, jsonpayload, headersheaders, timeout120) data resp.json() answer data.get(answer, str(data)) print(f[{i}] 问题{q}) print(f[{i}] 回答{answer}) print(- * 40) except Exception as e: print(f[{i}] 调用失败{e}) time.sleep(1)批量任务有几个工程问题需要提前考虑。第一限流。如果每秒发几十个请求本地服务很可能被压垮。建议在循环体里加time.sleep控制请求频率。第二超时与重试。模型回答慢的时候API 可能几十秒才返回因此要设置足够长的超时时间。如果调用失败可以记录日志稍后重试而不是把整个任务中断。第三会话隔离。批量任务里不同用户要传不同的user或conversation_id否则会串上下文。8. 资源占用与性能观察资源占用是本地部署最需要关注的一环但显存数字不能凭空套用必须实际观察。8.1 如何观察显存占用在 Linux 环境下用 NVIDIA 系统管理接口实时查看nvidia-smi -l 2每隔 2 秒刷新一次显存和 GPU 利用率。当 Agent 生成回答时可以看到显存上升问答结束后显存可能保持在高位因为模型还驻留在显存里。在 Windows 下可以用任务管理器查看 GPU 显存或者在 PowerShell 中执行nvidia-smi。8.2 如何观察容器资源Dify 和 Ollama 如果跑在容器中用 Docker 自带命令观察docker stats这个命令会显示每个容器的 CPU、内存和网络占用。当 Agent 处理请求时可以定位到具体容器判断瓶颈在模型层还是在应用层。8.3 影响性能的关键参数影响资源占用和响应速度的因素主要有几个。模型大小是最直接的因素。参数越大所需内存越多响应越慢。量化版本可以在不损失太多效果的情况下减少占用。并发数也很关键。如果同时多个请求进入 Ollama显存和内存占用会叠加。可以在 Ollama 的环境变量中调整并发策略比如限制同时加载的模型数量OLLAMA_MAX_LOADED_MODELS1上下文长度同样影响显存。聊天历史越长显存占用越高。如果 Agent 工具调用次数多上下文会被快速填满所以长对话场景要么清理历史要么使用支持更长上下文的模型。降低显存占用最直观的办法是换小模型、缩短上下文、减少并发。观察资源占用时不要只盯着峰值还要看服务长时间运行后是否稳定。如果内存持续增长可能是容器内存泄漏或日志堆积需要定期重启服务。9. 常见问题与排查方法问题现象可能原因排查方式解决方案Docker 启动 Dify 失败端口被占用或镜像拉取失败查看docker compose ps和docker compose logs调整端口映射更换镜像源重试拉取页面打不开安装未初始化完成等待容器全部启动访问http://localhost/install检查 Dify 初始化页面确认 80 端口映射Ollama 模型无法连接Base URL 写错或 Ollama 未启动在宿主机 curl 11434 地址使用host.docker.internal或宿主机 IP模型调用报模型不存在模型名与本地标签不一致执行ollama list查看准确名称修改配置里的模型名为实际标签显存不足模型太大或并发过高nvidia-smi查看显存换小模型、降低并发、重新加载模型Agent 不调用工具模型不支持 tool calling查看模型文档和 Ollama 日志换支持工具调用的模型调整提示词API 返回 401API Key 错误检查 Authorization 头在 Dify 应用 API 页面重新复制密钥批量任务卡住超时时间过短或并发过高查看服务日志和资源占用增加 timeout降低请求频率加入失败重试答案质量不稳定提示词设计不清晰检查系统提示词和模型选择细化 Agent 角色和任务描述必要时换更强模型排查问题时有一个基本原则先看日志再调配置。不要凭感觉改代码。Dify 容器日志用docker compose logs -f查看Ollama 日志在多数系统下会输出到终端或系统日志目录。日志里通常会直接给出错误原因比如端口占用、模型不存在、权限不足。10. 最佳实践与合规使用建议第一次部署不要追求大模型、多功能。先用最小模型把链路跑通再逐步增加知识库和工具。主要流程可以概括为启动 Ollama验证模型能回答问题启动 Dify接入 Ollama创建一个简单 Agent测试工具调用发布 API用脚本调用最后再上批量任务。每走一步确认一次结果避免把所有问题堆到一起排查这样调试成本低得多。工程上建议保留一份最小可运行配置。比如记录你使用的模型标签、Base URL、端口映射、环境变量这样换电脑或者给别人复现时会很方便。模型文件、输入素材、输出结果要分目录管理不要把几千个文件堆在同一个文件夹里。批量任务必须有日志和重试机制否则任务中断后很难定位失败原因。接口服务如果暴露到局域网或公网一定要限制访问范围。Dify 的 API Key 相当于访问凭证不要提交到公共仓库。如果你用云模型 API建议设置预算和限流防止异常调用产生高额费用。合规方面要格外注意Agent 的能力越强越要在使用边界上保持克制。知识库只允许上传你有权的文档不要扫描和上传未授权的数据Agent 调用的外部接口要与业务相关不要让它访问敏感资源生成内容不能直接对外发布特别是涉及医疗、法律、金融等领域的建议需要人工审核。如果你部署的是语音、图像、数字人相关能力还要确认素材中的人脸、声音已经获得授权。此外开源模型都有对应的许可证商用前要检查是否允许。你可以用 Docker 和容器做环境隔离避免不同项目之间的依赖冲突也方便随时销毁重建。11. 总结与下一步这套部署路线的最大价值是用最短路径把 Agent 从概念变成可运行的东西。你现在有了 Ollama 这个本地模型服务有了 Dify 这个可视化 Agent 平台也有了一个能看懂工具调用逻辑的 Python 最小实现。三者组合起来已经覆盖了 Agent 部署的大多数基础场景。建议你最先验证的是 Ollama 与 Dify 的连通性。这一步通了后面的工具调用、知识库、API 才具备基础。最容易踩的坑有三个一是 Base URL 写错Docker 容器访问不到宿主机端口二是模型标签不匹配三是没有选对支持 tool calling 的模型。这三个坑在本文中都给了排查方向。接下来可以按自己的需求扩展给 Agent 加知识库让它基于内部文档回答问题定义自定义工具把内部系统和 HTTP 服务接进来把 Dify 应用接入企业微信、钉钉或 Web 前端如果团队需求复杂再研究多 Agent 协作和工作流编排。你还可以把 Python 最小 Agent 继续改进比如增加日志、支持多个工具参数、接入向量数据库。这些方向都需要你先把当前的部署跑熟再逐步深化。建议你先按本文把 Agent 部署起来做一个能调工具的 Demo再往深处扩展。