企业官网建设流程全解析

Agent 部署看起来复杂，实际上拆开就是三件事：选一个 Agent 管理平台，接一个大模型，再把知识库或业务流程挂进去。这篇文章不走弯路，直接用“Dify 社区版 + Ollama 本地模型”这套组合，带你从零完成 Agent 搭建、知识库配置、工作流编排和 API 调用。全程按零基础小白的操作习惯来写，不需要你有深度学习背景，只需要会复制命令、会看网页。

先说重点：这套方案适合本地和私有化部署，数据掌握在自己手里；启动方式偏图形化，大部分操作在浏览器网页里完成；部署完成后会提供一个 HTTP API，可以接到自己的工具或脚本里，也支持通过脚本批量调用。整个过程覆盖环境准备、服务启动、模型接入、功能测试和问题排查，读完就可以照着做一遍。

如果你之前一直卡在“Agent 怎么部署”这个概念上，不知道从哪里下手，这篇文章就是给你准备的“第一步”。先跑通最小可用系统，再慢慢加功能，这是最稳的学习路径。

1. 核心能力速览

先给一张速览表，让你 30 秒判断这套方案适不适合自己。

这套组合的关键点是：Agent 管理平台负责“编排”，本地大模型负责“思考”。平台把用户的提问、知识库内容、提示词组合起来，交给模型推理，再把结果返回给用户。你不需要自己写模型推理代码，也不需要从头开发一套 Agent 框架，大部分功能在网页后台里可以配置完成。

需要提前说明的是，文章中的命令、路径和端口都是通用模板，实际部署时以你安装的版本和官方文档为准。尤其是模型名称、镜像版本、端口占用这些信息，不同环境会有差异，我会在每一步标注需要关注的地方。

2. 适用场景与使用边界

2.1 适合谁

• 零基础学习者：想弄清楚 Agent 到底是什么、怎么跑起来，需要一个可视化入口，而不是直接面对一堆代码。
• 企业内部知识库助手：把产品文档、操作手册、FAQ 喂给 Agent，员工提问后直接返回答案，减少重复检索。
• 自动化流程测试：用工作流把“知识检索 + 模型回答 + 结果输出”串起来，验证 Agent 在具体业务里的效果。
• 内容整理与问答辅助：上传文章、会议纪要、运营素材，让 Agent 基于这些内容回答提问。

2.2 不适合谁

• 需要超高并发生产环境的团队：社区版默认部署方式更适合中小规模使用，高并发场景需要额外设计消息队列、多副本、负载均衡等架构。
• 对生成质量要求极高的任务：本地部署的小模型能力有限，如果任务需要复杂的推理、严谨的逻辑或者极强的通用知识，云端大模型 API 通常更合适。
• 完全不想动手维护服务器的用户：自托管意味着你要负责服务状态、磁盘空间、升级备份，这不是“只管用”的开箱即用方案。

2.3 合规与安全边界

本地部署不意味着可以随意使用。你需要注意几条底线：

• 上传到知识库的文档、喂给 Agent 的业务数据，必须确认你拥有使用和传播的授权，不能把未经许可的内部资料或版权素材随意放入知识库。
• 不要把个人敏感信息、账号密码、身份证号、手机号等输入到 Agent 对话里，即使数据存在本地，也要遵循最小化原则。
• Agent 生成的内容需要人工抽查，尤其是对外发布或用于决策的内容，避免模型输出错误结论。
• 不要用 Agent 生成违法、侵权、误导性的内容，也不要试图绕过平台和模型的安全限制。
• 如果 Agent 服务部署在可对外访问的服务器上，必须做好访问控制，默认只允许内网或指定 IP 访问。

3. 环境准备与前置条件

3.1 部署思路说明

整个部署分成两层：第一层是 Agent 管理平台，推荐用 Dify 社区版，它提供可视化后台，可以在网页里创建应用、配置知识库、编排工作流；第二层是本地大模型服务，推荐用 Ollama，它把模型下载、启动、API 请求都封装得很简单，适合小白入门。

