1. 为什么要在局域网里自建 AI Agent 平台很多人第一次接触 AI Agent都是直接用云端服务注册个账号、拿个 API Key 就能跑。方便是真方便但用久了总会碰到几个绕不过去的问题数据要经过公网、响应延迟看网络脸色、调用次数一多成本就上来了而且一旦断网或者服务方调整策略整个流程直接停摆。尤其是团队内部有一些敏感文档、内部知识库需要喂给 Agent 做检索增强的时候把数据往外传这件事本身就让人心里不踏实。我这次折腾的目标很明确在局域网里搭一个能跑 AI Agent 的平台所有推理和数据处理都在内网完成团队成员通过浏览器或者内网 API 就能访问不依赖任何外部网络。选型上推理侧用的是 DeepSeek 系列模型部署方式用 Docker整体框架我把它叫做 DeepSeek Harness——说白了就是一套把模型、Agent 编排、工具调用、会话管理串起来的“马具”让模型能真正干活而不只是聊天。这篇文章适合三类人看一是手里有一台带显卡的机器、想在内网跑大模型的开发者二是团队里需要搭建内部 AI 助手、又对数据外流有顾虑的技术负责人三是已经用过云端 Agent、想搞清楚自建方案到底难在哪、值不值得折腾的实践派。我会把整个搭建过程拆开讲包括 Docker 环境怎么准备、模型怎么选、Agent 编排层怎么设计、工具调用怎么接、局域网访问怎么配以及我在实测中踩过的那些坑。全程不涉及任何外部网络依赖纯内网闭环。先说结论整套东西跑起来之后内网访问延迟稳定在几百毫秒级别一个中等规模的团队日常使用完全够用。下面我把每一步的选择理由和操作细节都摊开讲。2. 硬件与基础环境的现实考量2.1 显卡、内存与模型规模的匹配账自建 AI Agent 平台第一道坎不是软件是硬件。DeepSeek 系列有不同参数规模的版本选哪个直接决定了你需要什么级别的显卡。这里我给一个粗略但实用的估算方法模型以 FP16 精度加载时每 10 亿参数大约占 2GB 显存如果用 INT8 量化大约占 1GBINT4 量化则降到 0.5GB 左右。再加上推理时的 KV Cache 开销实际占用还要往上浮 20% 到 40%具体取决于上下文长度和并发数。举个例子假设你选一个 14B 参数量的模型用 INT4 量化加载权重部分大约 7GBKV Cache 按 4K 上下文、并发 4 路来算再留 3 到 4GB整体 12GB 显存能比较从容地跑起来。如果换成 32B 的模型INT4 下权重就要 16GB 左右加上缓存24GB 显存的卡是起步线。我自己的测试机是一张 24GB 显存的卡跑 32B INT4 模型时单路对话流畅并发到 4 路以上就开始出现明显的排队等待。内存方面系统内存至少要给到显存的 1.5 倍因为模型加载、数据预处理、Docker 容器本身都要吃内存。我建议 64GB 起步如果还要同时跑向量数据库和 Agent 编排服务128GB 会更稳。硬盘用 NVMe SSD模型文件动辄十几 GB机械盘加载一次要等好几分钟体验很差。提示不要只看显存总量还要看显存带宽。同样是 24GB带宽高的卡在推理吞吐上能拉开明显差距尤其是并发场景。2.2 Docker 与容器运行时的安装要点Docker 本身安装不复杂但要让容器里的推理服务用上显卡需要额外装容器运行时。以常见的 Linux 环境为例步骤大致是这样先装好 Docker Engine然后安装对应的容器工具包最后配置运行时让 Docker 能识别显卡设备。这里我不写具体命令因为不同发行版差异较大重点说几个容易忽略的点。第一驱动版本要和容器工具包版本匹配。我遇到过驱动太新、工具包太旧导致容器启动时报设备找不到的情况排查了半天才发现是版本错配。第二安装完运行时后一定要重启 Docker 服务否则配置不生效。第三验证是否成功可以跑一个测试容器看能不能正常输出设备信息。这一步别跳过不然后面模型加载失败你会以为是模型问题其实是运行时没配好。另外Docker 的默认存储路径在系统盘模型镜像和容器层会占不少空间。建议提前把数据目录迁移到大容量盘上通过修改配置文件里的数据根目录来实现迁移前记得把已有容器和镜像先停掉、备份好。2.3 内网隔离下的镜像与依赖准备局域网环境最大的麻烦是拉不到公网镜像。我的做法是提前在一台能联网的机器上把所有需要的镜像拉下来导出成归档文件再拷贝到内网机器上导入。需要准备的镜像包括推理服务镜像、向量数据库镜像、Agent 编排服务的运行时镜像以及可能用到的反向代理镜像。依赖方面Python 包也要提前下载好 wheel 文件。我习惯用离线下载的方式把 requirements 里列的所有包连同依赖一起下到一个目录内网机器上直接用本地路径安装。这一步看着繁琐但一次准备好后面重建环境会省很多事。注意导出镜像时用压缩归档能省不少拷贝时间。导入前先确认内网机器的磁盘空间够导入过程会临时占用额外空间。3. DeepSeek Harness 的架构拆解3.1 推理层、编排层与接入层的职责划分整套平台我分成三层来设计每层职责清晰方便单独调试和替换。推理层负责模型加载和文本生成对外暴露一个兼容常见接口规范的 HTTP 服务。这一层不关心业务逻辑只做“给输入、出输出”这件事。我把它单独放在一个容器里好处是模型更新时不用动其他层。编排层是 Harness 的核心负责 Agent 的逻辑接收用户请求、决定要不要调用工具、管理多轮对话的上下文、把检索结果拼进提示词、最后把推理层的输出整理成用户能看懂的回复。这一层我用一个轻量服务来实现里面定义了工具注册机制和会话状态管理。接入层负责对外提供访问入口包括 Web 界面和 API 网关。Web 界面给团队成员直接用API 网关给内部系统集成用。接入层还承担鉴权和限流的职责避免有人误操作把服务打满。三层之间通过内网 HTTP 通信容器之间用自定义网络连接不暴露到宿主机以外的网络。这样即使某一层出问题也不会影响其他层的稳定性。3.2 会话状态与上下文管理的设计取舍Agent 和普通聊天最大的区别在于它需要记住上下文还要能根据历史决定下一步动作。上下文管理有两个常见方案一是把完整历史都塞进提示词二是做摘要压缩。前者简单但吃 token对话一长就容易超上下文后者省资源但会丢细节。我的做法是折中保留最近若干轮完整对话更早的内容做摘要。具体保留多少轮取决于模型的上下文窗口大小和单轮平均长度。以 8K 上下文为例我一般保留最近 6 到 8 轮完整对话更早的压缩成一段简短摘要放在系统提示里。这样既保证了近期交互的连贯性又不会让上下文爆掉。会话状态存在内存里还是持久化也是个取舍。内存方案快但服务重启就丢持久化方案稳但每次读写有开销。我最终选了持久化到轻量数据库因为团队使用场景下会话丢失的体验太差。数据库用容器跑和编排层在同一网络内。3.3 工具调用的注册与路由机制Agent 要干活就得能调用工具。工具可以是查数据库、读文件、调内部 API、做计算等等。Harness 里我设计了一个工具注册表每个工具声明自己的名称、描述、参数格式和执行函数。编排层在生成回复前会把可用工具的描述拼进提示词让模型自己决定要不要调用、调用哪个。模型返回工具调用意图后编排层负责解析参数、执行对应函数、把结果再喂回模型让它生成最终回复。这个循环可能跑多轮所以要设一个最大轮数限制防止死循环。我一般设 5 轮超过就强制返回当前结果并提示用户。工具执行要做超时和异常处理。内部 API 偶尔会慢如果不设超时整个 Agent 就卡住了。我的做法是每个工具调用设 10 秒超时超时后返回一个明确的错误信息给模型让它决定是重试还是换方案。4. 从零跑通部署的完整操作链路4.1 模型文件的获取与量化选择模型文件我建议用已经量化好的版本省去自己转换的麻烦。量化精度上INT4 在多数场景下和 FP16 的差距肉眼可见地小但显存占用和速度优势明显。如果对输出质量要求极高比如做代码生成或者复杂推理可以考虑 INT8代价是显存翻倍。下载模型文件时注意校验完整性大文件传输过程中出错的概率不低。我一般会核对文件大小和哈希值确认无误再加载。模型文件放到宿主机的一个目录通过挂载的方式给容器访问这样更新模型不用重建镜像。加载模型时推理服务一般会提供参数控制显存占用比例、上下文长度、并发数等。显存占用比例不要设成 100%留一点给系统和其他进程我一般设 90%。上下文长度按实际需要设设太大浪费显存设太小对话容易截断。4.2 容器编排文件的编写与启动顺序我用编排文件来管理所有容器把推理服务、向量数据库、编排层、接入层都定义在一个文件里。关键配置项包括网络定义、卷挂载、环境变量、依赖关系、重启策略。启动顺序很重要。推理服务加载模型慢要先启动向量数据库要等推理服务就绪后再连编排层依赖前两者接入层最后起。编排文件里可以用依赖声明来控制顺序但更稳妥的做法是在服务内部做重试连接因为容器启动完成不等于服务就绪。环境变量里我会放模型路径、数据库连接串、服务端口、日志级别这些。敏感配置比如内部 API 的密钥用环境变量注入不写死在镜像里。提示给每个容器设合理的健康检查编排层启动前先确认推理服务真的能响应而不是只看容器状态是 running。4.3 局域网访问与端口映射的配置细节容器默认只在内部网络通信要让局域网其他机器访问需要做端口映射。我只映射接入层的端口到宿主机推理层和数据库层不对外暴露减少攻击面。端口映射时注意宿主机防火墙规则很多“服务起不来”的问题其实是防火墙把端口挡了。我一般先用本机 curl 测试确认服务本身正常再排查网络和防火墙。如果团队人多接入层前面可以加一层反向代理做负载均衡和统一入口。反向代理还能顺便处理静态资源、压缩响应减轻后端压力。配置反向代理时注意超时时间要设够Agent 处理复杂请求可能耗时较长默认超时往往不够。5. 实测中暴露的问题与排查过程5.1 模型加载失败的几类典型原因第一次启动推理服务时容器直接退出日志里报设备相关错误。排查链路是这样的先确认容器运行时配置是否正确用测试容器验证设备可见性确认没问题后再看模型文件路径是否挂载正确发现挂载目录权限不对容器内进程读不了文件改权限后重新启动又报显存不足原来是我把上下文长度设得太大KV Cache 把显存吃满了调小上下文长度终于正常加载。这个过程让我总结出一条经验模型加载失败先看日志最后几行通常错误信息就在那里然后按“运行时配置→文件权限→资源占用”的顺序排查基本能覆盖大部分情况。5.2 并发请求下的响应抖动分析单路测试很流畅但几个人同时用的时候响应时间从几百毫秒涨到好几秒。分析下来有两个原因一是推理服务的并发处理能力有限请求排队二是编排层每次都要查数据库读会话状态数据库成了瓶颈。针对第一个问题我调整了推理服务的批处理参数让多个请求能合并处理提升吞吐。针对第二个问题给会话状态加了内存缓存减少数据库读取次数。调整后并发 8 路的情况下平均响应时间控制在 2 秒以内可以接受。5.3 工具调用超时与循环的应对有一次 Agent 卡住不动日志显示它在反复调用同一个工具。原因是工具返回的结果格式和提示词里描述的不一致模型以为调用失败就一直重试。修复方法是统一工具返回格式并在提示词里明确说明成功和失败的返回结构。超时问题也遇到过。某个内部 API 响应慢工具调用等在那里整个 Agent 阻塞。加了超时控制后超时返回明确错误模型会尝试其他方案或者直接告诉用户暂时不可用体验反而更好。6. 让平台真正好用的几个调优方向6.1 提示词模板的迭代方法Agent 的表现很大程度上取决于提示词。我的做法是先写一个基础版本然后收集实际使用中的失败案例针对性调整。比如发现模型经常忽略某个工具就在提示词里把那个工具的适用场景写得更具体发现回复太啰嗦就加一句“回答简洁不超过三句话”。提示词迭代要有记录每次改了什么、效果如何都记下来。不然改来改去最后自己都忘了哪版最好。我一般用版本号管理提示词模板方便回滚。6.2 检索增强的接入与效果验证如果 Agent 需要回答内部知识相关的问题就要接检索增强。流程是把内部文档切块、向量化、存进向量数据库用户提问时先检索相关片段拼进提示词再让模型生成回答。效果验证很关键。我准备了一批标准问题和期望答案每次调整检索参数或提示词后跑一遍看命中率。检索的 top-k 值、相似度阈值这些参数都要根据实际数据调没有万能值。6.3 日志、监控与日常维护平台跑起来只是开始日常维护才是长久的事。我给每个服务配了日志输出集中收集到一个地方方便排查。关键指标比如响应时间、并发数、错误率做了简单监控异常时能收到提醒。模型和依赖的更新要有计划不要在生产环境直接改。我一般先在测试环境验证新版本确认没问题再切过去。数据定期备份尤其是会话数据和向量库丢了重建成本很高。7. 一些个人体会这套平台我从开始折腾到稳定运行前后花了大概两周时间其中大部分时间不是在写代码而是在排查环境问题和调参数。最大的感受是自建 AI Agent 平台的难点不在模型本身而在工程细节容器配置、资源分配、并发处理、错误恢复这些才是决定能不能用的关键。如果让我给后来者一条建议那就是先把最小闭环跑通——一个模型、一个简单工具、一个能访问的界面确认整条链路通了再往上加功能。我见过不少人一上来就想搭大而全的系统结果卡在某个环境问题上就放弃了。另外内网环境虽然麻烦但一旦搭好稳定性和可控性是云端服务比不了的。数据不出内网这件事对很多团队来说本身就是刚需。这套方案后续还可以扩展比如接入更多工具、支持多模型切换、做更细的权限控制这些都可以在现有架构上平滑加进去。