1. 为什么要在局域网里自己搭一套 AI Agent 平台很多人第一次接触大模型习惯直接开网页用。但真到了要干活的时候问题就来了数据不能出内网、调用要稳定、多个同事要共用、还得能接自己的知识库和工具链。这时候一个跑在局域网里的 AI Agent 平台就不是玩具而是实打实的生产力工具。我这次折腾的目标很明确用 Docker 把 DeepSeek 相关的模型服务和一个 Agent 编排层打包起来让整个平台在局域网内跑通。选 DeepSeek 的原因很直接——它在中文理解、代码生成、长上下文这几个维度上表现扎实而且开源权重版本对硬件相对友好不像某些模型动辄要一整柜卡。选 Docker 的原因更简单环境隔离、一键迁移、版本回滚方便团队里谁都能复现。这套平台能做什么简单说它把模型推理和Agent 调度两件事拆开又拼起来。模型层负责把话说通顺、把代码写对Agent 层负责决定什么时候该查资料、什么时候该调工具、什么时候该把结果汇总给用户。局域网部署意味着所有请求都在内网闭环敏感数据不出门响应延迟也低。适合谁来参考三类人一是公司内部想搭私有 AI 助手的运维或后端二是做垂直领域应用、需要把模型接进自己业务系统的开发者三是对 Agent 机制好奇、想亲手跑一遍完整链路的技术爱好者。哪怕你之前只写过 Dockerfile、没碰过模型部署跟着思路走也能搭起来。提示本文讲的是局域网内部署所有操作都在你自己的网络环境里完成不涉及任何外部网络访问配置。2. 部署前的硬件与软件盘点别等装到一半才发现卡不够2.1 显存和内存到底要多少这是最容易翻车的地方。很多人看网上说某模型能跑结果自己一装就 OOM。我先把账算清楚。模型推理吃的是显存Agent 编排和向量检索吃的是内存和 CPU。以常见的 7B 到 14B 量级模型为例量化方式不同占用差别很大模型规模量化方式显存占用约适用场景7BFP1614-16 GB单卡专业卡质量最好7BINT88-9 GB单卡消费级高端7BINT45-6 GB单卡中端性价比高14BINT815-17 GB双卡或大显存单卡14BINT49-11 GB单卡高端消费级32BINT420-24 GB专业卡或双卡这张表是经验值实际会因推理框架、上下文长度、并发数浮动。上下文越长、并发越高显存占用越大。我建议按峰值需求 × 1.3来预留别卡着下限装。内存方面Agent 平台本身编排服务、向量库、缓存建议至少 16 GB如果要做文档解析和向量化32 GB 更稳。CPU 核心数影响的是文档处理和并发调度8 核起步比较舒服。2.2 软件栈的版本选择Docker 和 Docker Compose 是基础。我踩过的坑是某些推理镜像对 Docker 版本有隐性要求太老的版本会出现 GPU 挂载失败。建议 Docker 用较新的稳定版Compose 用 v2 语法。GPU 支持方面需要装好对应的容器运行时和驱动。这里的关键是驱动版本、运行时版本、镜像内 CUDA 版本三者要对齐。我一般先在宿主机上确认驱动正常再跑一个最小的 GPU 测试容器验证挂载确认没问题再上大镜像。注意驱动和运行时的版本匹配是 GPU 容器最常见的故障源。装之前先查清楚镜像要求的 CUDA 版本再倒推宿主机驱动版本。2.3 网络与存储规划局域网部署要提前规划端口。模型服务、Agent 服务、向量库、管理界面各占一个端口别到时候冲突。存储上模型权重文件动辄几个 GB 到几十 GB建议单独挂一块盘或者用独立的数据卷别和系统盘混在一起。我习惯把目录结构规划成这样/opt/ai-platform/ ├── docker-compose.yml ├── models/ # 模型权重 ├── data/ # 向量库、数据库 ├── configs/ # 各服务配置 └── logs/ # 日志这样迁移的时候整个目录打包带走换台机器改改路径就能跑。3. 用 Docker Compose 把模型服务和 Agent 编排串起来3.1 整体架构怎么拆我不建议把所有东西塞进一个容器。原因很简单模型推理和 Agent 编排的更新节奏、资源需求、故障模式都不一样。混在一起改一行 Agent 逻辑就得重启整个模型服务得不偿失。我的拆法是三层模型推理层负责加载权重、提供推理接口。对外暴露一个兼容常见接口规范的 HTTP 端点。Agent 编排层负责对话管理、工具调用、记忆存储、任务规划。它调用模型层的接口。支撑层向量数据库、缓存、管理界面。三层之间通过 Docker 网络内部通信只有管理界面和 Agent 的对外接口映射到宿主机端口。这样局域网内的其他机器访问 Agent 接口就行模型层不直接暴露。3.2 模型服务的容器配置要点模型服务的 Compose 片段核心是 GPU 资源声明和卷挂载services: model-server: image: your-inference-image:latest container_name: model-server runtime: nvidia environment: - MODEL_PATH/models/deepseek - MAX_MODEL_LEN8192 - GPU_MEMORY_UTILIZATION0.9 volumes: - ./models:/models:ro ports: - 8000:8000 deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] restart: unless-stopped几个参数值得说清楚。MAX_MODEL_LEN控制最大上下文长度设太大显存吃紧设太小长文档处理不了8192 是个平衡点。GPU_MEMORY_UTILIZATION控制显存预分配比例0.9 意味着留 10% 给其他进程设成 1.0 有时候会因为碎片导致启动失败。volumes用只读挂载模型目录防止容器内误写。restart: unless-stopped保证宿主机重启后服务自动拉起但手动停掉后不会自己回来方便维护。3.3 Agent 编排层的依赖与启动顺序Agent 层依赖模型层和向量库所以启动顺序很重要。Compose 的depends_on只能保证启动顺序不能保证服务就绪。我的做法是给 Agent 服务加一个健康检查重试逻辑或者用启动脚本轮询模型接口直到返回正常。agent-server: image: your-agent-image:latest container_name: agent-server environment: - MODEL_ENDPOINThttp://model-server:8000/v1 - VECTOR_DB_URLhttp://vector-db:6333 - MEMORY_BACKENDredis - REDIS_URLredis://redis:6379 depends_on: - model-server - vector-db - redis ports: - 8080:8080 restart: unless-stopped注意MODEL_ENDPOINT用的是容器名model-server这是 Docker 内部 DNS 解析的功劳。同一网络内容器之间直接用服务名通信不用管 IP。3.4 向量库和缓存的角色向量库负责存知识库的向量表示Agent 做检索增强的时候要用。缓存负责存会话状态和临时结果避免每次对话都重新算。这两个组件看起来是配角但少了它们Agent 的记忆和知识就无从谈起。向量库我一般选轻量级的方案单机部署够用数据卷挂出来持久化。缓存用常见的内存数据库配置简单加个密码就行。4. 让 Agent 真正能干活工具接入与知识库配置4.1 Agent 和普通对话机器人的区别在哪普通对话机器人是你问我答Agent 是你给目标我自己想办法。差别就在工具调用和任务规划。比如你问帮我查一下上周的销售数据并生成图表普通机器人只能告诉你我做不到Agent 会先调数据库查询工具再调图表生成工具最后把结果拼起来。要让 Agent 能干活得给它配工具。工具的本质是一个带描述的接口Agent 根据描述决定什么时候调、传什么参数。描述写得越清楚Agent 用得越准。4.2 工具注册的实操细节工具注册一般用一个配置文件或者注册接口。我倾向于配置文件改起来直观也方便版本管理。一个工具的定义大概长这样{ name: query_database, description: 根据 SQL 语句查询业务数据库返回结果集。仅支持 SELECT 语句。, parameters: { type: object, properties: { sql: { type: string, description: 要执行的 SELECT 查询语句 } }, required: [sql] } }这里有个经验description里一定要写清楚能做什么和不能做什么。我见过 Agent 因为描述模糊把写操作也往查询工具里塞结果报错。明确写仅支持 SELECT能大幅降低误用率。参数描述同样重要。sql参数说明里写清楚是SELECT 查询语句Agent 就不会传个表名进来。4.3 知识库的切分与向量化知识库是 Agent 的长期记忆。把内部文档、手册、FAQ 喂进去Agent 回答时就能引用。关键在切分策略。切分太粗检索出来的段落包含太多无关信息模型容易被干扰。切分太细上下文断裂语义不完整。我的经验是按语义段落切每段 300 到 500 字段间保留一定重叠。技术文档按标题层级切FAQ 按问答对切。向量化用嵌入模型把每段文本转成向量存进向量库。检索时把用户问题也向量化找最相似的几段拼进提示词里。提示知识库更新后要重新向量化别指望增量更新能自动处理所有情况。我一般做个定时任务每天凌晨重建一次索引。4.4 会话记忆的管理Agent 要记住上下文但上下文窗口有限。全量塞进去很快就爆了。常见做法是滑动窗口加摘要最近几轮对话保留原文更早的对话压缩成摘要。缓存里存会话状态键用会话 ID值存消息列表和摘要。设置合理的过期时间避免缓存无限增长。我一般设 24 小时过期够一个工作日的连续对话用。5. 实测中遇到的坑和排查思路5.1 模型加载失败从日志倒查第一次启动模型服务容器起来几秒就退出。看日志发现是显存不足。但明明按表算的够用啊后来发现是宿主机上还有别的进程占着显存。排查思路先nvidia-smi看宿主机显存占用确认没有残留进程再启动容器。还有一种情况是模型文件损坏或不完整。下载大文件时网络抖动很常见校验一下文件哈希对不上就重下。5.2 Agent 调用模型超时Agent 发请求给模型等半天没响应。原因可能有三模型服务在加载中还没就绪、请求的上下文太长导致推理慢、网络配置有问题。我的排查顺序是先用 curl 直接打模型接口确认服务本身正常再检查 Agent 配置的 endpoint 对不对最后看请求的 token 数是不是超了MAX_MODEL_LEN。5.3 工具调用参数错误Agent 调工具时传的参数格式不对工具报错。这种情况多半是工具描述不够精确或者模型对参数类型的理解有偏差。解决办法是在描述里加示例明确告诉它参数长什么样。我还会在 Agent 层加一层参数校验格式不对就返回明确错误信息给模型让它重试。这比直接抛异常给用户友好得多。5.4 局域网访问不通宿主机自己能访问局域网其他机器访问不了。先查防火墙规则再看端口映射是不是只绑了127.0.0.1。Compose 里端口映射写成8080:8080默认绑所有网卡写成127.0.0.1:8080:8080就只绑本地。确认是后者的话改成前者。还有一个容易忽略的点如果宿主机有多张网卡要确认服务绑在了正确的网段上。6. 性能调优与日常维护的几点心得6.1 并发上不去怎么办默认配置下模型服务往往一次只处理一个请求并发一高就排队。可以开启动态批处理把多个请求合并成一批推理吞吐能提升好几倍。代价是单请求延迟略微增加但整体吞吐上去了。批处理的大小要调。太小没效果太大显存扛不住。我一般从较小的值开始试逐步往上加观察显存和延迟曲线找到拐点。6.2 显存碎片与长时间运行服务跑久了显存会出现碎片表现为明明有空间却分配失败。定期重启服务能缓解但治标不治本。更好的做法是控制上下文长度上限避免单个请求占用过大块显存。我还会监控显存使用曲线发现持续上涨不回落就说明有泄漏得查代码。6.3 日志和监控别省日志是排查问题的命根子。模型服务、Agent 服务、向量库的日志都要收集起来最好集中到一个地方看。我习惯用轻量的日志方案把各容器日志汇总出问题直接搜关键字。监控方面至少盯三个指标显存占用、请求延迟、错误率。这三个异常了基本能定位到问题方向。6.4 备份与迁移模型权重、向量库数据、配置文件这三样要定期备份。向量库数据尤其重要重建索引费时费力。我一般每周全量备份一次配置文件用版本管理模型权重如果太大就记录来源和版本号需要时重新拉取。迁移到新机器时把整个目录拷过去改一下路径和 GPU 配置docker compose up -d就能跑起来。这就是容器化部署最大的好处——环境一致性有保障。7. 关于这套平台后续能怎么扩展跑通基础版本之后能扩展的方向不少。比如接入更多工具把内部系统的接口都封装成 Agent 能调用的能力比如做多 Agent 协作让不同角色的 Agent 分工处理复杂任务再比如加一层权限管理不同用户能访问的知识库和工具不一样。我自己在实际操作中的体会是先把单条链路跑稳再谈扩展。很多人一上来就想搭个大而全的平台结果每个环节都没调透最后哪个功能都不好用。不如先把模型能答、Agent 能调工具、知识库能检索这三件事做扎实剩下的都是在这上面叠加。还有个小技巧每次改配置或加工具都先用一个固定的测试用例验证一遍确认没破坏原有功能再继续。这套平台涉及组件多牵一发动全身有个回归测试的习惯能省很多事。