选择这一组合的原因很简单：Dify 负责“复杂但可视化”的部分，Ollama 负责“模型但命令行”的部分。两者都有大量的社区使用案例，遇到问题容易搜到解决方案。

3.2 环境检查清单

在开始之前，按下面的表格检查一遍环境。

如果你使用的是云服务器，注意安全组和防火墙要放行需要用到的端口；如果只是本机学习，则不需要额外开放公网端口。

3.3 安装 Docker 环境

Docker 是运行 Agent 管理平台的基础依赖。不同操作系统的安装方式不一样，下面给一个 Linux 通用示例，Windows 和 macOS 用户请直接下载 Docker Desktop 安装包，按提示安装后启动即可。

# 以 Ubuntu/Debian 为例，不同发行版命令有差异，以官方安装文档为准 sudo apt update sudo apt install -y docker.io docker-compose-plugin # 启动 Docker 并设置开机自启 sudo systemctl enable --now docker # 验证安装结果 docker --version docker compose version

如果docker compose命令报错，说明 Docker Compose v2 插件没有安装成功，需要单独安装 compose 插件。安装完成后不要急着下一步，先确认 Docker 服务处于运行状态。

3.4 准备一个干净的部署目录

建议把所有 Agent 相关的文件放在同一个目录下，方便后续管理和备份。

mkdir -p ~/agent-selfhost && cd ~/agent-selfhost

之后克隆项目、存放配置、挂载数据都会基于这个目录。目录名可以自己改，记住路径即可。

4. 部署 Agent 管理平台

4.1 获取平台项目

Dify 社区版支持通过 Docker Compose 一键拉起整套服务。你需要先获取项目的部署文件，实际操作时以官方仓库为准。

cd ~/agent-selfhost # 克隆部署文件，仓库地址以官方文档为准 git clone <dify 项目仓库地址> cd dify

克隆完成后，目录里会有一个.env.example文件，这是环境变量模板。第一次部署需要复制一份并命名为.env，然后根据实际情况修改端口等关键参数。

cp .env.example .env

如果 80 端口已经被占用，可以在.env里修改服务端口，例如把 80 改成 8000，后续访问地址就变成http://localhost:8000。

4.2 启动服务

在项目目录下执行：

docker compose up -d

-d表示后台运行。首次启动会拉取多个镜像，时间取决于网络和镜像大小，耐心等待即可。启动完成后，用下面的命令确认容器状态：

docker compose ps

如果所有服务的状态都是Up，说明平台已经启动成功。此时在浏览器访问http://localhost（或你修改后的端口），应该能看到平台的初始化页面。

4.3 初始化管理员账号

第一次打开平台后台，会要求设置管理员邮箱和密码。设置完成后进入主界面，你会看到左侧菜单有“应用”“知识库”“工具”“工作流”等入口。到这一步，Agent 管理平台已经跑起来了。

这里多说一句：平台本身不包含模型，它是一个“空壳”管理层。下一步必须把大模型接进来，否则创建的应用无法回答问题。

5. 部署本地大模型服务

5.1 安装 Ollama

Ollama 的作用是下载和运行开源大模型。Linux 和 macOS 可以用官方安装脚本：

# 安装命令以官方文档为准 curl -fsSL https://ollama.com/install.sh | sh

Windows 用户直接下载 Ollama 的 Windows 安装包，双击安装即可。安装完成后，先启动服务：

ollama serve

正常情况下服务会监听11434端口。如果你在 Windows 上通过安装包安装，Ollama 服务一般会自动启动，不需要手动执行serve。

5.2 拉取一个适合小白的模型

模型选择直接影响硬件压力和回答质量。建议第一次部署选一个中小体量的模型，比如 7B 参数级别的模型，先把流程跑通，再考虑换更大的模型。

# 拉取模型，模型名和版本以 Ollama 模型仓库实际支持的为准 ollama pull qwen2.5:7b

