Agent 部署安装在整个 AI 应用开发链路里常常是零基础用户第一个放弃的地方。可能原因不是看不懂代码而是搞不清到底要装什么既要模型文件又要应用框架还要数据库和前端界面。很多人照着教程装到一半发现某个服务起不来或者模型一直没有响应问题往往出在“不知道一条完整的链路长什么样”。这篇文章会把 Agent 部署拆成三层模型层、编排层、访问层。模型层负责本地推理编排层负责把大模型、工具和记忆串起来访问层负责让用户在页面或 API 里使用这个 Agent。我会选择一条适合零基础的最小路径Ollama 提供本地模型服务Dify 提供 Agent 应用编排用 Docker Compose 拉起依赖服务。整篇文章按“概念 - 环境 - 实现 - 验证 - 排错 - 扩展”的顺序展开读者不需要精通编程只需要能跟着命令行操作。完成这条路径后你会有一个真正可对话、可调用工具、可继续扩展的 Agent 系统也掌握了后续排查问题的基本方法先看模型层是否正常再看编排层日志最后检查页面和 API 的调用方式。1. 先理解 Agent 部署到底在部署什么1.1 Agent 不是一个安装包而是“模型 编排 记忆 工具”的组合普通聊天机器人的工作方式比较简单用户发一句话模型回一句话。Agent 则更接近“一个会做事的小助手”它能根据用户目标把一个复杂任务拆成几步在需要时调用外部工具查数据库、做计算、发请求再根据结果继续回答用户。所以 Agent 不只包含一个大模型。常见组成包括大模型服务负责理解和生成文本是 Agent 的大脑。编排层负责管理对话流程、决定何时调用工具是 Agent 的执行逻辑。工具集比如计算器、天气查询、数据库查询等是 Agent 能“动手做”的部分。记忆或知识库保存历史对话、业务知识让 Agent 能回答更贴近场景的问题。访问入口页面、API、命令行用户真正接触 Agent 的地方。部署的本质就是把上面这些组件分别启动然后把它们连接起来。最容易出错的地方不是单个组件安装失败而是组件之间网络不通、模型名不匹配、服务没真正起来。后面的步骤会反复围绕这条链路做验证。1.2 三条流行部署路径零基础选哪条Agent 的部署方式大致有三条路径部署方式零基础难度可定制性适用场景在线平台低较低快速验证想法、做原型、非技术团队试用Docker 容器部署中等高本地开发、私有化部署、生产交付源码手动部署较高最高深度定制、学习框架原理、二开在线平台虽然快但数据、模型、工具都依赖平台很多学习场景并不合适。源码部署需要手动安装 Python、Node.js、数据库、缓存还要处理各种版本冲突对零基础用户不太友好。Docker 部署是折中最优解它把 Agent 系统需要的服务打包进容器通过一份配置文件就能启动。即使你不完全理解内部原理也能先把整套系统跑起来再逐步学习。这篇教程采用的就是 Docker 部署这也是目前开源 Agent 项目最常见的交付方式。2. 环境准备装好 Python、Git 和 Docker 再动手2.1 先检查系统资源避免装完跑不动部署 Agent 不是安装一个普通软件它背后有数据库、模型服务、前端页面等多个进程。开始之前先确认系统基本资源够用。资源最低要求推荐配置说明操作系统64 位系统Windows 10/11、macOS、主流 Linux 发行版32 位系统基本无法运行现代容器和模型服务CPU2 核4 核及以上模型推理和容器调度都会占用 CPU内存4 GB8 GB 以上跑 7B 级别本地模型建议 16 GB内存不足会直接导致服务被杀或模型加载失败磁盘20 GB 可用空间50 GB 以上系统镜像、模型文件、数据库都会占用空间查看资源命令Windows打开“任务管理器”在“性能”里看内存、CPU、磁盘。macOS点击左上角苹果图标 - 关于本机或执行system_profiler SPHardwareDataType。Linux执行free -h和df -h分别看内存和磁盘。如果在虚拟机里运行需要先给虚拟机分配足够内存和磁盘。安装 Docker Desktop 时Windows 还需要开启硬件虚拟化并安装 WSL2。这些前置条件没有满足后续容器很可能一起动就报错。2.2 Python 安装与环境变量虽然 Dify 本身采用 Docker 部署但学习 Agent 时经常要运行一些 Python 脚本和命令行工具所以 Python 仍然建议先装好。Windows 安装流程到 Python 官方网站下载对应系统的安装包。运行安装程序时务必勾选Add Python to PATH。安装完成后打开新的命令行窗口执行python --version验证。Linux 安装sudo apt update sudo apt install -y python3 python3-venv python3-pip python3 --versionmacOS 安装brew install python python3 --version常见坑是 Windows 安装时没有勾选Add Python to PATH导致命令行输入python提示找不到命令。解决办法是重新运行安装包修改安装选项或者在系统环境变量里手动添加 Python 安装目录。另一个常见坑是系统中同时存在多个 Python 版本。比如输入python是 Python 3.7输入python3是 Python 3.11。建议统一使用较新的稳定版本并在具体项目里使用虚拟环境避免依赖互相污染。2.3 Git 安装与用户信息配置Git 用来拉取 Agent 项目源码。很多开源项目在 GitHub 上发布输入git clone就能把代码下载到本地。Windows 安装 Git for WindowsmacOS 可用brew install gitLinux 执行sudo apt install -y git安装后验证git --version首次使用前建议配置用户信息否则提交代码时 Git 会提示缺少用户名和邮箱git config --global user.name yourname git config --global user.email youexample.com拉取公开仓库一般不需要账号无需提前配置 SSH。只有往自己的仓库推送代码时才需要配置访问令牌或 SSH Key。2.4 Docker 与 Docker Compose部署 Agent 最省心的方式Docker 的核心价值是解决“环境不一致”的问题。一个容器里可以预先装好运行某个服务需要的所有依赖启动后与应用隔离Docker Compose 则用来一次性启动一组互相配合的容器。Windows 和 macOS 通常安装 Docker Desktop安装后自带docker compose命令。Linux 可以通过系统包安装sudo apt update sudo apt install -y docker.io docker-compose-plugin sudo systemctl start docker验证安装结果docker --version docker compose version这里要注意老教程里经常写docker-compose带横线新版本推荐使用docker compose空格。两种命令代表的版本不同在复制命令之前先确认自己系统里支持哪一种。注意不要只验证命令能输出版本号还要确认 Docker 服务真的在运行。Linux 下执行sudo systemctl status dockerWindows/macOS 下确认 Docker Desktop 图标处于运行状态。环境准备阶段完成后用一张检查清单复核检查项验证命令预期结果Pythonpython --version或python3 --version输出 Python 3.xGitgit --version输出 git 版本Dockerdocker --version输出 Docker 版本Docker Composedocker compose version输出 Compose 版本Docker 服务docker info输出系统信息不报连接失败3. 选一条最小可跑通路线Ollama 负责模型Dify 负责应用3.1 为什么选择 Ollama 来管理本地模型Ollama 解决的是“模型从哪来、怎么跑、怎么被调用”的问题。它把模型下载、加载、HTTP 接口封装成一条命令普通用户不需要手动处理 Python 深度学习库、模型权重路径、GPU 驱动这些复杂内容。安装 Ollama 后输入ollama pull就能拉取模型输入ollama run就能在命令行里对话。它同时会启动一个本地 HTTP 服务默认监听11434端口。后续 Dify 就是通过这个端口访问模型。本地模型最大的价值是数据不出本机。学习调试时不需要把每一句话都发给在线模型也可以在没有网络的环境里复现实验。当然本地模型对硬件有要求模型越大内存或显存需求越高。零基础入门阶段建议先选一个小参数模型跑通整条链路再换更大模型。3.2 为什么选择 Dify 作为 Agent 编排层Dify 是一个开源项目提供可视化的 Agent 应用创建流程。它把模型供应商配置、Prompt 管理、工具调用、知识库、API 发布这几件事放在同一个界面里适合不想从底层框架写起的零基础用户。Dify 支持对接 Ollama 这类本地模型服务也支持接入云厂商模型。也就是说你可以在同一个 Agent 应用里切换不同模型不用重建整个系统。它的默认架构里通常包含 nginx、api、worker、PostgreSQL、Redis 等服务这些都会通过 Docker Compose 自动启动不需要手动安装 MySQL 或 Node.js 环境。这里顺便澄清一个误区Dify 不是模型本身。它是一个应用编排平台负责接收用户消息、判断是否需要调用工具、调用模型、把结果返回给用户。如果只部署 Dify 而不配置模型Agent 是无法回答问题的。3.3 最小系统由哪些组件组成沿着这条最小路径系统需要四个部分组件作用启动方式Ollama提供本地模型推理服务和 HTTP 接口本机独立安装并启动Dify 容器组提供 Agent 应用编排、界面和 APIDocker Compose 启动PostgreSQL保存用户、应用、对话等数据由 Dify 的 Compose 文件启动Redis缓存和队列配合 Dify 任务处理由 Dify 的 Compose 文件启动数据流大致是用户在 Dify 页面输入问题 - Dify 把问题发送给 Ollama 的模型接口 - 模型生成内容或工具调用指令 - Dify 执行工具并继续生成 - 最终结果返回给页面。这条链路是后面所有排查工作的主线。一个问题出现后先判断它发生在哪一层是页面打不开、模型没响应、还是工具没有触发。避免在一个地方反复检查却忽略了问题在另一层。4. 第一步安装 Ollama让本地模型能响应请求4.1 安装 OllamaOllama 官方提供 Windows、macOS、Linux 三种安装方式。Windows 和 macOS 可以直接下载安装包Linux 用户通常通过安装脚本安装。如果使用安装脚本建议先下载到本地查看到脚本内容再执行curl -fsSL https://ollama.com/install.sh -o install.sh less install.sh sh install.sh安装完成后验证ollama --version如果提示找不到命令可能是安装目录没有加入 PATH。重新打开终端窗口后再试一次如果仍然不行需要根据操作系统把 Ollama 的安装目录加入环境变量。每个系统安装路径不同以官方文档为准。4.2 拉取并启动模型先查看本机已经有哪些模型ollama list第一次使用时列表为空需要拉取一个模型。下面以qwen2.5:7b作为示例实际模型名称以官方模型库为准ollama pull qwen2.5:7b模型文件通常有几个 GB 到几十 GB需要等待一段时间。完成后再次执行ollama list能看到模型名称和体积。验证模型本身是否可用ollama run qwen2.5:7b进入对话界面后输入一句话比如“你好请介绍一下你自己”模型有回复说明推理正常。按 CtrlD 或输入退出指令退出命令行对话。注意一次不要同时拉取多个大模型。本地磁盘和内存不够时模型加载会非常慢甚至直接失败。常见坑是拉取时提示模型名不存在。不同模型的命名规则不一样参数版本也不同拉取前最好在官方模型库页面搜索确认。还有一个坑是模型加载后内存不足系统会把 Ollama 进程杀死表现是刚启动对话就退出这时需要换更小的模型或增加内存、显存。4.3 验证模型 HTTP 接口Agent 系统使用 Ollama 的 HTTP 接口不能只验证命令行对话还要确认接口可以访问。查看模型列表接口curl http://localhost:11434/api/tags正常情况下会返回一个包含模型名称的 JSON 数组。再测试生成接口curl http://localhost:11434/api/generate -d {model:qwen2.5:7b,prompt:你好请简单介绍你自己,stream:false}如果一切正常返回 JSON 中会包含response字段里面是模型生成的文本。检查端口是否被监听curl -I http://localhost:11434这一步通过后说明模型层已经可以对外提供服务。后续 Dify 连不上模型时回到这里检查是最快的定位方式。4.4 Ollama 常见坑模型名、内存、端口、下载慢现象可能原因检查方式处理建议拉取模型失败并提示 manifest not found模型名或标签写错去官方模型库搜索准确名称换成正确模型名重新拉取模型对话时进程退出内存不足Ollama 被系统杀死执行free -h查看内存查看系统日志换小模型或增加内存/显存接口无法访问Ollama 未启动或端口被占用curl -I http://localhost:11434查看端口监听重启 Ollama排查端口占用模型下载一直卡住网络不稳定或磁盘空间不足执行df -h查看磁盘保留足够磁盘空间网络稳定时重试5. 第二步用 Docker Compose 部署 Dify 平台5.1 获取 Dify 部署文件Dify 的部署文件以源码方式发布在 GitHub 仓库中。常见发行版本的docker目录下会提供docker-compose.yaml和.env.example具体路径以你下载的 release 版本为准。获取方式git clone https://github.com/langgenius/dify.git cd dify/docker进入docker目录后复制环境变量文件cp .env.example .env不需要现在修改所有配置先按默认值启动。第一次运行成功后再根据实际情况调整端口、密码和密钥。5.2 启动前要理解的关键配置.env文件是 Dify 的主要配置入口。下面是一段用于理解思路的示意不是完整配置EXPOSE_NGINX_PORT80 POSTGRES_PASSWORDchange_me SECRET_KEYchange_me_too常见配置项含义配置项作用错误配置的表现EXPOSE_NGINX_PORT对外访问端口端口被占用时无法打开页面POSTGRES_PASSWORD数据库密码默认密码不安全容器重启后可能异常SECRET_KEY加密签名密钥密钥过短或为空时应用可能无法启动或安全报错零基础学习阶段端口冲突是最常见的问题。如果本机 80 端口已经被其他程序占用需要修改EXPOSE_NGINX_PORT比如改成8080。改完后访问地址要跟着变化http://localhost:8080/install。安全提醒不要把包含密码和密钥的.env文件提交到公开仓库。一旦泄露任何人都可能知道你系统的数据库凭据。5.3 启动 Dify 并查看日志执行docker compose up -d第一次启动会拉取多个镜像耗时较长。启动后查看容器状态docker compose ps正常状态是大部分服务处于Up。有些服务需要时间初始化可以等十几秒后再执行一次。如果某个服务反复重启查看日志docker compose logs -f api也可以查看所有服务日志docker compose logs -f日志是判断问题的第一现场。不要只盯着页面报错容器里的日志通常会给出更具体的异常原因。5.4 初始化管理员账号并登录容器全部启动后在浏览器访问http://localhost/install如果修改了端口把地址改成对应的端口。第一次访问会进入初始化页面需要设置管理员邮箱和密码。设置完成后登录 Dify 主界面。常见打不开页面的原因有三个容器还在启动中、端口冲突、初始化还没完成。处理方式是先看docker compose ps再确认访问端口是否和配置一致最后检查对应容器的日志。问题现象可能原因检查方式处理建议页面一直转圈容器还在初始化docker compose ps等待一段时间后刷新访问被拒绝端口配置不对或端口被占用查看.env中端口设置修改端口并重新启动数据库容器反复重启内存不足或数据卷异常docker compose logs -f db增加内存检查数据卷情况6. 第三步在 Dify 里创建一个可对话的 Agent 应用6.1 配置模型供应商把 Dify 和 Ollama 连接起来登录 Dify 后进入“设置”中的“模型供应商”新增一个供应商选择 Ollama。这一步的作用是告诉 Dify模型服务在哪里模型叫什么。关键参数参数填写内容模型名称与ollama list中显示的模型名一致例如qwen2.5:7bBase URLOllama 的服务地址上下文长度通常先按模型默认值填写模型不支持时再调整最容易踩坑的是 Base URL。在浏览器里访问localhost:11434能通不代表 Dify 容器内也能访问localhost因为 Docker 容器的localhost指向容器自己而不是宿主机。在 Windows/macOS 的 Docker Desktop 中宿主机地址通常是http://host.docker.internal:11434在 Linux 容器环境中可能要换成宿主机实际 IPhttp://192.168.x.x:11434填完后点击测试。测试通过后模型供应商状态会显示正常。这个环节如果失败优先用前面第 4 章的curl http://localhost:11434/api/tags确认模型服务还在运行。6.2 创建 Agent 应用并开启工具调用在 Dify 中创建应用时要选择“Agent”类型而不是普通“聊天助手”。两者的区别在于普通聊天助手以对话问答为主Agent 应用则可以在回答过程中触发工具调用甚至完成多步操作。创建 Agent 应用后先配置一个不依赖外部服务的工具比如计算器类工具用来验证工具调用链路是否正常。系统提示词可以写成你是一个乐于助人的 Agent。回答用户问题时如果问题涉及计算请调用计算器工具而不是直接口算。调用工具后根据工具结果组织最终回答。保存并发布应用后进入调试预览界面。要注意工具需要在应用编辑页面开启或添加只在模型供应商里配置了模型还不够。如果 Agent 没有启用工具模型可能只会直接生成文本不会进入“调用工具”的流程。6.3 对话验证与结果分析在调试页面输入一个问题35 加 17 等于多少预期行为是 Agent 调用计算器工具得到结果52然后回答“35 加 17 等于 52”。如果页面直接输出了52但日志里没有出现工具调用记录那可能只是模型直接计算的结果并不是真正的工具调用。进一步验证可以观察 Dify 容器日志docker compose logs -f api日志中会体现模型请求、工具调用、工具结果返回等环节。看到完整的工具调用链路后这个 Agent 才算是真正跑通了。6.4 常见坑模型测试失败、工具不触发、请求超时问题现象可能原因检查方式处理建议模型供应商测试失败Base URL 填了 localhost检查宿主机的 Ollama 接口换成 host.docker.internal 或宿主机 IP模型名一直提示不存在填写的模型名与ollama list不一致执行ollama list复制真实模型名重新填写Agent 没有调用工具工具未启用或提示词没有引导检查应用编辑页面的工具开关和提示词启用工具并明确告知模型什么时候使用工具请求长时间无响应本地模型推理太慢查看 api 容器日志和模型监控换更小模型或调整请求超时时间7. 部署后的排查链路、数据备份和日常维护7.1 三层排查链路页面层 - 应用层 - 模型层Agent 系统跑起来后问题排查要按层进行不要跳来跳去第一层页面层。页面能否打开登录是否正常输入消息后是否有任何反馈。用浏览器开发者工具看网络请求判断请求是否已经发到 Dify。第二层应用层。进入 Dify 容器日志看 API 和 worker 是否有报错。消息发送后日志里有没有模型调用记录有没有工具执行记录。第三层模型层。直接访问 Ollama 的接口测试模型服务是否存活。可以执行curl http://localhost:11434/api/tags curl http://localhost:11434/api/generate -d {model:qwen2.5:7b,prompt:你好,stream:false}如果模型层正常应用层正常页面还是没反应才需要检查网络、端口、防火墙和浏览器缓存。在某些 Agent 命令行工具中你可能会看到类似agent terminated due to error的提示。这通常意味着 Agent 的一次任务因为模型调用或工具执行出错而中断提示信息会建议你重新触发模型。处理思路和上面一样先看底层模型服务是否正常再检查工具执行阶段的报错日志。7.2 日志是排错的第一现场Dify 使用容器化部署日志集中在 Docker 中。docker compose logs -f docker compose logs -f api docker compose logs -f workerOllama 不在 Compose 编排里日志需要单独查看。macOS 和 Windows 可以通过托盘图标或官方命令查看Linux 下如果使用 systemd 启动可以执行journalctl -u ollama -f排错时建议把以下信息记录到笔记里访问时间、页面操作、看到的具体报错、对应容器日志、模型接口状态。这样能大幅减少反复验证的时间。7.3 停止、重启与升级停止服务但不删除数据docker compose down这条命令会停止容器但默认保留数据卷。再次docker compose up -d可以恢复。绝不建议在没确认意义的情况下执行docker compose down -v-v会删除数据卷数据会清空。学习阶段可以接受但生产环境会丢失用户数据。升级前需要备份数据卷。先查看卷名docker volume ls使用一个临时容器打包数据卷内容是通用做法下面的命令是思路示例实际卷名以docker volume ls为准docker run --rm -v volume-name:/data -v $(pwd):/backup alpine tar czf /backup/backup-$(date %F).tar.gz -C /data .Dify 升级流程通常包括备份数据、拉取新版本源码、更新镜像、重新启动。不要在生产系统上直接升级先在测试环境验证兼容性。7.4 学习环境与生产环境的差异| 关注点 | 学习环境 |