局域网自建AI Agent平台：Docker部署DeepSeek Harness实战

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

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

过去一年，我身边不少做企业内部工具的朋友都经历过同一个阶段：一开始大家都是直接调用公有云上的大模型 API，写几行代码就能跑通一个问答机器人，感觉特别爽。但真到了要往业务系统里嵌、要给十几个同事同时用、要处理内部文档的时候，问题就一个接一个冒出来了。最典型的三类：一是数据出域，公司内部的合同、代码、客户资料，哪怕只是片段，传到外部服务上总有人心里不踏实；二是网络抖动，公网延迟忽高忽低，做个演示还好，真当生产力工具用，响应慢半拍就很影响体验；三是成本不可控，用量一上来账单就不好看，尤其是做批量文档处理的时候。

所以“把模型部署到局域网内部”这件事，从去年下半年开始就成了很多团队的实际选择。而Docker 部署 DeepSeek Harness这个组合，恰好踩在了这个需求点上：DeepSeek 系列模型在中文理解和推理上的表现大家有目共睹，Harness 这类编排层负责把模型能力包装成可调用的 Agent 服务，Docker 则解决了环境一致性和快速分发的问题。三者叠在一起，就是一套“开箱即用、数据不出内网、多人可共享”的 AI Agent 平台。

这篇文章我想聊的不是“怎么点下一步”，而是把这套东西从选型到落地到踩坑的完整过程讲清楚。适合两类人看：一类是有一定 Linux 和容器基础、想给团队搭一套内部 AI 服务的开发者；另一类是已经用过云端 API、想搞清楚自建方案到底值不值得的决策者。我会尽量把每个关键选择背后的理由讲透，让你看完能自己判断、自己动手。

1.2 局域网自建方案到底解决了哪些真实痛点

先把这个方案能解决的问题列清楚，避免大家抱着不切实际的期待上手。

数据边界清晰。所有推理请求、上传的文档、生成的中间结果，全部在局域网内部流转，不经过任何外部网络。对于有合规要求或者单纯就是“不想让数据出去”的团队来说，这是最核心的价值。

多人共享一套算力。一台带显卡的机器部署好之后，局域网内的同事通过浏览器或者内部工具就能访问，不用每个人都在自己电脑上装一遍环境。算力集中管理，利用率也高。

响应稳定可预期。内网千兆甚至万兆环境，请求延迟基本就是模型推理时间本身，没有公网那层不确定性。做实时交互类应用时，这个差别非常明显。

成本一次性投入。硬件买回来之后，后续就是电费和维护，没有按 token 计费的焦虑。用量越大，摊薄下来越划算。

当然也有代价：你需要一台像样的机器（显卡是硬门槛），需要有人懂 Docker 和基本的运维，模型更新、服务监控这些也得自己管。所以这套方案不是“比云端 API 更好”，而是“在特定约束下更合适”。想清楚这一点，后面的技术选择就顺了。

2. 核心组件拆解：DeepSeek、Harness 与 Docker 各自扮演什么角色

2.1 DeepSeek 模型：能力底座与硬件门槛

DeepSeek 系列模型是这套平台的“大脑”。实际部署时，大家最关心的两个问题是：选哪个尺寸的模型，以及需要什么级别的显卡。

从我的实测经验看，模型尺寸和显存需求大致是这样的关系（以常见的量化部署为参考）：

这里要强调一个很多人会忽略的点：显存不是唯一瓶颈，显存带宽和推理框架的调度效率同样关键。我见过有人用显存刚好够的卡跑 32B 模型，结果速度慢到没法用，就是因为带宽跟不上。所以选硬件时，别只盯着显存数字，实际跑一下基准测试最靠谱。

另外，量化方式的选择也有讲究。4-bit 量化能把显存需求压下来一大截，但会带来一定的质量损失。对于内部工具类应用，这个损失通常可以接受；如果做的是对准确性要求极高的任务，那就得考虑 8-bit 甚至全精度，硬件预算要相应往上加。

2.2 Harness 编排层：把模型变成真正的 Agent

