企业官网建设流程全解析

1. 为什么要在局域网里自建一个 AI Agent 平台

先说结论：这事最核心的诉求不是"赶时髦"，而是把 AI 能力真正圈在自己的网络边界内。

我最早尝试在局域网里搭 Agent 平台，是某项目组的一次内部需求。当时团队想做知识库问答和自动化任务处理，但数据完全不能出内网，云上大模型API根本不用考虑。市面上现成的私有化Agent方案不是偏贵就是偏重，动辄要一堆硬件和授权。后来试了一圈开源方案，发现基于 DeepSeek 系模型做本地化部署是一条很务实的路子——模型权重公开、推理框架成熟、生态工具链齐全，而且是中文场景下效果最稳的一批开源模型之一。

于是就有了标题里说的 DeepSeek Harness。这个名字听起来唬人，拆开看其实就两层意思：DeepSeek 指模型本体，Harness 指"驾驭、封装"——把模型、推理服务、Agent 调度、工具调用这些环节全部编排到一起，形成一个开箱即用的平台。用 Docker 部署的目的也很直白：把环境差异、依赖冲突、版本管理这些脏活累活全包掉，让整个平台像一个大容器一样，在局域网里任意一台 x86 机器上都能拉起来跑。

这套东西适合谁？适合下面几类人：

• 需要在内网做知识库问答、文档处理的团队，数据不出网；
• 想研究 Agent 工具调用（Function Call）机制，但不想从零搓推理服务的开发者；
• 对算力有一定预算，但又不是富到能上满血集群的实验室或小公司；
• 个人玩家，手上有一张 24GB 显存的卡，想搞一个"私有 ChatGPT + 自动化助手"。

如果你属于其中任何一类，这篇文章基本就是为你准备的。我会把从环境准备、镜像选择、容器编排、模型加载到 Agent 能力接入的完整链路拆开讲，中间还会带上我在实际部署中踩过的坑和绕过的弯。

2. 部署前的关键判断：模型选型、硬件底线与网络拓扑

2.1 先想清楚跑多大模型，再谈部署

DeepSeek 系列开源模型分布在不同的参数规模和量化等级上，不是"下载一个就能跑"那么简单。在选择之前，必须先搞清楚你的硬件能喂饱多大的模型。

我自己的判断是：在绝大多数"局域网 AI Agent"场景下，7B 到 14B 的量化版是最合适的区间。再往上走，显存压力骤增，但 Agent 能力的提升不一定成正比；再往下走，1.5B 的模型在工具调用和指令遵循上会明显吃力，容易出现"模型听懂了但做不对"的局面。

原因很简单：Agent 平台和普通聊天不一样，它需要模型在对话中稳定输出结构化指令（比如调用哪个工具、传什么参数），这对模型的指令遵循能力要求远高于纯文本生成。体量太小的模型，在这方面的表现通常比较飘。

2.2 硬件底线与驱动环境的三个细节

部署前先查三样东西：GPU 型号、驱动版本、显存大小。Docker 本身不挑 GPU，但要让容器里能用上 GPU，必须先装好 NVIDIA 容器工具包（nvidia-container-toolkit），这一步很多人会漏掉。

具体来说，宿主机需要满足：

• Linux 内核版本不低于某个发行版默认版本即可，主流 Ubuntu 20.04/22.04、Debian 11/12 都行；
• 显卡驱动版本要能支持 CUDA 11.8 或更高；
• 装好 docker-ce 和 nvidia-container-toolkit，并在 docker 配置里将 nvidia 设为默认运行时。

我用一张 RTX 4060 Ti 16G 做测试，跑 14B 的 4bit 量化模型，开启 vLLM 或 llama.cpp 的 GPU 加速，单轮推理延迟大概在 1.5 到 3 秒之间，完全能满足局域网内多人使用的交互体验。如果是 7B 模型，延迟能压到 1 秒以内。

提示：如果你手头只有 CPU 机器，也不是不能用。llama.cpp 支持纯 CPU 推理，14B 量化模型在 32 线程的机器上大概能跑出 5-10 token/s 的速度。做点知识库检索、离线批处理还行，但实时对话和 Agent 工具调用会有点着急。