等待下载完成后，可以用一条命令验证模型是否可用：

curl http://127.0.0.1:11434/api/chat -d '{ "model": "qwen2.5:7b", "messages": [{"role": "user", "content": "你好"}], "stream": false }'

如果返回了一段 JSON，里面包含模型的回答内容，说明本地模型服务正常。这一步是整个部署里最容易卡住的地方，很多问题的根源就是 Ollama 没有启动或者地址不对，建议优先确认 11434 端口能被访问。

5.3 关于 CPU 与 GPU 推理

Ollama 默认会尝试使用本机 GPU 加速。如果你的服务器有 NVIDIA 显卡并且安装了驱动，模型推理会明显更快；如果没有显卡，Ollama 会自动回退到 CPU 推理，速度会慢很多，但中小模型仍然可以跑，只是响应时间会长一些。

显存占用取决于模型大小。7B 模型在 CPU 模式下主要吃内存，在 GPU 模式下会吃显存。对小白来说，第一次不要追求速度，先用 CPU 跑通，再根据实际体验决定要不要上显卡。

6. 创建 Agent 应用并接入模型

6.1 在平台后台添加 Ollama 模型供应商

登录平台后台，找到“设置”或“模型供应商”入口，选择 Ollama 类型。需要填写的关键信息有：

• 模型服务地址：默认填http://127.0.0.1:11434
• 模型名称：填你在 Ollama 拉取的模型名，例如qwen2.5:7b

这里有一个很常见的坑：如果平台本身跑在 Docker 容器里，容器内的127.0.0.1指向的是容器自己，不是宿主机。此时需要把地址改成宿主机地址。Windows 和 macOS 的 Docker Desktop 通常可以用http://host.docker.internal:11434，Linux 则需要填宿主机的局域网 IP。

填写完成后点击“测试连接”，如果提示成功，说明模型已经接入平台。

6.2 创建聊天助手应用

回到后台首页，点击“创建应用”，选择“聊天助手”类型。创建一个应用后，进入应用编排页面，你可以配置：

• 系统提示词：告诉 Agent 它的角色和行为规范，比如“你是公司 IT 支持助手，回答要简洁准确”。
• 模型选择：选择刚才接入的 Ollama 模型。
• 对话开场白：用户在网页端看到的欢迎语。

配置完成后点击“发布”，然后在“概览”页面点击“运行”或“预览”，就能在网页里和 Agent 对话了。到这一步，你已经拥有了一个最简版本的 Agent 应用。

7. 配置知识库与工作流

7.1 创建知识库

只有对话能力的 Agent 还不够实用，真实场景下通常需要 Agent 回答“你自己的资料”里的内容。这时需要创建知识库。

在后台点击“知识库”，创建空白知识库，然后上传文档，支持常见的文本和办公文档格式。上传后平台会对文档进行分段和索引，这个步骤可能需要一点时间。索引完成后，在应用编排页面添加“知识检索”或关联知识库，这样 Agent 回答时就会优先参考你上传的文档。

知识库是私有化部署的核心卖点。你的文档不需要上传到公网，数据保留在自己的服务器上，适合企业内部资料问答场景。

7.2 创建工作流应用

如果你不想只做简单的问答，而是想串联多个步骤，可以创建“工作流”类型应用。工作流的核心逻辑是：

开始节点 -> 知识检索节点 -> LLM 节点 -> 直接回复节点

例如用户提问后，系统先从知识库检索相关片段，再把片段和问题一起交给大模型生成回答，最后将结果返回给用户。工作流的好处是每一步都可控、可调试，复杂业务也可以通过多个节点组合实现。

对零基础读者来说，建议先跑通聊天助手，再试着加知识库，最后再碰工作流。一步一个台阶，排错会容易很多。

8. 功能测试与效果验证

部署完成后，不要急着接入业务，先做一轮功能测试。测试的核心目的是确认 Agent 链路是否完整、知识库是否生效、模型输出是否稳定。

8.1 基础对话测试