光有模型还不够，模型本身只是个“文本进、文本出”的黑盒。要让它变成能查资料、能调工具、能多轮对话的 Agent，中间需要一层编排逻辑，这就是 Harness 这类框架的价值所在。

它主要干三件事：

第一，请求路由与会话管理。多个用户同时发请求时，怎么排队、怎么分配显存、怎么维护每个人的对话上下文，这些都需要编排层来管。没有这层，模型服务很容易被并发请求打爆。

第二，工具调用与能力扩展。Agent 之所以是 Agent，是因为它能调用外部工具——查数据库、读文件、调内部接口。Harness 负责解析模型的输出，判断它想调用什么工具，执行完之后再把结果喂回给模型。这个循环是 Agent 的核心。

第三，提示词模板与输出解析。不同任务需要不同的提示词结构，输出也需要被解析成结构化数据才能被下游系统使用。把这些逻辑集中在编排层，业务代码就能保持干净。

我个人的体会是，Harness 这层的设计质量，直接决定了整套平台好不好用。模型选得再好，如果编排层写得乱七八糟，多轮对话丢上下文、工具调用经常失败，用户体验一样很差。所以部署时别只关注模型，编排层的配置和调试同样要花时间。

2.3 Docker：环境一致性与快速分发的关键

为什么用 Docker 而不是直接在宿主机上装环境？这个问题我被问过很多次，答案其实很实在。

依赖地狱是真实存在的。模型推理涉及 CUDA 驱动、推理框架、Python 版本、各种底层库，版本之间还有兼容性要求。在宿主机上直接装，装一次可能就要折腾半天，换台机器又得重来。Docker 把这些全部打包进镜像，换机器时拉下来就能跑。

隔离性让维护变简单。模型服务、编排层、可能还有前端界面，各自跑在独立容器里，一个出问题不影响另一个。升级某个组件时，只重建对应的容器就行，不用动整个系统。

分发和回滚都方便。镜像打好之后，推到内部镜像仓库，其他机器直接拉取。哪天新版本有问题，回滚到旧镜像也就是一条命令的事。

不过 Docker 也不是没有代价。GPU 透传到容器里需要额外配置，镜像体积可能很大，网络模式选不对还会导致容器间通信出问题。这些坑我在后面会具体讲怎么处理。

3. 部署前的准备工作：硬件、系统与网络规划

3.1 硬件选型：别等买错了才后悔

硬件这块，我的建议是“按最坏情况预估，按实际需求配置”。什么意思呢？就是先想清楚这套平台最终要服务多少人、跑什么任务，然后往上留 30% 左右的余量。

几个关键决策点：

显卡选消费级还是专业级。消费级卡性价比高，但显存通常有限，而且有些型号对多卡并行支持不好。专业级卡显存大、稳定性好，但价格贵不少。如果是小团队内部用，消费级卡往往够用；如果要长期稳定运行、服务人数多，专业级更省心。

内存和硬盘别抠。模型文件动辄几十 GB，加上系统、镜像、日志，硬盘至少要留出几百 GB 的空间。内存方面，除了显存，系统内存也要够，否则加载模型时容易卡住。我的经验是系统内存至少是显存的两倍比较稳妥。

网络带宽要匹配。局域网内多人同时访问，如果只是文本交互，千兆基本够用；如果涉及大文件上传或者多模态任务，万兆会更舒服。这个在规划阶段就要考虑，后期改起来麻烦。

3.2 系统环境：驱动、Docker 与 GPU 支持

系统层面，我推荐用主流的 Linux 发行版，社区资料多，遇到问题好查。安装顺序很重要，建议按这个流程走：

1. 先装显卡驱动。这一步最容易出问题，一定要装和显卡型号匹配的版本。装完之后用nvidia-smi验证，能看到显卡信息才算成功。
2. 再装 Docker。用官方脚本或者包管理器安装都行，装完确认docker version能正常输出。
3. 最后装 GPU 容器支持。这一步是让 Docker 容器能访问显卡的关键，需要安装对应的容器运行时工具，并在 Docker 配置里注册。

注意：驱动、Docker、GPU 支持这三者的版本是有兼容性要求的。我踩过的坑是驱动版本太新，结果容器运行时还不支持，折腾了半天。建议装之前先查一下官方文档里的兼容性矩阵。