2.3 网络拓扑：Docker 容器、宿主机与局域网的关系

在局域网里部署，需要把"容器内部端口"和"局域网可访问端口"这两层网络关系搞清楚。Docker 默认的 bridge 网络会让容器拥有独立 IP，但外部设备想访问服务，通常要经过端口映射。

我的推荐拓扑是这样：

• 宿主机 IP 固定为某个内网地址，例如192.168.1.100；
• 模型推理服务（vLLM 或 llama.cpp 服务端）在容器内监听8000端口，通过-p 8000:8000映射出来；
• Agent 编排服务（比如 FastAPI 写的调度层）监听8080端口，对外暴露；
• 前端界面（如果有 Web UI）监听3000端口。

这样，局域网内任何一台设备，只要浏览器能访问http://192.168.1.100:3000，就能使用整个 Agent 平台，完全不需要公网 IP。

另外，不要用 Docker 默认的随机映射端口，因为重启容器后端口可能变化，局域网内其他人访问的地址就得跟着改。建议在docker-compose.yml里把所有端口映射写成显式的宿主机端口:容器端口，保证固定不变。

3. 镜像选型与 Docker Compose 编排：少走弯路的核心

3.1 模型推理服务：vLLM 还是 llama.cpp

这是整个平台里最核心的组件。简单说，它负责把 DeepSeek 模型加载进显存，对外提供兼容 OpenAI 格式的 API。之所以强调"兼容 OpenAI 格式"，是因为后面的 Agent 框架、工具调用插件、客户端工具全都默认按这个协议来对接。

在镜像选择上，我实际对比过两个主流方案：

vLLM 方案

• 优点：吞吐量高，高并发场景表现好，支持连续批处理（Continuous Batching），官方镜像直接支持 DeepSeek 系模型的架构；
• 缺点：对显存要求略高，镜像体积大（几个 GB），启动时 CUDA 环境检查比较严格；
• 适合：局域网内多人同时使用、需要稳定并发响应的场景。

llama.cpp 方案

• 优点：轻量、启动快、显存占用低，GGUF 量化模型生态成熟，对低配机器友好；
• 缺点：并发能力弱一些，吞吐量不如 vLLM，高并发下需要多开几个实例分摊；
• 适合：个人使用、低显存显卡、CPU 推理。

两种方案我都跑过。如果是 16G 显存以下，或者跑纯 CPU，llama.cpp 是更省心的选择；如果是 24G 显存以上的机器，且要服务多人，vLLM 是更靠谱的选择。

我自己最终选了 llama.cpp 的 Docker 镜像做主力部署，主要原因是它在显存占用和启动便捷性上更符合局域网小规模场景。但为了兼容不同需求，下面的编排示例我会把两者都写出来，读者按自己情况选。

3.2 完整的 docker-compose.yml 参考

下面是我实验环境里一份能直接跑起来的编排文件，核心组件有三个：模型推理服务、Agent 编排服务、Web UI。模型推理以 llama.cpp 为例。

version: "3.8" services: llama: image: ghcr.io/ggerganov/llama.cpp:server-cuda container_name: deepseek-llama restart: unless-stopped ports: - "8000:8000" volumes: - ./models:/models command: > --model /models/deepseek-14b-q4_k_m.gguf --host 0.0.0.0 --port 8000 --n-gpu-layers 99 --ctx-size 4096 --parallel 4 deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] agent: image: python:3.11-slim container_name: deepseek-agent restart: unless-stopped depends_on: - llama ports: - "8080:8080" volumes: - ./agent:/app - ./data:/data working_dir: /app environment: - MODEL_BASE_URL=http://llama:8000/v1 - MODEL_API_KEY=sk-none - MODEL_NAME=deepseek-14b - AGENT_PORT=8080 - TOOL_DATA_DIR=/data/tools command: > sh -c "pip install -r requirements.txt && uvicorn main:app --host 0.0.0.0 --port 8080" webui: image: node:20-alpine container_name: deepseek-webui restart: unless-stopped depends_on: - agent ports: - "3000:3000" volumes: - ./webui:/app working_dir: /app command: > sh -c "npm install --production && npm run serve"