在应用预览窗口输入一句简单的问题，例如“你好，请介绍一下你自己”。判断成功的标准是：模型能正常返回回答，且响应时间在可接受的范围内。

如果长时间没有响应，优先检查 Ollama 服务和模型加载状态。第一次请求时模型需要加载到内存或显存，耗时偏长是正常现象。

8.2 知识库问答测试

在知识库中上传一份你自己写的测试文档，然后问一个只有这份文档才能回答的问题。判断成功的关键是：回答内容是否引用了你上传的文档里的信息。

如果 Agent 完全没有参考知识库，回答得和通用大模型一样，通常说明知识库没有正确关联，或者分段索引没有完成。

8.3 工作流链路测试

创建工作流后，输入一个和知识库相关的提问，观察流程是否完整走通：开始节点是否收到输入、知识检索节点是否返回内容、LLM 节点是否生成回答、最终是否正常回复。

工作流出现问题时，后台通常会显示具体是哪个节点报错。先看节点日志，再针对性修改配置，是最高效的排错方式。

8.4 输出质量观察

本地小模型的回答质量通常不如云端大模型稳定。测试时重点关注：

• 答案是否答非所问。
• 长文本输入下是否丢失上下文。
• 复杂指令是否执行正确。
• 知识库引用是否准确。

如果质量明显不满足要求，可以考虑换一个更大的模型，或者在提示词里补充更明确的约束。

9. 接口 API 与批量任务

9.1 获取 API Key

Agent 应用发布后，可以把它当做一个 HTTP 服务来调用。在应用“访问 API”页面，生成一个 API Key，保存好。后面所有请求都要带上这个 Key。

9.2 对话接口调用示例

Dify 应用通常提供/v1/chat-messages接口用于对话，下面是一个 curl 示例。

curl --location --request POST 'http://localhost/v1/chat-messages' \ --header 'Authorization: Bearer <你的API密钥>' \ --header 'Content-Type: application/json' \ --data-raw '{ "inputs": {}, "query": "你好，请根据知识库介绍一下 Agent 的部署流程", "response_mode": "blocking", "user": "test-user" }'

使用blocking模式时，接口会等待模型生成完毕再返回完整结果。如果响应时间太长，可以改成流式模式，由客户端分块接收。

9.3 Python 调用示例

把接口接到自己的脚本或后端程序时，用 Python requests 比较方便。

import requests API_KEY = "<你的API密钥>" BASE_URL = "http://localhost/v1" payload = { "inputs": {}, "query": "请根据知识库告诉我 Agent 有哪些部署方式", "response_mode": "blocking", "user": "demo-user" } response = requests.post( f"{BASE_URL}/chat-messages", headers={ "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" }, json=payload, timeout=120 ) print(response.status_code) print(response.json())

如果返回401，说明 API Key 不对；如果超时，说明模型推理时间过长，需要换更小的模型或调整服务器配置。

9.4 批量任务设计

平台本身不一定自带“批量对话”按钮，但你可以通过写脚本实现批量调用。批量任务通常用于：批量文档问答、批量内容审核、批量 FAQ 生成。

下面是一个最小批量调用示例，核心是循环调用接口，保存结果，并做失败记录。

import json import time import requests API_KEY = "<你的API密钥>" BASE_URL = "http://localhost/v1" questions = [ "什么是 Agent？", "Agent 有哪些常见框架？", "私有化部署需要注意什么？" ] results = [] for i, question in enumerate(questions, start=1): payload = { "inputs": {}, "query": question, "response_mode": "blocking", "user": f"batch-user-{i}" } try: resp = requests.post( f"{BASE_URL}/chat-messages", headers={"Authorization": f"Bearer {API_KEY}"}, json=payload, timeout=120 ) resp.raise_for_status() answer = resp.json().get("answer", "") results.append({"question": question, "answer": answer}) print(f"[{i}/{len(questions)}] 完成：{question}") except Exception as exc: results.append({"question": question, "error": str(exc)}) print(f"[{i}/{len(questions)}] 失败：{exc}") time.sleep(1) with open("batch_results.json", "w", encoding="utf-8") as f: json.dump(results, f, ensure_ascii=False, indent=2)