验证 GPU 透传是否成功，可以跑一个测试容器：

docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

如果能在容器里看到显卡信息，说明配置没问题。这一步过了，后面就顺了。

3.3 网络规划：端口、访问控制与安全边界

局域网部署虽然不对外，但内部的安全和访问控制还是要做。

端口规划。模型服务、编排层、管理界面各用不同端口，提前规划好，避免冲突。建议把端口分配记在一个文档里，团队共享。

访问控制。至少要做一层简单的认证，别让局域网内任何人都能随便调用。可以用反向代理加基础认证，或者在应用层做 token 校验。

网络隔离。如果条件允许，把 AI 平台放在独立的网段，和办公网做一定隔离。这样即使平台出问题，也不会影响其他业务。

日志与审计。谁在什么时候调用了什么，这些记录要留。一方面是排查问题需要，另一方面也是内部管理的要求。

4. 实操部署全流程：从拉取镜像到服务可用

4.1 镜像准备与目录结构设计

部署的第一步是把镜像准备好。如果内部有镜像仓库，建议把常用镜像同步过去，避免每次都从外部拉取。目录结构我习惯这样组织：

/opt/ai-platform/ ├── models/ # 模型文件 ├── configs/ # 各服务的配置文件 ├── data/ # 持久化数据 ├── logs/ # 日志 └── docker-compose.yml

这样分的好处是，模型、配置、数据、日志各自独立，备份和迁移时很清楚该动哪些。模型文件通常很大，单独放一个目录，挂载到容器里就行，不用打进镜像。

4.2 模型服务的容器化配置

模型服务的容器配置，核心是三个部分：镜像选择、GPU 分配、模型挂载。

镜像方面，建议用推理框架官方提供的镜像，省去自己装依赖的麻烦。GPU 分配通过--gpus参数控制，可以指定用哪几张卡。模型挂载就是把宿主机的模型目录映射到容器内的指定路径。

一个典型的启动命令大概长这样：

docker run -d \ --name model-service \ --gpus '"device=0"' \ -v /opt/ai-platform/models:/models \ -p 8000:8000 \ --restart unless-stopped \ model-image:latest \ --model /models/deepseek-model \ --port 8000

几个参数说明一下：--restart unless-stopped保证容器异常退出后自动重启，生产环境必备；--gpus '"device=0"'指定用 0 号卡，多卡时可以调整；端口映射按实际规划来。

提示：模型加载比较慢，第一次启动可能要等几分钟。别看到容器起来了就以为服务好了，要等日志里出现“服务就绪”之类的提示再测试。

4.3 编排层与前端界面的联动配置

编排层要连模型服务，前端要连编排层，这个链路要配通。

编排层的配置里，模型服务的地址填容器名或者宿主机 IP 加端口。如果用 Docker Compose 编排，容器之间可以直接用服务名通信，不用管 IP。前端配置里填编排层的地址。

这里有个容易出问题的地方：容器间通信的网络模式。默认的 bridge 网络下，容器之间要通过 IP 通信；如果用自定义网络，可以用服务名。我建议用自定义网络，配置更清晰，也不受 IP 变化影响。

networks: ai-net: driver: bridge services: model-service: networks: - ai-net harness: networks: - ai-net

配好之后，harness 里访问模型服务直接用http://model-service:8000就行。

4.4 启动验证与基础功能测试

全部配好之后，按顺序启动：先起模型服务，等它就绪；再起编排层；最后起前端。然后做几项基础测试：

• 模型服务直连测试：用 curl 直接调模型接口，确认能返回结果。
• 编排层测试：通过编排层调模型，确认链路通。
• 前端测试：浏览器打开界面，发一条消息，看能否正常回复。
• 并发测试：模拟几个用户同时请求，看服务是否稳定。

这几步都过了，基础平台就算搭起来了。后面就是根据实际需求做调优和扩展。

5. 性能调优与常见问题排查

5.1 推理速度慢？先定位瓶颈在哪

推理慢是最常见的问题，但原因可能有很多。排查思路是按链路一段段看：