有几个细节要拎出来说：

1. --n-gpu-layers 99表示把所有能卸载到 GPU 的层全扔到 GPU 上。如果你的显存不够，需要调小这个值，让部分层留在 CPU。判断方法是启动日志里会打印每层加载的耗时和显存占用，卡住不动或报 OOM 就往下调。

2. --ctx-size 4096是上下文窗口长度。Agent 场景中，工具定义、历史对话都要占上下文，4096 是底线，建议 8192 更宽裕。但上下文越长，KV Cache 占的显存越多，需要自己平衡。

3. --parallel 4表示可以同时处理 4 个请求序列。llama.cpp 的并行能力有限，开太多反而可能因为显存不足导致启动失败。

3.3 Agent 编排层：模型只是"大脑"，编排层才是"四肢"

很多人以为部署好模型推理服务就完事了，其实那只是拿到了一个"能聊天的模型"。Agent 平台的灵魂在于编排层——它负责：

• 接收用户指令；
• 决定是否需要调用工具；
• 把工具调用结果返回给模型，生成最终回答；
• 管理多轮对话的历史和上下文裁剪。

我在这层用的是一个非常轻量的自研方案：FastAPI + 一个简单的工具注册表。核心代码思路如下：

from fastapi import FastAPI from pydantic import BaseModel import httpx, json app = FastAPI() TOOLS = { "get_server_status": { "description": "查询局域网内服务器状态", "parameters": {"type": "object", "properties": {}}, }, "search_knowledge_base": { "description": "在本地知识库中检索内容", "parameters": { "type": "object", "properties": { "query": {"type": "string", "description": "检索关键词"} }, "required": ["query"] }, }, } class ChatRequest(BaseModel): messages: list tools: list = [] @app.post("/v1/chat/completions") async def chat(req: ChatRequest): # 将工具定义注入 messages # 调用模型推理服务，解析返回的 tool_calls # 执行工具调用，把结果追加到 messages 里 # 再次调用模型，生成最终回复 pass

这个设计参考了 OpenAI 的 Function Calling 协议：先把可用工具的描述以 JSON Schema 的形式发给模型，模型在回复中通过tool_calls字段声明"我要调用哪个工具、参数是什么"，编排层负责实际执行工具，再把结果塞回上下文让模型继续生成。

为什么不直接用现成的 Agent 框架？当然也可以，但很多框架为了通用性做得很重，配置项一大堆。在局域网私有化场景里，我更需要的是"看得见、摸得着、出问题能快速改"的代码。自己的编排层虽然丑一点，但胜在逻辑透明，任何一个工具调用环节出问题，都能立刻定位到是哪一层的问题。

4. 模型文件获取与校验：被忽略但极其致命的一步

4.1 不要随便找一个 GGUF 就下载

DeepSeek 官方开源的是原始权重（safetensors 格式），而 llama.cpp 需要的是 GGUF 格式。GGUF 通常由社区或第三方转换发布，质量和版本参差不齐。同一个模型名，不同人转换出的 GGUF，指令遵循效果可能差不少。

我的经验是优先从三个渠道找：

• 模型官方仓库中如果有 GGUF 版，直接用官方版；
• llama.cpp 社区官方索引里列出的转换版本；
• 有明确转换来源和校验哈希的第三方仓库。

下载后一定要做两件事：

# 查看 GGUF 文件的基本信息 python3 gguf_dump.py deepseek-14b-q4_k_m.gguf # 对比 SHA256 哈希 sha256sum deepseek-14b-q4_k_m.gguf

如果 GGUF 信息和模型名称对不上，或者哈希和来源不一致，别用。我曾经因为贪快下载了一个"优化版" GGUF，结果工具调用经常输出非法 JSON，排查了两天才发现问题在模型文件上。

4.2 量化等级选择：Q4_K_M 是默认答案

量化等级直接影响生成质量和显存占用。llama.cpp 有一堆量化名目：Q2_K、Q3_K、Q4_K_M、Q5_K_M、Q6_K、Q8_0 等等。

