1. 为什么要在局域网里自建 AI Agent 平台1.1 从“调用云端 API”到“把模型搬进机房”的转变过去一年我身边不少做后端和运维的朋友都在干同一件事把大模型能力接进自己的内部系统。最开始大家的做法很统一——调云端 API写个封装层前端一调就完事。但真到了生产环境问题一个接一个冒出来内网服务访问外网要走出口延迟忽高忽低业务数据要出内网合规那边过不去按 token 计费量一上来账单看得人心惊肉跳。于是“把模型部署到局域网内部”这件事从可选项变成了必选项。DeepSeek 系列模型这两年在开源社区热度很高推理能力扎实、显存占用相对友好配合量化版本单张消费级显卡甚至纯 CPU 都能跑起来。但光有模型还不够我们要的是一个能对外提供稳定接口、能挂工具、能做多轮对话的AI Agent 平台而不是一个只能跑generate的脚本。这就是标题里 “Harness” 这个词的价值所在——它是一层“挽具”把裸模型套上让它能被人和系统真正用起来。1.2 局域网部署到底解决了哪些真实痛点我把这套方案落地到几个内部项目之后总结出局域网自建 Agent 平台的几个核心收益这也是我为什么推荐你用 Docker 来做这件事的原因数据不出内网所有对话、文档、工具调用记录都在自己的机器上敏感信息不经过任何第三方。延迟可控内网千兆甚至万兆环境首 token 延迟基本稳定在几百毫秒级别比走公网 API 稳定得多。成本一次性硬件买断之后跑多少 token 都是电费业务量越大越划算。可定制系统提示词、工具集、知识库、权限控制全部自己说了算想怎么改就怎么改。离线可用断网环境照样跑这对很多工业、科研场景是刚需。而 Docker 的价值在于它把“装环境”这件最折磨人的事标准化了。CUDA 版本、Python 依赖、模型路径、端口映射全部写进compose.yaml换台机器docker compose up -d就能复现。我踩过最深的坑就是早期手动装环境换一台服务器就要重来一遍自从全面转向容器化部署时间从半天压缩到十几分钟。1.3 这篇文章适合谁看如果你符合下面任意一条这篇内容应该能帮到你手里有一台带显卡的服务器或工作站想把它变成团队内部的 AI 服务节点正在做企业内部知识库、智能客服、代码助手这类项目需要私有化推理能力对 Docker 有一定了解但没试过把大模型和 Agent 框架一起容器化想搞清楚“模型服务”和“Agent 编排”这两层到底怎么分工、怎么对接。我会从整体架构讲起然后一步步拆解 Docker 镜像怎么选、模型怎么挂载、Agent 层怎么配、端口和网络怎么规划最后把我实际踩过的坑整理成排查表。全程给的是可以直接抄的配置不是泛泛而谈的概念。2. 整体架构设计与方案选型思路2.1 三层结构模型层、服务层、Agent 层一套能用的局域网 AI Agent 平台我习惯把它拆成三层来看这样出问题的时候能快速定位是哪一层挂了层级职责典型组件部署形态模型层加载权重、执行推理推理引擎 量化模型文件容器内进程服务层暴露 HTTP 接口、管理并发兼容 OpenAI 协议的推理服务独立容器Agent 层编排对话、挂载工具、管理会话Agent 框架 工具集独立容器这么分层的好处是解耦。模型层换一个量化版本服务层不用动Agent 层想加个新工具也不用重启推理服务。我见过有人把三层塞进一个容器结果改一行提示词就要重新加载几十 GB 的模型那体验简直灾难。2.2 为什么推理引擎优先选兼容 OpenAI 协议的那一类现在主流的推理引擎基本都支持 OpenAI 兼容接口这不是巧合而是生态选择的结果。原因很实在客户端零改造市面上绝大多数 Agent 框架、前端对话界面、SDK 都是按 OpenAI 协议写的你只要把base_url指到内网地址其余代码一行不用改。工具链成熟流式输出、函数调用、多轮上下文这些协议里都有约定省得自己造轮子。便于横向替换今天用 A 引擎明天想换 B 引擎只要协议一致Agent 层完全无感。我在选型时的判断标准很简单优先选社区活跃、文档齐全、对量化模型支持好的引擎。至于具体是哪一个不同硬件适配情况不一样你可以根据自己显卡的架构去挑思路是通用的。2.3 Docker 化部署的取舍镜像体积 vs 启动速度容器化大模型服务有个绕不开的矛盾镜像做大了拉取和分发慢做小了运行时又要临时下载依赖启动更慢。我的经验是分两种策略开发调试阶段用官方基础镜像模型文件通过 volume 挂载镜像保持精简改配置不用重建镜像。生产交付阶段把模型文件打进镜像或者做成独立的数据卷镜像配合内网镜像仓库一次分发到处运行。注意模型权重动辄几个 GB 到几十 GB千万不要用COPY直接打进普通镜像层否则每次改代码都会产生一个巨大的新层镜像仓库很快就被撑爆。正确做法是用 volume 挂载或者用多阶段构建把权重放到独立的数据层。2.4 网络规划端口、网段与访问控制局域网部署最容易忽视的就是网络规划。我建议在动手之前先把这几件事定下来服务端口推理服务默认端口、Agent 服务端口、前端端口三个分开别挤在一起。绑定地址容器内服务监听0.0.0.0宿主机映射时按需绑定到具体网卡不要无脑暴露到所有网段。访问控制如果内网也不是完全可信建议在 Agent 层前面加一层反向代理做鉴权和限流。DNS 或 hosts给服务起个好记的内网域名比记 IP 加端口舒服得多。我一般会预留一个172.20.0.0/16这样的自定义 bridge 网段给这套服务专用避免和公司现有网段冲突。这个细节看着小但真出冲突的时候排查起来很头疼。3. 核心细节解析与实操要点3.1 硬件与驱动的前置检查清单在写任何 Docker 配置之前先把宿主机的地基打好。这一步偷懒后面全是坑。我整理了一份必查清单显卡驱动版本用nvidia-smi确认驱动正常记下 CUDA 版本上限。容器运行时确认已安装支持 GPU 的容器工具包docker info里能看到对应的 runtime。显存容量根据模型参数量和量化等级估算留出至少 20% 余量给上下文缓存。磁盘空间模型文件 镜像 日志建议单独挂一块盘别和系统盘混用。内存与交换分区纯 CPU 推理时内存要够交换分区别设太小否则容易 OOM。显存估算有个粗略公式我平时这么算显存占用 ≈ 参数量 × 量化字节数 × 1.2 上下文缓存。比如一个 7B 模型用 4bit 量化权重约 3.5GB加上 KV 缓存和运行时开销8GB 显存基本能跑但上下文开太大就会爆。这个公式不精确但用来做初步判断足够了。3.2 模型文件的选择与目录组织模型文件从哪来、放哪里直接决定了后续维护的难易度。我的做法是建立一个统一的模型仓库目录按“模型名/版本/量化等级”三级组织/models └── deepseek-series ├── v1 │ ├── fp16 │ └── q4 └── v2 ├── fp16 └── q8这样组织的好处是切换模型版本只需要改一个挂载路径回滚也方便。选量化等级的时候要权衡q4 省显存但精度有损q8 精度好但占用翻倍fp16 是原汁原味但最吃资源。我的建议是先用 q4 跑通流程确认业务效果可接受再考虑升级。提示下载模型文件时注意校验文件完整性我遇到过下载中断导致权重损坏的情况加载时报的错五花八门排查了半天才发现是文件本身的问题。养成校验哈希值的习惯。3.3 推理服务容器的关键配置项推理服务容器的配置核心就几个参数但每个都影响体验并发数设太大显存扛不住设太小请求排队。一般从 1 开始压测后逐步调。上下文长度直接决定 KV 缓存大小是显存杀手。按业务实际需要设别盲目拉满。批处理大小影响吞吐但会增加首 token 延迟交互式场景要谨慎。量化后端不同引擎支持的后端不一样选和你的硬件最匹配的那个。下面是一个我常用的服务容器配置骨架你可以按自己的引擎替换镜像名和启动参数services: inference: image: your-inference-engine:latest runtime: nvidia environment: - NVIDIA_VISIBLE_DEVICES0 volumes: - /models/deepseek-series/v1/q4:/models:ro command: --model /models --host 0.0.0.0 --port 8000 --max-model-len 8192 --gpu-memory-utilization 0.85 ports: - 127.0.0.1:8000:8000 restart: unless-stopped注意ports这里我绑定的是127.0.0.1意思是只有宿主机本地能访问外部要通过 Agent 层或反向代理进来。这样做的目的是收敛暴露面别让推理服务裸奔在内网上。3.4 Agent 层容器的编排要点Agent 层是整个平台的“大脑”它负责接收用户请求、拼装提示词、调用工具、维护会话状态最后把推理请求转发给服务层。这一层的配置重点在于环境变量注入把推理服务的地址、API key内网可以随便设一个占位、默认模型名通过环境变量传进去。工具配置如果 Agent 要调用外部工具比如查数据库、读文件这些工具的连接信息也要配好。持久化会话历史、向量库、日志都要挂 volume容器删了数据不能丢。健康检查配一个healthcheck让编排工具能感知服务是否真的可用。agent: image: your-agent-framework:latest environment: - OPENAI_BASE_URLhttp://inference:8000/v1 - OPENAI_API_KEYinternal-placeholder - DEFAULT_MODELdeepseek-series volumes: - ./agent-data:/app/data - ./agent-logs:/app/logs ports: - 0.0.0.0:3000:3000 depends_on: - inference restart: unless-stopped这里OPENAI_BASE_URL指向的是容器名inference因为两个容器在同一个自定义网络里Docker 内置 DNS 会帮你解析。这就是为什么我强烈建议用 compose 而不是docker run一堆命令——网络和依赖关系它都帮你管了。3.5 数据持久化与备份策略模型平台的数据分三类备份策略各不相同模型文件体积大但基本不变做一次全量备份即可或者干脆保留原始下载源。会话与向量数据变化频繁建议每日增量备份保留最近 7 天。配置与提示词体积小但最关键建议纳入版本控制每次改动都有记录。我吃过一次亏某次升级 Agent 框架容器重建时把没挂载出来的会话数据全清了用户历史对话一夜回到解放前。从那以后凡是带状态的服务我一定先确认 volume 挂载正确再动手。4. 完整实操流程与关键环节实现4.1 环境准备从裸机到可运行 Docker假设你拿到一台干净的 Linux 服务器带一张显卡。第一步是把基础环境搭起来。我按顺序列一下更新系统包安装基础工具curl、git、vim 之类。安装显卡驱动重启后用nvidia-smi验证。安装 Docker 引擎和 compose 插件。安装 GPU 容器工具包配置容器运行时。验证跑一个测试容器确认能访问到显卡。验证这一步很关键我通常用一条命令快速确认docker run --rm --runtimenvidia your-base-image nvidia-smi如果这条命令能打印出显卡信息说明容器访问 GPU 的通路是通的。如果报错八成是运行时没配好回去检查容器工具包的安装步骤。4.2 目录结构与 compose 文件编写我习惯给每个服务建一个独立目录结构清晰迁移方便ai-agent-platform/ ├── compose.yaml ├── .env ├── models/ # 模型文件挂载点 ├── agent-data/ # Agent 持久化数据 ├── agent-logs/ # 日志 └── nginx/ # 反向代理配置可选.env文件用来放环境相关的变量比如端口号、模型路径、显存比例这样 compose 文件本身可以保持通用换环境只改.envINFERENCE_PORT8000 AGENT_PORT3000 MODEL_PATH/models/deepseek-series/v1/q4 GPU_UTIL0.85compose 文件里用${变量名}引用这样一套配置能在开发机和生产机上复用只改.env就行。4.3 启动顺序与依赖管理这套平台有启动顺序要求推理服务必须先起来Agent 层才能正常工作。compose 的depends_on能保证启动顺序但它不保证“服务真的就绪”。所以更稳妥的做法是给推理服务配健康检查Agent 层等健康检查通过再启动inference: healthcheck: test: [CMD, curl, -f, http://localhost:8000/health] interval: 30s timeout: 10s retries: 5 start_period: 120sstart_period这个参数很重要因为大模型加载慢给它留足初始化时间否则健康检查会一直失败导致容器被反复重启。我一般按模型大小给 60 到 180 秒不等。4.4 首次启动与验证流程一切就绪后启动命令很简单docker compose up -d docker compose logs -f inference盯着日志看模型加载进度加载完成后会打印监听地址。然后验证推理服务curl http://localhost:8000/v1/models能返回模型列表就说明服务层通了。接着验证 Agent 层curl http://localhost:3000/health最后做一次端到端对话测试确认从 Agent 到推理服务的链路完整。我一般会准备几个测试用例简单问答、多轮对话、工具调用分别验证不同能力。4.5 性能调优让首 token 延迟降下来平台跑通之后下一步就是调优。首 token 延迟是交互体验的关键指标我实测下来影响它的因素按重要性排序因素影响程度调整方向上下文长度高按需设置别拉满批处理策略高交互场景用连续批处理量化等级中精度和速度的权衡显存利用率中留足余量避免换页网络传输低内网基本可忽略我的调优顺序是先把上下文长度压到业务最小值再调批处理策略最后才考虑量化等级。因为前两个改动成本低、见效快量化等级一改往往要重新验证业务效果。5. 常见问题与排查技巧实录5.1 容器启动失败类问题速查这类问题最常见我把遇到过的整理成表现象可能原因排查方向容器秒退启动命令参数错误看docker logs首屏报错报显存不足模型太大或上下文过长降量化等级或减上下文找不到模型文件volume 路径写错进容器ls确认挂载端口被占用宿主机端口冲突换端口或查占用进程权限拒绝文件属主不对检查挂载目录权限排查这类问题的第一原则永远是先看日志。docker compose logs 服务名能解决 80% 的问题剩下 20% 再进容器里手动验证。5.2 推理速度慢的定位思路速度慢分两种情况首 token 慢还是后续 token 慢。这两个的病因完全不同。首 token 慢通常是提示词太长或者批处理策略不适合交互场景。我遇到过系统提示词写了三千多字每次请求都要重新处理首 token 自然慢。解决办法是精简提示词或者用提示词缓存功能。后续 token 慢多半是显存不够导致换页或者 CPU 推理时算力瓶颈。这时候要看nvidia-smi的显存占用和 GPU 利用率如果利用率上不去说明是内存带宽或调度问题。5.3 Agent 层调用失败的排查路径Agent 层报错先分清是它自己的问题还是下游推理服务的问题。我的排查路径是直接 curl 推理服务确认服务层正常。检查 Agent 容器的环境变量确认base_url指向正确。看 Agent 日志里的具体报错是超时、连接拒绝还是协议不匹配。确认两个容器在同一网络里能互相 ping 通。我踩过最隐蔽的一个坑是Agent 容器和推理容器不在同一个 compose 网络里容器名解析不了报的是“连接超时”看起来像服务挂了其实是网络隔离。后来统一用一个 compose 文件管理问题再没出现过。5.4 我踩过的三个真实坑与避坑建议第一个坑模型文件权限。容器内进程的用户 ID 和宿主机文件属主不一致导致读不了模型。解决办法是在 compose 里指定user或者把模型文件权限放开到可读。第二个坑日志把磁盘写满。推理服务默认日志级别很啰嗦跑几天就把盘写满了。建议配置日志轮转或者把日志级别调到 warning。第三个坑升级镜像后配置不兼容。有次升级 Agent 框架新版本改了环境变量名旧配置直接失效。教训是升级前先看 changelog并且保留旧镜像方便回滚。提示生产环境一定要给镜像打明确的版本标签别用latest。latest看着方便出事的时候你都不知道自己跑的是哪个版本。5.5 安全加固的几个实用动作局域网不等于绝对安全该做的加固还是要做接口鉴权Agent 层前面加一层鉴权哪怕是简单的 token 校验。限流防止某个客户端把推理资源占满影响其他人。日志脱敏对话内容可能含敏感信息日志里要注意脱敏。最小暴露推理服务只绑定本地外部一律走 Agent 层。定期更新基础镜像和依赖库的安全更新要及时跟进。这套平台我在几个内部项目里跑了小半年稳定性总体不错最大的体会是容器化不是目的可复现、可维护才是。把配置写进代码、把数据挂载出来、把版本固定住这三件事做到位后面基本不用怎么操心。至于模型选型和参数调优那是随着业务需求不断迭代的事先把平台搭稳剩下的慢慢磨。
1. 为什么要在局域网里自建 AI Agent 平台1.1 从“调用云端 API”到“把模型搬进机房”的转变过去一年我身边不少做后端和运维的朋友都在干同一件事把大模型能力接进自己的内部系统。最开始大家的做法很统一——调云端 API写个封装层前端一调就完事。但真到了生产环境问题一个接一个冒出来内网服务访问外网要走出口延迟忽高忽低业务数据要出内网合规那边过不去按 token 计费量一上来账单看得人心惊肉跳。于是“把模型部署到局域网内部”这件事从可选项变成了必选项。DeepSeek 系列模型这两年在开源社区热度很高推理能力扎实、显存占用相对友好配合量化版本单张消费级显卡甚至纯 CPU 都能跑起来。但光有模型还不够我们要的是一个能对外提供稳定接口、能挂工具、能做多轮对话的AI Agent 平台而不是一个只能跑generate的脚本。这就是标题里 “Harness” 这个词的价值所在——它是一层“挽具”把裸模型套上让它能被人和系统真正用起来。1.2 局域网部署到底解决了哪些真实痛点我把这套方案落地到几个内部项目之后总结出局域网自建 Agent 平台的几个核心收益这也是我为什么推荐你用 Docker 来做这件事的原因数据不出内网所有对话、文档、工具调用记录都在自己的机器上敏感信息不经过任何第三方。延迟可控内网千兆甚至万兆环境首 token 延迟基本稳定在几百毫秒级别比走公网 API 稳定得多。成本一次性硬件买断之后跑多少 token 都是电费业务量越大越划算。可定制系统提示词、工具集、知识库、权限控制全部自己说了算想怎么改就怎么改。离线可用断网环境照样跑这对很多工业、科研场景是刚需。而 Docker 的价值在于它把“装环境”这件最折磨人的事标准化了。CUDA 版本、Python 依赖、模型路径、端口映射全部写进compose.yaml换台机器docker compose up -d就能复现。我踩过最深的坑就是早期手动装环境换一台服务器就要重来一遍自从全面转向容器化部署时间从半天压缩到十几分钟。1.3 这篇文章适合谁看如果你符合下面任意一条这篇内容应该能帮到你手里有一台带显卡的服务器或工作站想把它变成团队内部的 AI 服务节点正在做企业内部知识库、智能客服、代码助手这类项目需要私有化推理能力对 Docker 有一定了解但没试过把大模型和 Agent 框架一起容器化想搞清楚“模型服务”和“Agent 编排”这两层到底怎么分工、怎么对接。我会从整体架构讲起然后一步步拆解 Docker 镜像怎么选、模型怎么挂载、Agent 层怎么配、端口和网络怎么规划最后把我实际踩过的坑整理成排查表。全程给的是可以直接抄的配置不是泛泛而谈的概念。2. 整体架构设计与方案选型思路2.1 三层结构模型层、服务层、Agent 层一套能用的局域网 AI Agent 平台我习惯把它拆成三层来看这样出问题的时候能快速定位是哪一层挂了层级职责典型组件部署形态模型层加载权重、执行推理推理引擎 量化模型文件容器内进程服务层暴露 HTTP 接口、管理并发兼容 OpenAI 协议的推理服务独立容器Agent 层编排对话、挂载工具、管理会话Agent 框架 工具集独立容器这么分层的好处是解耦。模型层换一个量化版本服务层不用动Agent 层想加个新工具也不用重启推理服务。我见过有人把三层塞进一个容器结果改一行提示词就要重新加载几十 GB 的模型那体验简直灾难。2.2 为什么推理引擎优先选兼容 OpenAI 协议的那一类现在主流的推理引擎基本都支持 OpenAI 兼容接口这不是巧合而是生态选择的结果。原因很实在客户端零改造市面上绝大多数 Agent 框架、前端对话界面、SDK 都是按 OpenAI 协议写的你只要把base_url指到内网地址其余代码一行不用改。工具链成熟流式输出、函数调用、多轮上下文这些协议里都有约定省得自己造轮子。便于横向替换今天用 A 引擎明天想换 B 引擎只要协议一致Agent 层完全无感。我在选型时的判断标准很简单优先选社区活跃、文档齐全、对量化模型支持好的引擎。至于具体是哪一个不同硬件适配情况不一样你可以根据自己显卡的架构去挑思路是通用的。2.3 Docker 化部署的取舍镜像体积 vs 启动速度容器化大模型服务有个绕不开的矛盾镜像做大了拉取和分发慢做小了运行时又要临时下载依赖启动更慢。我的经验是分两种策略开发调试阶段用官方基础镜像模型文件通过 volume 挂载镜像保持精简改配置不用重建镜像。生产交付阶段把模型文件打进镜像或者做成独立的数据卷镜像配合内网镜像仓库一次分发到处运行。注意模型权重动辄几个 GB 到几十 GB千万不要用COPY直接打进普通镜像层否则每次改代码都会产生一个巨大的新层镜像仓库很快就被撑爆。正确做法是用 volume 挂载或者用多阶段构建把权重放到独立的数据层。2.4 网络规划端口、网段与访问控制局域网部署最容易忽视的就是网络规划。我建议在动手之前先把这几件事定下来服务端口推理服务默认端口、Agent 服务端口、前端端口三个分开别挤在一起。绑定地址容器内服务监听0.0.0.0宿主机映射时按需绑定到具体网卡不要无脑暴露到所有网段。访问控制如果内网也不是完全可信建议在 Agent 层前面加一层反向代理做鉴权和限流。DNS 或 hosts给服务起个好记的内网域名比记 IP 加端口舒服得多。我一般会预留一个172.20.0.0/16这样的自定义 bridge 网段给这套服务专用避免和公司现有网段冲突。这个细节看着小但真出冲突的时候排查起来很头疼。3. 核心细节解析与实操要点3.1 硬件与驱动的前置检查清单在写任何 Docker 配置之前先把宿主机的地基打好。这一步偷懒后面全是坑。我整理了一份必查清单显卡驱动版本用nvidia-smi确认驱动正常记下 CUDA 版本上限。容器运行时确认已安装支持 GPU 的容器工具包docker info里能看到对应的 runtime。显存容量根据模型参数量和量化等级估算留出至少 20% 余量给上下文缓存。磁盘空间模型文件 镜像 日志建议单独挂一块盘别和系统盘混用。内存与交换分区纯 CPU 推理时内存要够交换分区别设太小否则容易 OOM。显存估算有个粗略公式我平时这么算显存占用 ≈ 参数量 × 量化字节数 × 1.2 上下文缓存。比如一个 7B 模型用 4bit 量化权重约 3.5GB加上 KV 缓存和运行时开销8GB 显存基本能跑但上下文开太大就会爆。这个公式不精确但用来做初步判断足够了。3.2 模型文件的选择与目录组织模型文件从哪来、放哪里直接决定了后续维护的难易度。我的做法是建立一个统一的模型仓库目录按“模型名/版本/量化等级”三级组织/models └── deepseek-series ├── v1 │ ├── fp16 │ └── q4 └── v2 ├── fp16 └── q8这样组织的好处是切换模型版本只需要改一个挂载路径回滚也方便。选量化等级的时候要权衡q4 省显存但精度有损q8 精度好但占用翻倍fp16 是原汁原味但最吃资源。我的建议是先用 q4 跑通流程确认业务效果可接受再考虑升级。提示下载模型文件时注意校验文件完整性我遇到过下载中断导致权重损坏的情况加载时报的错五花八门排查了半天才发现是文件本身的问题。养成校验哈希值的习惯。3.3 推理服务容器的关键配置项推理服务容器的配置核心就几个参数但每个都影响体验并发数设太大显存扛不住设太小请求排队。一般从 1 开始压测后逐步调。上下文长度直接决定 KV 缓存大小是显存杀手。按业务实际需要设别盲目拉满。批处理大小影响吞吐但会增加首 token 延迟交互式场景要谨慎。量化后端不同引擎支持的后端不一样选和你的硬件最匹配的那个。下面是一个我常用的服务容器配置骨架你可以按自己的引擎替换镜像名和启动参数services: inference: image: your-inference-engine:latest runtime: nvidia environment: - NVIDIA_VISIBLE_DEVICES0 volumes: - /models/deepseek-series/v1/q4:/models:ro command: --model /models --host 0.0.0.0 --port 8000 --max-model-len 8192 --gpu-memory-utilization 0.85 ports: - 127.0.0.1:8000:8000 restart: unless-stopped注意ports这里我绑定的是127.0.0.1意思是只有宿主机本地能访问外部要通过 Agent 层或反向代理进来。这样做的目的是收敛暴露面别让推理服务裸奔在内网上。3.4 Agent 层容器的编排要点Agent 层是整个平台的“大脑”它负责接收用户请求、拼装提示词、调用工具、维护会话状态最后把推理请求转发给服务层。这一层的配置重点在于环境变量注入把推理服务的地址、API key内网可以随便设一个占位、默认模型名通过环境变量传进去。工具配置如果 Agent 要调用外部工具比如查数据库、读文件这些工具的连接信息也要配好。持久化会话历史、向量库、日志都要挂 volume容器删了数据不能丢。健康检查配一个healthcheck让编排工具能感知服务是否真的可用。agent: image: your-agent-framework:latest environment: - OPENAI_BASE_URLhttp://inference:8000/v1 - OPENAI_API_KEYinternal-placeholder - DEFAULT_MODELdeepseek-series volumes: - ./agent-data:/app/data - ./agent-logs:/app/logs ports: - 0.0.0.0:3000:3000 depends_on: - inference restart: unless-stopped这里OPENAI_BASE_URL指向的是容器名inference因为两个容器在同一个自定义网络里Docker 内置 DNS 会帮你解析。这就是为什么我强烈建议用 compose 而不是docker run一堆命令——网络和依赖关系它都帮你管了。3.5 数据持久化与备份策略模型平台的数据分三类备份策略各不相同模型文件体积大但基本不变做一次全量备份即可或者干脆保留原始下载源。会话与向量数据变化频繁建议每日增量备份保留最近 7 天。配置与提示词体积小但最关键建议纳入版本控制每次改动都有记录。我吃过一次亏某次升级 Agent 框架容器重建时把没挂载出来的会话数据全清了用户历史对话一夜回到解放前。从那以后凡是带状态的服务我一定先确认 volume 挂载正确再动手。4. 完整实操流程与关键环节实现4.1 环境准备从裸机到可运行 Docker假设你拿到一台干净的 Linux 服务器带一张显卡。第一步是把基础环境搭起来。我按顺序列一下更新系统包安装基础工具curl、git、vim 之类。安装显卡驱动重启后用nvidia-smi验证。安装 Docker 引擎和 compose 插件。安装 GPU 容器工具包配置容器运行时。验证跑一个测试容器确认能访问到显卡。验证这一步很关键我通常用一条命令快速确认docker run --rm --runtimenvidia your-base-image nvidia-smi如果这条命令能打印出显卡信息说明容器访问 GPU 的通路是通的。如果报错八成是运行时没配好回去检查容器工具包的安装步骤。4.2 目录结构与 compose 文件编写我习惯给每个服务建一个独立目录结构清晰迁移方便ai-agent-platform/ ├── compose.yaml ├── .env ├── models/ # 模型文件挂载点 ├── agent-data/ # Agent 持久化数据 ├── agent-logs/ # 日志 └── nginx/ # 反向代理配置可选.env文件用来放环境相关的变量比如端口号、模型路径、显存比例这样 compose 文件本身可以保持通用换环境只改.envINFERENCE_PORT8000 AGENT_PORT3000 MODEL_PATH/models/deepseek-series/v1/q4 GPU_UTIL0.85compose 文件里用${变量名}引用这样一套配置能在开发机和生产机上复用只改.env就行。4.3 启动顺序与依赖管理这套平台有启动顺序要求推理服务必须先起来Agent 层才能正常工作。compose 的depends_on能保证启动顺序但它不保证“服务真的就绪”。所以更稳妥的做法是给推理服务配健康检查Agent 层等健康检查通过再启动inference: healthcheck: test: [CMD, curl, -f, http://localhost:8000/health] interval: 30s timeout: 10s retries: 5 start_period: 120sstart_period这个参数很重要因为大模型加载慢给它留足初始化时间否则健康检查会一直失败导致容器被反复重启。我一般按模型大小给 60 到 180 秒不等。4.4 首次启动与验证流程一切就绪后启动命令很简单docker compose up -d docker compose logs -f inference盯着日志看模型加载进度加载完成后会打印监听地址。然后验证推理服务curl http://localhost:8000/v1/models能返回模型列表就说明服务层通了。接着验证 Agent 层curl http://localhost:3000/health最后做一次端到端对话测试确认从 Agent 到推理服务的链路完整。我一般会准备几个测试用例简单问答、多轮对话、工具调用分别验证不同能力。4.5 性能调优让首 token 延迟降下来平台跑通之后下一步就是调优。首 token 延迟是交互体验的关键指标我实测下来影响它的因素按重要性排序因素影响程度调整方向上下文长度高按需设置别拉满批处理策略高交互场景用连续批处理量化等级中精度和速度的权衡显存利用率中留足余量避免换页网络传输低内网基本可忽略我的调优顺序是先把上下文长度压到业务最小值再调批处理策略最后才考虑量化等级。因为前两个改动成本低、见效快量化等级一改往往要重新验证业务效果。5. 常见问题与排查技巧实录5.1 容器启动失败类问题速查这类问题最常见我把遇到过的整理成表现象可能原因排查方向容器秒退启动命令参数错误看docker logs首屏报错报显存不足模型太大或上下文过长降量化等级或减上下文找不到模型文件volume 路径写错进容器ls确认挂载端口被占用宿主机端口冲突换端口或查占用进程权限拒绝文件属主不对检查挂载目录权限排查这类问题的第一原则永远是先看日志。docker compose logs 服务名能解决 80% 的问题剩下 20% 再进容器里手动验证。5.2 推理速度慢的定位思路速度慢分两种情况首 token 慢还是后续 token 慢。这两个的病因完全不同。首 token 慢通常是提示词太长或者批处理策略不适合交互场景。我遇到过系统提示词写了三千多字每次请求都要重新处理首 token 自然慢。解决办法是精简提示词或者用提示词缓存功能。后续 token 慢多半是显存不够导致换页或者 CPU 推理时算力瓶颈。这时候要看nvidia-smi的显存占用和 GPU 利用率如果利用率上不去说明是内存带宽或调度问题。5.3 Agent 层调用失败的排查路径Agent 层报错先分清是它自己的问题还是下游推理服务的问题。我的排查路径是直接 curl 推理服务确认服务层正常。检查 Agent 容器的环境变量确认base_url指向正确。看 Agent 日志里的具体报错是超时、连接拒绝还是协议不匹配。确认两个容器在同一网络里能互相 ping 通。我踩过最隐蔽的一个坑是Agent 容器和推理容器不在同一个 compose 网络里容器名解析不了报的是“连接超时”看起来像服务挂了其实是网络隔离。后来统一用一个 compose 文件管理问题再没出现过。5.4 我踩过的三个真实坑与避坑建议第一个坑模型文件权限。容器内进程的用户 ID 和宿主机文件属主不一致导致读不了模型。解决办法是在 compose 里指定user或者把模型文件权限放开到可读。第二个坑日志把磁盘写满。推理服务默认日志级别很啰嗦跑几天就把盘写满了。建议配置日志轮转或者把日志级别调到 warning。第三个坑升级镜像后配置不兼容。有次升级 Agent 框架新版本改了环境变量名旧配置直接失效。教训是升级前先看 changelog并且保留旧镜像方便回滚。提示生产环境一定要给镜像打明确的版本标签别用latest。latest看着方便出事的时候你都不知道自己跑的是哪个版本。5.5 安全加固的几个实用动作局域网不等于绝对安全该做的加固还是要做接口鉴权Agent 层前面加一层鉴权哪怕是简单的 token 校验。限流防止某个客户端把推理资源占满影响其他人。日志脱敏对话内容可能含敏感信息日志里要注意脱敏。最小暴露推理服务只绑定本地外部一律走 Agent 层。定期更新基础镜像和依赖库的安全更新要及时跟进。这套平台我在几个内部项目里跑了小半年稳定性总体不错最大的体会是容器化不是目的可复现、可维护才是。把配置写进代码、把数据挂载出来、把版本固定住这三件事做到位后面基本不用怎么操心。至于模型选型和参数调优那是随着业务需求不断迭代的事先把平台搭稳剩下的慢慢磨。