批量任务的三个建议：加固定间隔，避免把服务打满；每次调用都记录日志，方便回查；失败任务要能重试，不要直接丢弃。

10. 资源占用与性能观察

10.1 如何查看资源占用

部署完成后，可以用两个命令观察服务器负载。

# 查看 Docker 容器 CPU 和内存占用 docker stats # 查看 CPU 和内存整体情况 top

如果你有 NVIDIA 显卡，可以查看显存占用情况：

nvidia-smi

10.2 影响性能的主要因素

• 模型大小：模型越大，内存或显存占用越高，推理速度越慢。
• 推理方式：GPU 推理比 CPU 推理快很多，尤其是大模型在 CPU 上生成速度可能低到让人难以接受。
• 并发请求：同时多个请求进入时，资源争抢会导致每个请求都变慢。
• 上下文长度：对话越长，模型需要处理的 token 越多，内存和时间开销越大。
• 知识库检索：知识库文档过多或分段不合理，会拖慢检索节点。

10.3 降低资源占用的方法

• 第一次测试用最小的模型，不要一上来就拉几十 B 的大模型。
• 关闭不用的 Docker 容器，减少常驻内存占用。
• 限制单次对话的最大 token 数，避免长文本无限生成。
• 批量任务控制并发数量，避免瞬间打满资源。
• 如果不使用 GPU，在 Ollama 中设置 CPU 线程数，避免影响服务器其他应用。

实际占用数字依赖具体模型、并发量和机器配置，不要照着网上别人的截图去判断自己的服务器是不是“坏了”。用同样的请求跑 5 遍，观察平均响应时间和资源占用，比看单次结果更可靠。

11. 常见问题与排查方法

12. 最佳实践与合规提醒

12.1 工程化建议

• 第一次部署先用最小配置跑通，再逐步加模型、知识库和复杂工作流。
• 把.env文件和部署目录做备份，容器重建后能快速恢复。
• 数据目录建议单独挂载到磁盘，避免容器删除后数据丢失。
• 接口服务如果要对外开放，必须加访问控制；纯本机学习不要暴露公网端口。
• 批量任务必须写日志、加超时、加重试，否则跑到一半失败很难排查。
• 模型更新时先在小范围验证，确认效果后再替换正式环境。

12.2 合规与安全提醒

• 上传到知识库的资料必须确保有合法授权，尤其是公司内部文档、他人作品和个人信息。
• 使用涉及人脸、声音、品牌标识等素材时，必须取得明确授权，不能直接输入到 Agent 流程中生成内容。
• Agent 输出内容要人工抽检，不能把未审核的模型生成结果直接用于对外发布或关键决策。
• 不要利用 Agent 生成违法、侵权、诈骗类内容，也不要尝试绕过模型和平台的安全限制。
• 本机部署不等于绝对安全，服务器仍要做好基础防护：更新补丁、限制端口、设置强密码。

13. 总结

这次部署走通的核心链路是：Docker 启动 Agent 管理平台，Ollama 提供本地大模型，平台把对话、知识库、工作流串起来，最后通过 API 对外提供服务。对零基础小白来说，最先要验证的不是复杂工作流，而是“模型接入后能不能正常对话”和“知识库能不能被正确引用”。跑通这两点，Agent 部署就算入门了。

最容易踩的坑集中在三处：一是 Ollama 服务没启动，导致模型连接失败；二是 Docker 容器内访问宿主机地址不对；三是知识库文档索引没完成，导致 Agent 回答完全忽略上传的资料。这三个问题解决了，整个部署就顺了。

后续可以继续扩展的方向很多：换更大更强的模型，接入更多工具插件，把工作流和业务系统打通，或者用 API 批量处理真实业务数据。建议先收藏这份流程，把最小环境跑起来，再按实际需求逐步扩展。