1. 为什么要在局域网里自建 AI Agent 平台1.1 从“调用云端 API”到“把模型搬回自己机房”的转变过去一年我身边不少做企业内部工具的朋友都经历过同一个阶段一开始图省事直接调用公有云上的大模型接口写几行代码就能跑通对话。但真到了要落地到业务场景里问题就一个接一个冒出来。最典型的是数据合规——公司内部的合同、工单、客户资料谁也不敢随手往外部接口上丢。其次是成本调用量一上来账单涨得比预期快得多。再就是网络稳定性一旦外网抖动整个 Agent 服务就跟着卡壳。于是“把模型部署到局域网内部”这件事从可选项变成了刚需。所谓局域网里的 AI Agent 平台说白了就是在自己可控的网络环境里跑一个能理解自然语言、能调用工具、能完成多步任务的智能体服务外部访问不出去内部数据也不出去。DeepSeek 系列模型因为开源权重、推理质量不错、对硬件相对友好成了很多团队的首选底座。而 Docker 部署的价值在于它把“装环境、配依赖、调版本”这些最容易翻车的环节全部封装起来让一个原本要折腾一两天的部署流程压缩到半小时以内。这篇文章面向的是有一定 Linux 基础、想在自己内网搭一套 AI Agent 平台的开发者或运维同学。哪怕你之前只写过业务代码、没怎么碰过模型部署跟着思路走也能落地。我会把整体设计思路、Docker 编排细节、模型加载参数、Agent 工具链配置、以及我踩过的坑全部摊开讲清楚。1.2 局域网部署到底解决了哪些真实痛点先把这个平台能干什么说清楚不然容易变成为了部署而部署。一套跑在局域网里的 AI Agent 平台通常承担三类任务。第一类是内部知识问答。把公司的产品文档、运维手册、历史工单灌进向量库员工用自然语言提问Agent 检索后给出带出处的回答。因为全程在内网敏感信息不出门。第二类是工具调用型自动化。比如让 Agent 根据一句“帮我查一下昨天那批订单的异常情况”自动去调用内部的订单查询接口、日志检索接口把结果汇总成一段人话。这类场景对模型的函数调用能力要求高DeepSeek 在这块表现比较稳。第三类是多步任务编排。复杂一点的需求比如“生成本周运维周报”Agent 需要先拉监控数据、再查告警记录、然后调用模板生成文档。这背后是一套 Agent 框架在调度模型只是其中一环。理解了这三类任务你就明白为什么部署方案不能只是“跑个模型”那么简单。它需要模型推理服务、Agent 调度框架、向量数据库、工具接口层这几块协同工作而 Docker 恰好是把这些组件编排到一起的最佳粘合剂。2. 整体架构设计与组件选型思路2.1 一套典型的局域网 AI Agent 平台长什么样在动手之前先把架构在脑子里过一遍比直接抄命令强得多。我这套方案的组件划分是这样的模型推理层负责加载 DeepSeek 权重对外暴露一个兼容 OpenAI 协议的 HTTP 接口。这样上层 Agent 框架不用改代码就能对接。Agent 调度层负责接收用户请求、管理对话上下文、决定是否调用工具、编排多步流程。向量检索层存放知识库的向量化数据供 Agent 做 RAG 检索。工具接口层把内部系统的 API 包装成 Agent 能识别的工具描述。网关与前端对内提供统一的访问入口和简单的对话界面。这五层里前三层基本都能用现成的开源组件通过 Docker 跑起来第四层需要你自己写适配代码第五层看需求简单的话一个反向代理加个静态页面就够了。2.2 为什么选 Docker 而不是裸机部署我试过两种方式一种是在物理机上直接装 Python 环境、编译推理框架另一种是全部容器化。裸机部署的坑在于依赖冲突——推理框架对 CUDA 版本、Python 版本、各种底层库的版本极其敏感你为了跑模型 A 装的一套依赖很可能把之前跑得好好的服务 B 搞崩。而且一旦要迁移到另一台机器环境复现又是一场噩梦。Docker 方案的核心优势有三个。一是环境隔离每个组件跑在自己的容器里依赖互不干扰。二是版本锁定镜像一旦构建好换台机器拉下来跑起来的行为完全一致。三是编排方便用一份 compose 文件就能把五六个服务的关系、网络、数据卷全部定义清楚启动一条命令搞定。当然 Docker 也不是没有代价。GPU 透传需要额外配置容器内的显存管理和裸机略有差异镜像体积动辄几个 G拉取需要时间。但综合下来对于“要稳定、要可复现、要能交付给同事”的场景Docker 是更省心的选择。2.3 硬件与显存预算的粗略估算选型绕不开硬件。DeepSeek 有不同参数规模的版本显存需求差别很大。下面这张表是我实测和根据经验整理的参考值实际会因量化方式、上下文长度、并发数而浮动。模型规模精度大致显存需求适用场景7B 级别FP1616GB 左右单人或小团队问答7B 级别4bit 量化6GB 左右消费级显卡可跑14B 级别FP1628GB 以上中等并发内部服务32B 级别4bit 量化24GB 左右质量与成本平衡70B 级别4bit 量化48GB 以上高质量要求场景提示显存估算要把 KV Cache 算进去。上下文长度开到 8K 和开到 32K显存占用能差出一大截。规划时按峰值并发和最大上下文来留余量别卡着线配。如果手头只有一张消费级显卡我建议从 7B 的 4bit 量化版本起步先把整条链路跑通再根据实际效果决定要不要升级。别一上来就追求大模型链路没通之前模型再大也体现不出价值。3. Docker 环境准备与基础配置3.1 宿主机环境检查清单在装 Docker 之前先把宿主机的基础条件确认一遍能省掉后面很多莫名其妙的报错。操作系统主流 Linux 发行版都行内核版本建议 5.10 以上太老的内核对容器网络和 GPU 支持不友好。显卡驱动如果要用 GPU先确认驱动装好nvidia-smi能正常输出。驱动版本要和后面容器里的 CUDA 版本匹配。磁盘空间模型权重加上镜像轻松吃掉几十 G。给 Docker 数据目录留至少 100G 空间放在 SSD 上加载速度差别很明显。内存除了显存系统内存也要够。向量库、Agent 框架、模型加载的中间态都吃内存建议 32G 起步。网络内网部署要确认各服务之间能互通端口别和现有服务冲突。我遇到过最典型的问题是磁盘空间不足导致镜像拉取到一半失败报错信息还特别隐晦。所以动手前先df -h看一眼心里有数。3.2 Docker 与容器运行时的安装要点安装 Docker 本身不复杂但有几个细节值得注意。第一安装完记得把当前用户加入 docker 组否则每条命令都要 sudo很烦。第二如果要用 GPU需要额外安装对应的容器运行时工具包让容器能访问显卡设备。第三配置好镜像加速源内网环境如果没法访问外部仓库需要提前把镜像导出成 tar 包再导入。# 安装完成后验证 docker --version docker compose version # 验证 GPU 是否能在容器里访问 docker run --rm --gpus all 基础镜像 nvidia-smi最后这条命令很关键。如果容器里跑nvidia-smi报错说明 GPU 透传没配好后面模型加载必然失败。先把这个验证通过再往下走。3.3 目录结构规划别把数据卷搞乱容器化部署有个原则容器随时可以删数据不能丢。所以要把需要持久化的东西全部挂到宿主机目录上。我习惯用这样一套目录结构/opt/ai-platform/ ├── models/ # 模型权重文件 ├── data/ │ ├── vector-db/ # 向量库数据 │ └── agent/ # Agent 配置与日志 ├── config/ # 各服务的配置文件 ├── compose/ # docker-compose 文件 └── logs/ # 统一日志目录这样规划的好处是备份的时候直接打包整个目录迁移的时候拷过去就能用。模型权重单独放因为体积大迁移时可以按需处理。配置文件集中管理改参数不用进容器。注意模型权重目录的权限要设对。容器内进程的用户 ID 和宿主机可能不一致权限没配好会出现“文件存在但读不了”的情况报错还很难定位。4. 模型推理服务的容器化部署4.1 推理框架选型够用就好跑 DeepSeek 权重的推理框架有好几个选择各有取舍。我对比过几种常见方案结论是没有最好的只有最适合你当前硬件和需求的。框架类型优势劣势适合谁通用推理框架生态成熟、文档全对特定模型优化一般求稳、多模型混跑高吞吐框架并发性能强配置复杂、显存占用高多人并发场景轻量框架部署简单、资源占用低功能相对少单机小规模我的建议是先用通用框架把链路跑通等发现并发扛不住了再换高吞吐方案。过早优化是部署阶段最大的时间黑洞。4.2 模型权重的获取与存放权重文件通常从模型托管平台下载。内网环境如果没法直连需要在外网机器上下好再通过内网传输工具搬进去。下载时注意几点确认下载的是完整权重而不是分片缺失的版本核对文件校验值避免传输损坏权重目录结构要符合推理框架的预期有些框架要求特定的文件夹命名。权重放好后先别急着起容器用推理框架的命令行工具在宿主机上做一次加载测试。这一步能提前暴露显存不足、文件损坏、版本不匹配等问题比在容器里排查方便得多。4.3 编写推理服务的 compose 配置下面是一份推理服务的 compose 配置骨架我做了简化重点看结构。services: inference: image: 推理框架镜像 container_name: ai-inference runtime: nvidia environment: - NVIDIA_VISIBLE_DEVICESall - MODEL_PATH/models/deepseek - MAX_MODEL_LEN8192 - GPU_MEMORY_UTILIZATION0.9 volumes: - /opt/ai-platform/models:/models:ro ports: - 8000:8000 deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] restart: unless-stopped几个参数值得展开说。MAX_MODEL_LEN控制最大上下文长度开得越大显存占用越高要结合业务需求权衡。GPU_MEMORY_UTILIZATION控制显存使用比例设成 0.9 是给系统留点余量设成 1.0 容易在峰值时 OOM。volumes里模型目录挂成只读防止容器内进程误改权重文件。4.4 启动验证与接口连通性测试容器起来后先看日志确认模型加载成功。加载过程可能要几分钟日志里会显示进度。加载完成后用 curl 测一下接口。curl http://localhost:8000/v1/models如果返回模型列表说明推理服务正常。再发一条对话请求验证生成能力curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: deepseek, messages: [{role: user, content: 你好}] }能正常返回内容推理层就算通了。这一步是整个平台的地基地基不稳后面全是坑。5. Agent 调度层与工具链配置5.1 Agent 框架的核心职责推理服务只是“会说话的大脑”Agent 框架才是“会干活的手脚”。它的核心职责包括管理多轮对话的上下文、根据用户意图决定是否调用工具、解析工具返回结果并继续推理、维护任务状态。选框架时重点看它对函数调用的支持程度、上下文管理策略、以及扩展工具的难易度。我倾向选那种配置驱动、代码侵入少的框架。因为 Agent 的逻辑经常要调整如果每次改流程都要动源码维护成本太高。配置化的框架改个 YAML 就能调整行为交付给同事也容易。5.2 把内部接口包装成 Agent 工具这是整个平台最需要动手写代码的部分。Agent 要调用内部系统你得把每个接口包装成它认识的工具描述。一个工具描述通常包含工具名称、功能说明、参数定义、调用方式。tools [ { name: query_order, description: 根据订单号查询订单状态和详情, parameters: { type: object, properties: { order_id: { type: string, description: 订单编号 } }, required: [order_id] } } ]写工具描述有几个经验。说明要写清楚边界比如“只支持查询最近 90 天的订单”否则模型会乱调。参数描述要具体别只写“订单号”要写“订单编号格式为纯数字”。工具数量别太多一次给模型几十个工具它选择时会犯迷糊按场景分组加载效果更好。5.3 向量库接入与知识库构建RAG 检索是内部问答的核心。流程是文档切块、向量化、存入向量库、检索时按相似度召回。向量库同样用 Docker 跑数据卷挂到宿主机。文档切块这一步很讲究。切得太碎语义不完整切得太大检索精度下降。我的经验是按段落切每块控制在几百字块之间留一点重叠避免关键信息被切断。向量化用的模型可以和推理模型分开选个轻量的嵌入模型就行没必要用大模型做嵌入。知识库构建是个持续过程。文档更新了要重新向量化所以最好写个脚本把整个流程自动化别手动操作。5.4 对话上下文与多步任务的状态管理多步任务是 Agent 最容易出问题的地方。模型在第一步调用了工具拿到结果后要能正确地把结果带入第二步的推理。这中间涉及上下文拼接、状态存储、超时处理。我的做法是给每个会话分配一个独立的上下文空间工具调用的中间结果按顺序追加。同时设置最大步数限制防止模型陷入死循环反复调用同一个工具。超时也要处理某个工具调用卡住了不能让整个会话一直挂着。提示多步任务的调试很痛苦建议把每一步的输入输出都打到日志里出问题时能完整回放整个推理链路。这个日志在排查“模型为什么调错工具”时特别有用。6. 网络、安全与访问控制6.1 局域网内的服务发现与端口规划所有服务跑在同一个 Docker 网络里容器之间用服务名互相访问不用记 IP。对外暴露的端口要规划好避免和现有服务冲突。我的习惯是给这套平台分配一个连续的端口段比如 8000 到 8010方便记忆和管理。networks: ai-net: driver: bridge容器加入同一个网络后Agent 框架访问推理服务直接用http://inference:8000就行不用管宿主机 IP 怎么变。6.2 访问鉴权与内网隔离策略虽然是内网但鉴权不能省。至少要做两层一层是网关层的访问控制限制哪些网段能访问另一层是应用层的 API Key防止内网里的其他服务随意调用。推理服务的接口最好只对 Agent 框架开放不直接暴露给终端用户。用户请求统一走网关由网关做鉴权和限流。这样即使某个环节出问题影响范围也可控。6.3 日志审计与数据留存内网平台也要留日志。谁在什么时候问了什么、Agent 调用了哪些工具、返回了什么结果这些记录在排查问题和合规审计时都用得上。日志统一收集到一个目录按日期切分定期归档。数据留存策略要提前定。对话记录存多久、向量库数据怎么备份、模型权重更新后旧版本留不留这些都要有明确规则别等到磁盘满了才想起来清理。7. 常见问题与排查技巧实录7.1 模型加载失败的几类典型原因模型加载失败是最常见的拦路虎原因基本集中在几类。显存不足日志里会明确报 OOM解决办法是降低上下文长度、换量化版本、或者减少并发。权重文件损坏通常是下载中断导致重新下载并校验。版本不匹配推理框架版本和模型格式对不上看框架文档确认支持的模型版本。权限问题容器内用户读不了权重文件检查目录权限和挂载配置。排查顺序建议从显存开始因为这是最高频的原因。用nvidia-smi看加载时的显存变化能快速定位。7.2 容器间网络不通的排查路径Agent 框架连不上推理服务先确认两个容器在不在同一个网络里。docker network inspect能看到网络里的容器列表。如果不在检查 compose 文件里的网络配置。如果在同一网络还连不上进容器里用curl测一下目标服务名能不能解析。DNS 解析失败通常是网络配置问题端口不通则可能是服务没起来或者监听地址不对。7.3 Agent 调用工具出错的调试方法Agent 调错工具或者参数传错是调试中最费时的。我的排查套路是先看工具描述写得够不够清楚大部分问题出在这里再看模型返回的函数调用格式对不对格式错了框架解析不了最后看工具本身的实现有没有 bug。把这三步的日志都打全问题基本能定位。下面这张表是我整理的常见问题速查遇到时对照着看能省不少时间。现象可能原因排查方向模型加载 OOM显存不足降上下文、换量化接口 404路径写错核对 API 路径容器间不通网络隔离检查网络配置工具调用失败描述不清优化工具说明响应超时并发过高限流或扩容检索不准切块不当调整切块策略7.4 性能调优的几个实操方向平台跑起来之后性能调优是持续的事。几个见效比较快的方向批处理把多个请求合并推理能提升吞吐KV Cache 复用相同前缀的请求可以复用缓存量化在质量可接受的前提下用低精度换速度并发控制别让请求无限堆积超过处理能力就排队或拒绝。调优要基于数据别凭感觉。先压测拿到基线再针对性优化每次只改一个变量看效果。8. 我踩过的坑和几条实在建议部署这套平台的过程中有几个坑让我印象特别深。第一个是镜像体积一开始没注意拉了个包含完整 CUDA 工具链的镜像好几个 G内网传输慢得要命。后来换成精简基础镜像体积小了一半多。第二个是模型加载时间大模型从磁盘加载到显存要几分钟如果容器配置了自动重启频繁重启会导致反复加载反而更慢。第三个是日志膨胀Agent 的调试日志开得太详细几天就把磁盘写满了后来加了日志轮转才解决。给准备动手的同学几条建议。先把最小链路跑通别一上来就追求完整功能推理服务能对话了再加 AgentAgent 能用了再加知识库。配置全部外置别把参数写死在镜像里改个参数要重新构建镜像太痛苦。做好备份模型权重、向量库数据、配置文件定期备份出问题时能快速恢复。留好回滚方案新版本镜像先在小范围验证确认没问题再全量替换。这套平台搭好之后后续扩展空间很大。可以接入更多工具、可以换更大的模型、可以做多 Agent 协作。但基础架构稳定是第一位的地基打牢了上面盖什么都踏实。