我实际对比下来，Q4_K_M 是综合性价比之王。它比 Q5/Q6 小不少，但质量差距在大多数实际任务上可以忽略；比 Q2/Q3 质量强很多，显存占用却没高太多。如果你显存有富余，可以上 Q5_K_M 或 Q6_K；如果显存吃紧，Q4_K_M 是最稳妥的选择。

4.3 启动时的显存观察技巧

启动推理服务后，不要急着开 Agent，先观察一两分钟：

nvidia-smi

重点看Memory-Usage那行。如果显存占用超过 95%，说明配置得太满，后续 Agent 长对话一上来就容易 OOM。可以适当降低--ctx-size或--parallel的值，给自己留 10%-15% 的余量。

5. Agent 能力接入：工具注册、知识库检索与多轮对话管理

5.1 工具注册表是 Agent 的"说明书"

工具注册表是整个 Agent 平台里最有价值的部分。它告诉模型：你能做什么、这些事需要什么参数。我把注册表设计成 JSON 文件，放在容器挂载的/data/tools目录下，修改后无需重启容器，编排层每次请求前动态读取。

[ { "name": "get_cpu_memory_status", "description": "获取宿主机的 CPU 和内存使用情况", "parameters": { "type": "object", "properties": {} } }, { "name": "run_shell_command", "description": "在宿主机上执行指定命令，返回标准输出。仅限运维白名单命令。", "parameters": { "type": "object", "properties": { "command": { "type": "string", "description": "要执行的命令，例如 df -h" } }, "required": ["command"] } } ]

这里特别提醒一个安全注意点：Agent 工具调用相当于给模型发了一张"可执行操作"的授权书。如果工具包含 RCE（远程命令执行）能力，就一定要加白名单和权限校验，否则一旦模型被注入恶意指令，整个内网都有风险。实际部署中我只开放了少量只读命令，且执行者用了低权限系统账户。

5.2 知识库检索：把文档变成 Agent 的"长期记忆"

一个完整点的 Agent 平台通常要配知识库，不然模型只能依靠参数里的知识回答，很多内部文档内容是不知道的。

我的做法是：容器内挂载一个轻量的向量检索服务，用chromadb或者直接用一个 JSON 倒排索引文件做关键词检索。不做太重的原因还是那个——内网场景数据量通常不大，文档几千篇以内，关键词检索配合模型重排序已经够用。

工具定义如下：

{ "name": "search_internal_docs", "description": "在内部文档知识库中执行关键词检索，返回前k条匹配片段。当问题涉及公司内部流程、产品手册、项目文档时使用。", "parameters": { "type": "object", "properties": { "query": { "type": "string", "description": "检索的关键词或短句" }, "top_k": { "type": "integer", "description": "返回结果条数，默认3，最大5" } }, "required": ["query"] } }

整个链路是：用户提问 → Agent 判断需要查知识库 → 调用检索工具 → 获取检索片段 → 拼进上下文 → 模型整合生成回答。这一步看似绕，但实际效果比直接把整篇文档塞给模型好得多，因为上下文长度有限，而检索后的片段更集中、更相关。

5.3 多轮对话管理：上下文窗口是稀缺资源

用模型做 Agent，最大的隐形瓶颈是上下文。DeepSeek 系模型的上下文如果开太长，KV Cache 会把显存吃掉大半。所以编排层一定要做上下文管理。

我常用的策略有几种：

• 滑动窗口：只保留最近 N 轮对话，更早的丢给"摘要记忆"模块；
• 关键信息摘要：每几轮对话后，让模型生成一次摘要，作为长期记忆注入后续请求；
• 工具结果裁剪：工具返回的内容如果太长，只截取前 1000 字符，或者提炼关键字段后再放回上下文。

实际编码中，我封装了一个简单的ContextManager，核心逻辑如下：

