局域网自建AI Agent平台：Docker部署DeepSeek模型与推理服务实战-平芜编程栈

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

1.1 从“调用云端 API”到“把模型搬进机房”的转变

过去一年，我身边不少做后端和运维的朋友都在干同一件事：把大模型能力接进自己的内部系统。最开始大家的做法很统一——调云端 API，写个封装层，前端一调就完事。但真到了生产环境，问题一个接一个冒出来：内网服务访问外网要走出口，延迟忽高忽低；业务数据要出内网，合规那边过不去；按 token 计费，量一上来账单看得人心惊肉跳。于是“把模型部署到局域网内部”这件事，从可选项变成了必选项。

DeepSeek 系列模型这两年在开源社区热度很高，推理能力扎实、显存占用相对友好，配合量化版本，单张消费级显卡甚至纯 CPU 都能跑起来。但光有模型还不够，我们要的是一个能对外提供稳定接口、能挂工具、能做多轮对话的AI Agent 平台，而不是一个只能跑generate的脚本。这就是标题里 “Harness” 这个词的价值所在——它是一层“挽具”，把裸模型套上，让它能被人和系统真正用起来。

1.2 局域网部署到底解决了哪些真实痛点

我把这套方案落地到几个内部项目之后，总结出局域网自建 Agent 平台的几个核心收益，这也是我为什么推荐你用 Docker 来做这件事的原因：

数据不出内网：所有对话、文档、工具调用记录都在自己的机器上，敏感信息不经过任何第三方。
延迟可控：内网千兆甚至万兆环境，首 token 延迟基本稳定在几百毫秒级别，比走公网 API 稳定得多。
成本一次性：硬件买断之后，跑多少 token 都是电费，业务量越大越划算。
可定制：系统提示词、工具集、知识库、权限控制，全部自己说了算，想怎么改就怎么改。
离线可用：断网环境照样跑，这对很多工业、科研场景是刚需。

而 Docker 的价值在于，它把“装环境”这件最折磨人的事标准化了。CUDA 版本、Python 依赖、模型路径、端口映射，全部写进compose.yaml，换台机器docker compose up -d就能复现。我踩过最深的坑就是早期手动装环境，换一台服务器就要重来一遍，自从全面转向容器化，部署时间从半天压缩到十几分钟。

1.3 这篇文章适合谁看

如果你符合下面任意一条，这篇内容应该能帮到你：

手里有一台带显卡的服务器或工作站，想把它变成团队内部的 AI 服务节点；
正在做企业内部知识库、智能客服、代码助手这类项目，需要私有化推理能力；
对 Docker 有一定了解，但没试过把大模型和 Agent 框架一起容器化；
想搞清楚“模型服务”和“Agent 编排”这两层到底怎么分工、怎么对接。

我会从整体架构讲起，然后一步步拆解 Docker 镜像怎么选、模型怎么挂载、Agent 层怎么配、端口和网络怎么规划，最后把我实际踩过的坑整理成排查表。全程给的是可以直接抄的配置，不是泛泛而谈的概念。

2. 整体架构设计与方案选型思路

2.1 三层结构：模型层、服务层、Agent 层

一套能用的局域网 AI Agent 平台，我习惯把它拆成三层来看，这样出问题的时候能快速定位是哪一层挂了：

层级	职责	典型组件	部署形态
模型层	加载权重、执行推理	推理引擎 + 量化模型文件	容器内进程
服务层	暴露 HTTP 接口、管理并发	兼容 OpenAI 协议的推理服务	独立容器
Agent 层	编排对话、挂载工具、管理会话	Agent 框架 + 工具集	独立容器

这么分层的好处是解耦。模型层换一个量化版本，服务层不用动；Agent 层想加个新工具，也不用重启推理服务。我见过有人把三层塞进一个容器，结果改一行提示词就要重新加载几十 GB 的模型，那体验简直灾难。

2.2 为什么推理引擎优先选兼容 OpenAI 协议的那一类

现在主流的推理引擎基本都支持 OpenAI 兼容接口，这不是巧合，而是生态选择的结果。原因很实在：

客户端零改造：市面上绝大多数 Agent 框架、前端对话界面、SDK 都是按 OpenAI 协议写的，你只要把base_url指到内网地址，其余代码一行不用改。
工具链成熟：流式输出、函数调用、多轮上下文，这些协议里都有约定，省得自己造轮子。
便于横向替换：今天用 A 引擎，明天想换 B 引擎，只要协议一致，Agent 层完全无感。

