1. 为什么要在局域网里自建 AI Agent 平台1.1 从“调用云端 API”到“把模型搬进机房”的转变过去一年我身边不少做企业内部工具的朋友都经历了同一个心路历程一开始图省事直接调云端大模型的 API几行代码就能跑通一个问答机器人演示效果也漂亮。但真到了要往业务里塞的时候问题就一个接一个冒出来——数据要出内网合规部门第一个不答应调用量一上来账单涨得比预期快得多网络一抖动整个 Agent 链路就卡住更别提有些场景要求响应稳定在几百毫秒内公网往返根本兜不住。于是“把模型部署到自己的局域网里”这件事就从“极客玩具”变成了“正经需求”。而 Docker 部署 DeepSeek Harness 这套组合恰好踩在了这个需求点上DeepSeek 系列模型在中文理解和推理上的表现这两年大家有目共睹开源权重也让自部署成为可能Harness 则是一个把模型、工具调用、会话管理、Agent 编排打包在一起的运行框架Docker 负责把这些东西装进一个可复制、可迁移的容器里。三者叠加你得到的就是一个跑在局域网内、数据不出门、可被多个内部系统复用的 AI Agent 平台。这篇文章面向的读者很明确有一定 Linux 和 Docker 基础想在内网搭一套 AI Agent 服务但又不希望从零造轮子的开发者或运维同学。哪怕你之前只跑过docker run hello-world跟着思路走也能搭起来如果你已经玩过 Ollama、vLLM 这类推理服务那这篇更像是帮你把“单点模型服务”升级成“完整 Agent 平台”的落地笔记。1.2 局域网自建到底解决了哪些真实痛点我把实际项目里遇到的痛点归了归类大概是这样几类数据主权问题内部文档、客户资料、代码片段这些东西一旦离开内网合规上就很难交代。自建之后所有推理都在自己的机器上完成数据流向完全可控。成本可预期云端按 token 计费用量波动大时预算很难做。自建是一次性硬件投入加电费边际成本几乎为零用得越多越划算。响应稳定性内网千兆甚至万兆环境模型推理的瓶颈在 GPU 而不在网络延迟稳定可控适合做实时交互类 Agent。可定制性系统提示词、工具集、会话策略、日志留存全部自己说了算不用受制于第三方平台的接口限制。多系统复用一个内网 Agent 平台搭好之后OA、工单系统、内部知识库、运维助手都能接进来避免每个业务线各搭一套。提示自建不等于“零成本”。GPU 采购、机房散热、运维人力都是实打实的投入。建议先想清楚并发量和模型规模再决定硬件配置别一上来就堆顶配。2. 方案选型为什么是 Docker DeepSeek Harness 这套组合2.1 三个组件各自的角色定位很多人第一次听到这套组合会有点懵DeepSeek 是模型Docker 是容器那 Harness 到底是干嘛的我用一个类比来解释如果把 AI Agent 平台比作一家餐厅DeepSeek 是后厨的厨师负责“思考”和“生成”Docker 是整栋可移动的店面把厨房、仓库、前台打包在一起而 Harness 就是那个跑前跑后的店长——它负责接单、调度厨师、管理食材、记录账目、协调服务员。具体来说Harness 承担了这些职责模型接入层统一封装对 DeepSeek 推理服务的调用屏蔽底层是本地推理还是远程接口的差异。Agent 编排层管理多轮对话、工具调用function calling、任务分解与执行链路。会话与状态管理维护每个用户的上下文处理超长对话的截断与摘要。工具注册机制把内部 API、数据库查询、文件检索等能力注册成 Agent 可调用的工具。日志与可观测性记录每次调用的输入输出、耗时、token 消耗方便排查和优化。2.2 为什么不用“裸跑模型 自己写胶水代码”我早期试过一种更“原始”的方案直接用推理框架起一个模型服务然后自己写 Python 脚本处理对话逻辑。跑通 demo 没问题但一旦要支持多用户、多工具、上下文管理代码量就失控了。具体踩过的坑包括会话状态存在内存里服务一重启全丢工具调用的参数校验、异常处理、重试逻辑每个工具都要写一遍并发上来之后请求排队和超时处理全靠自己造日志散落在各处出问题根本不知道是哪一步挂了。Harness 这类框架的价值就在于它把这些“脏活累活”标准化了。你只需要关注两件事模型怎么接、工具怎么注册。剩下的编排、状态、日志框架帮你兜底。2.3 Docker 化带来的可迁移性用 Docker 部署最大的好处不是“看起来高级”而是环境一致性。我在一台机器上调试好的镜像推到内网镜像仓库其他机器docker pull下来就能跑不用担心 CUDA 版本、Python 依赖、系统库这些经典问题。这里有个关键决策点GPU 支持怎么处理。如果你的推理服务要用 GPU容器需要能访问宿主机的显卡。常见做法是安装对应的容器运行时工具然后在启动时声明 GPU 资源。这一步配置对了后面就一劳永逸配置错了容器里nvidia-smi会直接报错模型加载也会失败。方案优点缺点适用场景裸机直接部署性能损耗最小环境难复制迁移痛苦单机长期固定使用Docker 容器化环境一致易迁移需要配置 GPU 透传多机部署、需要快速复制虚拟机 容器隔离性最强资源开销大GPU 透传复杂强隔离要求的场景综合下来对于“局域网内多系统复用”这个目标Docker 容器化是性价比最高的选择。3. 环境准备与核心配置实操3.1 硬件与系统的基础门槛在动手之前先把硬件账算清楚。DeepSeek 系列模型有不同的参数规模对显存的要求差异很大。以常见的量化版本为例粗略的显存占用估算如下7B 级别模型4-bit 量化后大约需要 6-8GB 显存14B 级别4-bit 量化后大约需要 12-16GB32B 级别4-bit 量化后大约需要 24-32GB更大的模型基本要上多卡或者专业级显卡。注意显存估算不是线性的还要留出 KV Cache 的空间。上下文越长、并发越高KV Cache 占用越大。建议在估算值基础上再留 20%-30% 的余量。系统层面我推荐用较新的 Linux 发行版内核版本不要太老否则容器运行时和显卡驱动容易出兼容问题。磁盘方面模型文件动辄几十 GB加上镜像和日志建议至少预留 200GB 的 SSD 空间机械盘加载模型会慢到让你怀疑人生。3.2 容器运行环境的关键配置容器运行环境的安装网上教程很多这里只强调几个容易出错的点第一驱动版本要和容器运行时匹配。驱动太新、运行时太旧或者反过来都会导致 GPU 无法在容器内识别。装完之后一定要用官方提供的检测命令验证一下确认容器里能看到显卡。第二镜像仓库的镜像源要配好。内网环境如果拉不动公共镜像需要提前配置内部镜像仓库或者离线导入镜像包。这一步在离线机房尤其重要别等到部署当天才发现拉不下来。第三存储卷的规划。模型文件、配置文件、日志目录建议都挂载到宿主机上而不是放在容器内部。这样容器重建时数据不会丢也方便直接在宿主机上查看日志。# 验证容器内 GPU 是否可见示例命令具体以实际运行时为准 docker run --rm --gpus all 基础镜像 nvidia-smi如果这条命令能正常输出显卡信息说明 GPU 透传配置成功如果报错先检查运行时安装和驱动版本别急着往下走。3.3 目录结构与配置文件的组织我习惯在宿主机上建一个统一的工作目录结构大概是这样ai-agent-platform/ ├── models/ # 存放模型权重文件 ├── config/ # Harness 及推理服务的配置文件 ├── data/ # 会话数据、向量库等持久化数据 ├── logs/ # 运行日志 └── docker-compose.yml这种组织方式的好处是所有需要持久化的东西都在宿主机上容器只是“计算单元”。哪天要升级镜像直接换镜像重启数据原封不动。配置文件方面Harness 通常需要一个主配置文件来定义模型接入地址、工具列表、会话策略等。我建议把敏感配置比如内部 API 的密钥通过环境变量注入而不是硬编码在配置文件里。这样配置文件可以进版本管理密钥单独管理安全性和可维护性都更好。4. 部署流程与核心环节实现4.1 推理服务的启动与验证整个平台的第一块拼图是推理服务。DeepSeek 模型需要一个推理引擎来加载和对外提供接口。常见的做法是用支持该模型架构的推理框架把模型权重加载起来暴露一个兼容标准接口的服务。启动推理服务时几个关键参数需要重点关注模型路径指向宿主机上挂载进来的模型目录上下文长度决定了单次对话能处理多长的文本设太大吃显存设太小长文档处理不了并发数同时能处理多少个请求和显存、吞吐直接相关量化方式影响精度和显存占用需要在效果和资源之间权衡。启动之后先用一个简单的请求验证服务是否正常# 验证推理服务是否响应示例 curl http://localhost:端口/v1/models能返回模型列表说明推理服务已经就绪。这一步没通过后面 Harness 接进来也是白搭所以务必先单独验证。4.2 Harness 的接入与工具注册推理服务跑通之后接下来是让 Harness 接进来。核心工作是在 Harness 的配置里声明模型接入点把刚才验证过的推理服务地址填进去。这里有个细节如果 Harness 和推理服务在同一个 Docker 网络里地址可以用容器名如果跨容器或跨主机就要用实际的 IP 和端口。工具注册是 Harness 最有价值的部分。所谓“工具”就是 Agent 可以调用的外部能力。比如查询内部知识库的检索接口读取工单系统的 API执行数据库查询的函数调用内部计算服务的接口。每个工具需要定义名称、描述、参数结构。描述写得越清楚模型越容易在合适的时机调用它。我踩过的坑是工具描述写得太简略模型要么不调用要么乱调用。后来把描述改成“什么场景下用、参数分别代表什么、返回什么”调用准确率明显提升。# 工具注册配置示例结构示意 tools: - name: query_knowledge_base description: 当用户询问内部文档、制度、流程相关问题时使用此工具 parameters: query: type: string description: 用户的查询关键词4.3 用编排文件一键拉起整个平台当推理服务和 Harness 都验证通过后就可以用编排文件把它们组织在一起实现一键启动。编排文件里要定义好服务之间的依赖关系、网络、存储卷、环境变量。# docker-compose.yml 结构示意 services: inference: image: 推理服务镜像 volumes: - ./models:/models deploy: resources: reservations: devices: - capabilities: [gpu] harness: image: Harness镜像 depends_on: - inference ports: - 8080:8080 volumes: - ./config:/app/config - ./data:/app/data - ./logs:/app/logs启动顺序很重要推理服务要先起来并加载完模型Harness 才能正常连接。编排文件里的依赖声明能保证启动顺序但模型加载需要时间Harness 启动时如果连不上要有重试机制。我在实际项目里就遇到过 Harness 比推理服务先就绪导致第一次请求失败的情况后来加了健康检查和重试才稳定。4.4 局域网访问与多系统对接平台跑起来之后最后一步是让局域网内的其他系统能访问。这里涉及几个层面端口暴露Harness 的服务端口要映射到宿主机局域网内其他机器才能访问访问控制内网也不是完全可信的建议加一层简单的鉴权比如 API Key反向代理如果需要 HTTPS 或者统一入口可以在前面挂一个反向代理文档与 SDK给接入方提供清晰的接口文档和调用示例降低对接成本。我一般会先用curl从另一台机器测一下连通性确认网络没问题再让业务方接入。这样出问题时能快速定位是网络问题还是应用问题。5. 常见问题与排查技巧实录5.1 部署阶段的高频故障部署阶段的问题八成集中在 GPU、网络、存储这三块。我整理了一个速查表现象可能原因排查方向容器内看不到显卡运行时未安装或驱动不匹配检查运行时配置和驱动版本模型加载失败权重文件不完整或路径错误核对挂载路径和文件校验值拉取镜像超时镜像源不可达配置内部镜像仓库或离线导入端口无法访问防火墙或端口未映射检查映射配置和防火墙规则显存不足模型太大或上下文过长降低量化精度或缩短上下文提示遇到问题先看日志别凭感觉猜。推理服务的日志会明确告诉你模型加载到哪一步失败Harness 的日志会告诉你请求卡在哪个环节。5.2 运行阶段的性能与稳定性问题平台跑起来之后新的问题会浮现出来。最常见的是响应变慢。原因可能有很多并发请求太多导致排队、上下文太长导致 KV Cache 膨胀、工具调用超时拖慢整体链路。我的排查顺序是先看推理服务的队列长度和 GPU 利用率判断是不是算力瓶颈再看 Harness 的日志看是不是某个工具调用卡住了最后看网络确认容器间通信没有异常。另一个常见问题是会话状态丢失。如果 Harness 的状态存在容器内存里容器一重启就全没了。解决办法是把状态持久化到外部存储比如数据库或者挂载的卷。这个坑我在早期项目里踩过用户反馈“聊到一半机器人失忆了”查了半天才发现是容器被自动重启了。5.3 几个我踩过的坑和独家经验第一个坑模型文件权限。容器内运行的用户和宿主机上的文件属主不一致导致模型加载时读不到文件。解决办法是提前把模型目录的权限设好或者在编排文件里指定运行用户。第二个坑日志把磁盘写满。推理服务和 Harness 的日志量都不小尤其是开了详细日志之后。一定要配置日志轮转否则跑几天磁盘就满了服务直接挂掉。第三个坑上下文长度设太大。一开始想着“越大越好”结果显存被 KV Cache 吃光并发一上来就 OOM。后来根据实际业务场景把上下文控制在合理范围稳定性和并发能力都上来了。第四个经验先小后大。别一上来就部署最大的模型先用小模型把整条链路跑通验证 Docker 配置、Harness 接入、工具调用都没问题再换大模型。这样出问题时容易定位不会一上来就被一堆变量搞晕。6. 平台扩展与长期维护的一些思路6.1 从单模型到多模型路由平台稳定运行之后很自然会想到扩展能不能同时接多个模型根据任务类型路由比如简单问答用小模型复杂推理用大模型。Harness 的模型接入层如果设计得当加一个路由策略就能实现。这样既省资源又能保证复杂任务的效果。6.2 监控与容量规划长期维护离不开监控。我建议至少监控这几个指标GPU 利用率、显存占用、请求队列长度、平均响应时间、错误率。这些数据积累一段时间后就能看出容量瓶颈在哪什么时候该加卡、什么时候该优化模型。6.3 版本升级与回滚策略模型和框架都会有版本更新。升级前一定要在测试环境验证确认新版本和现有工具、配置兼容。镜像要打标签保留旧版本出问题能快速回滚。我见过太多“升级完发现不兼容又回不去”的惨案提前做好版本管理能省很多事。这套平台我自己维护了大半年从最初单机跑一个模型到现在支撑内部好几个系统的 Agent 调用中间踩的坑基本都写在上面的排查表里了。如果你也在规划类似的内网 AI 平台建议先把推理服务和 Harness 分开验证再合到一起编排这样每一步都可控。硬件上别贪大先跑通再扩容比一上来堆配置然后卡在某个环节要舒服得多。