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 级别 | FP16 | 16GB 左右 | 单人或小团队问答 |
| 7B 级别 | 4bit 量化 | 6GB 左右 | 消费级显卡可跑 |
| 14B 级别 | FP16 | 28GB 以上 | 中等并发内部服务 |
| 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_DEVICES=all - MODEL_PATH=/models/deepseek - MAX_MODEL_LEN=8192 - GPU_MEMORY_UTILIZATION=0.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 的调试日志开得太详细，几天就把磁盘写满了，后来加了日志轮转才解决。
给准备动手的同学几条建议。先把最小链路跑通，别一上来就追求完整功能，推理服务能对话了再加 Agent，Agent 能用了再加知识库。配置全部外置，别把参数写死在镜像里，改个参数要重新构建镜像太痛苦。做好备份，模型权重、向量库数据、配置文件，定期备份，出问题时能快速恢复。留好回滚方案，新版本镜像先在小范围验证，确认没问题再全量替换。
这套平台搭好之后，后续扩展空间很大。可以接入更多工具、可以换更大的模型、可以做多 Agent 协作。但基础架构稳定是第一位的，地基打牢了，上面盖什么都踏实。
