不少同学在准备上手 Agent 开发时第一步就被环境配置劝退了。网上教程很多但要么默认你已经有 Docker、有 GPU、懂 Linux要么只讲概念不讲落地最后跑起来一个能对话的 Agent 依然很遥远。这篇文章围绕“零基础也能跟着做完”这个目标把 Agent 部署安装拆解成一条完整的本地实操链路从选型、环境准备、模型部署到可视化 Agent 平台搭建最后创建一个真正能运行的智能体应用。内容覆盖最常用的 Ollama Dify 组合新手可以照着操作有基础的开发者也能快速补全流程细节。1. 背景与核心概念1.1 什么是 Agent它和普通聊天机器人有什么区别Agent 在技术圈里经常被翻译成“智能体”通俗理解它是一个具备“目标理解、任务拆解、工具调用、结果验证”能力的 AI 程序。普通聊天机器人只能一问一答你问一句它回一句缺少主动规划能力。而 Agent 更像一个“有手有脚”的 AI 员工当你想实现“帮我查一下本周天气然后整理成出行建议”这样的任务时它可以自动拆解成多个步骤调用天气查询接口、读取城市信息、再基于大模型生成最终回复。从工程角度说Agent 至少包含几个核心模块大模型LLM作为推理大脑。提示词Prompt用来定义角色、目标和约束。工具Tool让 Agent 能查天气、搜网页、操作数据库等。编排逻辑Agent Framework负责规划步骤、调用模型、解析结果并决定下一步动作。这里需要明确一个容易混淆的点Agent 和大模型不是同一个东西。大模型是“大脑”Agent 是“完整的工作流”。部署一个大模型并不等于部署了一个 Agent还需要一个能编排、能调用工具的框架或平台。1.2 本地部署 Agent 的主流方案对比目前搭建 Agent 应用主要有几条路线适合的人群和门槛差别比较大。第一条是纯代码路线。使用 LangChain、LlamaIndex 这类框架配合 OpenAI、DeepSeek 或其他大模型 API自己写工具函数、自己管理对话状态。优点是非常灵活适合开发者做深度定制缺点是对新手很不友好需要同时掌握 Python、异步编程、API 调用、Prompt 工程等一系列技能。第二条是云端平台路线。使用 Coze、Dify Cloud、百度千帆等在线平台在网页上拖拽配置就能生成 Agent。优点是上手很快不需要管服务器还能一键发布到微信、飞书等渠道缺点是数据和配置都在云端想要私有化部署或做二次开发时会受限。第三条是本地私有化路线。自己准备一台服务器或本地电脑先部署一个大模型运行时比如 Ollama、vLLM再部署一个可视化 Agent 编排平台比如 Dify、FastGPT。优点是完全掌握数据和配置可以自由接入内部系统适合学习、科研以及企业内部落地缺点是环境配置多一些对硬件有一定要求。本文选择的方案是 Ollama Dify原因很简单Ollama 是目前最省心的本地大模型运行工具一条命令就能拉起一个模型Dify 则提供了完整的 Agent 编排界面、知识库、工作流和工具集成能力。两者组合在一起既不需要写大量代码又能真正跑通“部署 搭建 使用”的完整闭环。1.3 学完本文你能得到什么跟着本文操作完成后你的本机或服务器上将运行起来这样一套环境一个使用 Ollama 管理的本地大模型服务默认端口 11434。一个使用 Docker 部署的 Dify 平台默认通过 80 端口提供 Web 访问。Dify 与 Ollama 打通后你可以直接创建自己的 Agent让它在对话中调用工具。整个过程中你会掌握 Docker 容器基础操作、Ollama 模型管理、Dify 初始化配置、模型供应商接入方法以及一份可复用的 Agent 搭建流程。这些技能可以迁移到 DeepSeek、Qwen、Llama 等各种本地模型的部署场景中。2. 环境准备与版本说明2.1 硬件要求本地部署 Agent 对硬件要求不是“必须很高”而是“看模型大小”。如果只想跑 1.5B、3B 级别的小模型普通 8GB 内存的电脑也能运行但速度会比较慢。想流畅运行 7B 级别模型建议内存 16GB 以上如果是量化后的 7B 模型CPU 推理 8 到 12 秒生成一个字属于正常状态不要因此误以为程序卡死了。如果有 NVIDIA 独立显卡体验会好很多。显存 6GB 以上可以顺畅运行 7B 量化模型显存 12GB 以上有机会运行 13B 甚至更大模型。没有 GPU 也不必担心本文所有步骤在纯 CPU 环境下同样可以操作只是推理速度偏慢。推荐配置可以这样参考场景CPU内存显卡适合模型最低体验2核以上8GB无1.5B~3B日常学习4核以上16GB无3B~7B流畅使用8核以上32GB6GB显存以上7B~14B生产力环境多核服务器64GB多卡14B以上需要注意的是模型参数量不是唯一的指标量化等级、上下文长度、推理框架也会影响资源占用。建议新手第一次先用小模型跑通流程再逐步换大模型。2.2 操作系统与基础软件本文命令以 Ubuntu 22.04 为例Windows 用户可以使用 WSL2 或 Docker Desktop 配合执行。macOS 用户同样可以复现只是在 Ollama 安装方式上稍有差异。需要提前装好的软件如下软件用途安装方式Git拉取 Dify 代码apt install git或官方安装包Docker运行 Dify 容器官方脚本或系统包管理器Docker Compose v2编排多容器服务通常随 Docker 一起安装curl调试验证 API系统自带或apt install curlDocker 是整套方案中最重要的依赖。Dify 官方推荐使用 Docker Compose 方式部署因此先把 Docker 环境整理干净。建议在安装 Docker 之前确认机器上没有遗留的旧版本容器服务避免端口冲突。版本方面不需要纠结。Dify、Ollama 以及各开源大模型的迭代速度都很快本文示例环境以当前常见稳定版本为准重点演示配置思路和操作步骤而不是锁定某个具体版本号。2.3 整体架构图文字版为了便于理解先用文字把部署后的访问链路画出来。浏览器访问 http://localhost ↓ Dify Web 界面容器内 Nginx 前端 ↓ Dify API / Worker 服务 ↓ Ollama 本地模型服务监听 11434 ↓ qwen2.5、deepseek-r1 等模型权重文件Dify 本身由多个容器组成包含前端、API、Worker、PostgreSQL、Redis、Weaviate 等组件。用户只需要把注意力放在 Web 界面上底层容器编排交给 Docker Compose 处理。3. 第一步使用 Ollama 部署本地大模型3.1 为什么选择 OllamaOllama 是一个本地大模型运行工具它解决的核心痛点是在本地运行 LLM 通常需要手动安装 Python、PyTorch、CUDA、模型权重管理工具等一整套复杂环境对小白极不友好。Ollama 把这些事情封装成了一条命令。安装完成后执行ollama run qwen2.5:7b它就会自动下载模型、加载权重、启动服务并进入对话窗口。如果想要 HTTP APIOllama 也会自动在 11434 端口启动一个兼容 OpenAI 风格的接口。这使得 Ollama 成为很多 Agent 编排工具的首选模型运行时。Ollama 在 macOS、Windows、Linux 上都有安装包还支持通过 Docker 运行。它自动管理模型缓存和并发请求使用者不需要关心底层推理细节这一点非常适合零基础入门。3.2 在 Linux 上安装 Ollama在 Ubuntu 服务器上安装 Ollama 非常简单执行官方安装脚本即可。curl -fsSL https://ollama.com/install.sh | sh脚本会自动检测系统架构、安装必要的依赖、创建 systemd 服务并启动 Ollama。安装完成后执行ollama --version如果你看到了类似ollama version 0.x.x的输出说明安装成功。macOS 和 Windows 用户可以前往 Ollama 官网下载对应系统的安装包安装完成后同样可以在终端中执行ollama --version验证。需要特别提醒的是Linux 上如果 Ollama 是以 systemd 服务方式运行的默认可能只监听本机回环地址。后续 Dify 容器要访问 Ollama 时需要让 Ollama 监听在0.0.0.0。修改方式是在 systemd 服务中增加环境变量OLLAMA_HOST0.0.0.0:11434然后重启服务。不同版本的服务文件位置略有差异可以执行systemctl cat ollama查看当前配置。3.3 拉取并运行本地大模型Ollama 提供了模型库可以通过ollama pull命令下载模型也可以直接通过ollama run自动拉取。这里以通义千问 Qwen2.5 系列为例它是目前综合表现稳定、中文支持较好的开源模型。ollama run qwen2.5:7b第一次执行时Ollama 会先下载模型权重。7B 模型文件大小通常在 4GB 到 5GB 左右具体取决于量化版本下载时间取决于网络状况。等待出现Send a message或类似提示后说明模型已经启动成功可以直接在终端对话。如果机器配置比较低可以换成更小的模型ollama run qwen2.5:3b也可以拉取其他模型比如 DeepSeek 系列、Llama 系列。执行ollama list可以查看本地已有的模型列表执行ollama rm可以删除某个模型。3.4 验证 Ollama APIAgent 平台通常不是通过命令行与模型交互而是通过 HTTP API。Ollama 默认在 11434 端口提供 REST API用 curl 可以快速验证服务是否正常。curl http://localhost:11434/api/generate -d { model: qwen2.5:7b, prompt: 请简单介绍一下你自己, stream: false }返回结果中会包含response字段内容是模型生成的文本。如果请求成功说明 Ollama 已经准备好被其他平台调用了。这里还需要检查一点如果 Dify 运行在 Docker 容器内容器内不能直接使用localhost访问宿主机服务。后续配置 Dify 模型供应商时需要填写宿主机的内网 IP例如http://192.168.1.100:11434如果 Dify 和 Ollama 在同一台机器上也可以使用 Docker 默认网关地址例如http://172.17.0.1:11434。具体方式会在第 5 章详细说明。4. 第二步部署 Dify 作为 Agent 开发平台4.1 Dify 是什么Dify 是一个开源的大语言模型应用开发平台提供了可视化的工作流编排、Agent 创建、知识库管理、Prompt 调试和 API 发布能力。简单说它把“给大模型写代码”这件事变成了“在网页上配置”这件事。Dify 支持接入多种模型供应商包括 OpenAI、Anthropic、DeepSeek 等云端模型也可以通过 OpenAI 兼容接口接入 Ollama、vLLM 等本地模型。这意味着你可以在 Dify 中统一管理多个模型而不需要为每个模型单独写调用代码。对于 Agent 开发来说Dify 内置了 Agent 节点、工具节点和条件分支用户可以像搭积木一样创建智能体还可以添加自定义工具或内置工具。4.2 安装 Docker 与 Docker Compose如果服务器还没有安装 Docker先执行下面的命令完成基础安装。sudo apt update sudo apt install -y ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc sudo chmod ar /etc/apt/keyrings/docker.asc echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release echo $VERSION_CODENAME) stable | \ sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin安装完成后启动 Docker 并设置为开机自启sudo systemctl enable docker sudo systemctl start docker验证安装结果docker --version docker compose version如果两条命令都正常输出版本信息说明 Docker 环境准备完成。4.3 拉取 Dify 源码并启动Dify 官方仓库提供了完整的 Docker Compose 配置直接克隆代码后启动即可。git clone https://github.com/langgenius/dify.git cd dify/docker cp .env.example .env docker compose up -d首次启动会拉取多个镜像包括 PostgreSQL、Redis、Weaviate、Dify API 和 Web 等耗时取决于网络状况和机器性能。拉取完成后执行docker compose ps看到多个容器状态为Up说明 Dify 已经启动成功。4.4 初始化 Dify打开浏览器访问http://localhost。首次访问会进入管理员初始化页面需要设置管理员邮箱和密码。这个账号是整套系统的超级管理员务必使用真实可用邮箱并设置强密码。初始化完成后进入 Dify 主界面。此时可以看到左侧菜单有“工作区”“知识库”“工具”“监控”等入口一个完整的 Agent 开发平台已经跑起来了。如果当前机器的 80 端口已经被占用可以在.env文件中调整端口映射例如将NGINX_PORT80改为NGINX_PORT8080然后重新执行docker compose up -d。5. 第三步打通 Ollama 与 Dify创建第一个 Agent5.1 在 Dify 中接入 Ollama 模型供应商登录 Dify 后点击页面右上角的头像进入“设置”页面选择“模型供应商”。在供应商列表中找到 Ollama点击“添加模型”。需要填写以下关键信息模型名称与 Ollama 中已下载的模型 tag 保持一致例如qwen2.5:7b。API 地址Ollama 服务地址注意不能写localhost因为 Dify 运行在容器内。推荐填写宿主机的局域网 IP例如http://192.168.1.100:11434。模型类型这里选择LLM。上下文长度按模型实际支持长度填写不确定时可以填 4096 或 8192使用中如果报错再调整。填写完成后点击“保存”。Dify 会尝试连接模型并加载模型列表如果配置正确模型会出现在可直接调用的列表中。5.2 创建 Agent 应用在 Dify 首页点击“创建空白应用”输入应用名称选择应用类型为“Agent”然后点击创建。进入 Agent 编辑器后可以看到“提示词”“模型”“工具”几个主要配置区域。先把右上角的模型切换为刚才接入的 Ollama 模型然后在“提示词”区域设置 Agent 的角色和任务。例如你是一个生活助手负责帮助用户规划日常安排、查询信息和解答问题。回答时要简洁清晰确认信息不完整时可以向用户提问。这里的提示词会作为系统提示词交给大模型决定了 Agent 的“人设”和行为风格。5.3 配置工具Dify 内置了多个工具选项例如网页搜索、天气查询、计算器等。首次使用部分工具需要申请对应的第三方 API Key如果暂时没有可以先只启用内置的计算器或代码执行器。工具配置的原则是“按需启用”。对新手来说可以先不启用任何外部工具直接让 Agent 基于大模型能力回答问题等跑通后再逐项添加工具。在 Agent 编辑器右侧的“工具”区域点击添加工具勾选需要启用的工具即可。启用后Agent 在对话中会自动判断是否需要调用工具并在界面上展示调用过程。5.4 运行验证配置完成后点击右上角的“发布”按钮然后在左下角的调试对话框中输入一句话例如我想了解一下本地部署 Agent 的主要步骤请帮我列出一个简单的计划。如果一切正常Agent 会调用 Ollama 模型生成回答。由于是本地模型首次响应可能需要几秒钟甚至更久请不要频繁点击重发避免多个推理任务同时排队。也可以让 Agent 执行一段计算任务来验证工具调用链路例如请计算 23 乘以 17 的结果。当 Agent 决定调用“计算器”工具时调试界面会显示工具调用日志这是判断 Agent 是否真正具备“工具调用能力”的重要标志。6. 常见问题与排查思路本地部署 Agent 过程中最容易出问题的环节主要集中在 Docker 容器、网络访问、模型下载和资源不足这几个方面。问题现象常见原因解决思路docker compose命令找不到只安装了 Docker Engine未安装 Compose v2 插件安装 docker-compose-plugin或升级 Docker浏览器无法访问http://localhost80 端口被占用或 Dify 容器未启动成功查看.env中端口配置执行docker compose ps检查容器状态Dify 无法连接 OllamaOllama 未监听0.0.0.0或 Dify 容器内不能访问localhost修改 Ollama 监听地址Dify 中填写宿主机局域网 IPOllama 下载模型很慢网络不稳定或模型文件较大检查网络后重试或先下载到本地再导入 OllamaAgent 响应速度极慢模型参数过大CPU 推理能力不足换用 3B 或 1.5B 小模型或使用 GPU 推理Dify 初始化页面一直转圈PostgreSQL 容器尚未完全就绪等待几十秒后刷新页面或查看docker compose logs api日志容器频繁崩溃日志提示内存不足Docker 可用内存太小增加系统内存或调整 Docker Desktop 内存限制6.1 模型下载类问题模型下载是很多人卡住的第一关。7B 模型文件通常有几个 GB如果网络不稳定很容易中途失败。遇到这种情况可以先暂停清理不完整的下载缓存然后重新执行ollama pull。也可以选择更小的模型例如qwen2.5:1.5b先把流程跑通再说。如果 Ollama 一直无法从远程库下载模型建议检查网络环境确认能够正常访问模型库后重试。不要同时并发拉取多个模型容易造成带宽占用和磁盘空间不足。6.2 Dify 与 Ollama 联调失败这是最常见的配置问题。Dify 通过 Docker 容器运行在容器内部访问localhost指向的并不是宿主机而是容器自身。所以在 Dify 配置 Ollama API 地址时必须使用宿主机可达的 IP。Linux 下可以通过ip addr查看宿主机 IP也可以在 Docker 桥接网络中尝试172.17.0.1。macOS 或 Windows 的 Docker Desktop 通常支持host.docker.internal这种特殊域名指向宿主机。配置时优先使用局域网 IP因为它在桥接和 host 网络下都更稳定。6.3 Agent 逻辑不对或回答质量差如果 Agent 能正常响应但行为和预期不符问题通常出在提示词上。提示词越模糊Agent 的行为越不确定。建议在提示词中明确“你是谁、你能做什么、你回答问题的风格、遇到不确定情况怎么办”。模型无法通过一次提示词就理解所有内部系统细节需要迭代调优。另外要注意7B 级别的本地模型在复杂推理任务上的能力与 GPT-4o、Claude 这类云端大模型仍有差距。这不代表本地部署没有价值而是要对模型能力边界有合理预期。7. 最佳实践与工程建议7.1 模型选择与资源规划本地部署 Agent 的第一条建议模型不是越大越好。部署一个超出硬件承载能力的大模型最终只会得到一段段超时的响应和一个心情崩溃的你。更好的做法是准备好一套“从小到大的模型列表”先确保链路畅通再逐步升级。一个推荐的路径1.5B / 3B 模型验证部署、联调 API、学习 Agent 机制。7B 模型日常使用、简单问答、知识库测试。14B 及以上模型有 GPU 后再尝试做深度推理和复杂任务。同时要留意磁盘空间多个模型并存会占用大量磁盘。建议在ollama list中定期检查运行ollama rm卸载不常用的模型。Dify 占用的 docker volume 也不要随意清理否则会导致知识库和配置数据丢失。7.2 配置管理与数据备份生产环境中docker compose up -d并不是“一劳永逸”的操作。Dify 的升级、容器重建、环境变量修改都可能影响数据。建议在正式使用后修改.env配置时先备份原文件。使用docker compose down停止容器再执行docker compose up -d启动。定期备份 PostgreSQL 和 Redis 的数据卷。每次升级前阅读官方 Release 说明避免跨大版本直接升级。对于 Ollama模型权重文件本身不需要频繁备份但如果你自己微调或导入了私有模型记得把对应文件单独归档。7.3 安全边界与权限控制本地部署不等于“绝对安全”。如果服务器暴露在公网至少要处理以下几件事修改 Dify 管理员默认密码使用高强度密码。在反向代理层启用 HTTPS不要让浏览器直接以 HTTP 明文访问。限制 MongoDB、PostgreSQL、Redis 等内部服务端口不要对公网开放。Ollama 的 11434 端口如需对外提供服务应增加访问控制防止未授权调用。如果 Agent 要接入内部系统、数据库或第三方 API一定要遵循最小权限原则。每个工具都应该使用独立的 API Key并设置调用频率和访问范围不要把管理员令牌直接写到提示词或工具配置里。7.4 日志、监控与长期维护容器化部署的便利性也会带来一个隐患服务太多问题发生时不知道看哪个日志。Dify 官方提供了查看日志的命令docker compose logs -f api docker compose logs -f web docker compose logs -f worker一旦页面报错或 Agent 响应异常优先查看 api 和 worker 日志这两者负责核心的业务逻辑和模型调用。Ollama 的日志可以通过journalctl -u ollama查看。随着使用深入可以引入 Prometheus 监控容器资源但这属于进阶内容。初期先掌握“看日志”这个能力就足以解决大部分问题。7.5 从演示到生产环境的注意事项在本地跑通 Agent 后如果打算部署到团队或生产环境还需要额外考虑以下几点。一是并发能力。本地单机 Ollama 能同时处理的推理请求非常有限多个用户同时使用 Agent 时响应速度会明显下降。需要评估模型推理吞吐量必要时引入 GPU 集群或模型推理服务层。二是知识库与数据隔离。如果多个业务团队共用一套 Dify要为每个团队创建独立的工作区和知识库设置好成员权限避免数据越权访问。三是应用发布方式。Dify 创建的应用可以发布为 API也可以在对话调试界面直接使用。生产环境建议通过 API 方式集成到现有系统中而不是让用户直接操作 Dify 后台。四是更新策略。开源平台迭代速度快但不要每天都执行docker compose pull。生产环境应该采用“固定版本 定期评估升级”的策略降低未知回归风险。8. 总结与下一步学习建议到这里你已经亲手完成了一条完整的 Agent 本地部署链路通过 Ollama 拉起本地大模型通过 Dify 搭建可视化 Agent 编排平台然后创建了第一个能对话、能调用工具的 Agent 应用。整体来看这套方案不依赖任何云端厂商数据和代码都掌握在自己手中非常适合作为 Agent 开发的第一块跳板。接下来可以沿着几个方向继续深入。第一个方向是 Dify 的高级功能比如知识库管理、工作流编排、多 Agent 协作这些功能可以让 Agent 从“会聊天”变成“能干活”。第二个方向是学习代码级 Agent 开发框架比如 LangChain、LlamaIndex以及当前大热的 Harness 概念。理解了大模型、工具调用、记忆管理和规划策略之间的联系后再回到 Dify 里做配置视角会完全不一样。第三个方向是模型层面的优化比如量化加速、LoRA 微调、提示词压缩这些对提升本地 Agent 的响应质量和速度非常有帮助。Agent 搭建并不是一次性工作模型会换、框架会变、工具会越来越多。建议你先把今天这套流程保存下来跑熟之后再逐步替换组件找到最适合自己环境和业务的那套组合。亲手把一个 Agent 从零部署起来比看一百篇教程都更有价值。