我在选型时的判断标准很简单：优先选社区活跃、文档齐全、对量化模型支持好的引擎。至于具体是哪一个，不同硬件适配情况不一样，你可以根据自己显卡的架构去挑，思路是通用的。

2.3 Docker 化部署的取舍：镜像体积 vs 启动速度

容器化大模型服务有个绕不开的矛盾：镜像做大了，拉取和分发慢；做小了，运行时又要临时下载依赖，启动更慢。我的经验是分两种策略：

开发调试阶段：用官方基础镜像，模型文件通过 volume 挂载，镜像保持精简，改配置不用重建镜像。
生产交付阶段：把模型文件打进镜像或者做成独立的数据卷镜像，配合内网镜像仓库，一次分发到处运行。

注意：模型权重动辄几个 GB 到几十 GB，千万不要用COPY直接打进普通镜像层，否则每次改代码都会产生一个巨大的新层，镜像仓库很快就被撑爆。正确做法是用 volume 挂载，或者用多阶段构建把权重放到独立的数据层。

2.4 网络规划：端口、网段与访问控制

局域网部署最容易忽视的就是网络规划。我建议在动手之前先把这几件事定下来：

服务端口：推理服务默认端口、Agent 服务端口、前端端口，三个分开，别挤在一起。
绑定地址：容器内服务监听0.0.0.0，宿主机映射时按需绑定到具体网卡，不要无脑暴露到所有网段。
访问控制：如果内网也不是完全可信，建议在 Agent 层前面加一层反向代理做鉴权和限流。
DNS 或 hosts：给服务起个好记的内网域名，比记 IP 加端口舒服得多。

我一般会预留一个172.20.0.0/16这样的自定义 bridge 网段给这套服务专用，避免和公司现有网段冲突。这个细节看着小，但真出冲突的时候排查起来很头疼。

3. 核心细节解析与实操要点

3.1 硬件与驱动的前置检查清单

在写任何 Docker 配置之前，先把宿主机的地基打好。这一步偷懒，后面全是坑。我整理了一份必查清单：

显卡驱动版本：用nvidia-smi确认驱动正常，记下 CUDA 版本上限。
容器运行时：确认已安装支持 GPU 的容器工具包，docker info里能看到对应的 runtime。
显存容量：根据模型参数量和量化等级估算，留出至少 20% 余量给上下文缓存。
磁盘空间：模型文件 + 镜像 + 日志，建议单独挂一块盘，别和系统盘混用。
内存与交换分区：纯 CPU 推理时内存要够，交换分区别设太小，否则容易 OOM。

显存估算有个粗略公式，我平时这么算：显存占用 ≈ 参数量 × 量化字节数 × 1.2 + 上下文缓存。比如一个 7B 模型用 4bit 量化，权重约 3.5GB，加上 KV 缓存和运行时开销，8GB 显存基本能跑，但上下文开太大就会爆。这个公式不精确，但用来做初步判断足够了。

3.2 模型文件的选择与目录组织

模型文件从哪来、放哪里，直接决定了后续维护的难易度。我的做法是建立一个统一的模型仓库目录，按“模型名/版本/量化等级”三级组织：

/models └── deepseek-series ├── v1 │ ├── fp16 │ └── q4 └── v2 ├── fp16 └── q8

这样组织的好处是，切换模型版本只需要改一个挂载路径，回滚也方便。选量化等级的时候要权衡：q4 省显存但精度有损，q8 精度好但占用翻倍，fp16 是原汁原味但最吃资源。我的建议是先用 q4 跑通流程，确认业务效果可接受再考虑升级。

提示：下载模型文件时注意校验文件完整性，我遇到过下载中断导致权重损坏的情况，加载时报的错五花八门，排查了半天才发现是文件本身的问题。养成校验哈希值的习惯。

3.3 推理服务容器的关键配置项

推理服务容器的配置，核心就几个参数，但每个都影响体验：

并发数：设太大显存扛不住，设太小请求排队。一般从 1 开始，压测后逐步调。
上下文长度：直接决定 KV 缓存大小，是显存杀手。按业务实际需要设，别盲目拉满。
批处理大小：影响吞吐，但会增加首 token 延迟，交互式场景要谨慎。
量化后端：不同引擎支持的后端不一样，选和你的硬件最匹配的那个。

下面是一个我常用的服务容器配置骨架，你可以按自己的引擎替换镜像名和启动参数：

services: inference: image: your-inference-engine:latest runtime: nvidia environment: - NVIDIA_VISIBLE_DEVICES=0 volumes: - /models/deepseek-series/v1/q4:/models:ro command: > --model /models --host 0.0.0.0 --port 8000 --max-model-len 8192 --gpu-memory-utilization 0.85 ports: - "127.0.0.1:8000:8000" restart: unless-stopped

