Docker 局域网部署 DeepSeek AI Agent 平台实战-北京尧图网络

1. 为什么要在局域网里自己搭一套 AI Agent 平台很多人第一次接触 AI Agent都是直接用云端服务注册个账号、拿个 API Key 就能跑起来。方便是真方便但用久了总会碰到几个绕不过去的问题数据要往外传、网络延迟不稳定、调用次数一多成本就上来了而且一旦断网整个流程直接瘫痪。尤其是团队内部有一些敏感文档、内部知识库需要做检索增强的时候把资料往外部服务上传心里总是不踏实。我这次要聊的就是用 Docker 把 DeepSeek 相关的模型能力封装起来在局域网内部搭一套可以自己掌控的 AI Agent 平台。所谓 Harness在这里可以理解成一层“编排外壳”——它把模型推理、工具调用、对话管理、上下文记忆这些零散能力串成一个完整的 Agent 运行时。你不需要从零写调度逻辑只要把模型服务跑起来再通过 Harness 把工具和流程挂上去一个局域网内可访问的 Agent 平台就成型了。这套方案适合几类人一是手里有一台带独立显卡的机器、想物尽其用的开发者二是团队里需要内部 AI 助手、但又不方便走公网的中小团队三是想学习 Agent 架构、又不想被云服务黑盒挡住视线的技术爱好者。哪怕你之前只写过简单的脚本只要对 Docker 有基本概念跟着走一遍也能跑通。需要提前说清楚的是本文讲的“DeepSeek”指的是可本地部署的模型权重或推理服务Harness 则是你自己搭建的编排层。整套东西跑在局域网里不依赖任何外部网络数据不出内网这也是它最大的价值所在。2. 部署前的环境盘点与选型逻辑2.1 硬件与系统的最低门槛在动手之前先别急着敲命令把机器条件摸清楚能省掉后面一大堆返工。本地跑模型瓶颈几乎永远在显存上。以常见的 7B 到 14B 参数量级模型为例如果用 FP16 精度7B 大概需要 14GB 左右的显存14B 则要接近 28GB如果用量化版本比如 4-bit 量化7B 可以压到 5GB 上下14B 大概 9GB 到 10GB。这意味着一张 8GB 显存的消费级显卡跑 4-bit 量化的 7B 模型比较舒服12GB 到 16GB 显存可以尝试 14B 量化版如果只有 CPU也不是完全不能跑但推理速度会慢到影响 Agent 的交互体验只适合做功能验证。内存方面建议至少 32GB因为 Docker 容器、模型加载、向量库、Harness 服务会同时占用。硬盘留出 100GB 以上的空间比较稳妥模型文件本身就动辄十几 GB加上镜像和日志空间消耗比想象中快。操作系统上Linux 是首选Ubuntu 22.04 这类长期支持版本驱动生态最成熟。Windows 用户可以用 WSL2但要注意显卡直通和显存分配的配置坑会多一些。macOS 的话Apple Silicon 芯片可以用 Metal 加速但 Docker 对 GPU 的支持不如 Linux 直接需要额外折腾。2.2 容器化方案为什么比裸装更省心有人会问既然模型和 Harness 都是自己写的为什么不直接装在宿主机上非要套一层 Docker我踩过的坑告诉我裸装最大的问题是依赖冲突。模型推理框架对 CUDA 版本、Python 版本、各种底层库的版本极其敏感而 Harness 那边可能又依赖另一套 Web 框架和数据库驱动。两边的依赖一旦打架排查起来非常痛苦。Docker 把每个服务隔离开模型服务用一套镜像Harness 用另一套向量库再用官方镜像彼此互不干扰。升级某个组件时只需要重建对应的容器不会牵一发动全身。而且 Docker Compose 能把多个容器的网络、卷、启动顺序统一管理一条命令拉起整套平台这对局域网部署来说太重要了——毕竟你不是天天改配置稳定复现才是关键。还有一个容易被忽略的好处镜像可以导出成文件拷贝到完全离线的机器上导入。对于真正隔离的局域网环境这个能力几乎是刚需。2.3 网络与端口规划局域网部署端口规划要提前想好不然容器之间、宿主机和容器之间的通信很容易乱。我的习惯是给每个服务分配固定端口并且只在宿主机上暴露必要的那个。比如模型推理服务监听 8000Harness 后端监听 8080前端监听 3000向量库监听 6333。容器内部用服务名互相访问宿主机只对外暴露 Harness 的入口端口。这里有个细节Docker 默认的 bridge 网络里容器之间可以通过服务名解析但如果你用了自定义网络记得把相关容器都加进同一个网络。另外局域网内其他机器要访问宿主机的防火墙得放行对应端口这一步经常被忘记导致“本机好好的同事就是连不上”。提示端口冲突是部署初期最常见的问题。动手前先用ss -tlnp看一眼宿主机已经占用了哪些端口避开常见服务比如 80、443、3306、6379能减少很多麻烦。3. 用 Docker Compose 编排整套 Agent 平台3.1 目录结构与配置文件组织我习惯把整个项目放在一个统一目录下结构清晰备份和迁移都方便。大致长这样ai-agent-platform/ ├── docker-compose.yml ├── .env ├── model/ │ └── (模型权重文件) ├── harness/ │ ├── Dockerfile │ ├── requirements.txt │ └── app/ ├── vector-db/ │ └── data/ └── logs/.env文件放环境变量比如模型路径、端口号、数据库密码这样docker-compose.yml里就不用写死换环境时只改一个文件。模型权重单独放一个目录通过 volume 挂载进容器避免每次重建镜像都重新拷贝几十 GB 的文件。3.2 模型推理服务的容器定义模型服务是整个平台的地基它负责把权重加载进显存对外提供统一的推理接口。下面是一个基于常见推理框架的 Compose 片段思路services: model-server: image: your-inference-image:latest container_name: model-server runtime: nvidia environment: - NVIDIA_VISIBLE_DEVICES0 - MODEL_PATH/models/deepseek volumes: - ./model:/models ports: - 8000:8000 deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] restart: unless-stopped这里几个点值得展开。runtime: nvidia和deploy.resources是让容器能用上 GPU 的关键前提是宿主机装好了 NVIDIA 驱动和对应的容器工具包。NVIDIA_VISIBLE_DEVICES0指定用哪张卡多卡机器上这个变量很重要。restart: unless-stopped保证机器重启后服务自动拉起局域网平台讲究的就是“开机即用”。模型加载慢是正常的十几 GB 的权重读进显存可能要一两分钟所以健康检查的start_period要给足别让编排器误判成启动失败。3.3 Harness 编排层的镜像构建Harness 这一层是我们自己写的负责接收用户请求、调用模型、管理对话历史、调度工具。它的 Dockerfile 大致是这样FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY app/ ./app/ EXPOSE 8080 CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8080]用 slim 基础镜像能显著减小体积--no-cache-dir避免 pip 缓存撑大镜像。把requirements.txt单独 COPY 再安装是为了利用 Docker 的层缓存——只要依赖没变重建时这一步直接命中缓存速度快很多。这是构建镜像时一个很实用的小技巧。Harness 里最关键的是它怎么和模型服务通信。因为都在同一个 Docker 网络里直接用服务名http://model-server:8000就能访问不需要走宿主机的 IP。这一点比裸装方案优雅太多服务迁移时完全不用改地址。3.4 向量库与持久化存储Agent 要做知识检索向量库少不了。用官方镜像起一个数据目录挂载到宿主机保证容器删了数据还在vector-db: image: qdrant/qdrant:latest container_name: vector-db volumes: - ./vector-db/data:/qdrant/storage ports: - 6333:6333 restart: unless-stopped持久化这件事我吃过亏。早期图省事没挂载数据卷结果一次docker compose down把索引全清了重建知识库花了大半天。从那以后凡是带状态的容器一律挂载宿主机目录这是铁律。3.5 一键拉起与启动顺序控制把上面几个服务写进同一个docker-compose.yml用depends_on控制启动顺序让 Harness 等模型服务和向量库就绪后再启动harness: build: ./harness container_name: harness depends_on: - model-server - vector-db environment: - MODEL_ENDPOINThttp://model-server:8000 - VECTOR_DB_URLhttp://vector-db:6333 ports: - 8080:8080 restart: unless-stopped然后docker compose up -d一条命令整套平台就起来了。第一次启动会慢一些因为要拉镜像、加载模型之后重启就快多了。注意depends_on只保证容器启动顺序不保证服务真正就绪。如果 Harness 启动时模型还没加载完请求会失败。稳妥的做法是在 Harness 里加一段重试逻辑或者用健康检查配合condition: service_healthy。4. 让 Agent 真正能干活的几个关键配置4.1 对话上下文与记忆管理一个只会单轮问答的模型算不上 Agent。真正的 Agent 要记住上下文甚至跨会话保留关键信息。Harness 里我一般做两层记忆短期记忆放在内存里维护最近若干轮对话长期记忆写进向量库把重要事实和用户偏好存起来下次对话时检索出来拼进提示词。短期记忆的窗口大小要权衡。窗口太大显存和延迟都吃不消窗口太小模型容易“失忆”。我的经验是保留最近 10 到 20 轮超出部分做摘要压缩把摘要作为系统提示的一部分带进去。这样既控制了 token 消耗又不至于丢掉关键信息。长期记忆的写入要有选择性不是什么话都存。我通常只在检测到明确的事实陈述或用户偏好时才写入避免向量库被垃圾信息淹没导致检索质量下降。4.2 工具调用的注册与调度Agent 的价值很大程度体现在它能调用外部工具。Harness 里需要维护一个工具注册表每个工具声明名称、描述、参数结构模型根据用户意图决定调哪个。常见的工具有查数据库、读文件、发请求、做计算。工具描述写得越清楚模型选得越准。我见过很多人工具描述就写一句“查询数据”结果模型经常调错。正确的做法是把参数含义、适用场景、返回格式都写明白相当于给模型一份使用说明书。参数校验也不能省模型偶尔会传出格式不对的参数Harness 要在调用前拦一道返回明确的错误信息让模型自我纠正。4.3 局域网访问与多用户隔离平台跑起来后局域网里其他机器通过http://宿主机IP:8080就能访问。如果要做多用户Harness 里得加上会话隔离每个用户有独立的对话历史和记忆空间不能串。简单做法是用会话 ID 区分复杂一点可以接入内部的身份认证。多用户并发时要注意模型服务的承载能力。单张显卡同时处理多个请求会排队延迟上升。如果团队人多可以考虑给模型服务加一层请求队列或者部署多个模型实例做负载均衡。这一步在初期用户少的时候可以先不做但架构上要留出扩展空间。5. 实测中踩过的坑与排查思路5.1 容器起不来从日志倒推根因部署阶段最常见的现象就是某个容器反复重启。这时候别慌第一步永远是看日志docker compose logs -f model-server日志会告诉你真相。我遇到过几次典型情况一是显存不足日志里会明确报 out of memory解决办法是换更小的量化模型或减少并发二是模型路径挂载错了容器里找不到权重文件三是 CUDA 版本和驱动不匹配报错信息里通常带版本号对照着升级或降级即可。排查顺序建议是先看容器状态docker compose ps再看日志最后进容器里手动执行命令验证。进容器用docker exec -it model-server bash在里面直接跑推理脚本能快速定位是环境问题还是代码问题。5.2 局域网连不上网络链路的逐段验证“本机能访问同事连不上”这个问题排查要分段。先在宿主机上curl http://localhost:8080确认服务本身正常再用宿主机的局域网 IPcurl http://192.168.x.x:8080确认端口监听在正确的网卡上最后让同事那边 ping 一下宿主机确认网络可达。常见原因有三个防火墙没放行端口、Docker 端口映射写成了127.0.0.1:8080:8080这样只监听本地、宿主机有多张网卡绑错了。把映射改成8080:8080就能监听所有网卡防火墙用ufw allow 8080放行即可。5.3 推理速度慢定位瓶颈在哪一环Agent 响应慢可能是模型推理慢也可能是 Harness 处理慢还可能是向量检索慢。定位方法是给每个环节打时间戳。我一般在 Harness 里记录请求进入、模型调用开始、模型返回、工具调用、最终返回这几个时间点一看日志就知道卡在哪。如果瓶颈在模型推理可以考虑用量化、减少上下文长度、开启批处理。如果瓶颈在向量检索检查索引是否建好、检索的 top-k 是不是设得太大。如果瓶颈在 Harness 本身多半是同步阻塞的代码拖慢了整体改成异步会好很多。5.4 数据持久化别让一次重启清空所有积累前面提过向量库挂载的事这里再强调一次。除了向量库Harness 如果用了本地数据库存对话历史同样要挂载。判断一个容器要不要挂载数据卷就看它有没有“状态”——只要重启后需要保留的数据统统挂出去。备份也简单把挂载的宿主机目录打包就行。我习惯定期把vector-db/data和 Harness 的数据目录压缩存一份万一哪天误操作恢复起来几分钟的事。6. 性能调优与长期维护的实战心得6.1 显存不够时的量化与切分策略显存是本地部署最紧的资源。当模型跑不动时第一选择是量化。4-bit 量化通常能把显存需求降到原来的三分之一左右精度损失在多数 Agent 场景下可以接受。如果量化后还是不够可以考虑模型切分把不同层放到不同设备上但这会引入通信开销速度会下降。另一个思路是控制并发。单请求时显存占用是固定的但并发请求会成倍增加 KV Cache 的占用。把并发数限制在显存能承受的范围内比盲目追求高并发更实际。我一般会压测一下找到延迟和吞吐的平衡点然后把这个并发数写进配置。6.2 镜像体积与启动速度的优化镜像越大拉取和分发越慢离线环境拷贝也越费劲。优化手段有几个用多阶段构建把编译依赖留在构建阶段运行阶段只保留必要文件合并 RUN 指令减少层数清理 pip 缓存和临时文件。这些做下来镜像体积能砍掉一半以上。启动速度方面模型加载是主要耗时。如果推理框架支持可以把模型转成更适合快速加载的格式或者用内存映射的方式加载。另外把不常变的服务和常变的服务分开构建避免每次改 Harness 代码都重建模型镜像。6.3 日志、监控与故障自愈局域网平台虽然用户不多但稳定性一样重要。我给每个容器配了日志轮转避免日志文件把磁盘写满。监控方面简单的做法是定期检查容器健康状态异常时发个通知。Docker 自带的 healthcheck 配合 restart 策略能覆盖大部分“进程挂了自动拉起”的场景。对于模型服务这种启动慢的健康检查的间隔和超时要放宽否则会被误杀重启陷入循环。我一般把interval设成 30 秒start_period给到 120 秒给足加载时间。6.4 版本升级与回滚的稳妥做法升级模型或 Harness 时别直接覆盖生产环境。我的做法是保留旧镜像新版本先用不同容器名和端口起一套验证没问题再切换。Compose 文件里用变量控制镜像 tag回滚时改回旧 tag 重新拉起即可。模型权重升级尤其要谨慎新模型可能对提示词格式、工具调用协议有细微变化直接替换可能导致 Agent 行为异常。先在测试环境跑一轮典型对话确认输出正常再上线这一步花的时间绝对值得。7. 从单机 Demo 到团队平台的扩展方向7.1 多模型路由与能力分级当平台用户变多单一模型可能满足不了所有需求。有的任务需要强推理有的只需要快速响应。可以在 Harness 里做一层模型路由根据请求类型分发给不同的模型实例。轻量任务走小模型复杂任务走大模型既省资源又提体验。路由策略可以基于规则也可以让一个轻量模型先做意图分类再转发。规则简单直接分类灵活但多一次调用开销。初期用规则就够了等请求量上来再考虑更智能的方案。7.2 知识库的持续更新机制Agent 的知识库不是建一次就完事。内部文档在更新知识库也得跟着更新。我一般做一个定时任务定期扫描指定目录把新增或修改的文档重新切分、向量化、写入向量库。增量更新比全量重建快得多也不会影响正在进行的对话。文档切分策略直接影响检索质量。切得太碎语义不完整切得太粗检索不精准。我的经验是按语义段落切每段控制在几百字重叠一小部分保证上下文连贯。这个参数需要根据实际文档类型调没有万能值。7.3 权限控制与审计日志团队使用就绕不开权限。谁能访问哪些知识库、谁能调用哪些工具Harness 里要有对应的控制。简单做法是按用户角色分配权限请求进来先鉴权再处理。审计日志记录谁在什么时候调用了什么出了问题能追溯。这些功能在单机 Demo 阶段可以先不做但架构上要预留接口。等真正多人使用时再补比一开始就设计复杂权限体系更务实。8. 写在最后的一点个人体会这套局域网 AI Agent 平台我从最初跑通到稳定使用前后折腾了不少时间最大的感受是容器化带来的可复现性远比省下的那点性能开销值钱。裸装方案可能启动快那么几秒但一旦环境出问题排查成本高得离谱。Docker 把环境固化下来换台机器导入镜像就能跑这种确定性对长期维护太重要了。另一个体会是别一上来就追求大模型、高并发。先用小模型把整条链路跑通确认 Harness、向量库、工具调用都正常再逐步换大模型、加功能。很多问题在链路没通的时候是看不出来的过早优化只会让排查更复杂。最后分享一个小技巧把常用的排查命令写成脚本比如一键看所有容器状态、一键导出日志、一键备份数据。部署稳定后日常维护其实就靠这几个脚本省心省力。平台这东西跑起来只是开始能长期稳定地跑下去才是真正有价值的地方。

Docker 局域网部署 DeepSeek AI Agent 平台实战

相关推荐

华为设备实战：命令行视图、Trunk配置与Python自动化指南

上下文管理实战：从滑动窗口到结构化记忆的对话系统设计

优惠券、满减、折扣叠加规则详解：计算顺序与分摊逻辑

更多资讯

artcraft：用工程化流程实现可复现的艺术创作

概率方向论文投稿PEIS期刊全流程实战经验分享

数据埋点如何发现用户非预期路径？从行为序列到产品优化实战

AI辅助开题报告写作：8类工具拆解与选择指南

基于RapidOCR的Python OCR源码：识别并返回HTML结构

AI内容合规挑战：安全过滤与不当请求处理

今日更新

Susi AI API实战指南：susi_alexa_skill如何用Node.js调用chat.json获取智能回答

换新电脑了？KeyStats 恢复码数据找回完全指南，端到端加密统计一键重建

重建二叉树：由前序与中序遍历序列还原二叉树的原理与 Java 实现（YCBlogs 剑指 Offer 精讲）

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？