class ContextManager: def __init__(self, max_turns=6, max_tokens=4000): self.history = [] self.max_turns = max_turns def add(self, user_message, assistant_message): self.history.append({"user": user_message, "assistant": assistant_message}) if len(self.history) > self.max_turns: self.history = self.history[-self.max_turns:] def build_messages(self, system_prompt="", tools=None): messages = [] if system_prompt: messages.append({"role": "system", "content": system_prompt}) for turn in self.history: messages.append({"role": "user", "content": turn["user"]}) messages.append({"role": "assistant", "content": turn["assistant"]}) if tools: # 将工具定义追加为最后一条系统消息 messages.append({"role": "system", "content": "可用工具: " + json.dumps(tools, ensure_ascii=False)}) return messages

这个过程不需要很复杂，但必须有。不做上下文管理的 Agent，聊十几轮之后就会出现"模型忘了自己在干嘛"的情况，因为它看到的有效上下文已经被无关历史挤爆了。

6. 实测跑通全流程：一台 16G 显卡机器上的完整记录

6.1 从拉镜像到 Web UI 可访问的 12 分钟

为了让你对"这套东西到底多好搭"有个直观感受，我把一次完整的新机部署流程按时间顺序列在下面。环境是 Ubuntu 22.04 + RTX 4060 Ti 16G + 32GB 内存 + 1TB NVMe。

第一步：准备目录结构

mkdir -p ~/deepseek-harness/{models,agent,webui,data/tools} cd ~/deepseek-harness

第二步：下载模型文件

wget -O models/deepseek-14b-q4_k_m.gguf <GGUF下载地址>

这一步最耗时，14B Q4_K_M 大概 8-9GB，内网速度还行，公网就看带宽了。建议提前下好，或者用 BT/网盘工具断点续传。

第三步：写入 docker-compose.yml 和 agent 代码

把前面那份编排文件另存为docker-compose.yml，把 agent 主程序和工具注册 JSON 放进对应目录。

第四步：启动编排

docker compose up -d

首次启动会自动拉取镜像。llama.cpp 的 CUDA 镜像比较大，大概 2-4GB，拉取时间看网速。拉完之后容器会开始加载模型，docker logs -f deepseek-llama可以看到加载进度和每层耗时。

第五步：验证模型服务

curl http://127.0.0.1:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek-14b", "messages": [{"role": "user", "content": "用三句话介绍你自己"}], "max_tokens": 200 }'

能正常返回 JSON 和生成文本，说明模型服务已通。

第六步：验证 Agent 层

curl http://127.0.0.1:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "messages": [{"role": "user", "content": "请查询一下宿主机磁盘使用情况，并总结给我"}] }'

如果编排逻辑正确，这条请求内部应该触发一次df -h工具调用，然后把结果拼回上下文，生成一段简洁的总结。从发起请求到拿到最终回复，16G 显卡跑 14B 模型大概 4-6 秒。

第七步：打开 Web UI

浏览器访问http://宿主机IP:3000，如果能看到聊天界面并能正常对话，恭喜，整个平台通了。

以上总共花费约 12 分钟，其中 8 分钟花在拉镜像和下载模型上。真正的代码和配置时间只需几分钟。

6.2 实测效果：工具调用成功率和响应延迟

我在测试集上简单统计了工具调用表现，样本量不大但能说明问题：

结论很明确：Agent 工具调用场景下，14B 比 7B 的稳定性高出不少。如果你计划让 Agent 干点正经事，14B 起步比较靠谱。

6.3 内网多用户访问的并发体验

我在测试环境里同时开了 4 个会话窗口，轮流提问。llama.cpp 的--parallel 4工作得还算稳，每个请求排队等待的时间在可接受范围，体感上没有明显排队卡顿。但如果真的要让十个人以上同时高频使用，建议换 vLLM，或者多开两个 llama.cpp 实例做负载均衡。

7. 最容易翻车的五个细节：来自真实排障经验的整理

7.1 GPU 没进容器：最常见的"怎么这么慢"原因

很多人部署完发现推理速度还不如 CPU，第一反应是模型不行，其实是NVIDIA 容器工具包没装或没配置好。

判断方法很简单：

docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi

如果这条命令报错或者看不到 GPU，说明 Docker 的 GPU 支持没配好。需要安装nvidia-container-toolkit并重启 Docker：