注意ports这里我绑定的是127.0.0.1，意思是只有宿主机本地能访问，外部要通过 Agent 层或反向代理进来。这样做的目的是收敛暴露面，别让推理服务裸奔在内网上。

3.4 Agent 层容器的编排要点

Agent 层是整个平台的“大脑”，它负责接收用户请求、拼装提示词、调用工具、维护会话状态，最后把推理请求转发给服务层。这一层的配置重点在于：

环境变量注入：把推理服务的地址、API key（内网可以随便设一个占位）、默认模型名通过环境变量传进去。
工具配置：如果 Agent 要调用外部工具（比如查数据库、读文件），这些工具的连接信息也要配好。
持久化：会话历史、向量库、日志，都要挂 volume，容器删了数据不能丢。
健康检查：配一个healthcheck，让编排工具能感知服务是否真的可用。

agent: image: your-agent-framework:latest environment: - OPENAI_BASE_URL=http://inference:8000/v1 - OPENAI_API_KEY=internal-placeholder - DEFAULT_MODEL=deepseek-series volumes: - ./agent-data:/app/data - ./agent-logs:/app/logs ports: - "0.0.0.0:3000:3000" depends_on: - inference restart: unless-stopped

这里OPENAI_BASE_URL指向的是容器名inference，因为两个容器在同一个自定义网络里，Docker 内置 DNS 会帮你解析。这就是为什么我强烈建议用 compose 而不是docker run一堆命令——网络和依赖关系它都帮你管了。

3.5 数据持久化与备份策略

模型平台的数据分三类，备份策略各不相同：

模型文件：体积大但基本不变，做一次全量备份即可，或者干脆保留原始下载源。
会话与向量数据：变化频繁，建议每日增量备份，保留最近 7 天。
配置与提示词：体积小但最关键，建议纳入版本控制，每次改动都有记录。

我吃过一次亏：某次升级 Agent 框架，容器重建时把没挂载出来的会话数据全清了，用户历史对话一夜回到解放前。从那以后，凡是带状态的服务，我一定先确认 volume 挂载正确再动手。

4. 完整实操流程与关键环节实现

4.1 环境准备：从裸机到可运行 Docker

假设你拿到一台干净的 Linux 服务器，带一张显卡。第一步是把基础环境搭起来。我按顺序列一下：

更新系统包，安装基础工具（curl、git、vim 之类）。
安装显卡驱动，重启后用nvidia-smi验证。
安装 Docker 引擎和 compose 插件。
安装 GPU 容器工具包，配置容器运行时。
验证：跑一个测试容器，确认能访问到显卡。

验证这一步很关键，我通常用一条命令快速确认：

docker run --rm --runtime=nvidia your-base-image nvidia-smi

如果这条命令能打印出显卡信息，说明容器访问 GPU 的通路是通的。如果报错，八成是运行时没配好，回去检查容器工具包的安装步骤。

4.2 目录结构与 compose 文件编写

我习惯给每个服务建一个独立目录，结构清晰，迁移方便：

ai-agent-platform/ ├── compose.yaml ├── .env ├── models/ # 模型文件挂载点 ├── agent-data/ # Agent 持久化数据 ├── agent-logs/ # 日志 └── nginx/ # 反向代理配置（可选）

.env文件用来放环境相关的变量，比如端口号、模型路径、显存比例，这样 compose 文件本身可以保持通用，换环境只改.env：

INFERENCE_PORT=8000 AGENT_PORT=3000 MODEL_PATH=/models/deepseek-series/v1/q4 GPU_UTIL=0.85

compose 文件里用${变量名}引用，这样一套配置能在开发机和生产机上复用，只改.env就行。

4.3 启动顺序与依赖管理

这套平台有启动顺序要求：推理服务必须先起来，Agent 层才能正常工作。compose 的depends_on能保证启动顺序，但它不保证“服务真的就绪”。所以更稳妥的做法是给推理服务配健康检查，Agent 层等健康检查通过再启动：

inference: healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/health"] interval: 30s timeout: 10s retries: 5 start_period: 120s

start_period这个参数很重要，因为大模型加载慢，给它留足初始化时间，否则健康检查会一直失败导致容器被反复重启。我一般按模型大小给 60 到 180 秒不等。

4.4 首次启动与验证流程

一切就绪后，启动命令很简单：

docker compose up -d docker compose logs -f inference

盯着日志看模型加载进度，加载完成后会打印监听地址。然后验证推理服务：