我的经验是，大部分“慢”的问题，要么是显存不够导致频繁换入换出，要么是并发配置不合理导致请求堆积。先把这两个排除掉，再看其他。

5.2 容器启动失败与 GPU 识别问题

容器起不来，八成是 GPU 相关配置有问题。常见的有：

• 驱动版本不匹配：宿主机驱动和容器内 CUDA 版本对不上。解决方法是统一版本，或者用兼容性更好的基础镜像。
• GPU 权限问题：容器里的用户没有访问显卡设备的权限。检查设备映射和用户组配置。
• 显存被占用：之前有残留进程没退干净。用nvidia-smi看有没有僵尸进程，清掉再启动。

注意：每次改完 GPU 相关配置，都要重新验证透传是否正常，别改完直接上生产。

5.3 多人访问时的并发与资源争抢

多人用的时候，资源争抢是必然的。几个实用的调优手段：

限制单次请求的最大长度。输入太长会占用大量显存，限制一下能显著提升并发能力。

设置请求队列和超时。编排层里配置队列长度和超时时间，避免请求无限堆积。

按优先级分配资源。如果有些任务更紧急，可以在编排层做优先级调度。

监控显存使用率。设置告警，显存接近上限时提前干预。

这些配置没有万能值，要根据实际使用情况慢慢调。我的建议是先保守一点，观察一段时间再逐步放开。

6. 落地后的运维与扩展思路

6.1 日常监控与日志管理

平台跑起来之后，监控是保证稳定的关键。至少要盯这几个指标：GPU 利用率、显存占用、请求延迟、错误率、容器状态。

日志方面，建议集中收集，别散落在各个容器里。可以用轻量的日志方案，把各容器的日志汇总到一个地方，方便排查。日志保留时间根据实际情况定，一般留一到两周够用。

6.2 模型更新与版本管理

模型更新是个需要谨慎对待的事。新版本可能效果更好，但也可能引入不兼容的变化。我的做法是：

1. 新模型先在测试环境验证，跑一批典型任务对比效果。
2. 确认没问题后，用新镜像起一个新容器，和旧容器并存。
3. 切换流量到新容器，观察一段时间。
4. 稳定后再下线旧容器。

这样即使新版本有问题，也能快速切回去。

6.3 从单机到多机的扩展路径

单机跑满之后，往多机扩展是自然的选择。扩展路径大致是：先做模型服务的多实例，前面加负载均衡；再把编排层也做成多实例；最后考虑模型分片，把大模型拆到多台机器上。

不过多机扩展会带来新的复杂度，网络通信、状态同步、故障处理都要重新考虑。我的建议是，单机能满足需求就别急着上多机，等真的遇到瓶颈再动。

7. 我踩过的坑和几条实在建议

最后分享几条从实际部署中总结出来的经验，都是文档里不太会写、但实际很影响体验的点。

第一条，别在部署当天才准备模型文件。模型下载动辄几十 GB，网络不好的时候能下一天。提前下好，放到规划好的目录里，部署时直接挂载，能省大量时间。

第二条，容器日志一定要配轮转。我见过因为日志文件把硬盘写满导致服务挂掉的案例。Docker 的日志驱动配置里加上大小和数量限制，几行配置的事，能避免大麻烦。

第三条，先跑通最小链路再堆功能。别一上来就把所有组件都配上，先让模型服务能返回结果，再加编排层，再加前端。每加一层验证一次，出问题好定位。

第四条，把配置都写进文件，别用命令行参数。命令行参数容易丢、不好版本管理，配置文件可以进 Git，改了什么一目了然。

第五条，留一台备用机器或者至少留出快速重建的能力。硬件故障是概率问题，真出事了能快速恢复比什么都重要。镜像、配置、模型文件都有备份，重建就是几十分钟的事。

这套平台我从最初搭起来到现在，前后调整了大概两三个月，中间经历了几次模型更换和配置优化。现在团队里十几个人日常在用，跑文档问答、代码辅助、内部知识检索这些任务，整体挺稳的。如果你也在考虑类似方案，希望这些经验能帮你少走点弯路。