sudo apt-get install -y nvidia-container-toolkit sudo systemctl restart docker

然后重新验证。

7.2 端口映射失效：常见于防火墙和 SELinux

局域网里其他机器访问不到 Web UI，但宿主机本地 curl 又能通，大概率是防火墙拦截了端口。Ubuntu 上先用ufw status查一下，如果是开启状态，放行对应端口：

sudo ufw allow 3000/tcp sudo ufw allow 8000/tcp sudo ufw allow 8080/tcp

有些发行版还开着 SELinux，虽然 Docker 时代默认影响不大，但个别环境也会造成容器端口无法从外部访问。如果curl本地通、外部不通，优先排查这两层。

7.3 模型上下文越聊越慢：KV Cache 膨胀问题

这是 Agent 平台后期最常遇到的性能杀手。多轮对话越长，模型需要缓存的 K 和 V 矩阵越大，显存占用不断上涨，推理延迟也随之升高。

我自己处理过的最夸张一次，是连续跑了一个多小时的长对话，kv cache 从 2GB 涨到 6GB，响应时间从 2 秒变成 8 秒。最后靠重启进程才缓过来。

正确的做法前面提过：在编排层做上下文裁剪，不要让历史无限膨胀。同时把--ctx-size设为合理值（如 8192），超过这个长度后，旧内容会被自动丢弃，但要注意，被丢弃的内容模型就"忘"了，所以编排层最好能主动管理哪些内容不要被冲掉。

7.4 工具返回内容太长导致输出崩坏

模型在工具调用后，编排层会把工具结果拼进 messages。如果工具返回了几千行日志，这堆内容会直接把上下文塞爆，模型生成质量断崖式下降。

解决方案是我在编排层里加了一个ToolResultTruncator：

TRUNCATE_LIMIT = 1200 def truncate_tool_result(result: str) -> str: if len(result) <= TRUNCATE_LIMIT: return result head = result[:800] tail = result[-200:] return head + "\n...[中间内容省略]...\n" + tail

核心思路是保留开头和结尾，因为日志类的关键信息通常出现在这些位置。

7.5 容器日志无限增长：磁盘被日志吃满

Docker 默认日志驱动是 json-file，如果不加限制，长时间运行后日志文件能膨胀到几十 GB。我踩过一次坑：内网机器磁盘满了，容器动不动就挂。

在docker-compose.yml里加上日志滚动配置：

logging: driver: json-file options: max-size: "20m" max-file: "5"

这样单容器日志最多占 100MB，对磁盘非常友好。

8. 这套方案的扩展方向与我的最终建议

如果你顺利跑通了以上内容，那么恭喜，你已经拥有了一套完全属于局域网内网的 AI Agent 平台。接下来可以考虑几个扩展方向：

• 接入更多工具：比如定时任务触发、数据库查询、内部 API 封装，让 Agent 真的变成"干活的人"；
• 换用更强模型：当显存充足时，把 GGUF 换成更高量化等级，或直接用 vLLM 部署更大参数模型；
• 加一层统一 API 网关：把模型推理、Agent 编排、知识库检索封装成一套标准接口，供内网其他系统调用；
• 做身份认证与审计：局域网不等于绝对安全，加一层简单的 token 认证和操作日志，能让平台更可靠。

最后说点我自己的体会。用 Docker 部署 DeepSeek Harness 这套方案，真正的价值不是省下了那点 API 费用，而是把 AI 能力变成了一种内网基础设施——它不依赖外部网络，不会因为服务商调整策略而失效，数据全程不出网，团队可以在上面随意折腾。刚开始搭的时候，我也走过不少弯路，尤其是模型文件和 GPU 环境这两块，浪费了不少时间。如果你照着这篇文章的路径走，应该能比我当时顺很多。

在我目前的实际使用中，这套平台承担了内部文档问答、运维信息查询、竞品信息整理等一批琐碎任务。虽然不是每次回答都完美，但相比"没有它"和"有它"，完全是两种工作效率。希望这篇记录能帮到你，让你的局域网也能拥有一台随叫随到的 AI Agent。