curl http://localhost:8000/v1/models

能返回模型列表就说明服务层通了。接着验证 Agent 层：

curl http://localhost:3000/health

最后做一次端到端对话测试，确认从 Agent 到推理服务的链路完整。我一般会准备几个测试用例：简单问答、多轮对话、工具调用，分别验证不同能力。

4.5 性能调优：让首 token 延迟降下来

平台跑通之后，下一步就是调优。首 token 延迟是交互体验的关键指标，我实测下来影响它的因素按重要性排序：

因素	影响程度	调整方向
上下文长度	高	按需设置，别拉满
批处理策略	高	交互场景用连续批处理
量化等级	中	精度和速度的权衡
显存利用率	中	留足余量避免换页
网络传输	低	内网基本可忽略

我的调优顺序是：先把上下文长度压到业务最小值，再调批处理策略，最后才考虑量化等级。因为前两个改动成本低、见效快，量化等级一改往往要重新验证业务效果。

5. 常见问题与排查技巧实录

5.1 容器启动失败类问题速查

这类问题最常见，我把遇到过的整理成表：

现象	可能原因	排查方向
容器秒退	启动命令参数错误	看`docker logs`首屏报错
报显存不足	模型太大或上下文过长	降量化等级或减上下文
找不到模型文件	volume 路径写错	进容器`ls`确认挂载
端口被占用	宿主机端口冲突	换端口或查占用进程
权限拒绝	文件属主不对	检查挂载目录权限

排查这类问题的第一原则永远是：先看日志。docker compose logs 服务名能解决 80% 的问题，剩下 20% 再进容器里手动验证。

5.2 推理速度慢的定位思路

速度慢分两种情况：首 token 慢，还是后续 token 慢。这两个的病因完全不同。

首 token 慢，通常是提示词太长或者批处理策略不适合交互场景。我遇到过系统提示词写了三千多字，每次请求都要重新处理，首 token 自然慢。解决办法是精简提示词，或者用提示词缓存功能。

后续 token 慢，多半是显存不够导致换页，或者 CPU 推理时算力瓶颈。这时候要看nvidia-smi的显存占用和 GPU 利用率，如果利用率上不去，说明是内存带宽或调度问题。

5.3 Agent 层调用失败的排查路径

Agent 层报错，先分清是它自己的问题还是下游推理服务的问题。我的排查路径是：

直接 curl 推理服务，确认服务层正常。
检查 Agent 容器的环境变量，确认base_url指向正确。
看 Agent 日志里的具体报错，是超时、连接拒绝还是协议不匹配。
确认两个容器在同一网络里，能互相 ping 通。

我踩过最隐蔽的一个坑是：Agent 容器和推理容器不在同一个 compose 网络里，容器名解析不了，报的是“连接超时”，看起来像服务挂了，其实是网络隔离。后来统一用一个 compose 文件管理，问题再没出现过。

5.4 我踩过的三个真实坑与避坑建议

第一个坑：模型文件权限。容器内进程的用户 ID 和宿主机文件属主不一致，导致读不了模型。解决办法是在 compose 里指定user，或者把模型文件权限放开到可读。

第二个坑：日志把磁盘写满。推理服务默认日志级别很啰嗦，跑几天就把盘写满了。建议配置日志轮转，或者把日志级别调到 warning。

第三个坑：升级镜像后配置不兼容。有次升级 Agent 框架，新版本改了环境变量名，旧配置直接失效。教训是升级前先看 changelog，并且保留旧镜像方便回滚。

提示：生产环境一定要给镜像打明确的版本标签，别用latest。latest看着方便，出事的时候你都不知道自己跑的是哪个版本。

5.5 安全加固的几个实用动作

局域网不等于绝对安全，该做的加固还是要做：

接口鉴权：Agent 层前面加一层鉴权，哪怕是简单的 token 校验。
限流：防止某个客户端把推理资源占满，影响其他人。
日志脱敏：对话内容可能含敏感信息，日志里要注意脱敏。
最小暴露：推理服务只绑定本地，外部一律走 Agent 层。
定期更新：基础镜像和依赖库的安全更新要及时跟进。

这套平台我在几个内部项目里跑了小半年，稳定性总体不错，最大的体会是：容器化不是目的，可复现、可维护才是。把配置写进代码、把数据挂载出来、把版本固定住，这三件事做到位，后面基本不用怎么操心。至于模型选型和参数调优，那是随着业务需求不断迭代的事，先把平台搭稳，剩下的慢慢磨。

局域网自建AI Agent平台：Docker部署DeepSeek模型与推理服务实战