1. 为什么要在局域网里自建 AI Agent 平台1.1 从“调用云端 API”到“把模型搬进机房”的转变过去一年我身边不少做企业内部工具的朋友都经历了同一个心路历程一开始图省事直接调用公有云的大模型 API写几行代码就能跑通对话、总结、翻译这些功能。但真到了要落地到业务场景里问题就一个接一个冒出来。数据合规部门会问你客户的合同文本、内部的会议纪要、生产环境的日志这些东西发到外部服务上合规吗网络运维的同事会问你办公网出口带宽就那么大几十号人同时用延迟能接受吗财务会问你按 token 计费的模式月底账单能不能预估这些问题的答案往往指向同一个方向把模型部署在自己能掌控的环境里。而“局域网”这个场景恰恰是很多中小团队、实验室、工作室最现实的选择——不需要公网 IP不需要备案不需要复杂的网关配置一台性能还不错的机器加上 Docker就能把一整套 AI Agent 平台跑起来。标题里提到的 DeepSeek Harness本质上就是这样一个“把模型能力封装成可编排 Agent 服务”的框架。它不是一个模型本身而是一层调度和编排的壳你给它一个本地部署的模型推理服务它帮你管理对话上下文、工具调用、任务分解、多轮交互这些逻辑。Docker 部署的意义在于把这套东西连同它的依赖、配置、运行环境一起打包换一台机器照样能跑不用再经历“在我电脑上明明是好的”这种经典困境。1.2 局域网部署的真实收益与适用边界先说收益最直接的三点数据不出内网、延迟可控、成本可预测。数据不出内网意味着你可以放心地把内部文档、代码片段、业务数据喂给 Agent 去处理不用担心它们出现在别人的训练集里。延迟可控是因为模型推理服务就在同一交换机下网络往返通常在个位数毫秒剩下的时间基本花在推理本身。成本可预测则是因为硬件是一次性投入电费和折旧摊下来比按量计费心里有底得多。但也要说清楚边界。局域网部署不等于“随便一台笔记本就能跑”。DeepSeek 系列模型有不同参数规模7B 级别的量化版本在消费级显卡上能跑但如果你要的是接近云端体验的推理质量那至少需要一张显存 24GB 以上的卡或者多卡并行。另外Agent 平台涉及工具调用、文件读写、代码执行这些能力安全边界要提前划好——局域网内部也不是完全可信的环境权限隔离该做还是要做。提示如果你的团队只有三五个人日常任务是文档问答、会议纪要整理、简单代码补全那么一台带中端显卡的工作站加 Docker 就足够了。如果是要给几十人提供稳定服务建议单独准备一台推理服务器把模型服务和 Agent 编排服务分开部署。1.3 这篇文章适合谁读如果你符合下面任意一条这篇内容应该能帮到你手里有一台带显卡的机器想把它变成团队内部的 AI 助手但不知道从哪下手已经试过直接跑模型推理但被 Python 依赖、CUDA 版本、端口冲突折腾得够呛听说过 Agent 编排框架但觉得概念太虚想要一个能实际跑起来的最小可用方案负责内部工具建设需要一套可复制、可迁移、可维护的部署流程。我会按照“整体设计思路 → 核心组件拆解 → 完整实操流程 → 问题排查”的顺序来讲每一步都尽量说清楚为什么这么做以及我踩过哪些坑。2. 整体架构设计与组件选型思路2.1 三层结构推理层、编排层、接入层一套能用的局域网 AI Agent 平台我习惯把它拆成三层来看。推理层负责把模型跑起来对外暴露一个兼容 OpenAI 接口规范的 HTTP 服务。这一层可以用多种推理引擎来实现选择的关键在于它对量化格式的支持、显存占用、并发吞吐这几个指标。推理层是整个平台的地基它的稳定性直接决定上层体验。编排层就是 DeepSeek Harness 所在的位置。它不直接接触 GPU而是通过 HTTP 调用推理层的接口然后在上面叠加 Agent 逻辑会话管理、工具注册、任务规划、结果聚合。这一层用 Docker 部署最合适因为它的依赖主要是 Python 生态和一堆配置文件容器化之后版本冲突问题基本消失。接入层是用户实际接触的部分可以是一个 Web 界面也可以是 API 网关甚至是一个内部聊天工具的机器人。局域网环境下接入层通常就是一个跑在内网 IP 上的 Web 服务团队成员通过浏览器访问。这三层分开的好处是推理层升级模型不影响编排逻辑编排层改 Agent 策略不影响用户界面接入层换皮肤不影响后端。每一层都可以独立重启、独立扩容。2.2 为什么用 Docker 而不是裸机部署我早期试过裸机部署Python 虚拟环境建了一个又一个CUDA 驱动版本和推理引擎要求的版本对不上系统自带的库和 pip 安装的库打架最后环境乱到连自己都记不清哪个包是哪个版本。Docker 解决的核心问题就是环境一致性。具体来说Docker 带来这几个实际好处依赖隔离编排层的 Python 包、系统库、配置文件全部封在镜像里和宿主机环境互不干扰一键迁移镜像推到内网 registry换机器直接拉取运行不用重新配环境版本回滚镜像打 tag新版本出问题秒回旧版本资源限制可以用--memory、--cpus限制容器资源避免编排层把推理层的资源抢光。当然Docker 也有代价。GPU 直通需要额外配置容器内访问宿主机的推理服务需要处理网络模式数据持久化要挂载 volume。这些在后面的实操里都会具体讲。2.3 组件选型对照表下面这张表是我实际对比过几种组合之后整理出来的供你按自己的硬件条件做选择。组件可选方案适用场景注意事项推理引擎支持量化格式的本地推理服务消费级显卡、单机部署注意量化格式与引擎的兼容性推理引擎高吞吐推理服务多卡、多人并发配置复杂度较高显存占用大编排框架DeepSeek HarnessAgent 逻辑编排需确认与推理接口的兼容性容器运行时Docker Engine通用场景GPU 直通需额外配置容器运行时兼容 Docker 的替代运行时对资源占用敏感生态兼容性需验证接入方式内置 Web UI快速验证功能相对基础接入方式自建 API 网关集成到现有系统需要额外开发选型的核心原则是先用最小组合跑通再按需替换。不要一上来就追求“最优解”先把推理层和编排层连通看到 Agent 能正常回复再去优化性能和体验。3. 核心组件拆解与关键配置解析3.1 推理层模型服务怎么跑起来推理层的关键是选一个能加载 DeepSeek 量化模型、并且暴露标准 HTTP 接口的引擎。我实际用下来比较稳妥的做法是选择支持 GGUF 或类似量化格式的推理服务因为这类格式对显存要求相对友好7B 模型量化后大概 4-6GB 显存就能跑13B 大概 8-10GB30B 级别则需要 20GB 以上。启动推理服务时几个参数需要特别注意上下文长度默认可能是 2048 或 4096Agent 场景下多轮对话会迅速吃掉上下文建议至少设到 8192显存够的话设到 16384并发数单卡情况下并发不宜过高设成 4-8 比较稳太高会导致请求排队甚至显存溢出量化精度Q4 和 Q5 在质量上差距不大但 Q4 显存占用明显更低优先选 Q4GPU 层数这个参数决定有多少层跑在 GPU 上设得越高越快但显存不够会直接报错需要根据显存反复试。我一般会先用一个较小的上下文和并发数启动确认服务能正常响应再逐步往上调观察显存占用和响应延迟的变化。这个过程有点像调音急不得。3.2 编排层DeepSeek Harness 的容器化要点DeepSeek Harness 的容器化核心要解决三个问题配置怎么传、数据怎么存、怎么连推理层。配置传递推荐用环境变量加挂载配置文件的方式。环境变量放一些简单的开关和地址比如推理服务的 URL、监听端口、日志级别复杂的 Agent 定义、工具配置则放在一个 YAML 或 JSON 文件里通过 volume 挂载进容器。这样改配置不用重新打镜像重启容器即可生效。数据持久化主要是会话记录和上传的文件。会话记录建议挂载到宿主机的一个目录方便备份和查看上传文件如果涉及敏感内容要确保挂载目录的权限设置正确不要让容器内的进程有越权访问的可能。连接推理层有两种网络模式可选。如果推理服务和编排容器在同一台宿主机上用 host 网络模式最省事容器内直接访问127.0.0.1:端口就能连上推理服务。如果推理服务在另一台机器上就用默认的 bridge 网络通过宿主机的局域网 IP 加端口来访问。两种方式我都试过host 模式延迟略低但端口管理要注意别冲突。3.3 接入层内网访问与权限控制接入层最简方案就是编排框架自带的 Web 界面监听在宿主机的某个端口上团队成员通过http://内网IP:端口访问。这种方式零开发成本适合快速验证。但如果要长期使用有几个点必须考虑访问控制至少加一层简单的身份验证哪怕是共享口令也比完全裸奔强HTTPS局域网内部虽然风险较低但如果涉及敏感数据建议配一个自签名证书反向代理用 Nginx 之类的工具做一层反向代理方便后续加限流、日志、多服务路由。我自己的做法是先用自带界面跑通流程确认 Agent 逻辑没问题之后再在前面加一层反向代理把认证和日志补上。不要一开始就追求完美先把核心链路打通。4. 完整实操流程从零到可用的 Agent 平台4.1 环境准备与依赖检查假设你手里是一台装了 Linux 的机器有一张显卡驱动已经装好。第一步是确认基础环境# 检查显卡驱动和 CUDA 版本 nvidia-smi # 检查 Docker 是否安装 docker --version # 检查 Docker 是否能识别 GPU需要 nvidia-container-toolkit docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi如果最后一条命令能正常输出显卡信息说明 GPU 直通环境没问题。如果报错需要先安装并配置容器 GPU 支持工具这一步网上教程很多核心就是让容器运行时能调用宿主机的显卡驱动。接下来创建工作目录我习惯把推理层和编排层的数据分开存放mkdir -p /opt/ai-platform/{models,harness-data,logs} cd /opt/ai-platformmodels放模型文件harness-data放编排层的会话和配置logs放日志。目录结构清晰后面排查问题会方便很多。4.2 启动推理服务并验证接口推理服务的启动方式取决于你选的引擎。以常见的本地推理服务为例大致流程是# 假设推理服务镜像已经拉取到本地 docker run -d \ --name inference-server \ --gpus all \ -p 8080:8080 \ -v /opt/ai-platform/models:/models \ inference-image \ --model /models/deepseek-model.gguf \ --ctx-size 8192 \ --n-gpu-layers 35 \ --parallel 4这里的--n-gpu-layers 35是个需要反复试的参数。设得太低推理速度慢设得太高显存不够直接崩。我的经验是先用一个保守值启动然后用nvidia-smi观察显存占用逐步往上加直到显存占用到 85% 左右为止。启动后验证接口curl http://127.0.0.1:8080/v1/models如果返回模型列表说明推理层就绪。再发一条测试消息curl http://127.0.0.1:8080/v1/chat/completions \ -H Content-Type: application/json \ -d { model: deepseek-model, messages: [{role: user, content: 你好请回复一句话确认你在线}], max_tokens: 50 }能收到正常回复推理层就算通了。4.3 部署 DeepSeek Harness 容器编排层的部署关键是配置文件要写对。先准备一个最小配置# /opt/ai-platform/harness-data/config.yaml server: host: 0.0.0.0 port: 3000 inference: base_url: http://127.0.0.1:8080/v1 model: deepseek-model timeout: 120 agent: max_rounds: 10 context_window: 8192 tools: - name: file_read enabled: true allowed_paths: - /data/shared - name: code_execute enabled: false注意code_execute我默认关掉了。工具调用里的代码执行能力很强但风险也大局域网内部也不是完全可信的建议先关着等确认需求和安全边界之后再开。启动容器docker run -d \ --name deepseek-harness \ --network host \ -v /opt/ai-platform/harness-data:/app/data \ -v /opt/ai-platform/logs:/app/logs \ -e HARNESS_CONFIG/app/data/config.yaml \ deepseek-harness-image用 host 网络模式是因为推理服务在同一台机器上容器内直接访问127.0.0.1:8080最方便。如果推理服务在别的机器上就把base_url改成那台机器的局域网 IP网络模式换成 bridge 并映射端口。4.4 验证 Agent 完整链路容器起来之后先看日志确认没有报错docker logs -f deepseek-harness日志里应该能看到它成功连接推理服务、加载工具配置、监听端口的记录。然后用 curl 测一下编排层的接口curl http://127.0.0.1:3000/api/chat \ -H Content-Type: application/json \ -d { session_id: test-001, message: 帮我总结一下今天的工作重点 }如果返回的内容里包含了 Agent 的思考过程和最终回复说明整条链路通了。这时候打开浏览器访问http://内网IP:3000应该能看到 Web 界面。4.5 参数调优与性能观察跑通之后下一步是调优。我一般会关注这几个指标指标观察方式目标值调整手段首字延迟界面响应速度 2秒降低上下文长度、提高 GPU 层数显存占用nvidia-smi 90%调整量化精度、并发数并发响应多人同时使用不排队增加推理实例、限制单用户并发会话长度日志中的 token 数不超上下文调整上下文窗口、开启会话截断调优是个反复的过程我的建议是每次只改一个参数改完观察一段时间确认稳定再改下一个。同时改多个参数出了问题根本不知道是哪个引起的。5. 常见问题与排查技巧实录5.1 推理服务启动失败排查表现象可能原因排查方法解决方式容器启动即退出模型文件路径错误查看容器日志确认挂载路径和文件名显存不足报错GPU 层数设太高nvidia-smi 看占用降低 n-gpu-layers接口无响应端口被占用netstat 查端口换端口或停掉占用进程回复乱码模型文件损坏校验文件哈希重新下载模型速度极慢层数设太低观察 GPU 利用率逐步提高层数5.2 编排层连接推理层失败的几种情况这是我最常遇到的问题表现是 Agent 界面一直转圈或者报“无法连接后端”。排查顺序如下第一确认推理服务本身是活的。直接在宿主机上 curl 推理接口如果能通说明问题在编排层到推理层的网络。第二确认容器内的网络能到达推理服务。如果用的是 bridge 网络容器内的127.0.0.1指向的是容器自己不是宿主机。这时候要么改成 host 网络要么把base_url改成宿主机的局域网 IP。第三确认防火墙没有拦截。有些系统默认会拦截容器到宿主机的流量需要放行对应端口。第四确认配置文件里的base_url路径正确。有些推理服务的接口路径是/v1/chat/completions配置里如果只写到/v1框架可能会拼接错误。提示排查网络问题时可以在编排容器里装一个 curl直接测试到推理服务的连通性。这比看日志猜要快得多。5.3 会话上下文溢出与截断策略Agent 多轮对话很容易把上下文撑满。表现是对话到一定轮数后Agent 开始“失忆”或者回复质量骤降。解决办法有几个开启自动截断在配置里设置上下文窗口上限超出时自动丢弃最早的对话轮次摘要压缩让 Agent 定期把历史对话总结成一段短文本替换掉原始对话分会话管理不同任务用不同 session_id避免所有对话挤在一个上下文里。我自己的做法是组合使用设置一个 8192 的硬上限同时开启摘要压缩每 10 轮触发一次总结。这样既能保持较长的对话记忆又不会撑爆上下文。5.4 工具调用的安全边界设置Agent 的工具调用能力是双刃剑。文件读取、代码执行、网络请求这些工具用好了效率翻倍用不好就是安全隐患。我的建议是文件工具只开放特定目录用allowed_paths限制不要开放根目录代码执行默认关闭确需开启时用独立的低权限容器限制网络和文件系统访问网络请求限制目标域名或 IP 范围避免 Agent 被诱导访问内部敏感服务操作审计所有工具调用记录日志定期检查异常调用。局域网内部虽然相对可信但“相对”不等于“绝对”。权限最小化原则在这里同样适用。5.5 性能瓶颈定位思路当平台变慢时按这个顺序定位先看 GPU 利用率如果长期 100%说明推理层是瓶颈考虑升级硬件或降低并发如果 GPU 利用率不高但响应慢看编排层的 CPU 和内存占用可能是 Agent 逻辑太重如果两者都不高看网络延迟可能是容器网络模式或跨机访问的问题最后看磁盘 IO会话数据读写频繁时机械硬盘可能成为瓶颈。我遇到过最隐蔽的一次性能问题是日志文件写满了磁盘导致所有服务响应变慢。后来加了日志轮转问题再没出现过。6. 后续扩展与个人经验分享平台跑通之后能扩展的方向其实很多。比如把 Agent 接入内部的聊天工具让团队成员在熟悉的界面里直接使用比如给 Agent 加上知识库检索能力让它能回答基于内部文档的问题比如做多 Agent 协作一个负责拆解任务一个负责执行一个负责检查结果。但我想说的是扩展的前提是核心链路足够稳定。我见过太多项目基础还没打牢就急着加功能最后问题叠问题维护成本高到没人愿意碰。先把推理层和编排层跑稳把日志和监控做好把常见问题的排查流程固化下来再去想那些花哨的东西。另外一个小技巧给推理服务和编排服务分别打上版本 tag每次升级前先备份配置和数据。我有一次升级编排框架新版本改了配置格式结果容器起不来幸好旧镜像还在五分钟就回滚了。这种保险措施平时感觉多余出事的时候能救命。最后分享一个我自己的习惯在/opt/ai-platform下放一个README.md记录当前部署的版本、端口、配置要点、常见问题处理方式。过几个月再回来看或者换人来维护这份记录能省下大量时间。部署文档不是写给别人的是写给未来的自己的。