1. 为什么要在隔离内网里折腾 AI Agent先把场景说清楚。所谓隔离内网就是那种物理上跟公网断开、或者只允许单向数据摆渡的环境常见于金融、制造、能源、科研院所这类对数据外流极度敏感的机构。你在这种环境里想跑一个 AI Agent第一反应通常是模型怎么进来依赖怎么装工具怎么调这三个问题任何一个卡住整个工程就停在原地。我前后在三个不同规模的内网环境里落地过 Agent 项目从最初级的单机跑个问答机器人到后来多 Agent 协作处理工单流踩的坑足够写一本小册子。这篇就把整套方法论摊开讲围绕AI Agent、MCP、内网、工程实战、Skills这几个核心词把从零到跑通的完整路径拆给你看。适合谁看如果你手上有内网服务器、有一块能用的 GPU 或者哪怕只有 CPU、并且被要求数据不出内网那这篇就是写给你的。不需要你事先懂 MCP 协议细节也不需要你玩过多 Agent 框架我会把每个决策背后的理由讲透让你能直接抄作业。核心结论先放这儿内网 Agent 工程的难点从来不是模型本身而是依赖闭环、工具协议、以及可观测性这三件事。把这三件事解决剩下的都是体力活。2. 内网 Agent 的整体架构设计与选型逻辑2.1 三种典型部署形态与适用边界内网环境千差万别我把它归成三类你对号入座。形态网络条件典型硬件适合的 Agent 规模主要痛点单机离线完全物理隔离单台带 GPU 工作站单 Agent、单轮任务模型与依赖全靠摆渡内网集群内网互通、无外网多台服务器 共享存储多 Agent、并发任务服务发现、资源调度半隔离有受控出口或镜像源混合中等规模出口策略、审计我最早做的是单机离线形态一台 4090 工作站模型权重用移动硬盘拷进去Python 依赖提前在外网机器上pip download打成离线包。这种形态最纯粹也最能暴露依赖闭环这个核心问题。后来做内网集群才引入 MCP 做工具标准化因为多 Agent 之间要共享工具能力硬编码调用根本维护不动。选型的第一原则能单机就别集群。很多人一上来就想搞分布式 Agent 编排结果连一个模型服务都没跑稳。内网环境的调试成本极高每改一次配置可能要重新走一遍摆渡流程所以架构越简单越好。2.2 模型层本地推理服务怎么选模型这块内网里你基本只有两条路本地跑开源权重或者内网自建的推理网关。后者通常是单位统一部署的你只管调 API。如果是前者选型要考虑三件事——显存、量化、推理框架。显存是硬约束。一个 7B 模型 FP16 大概要 14GB 显存INT4 量化后压到 4GB 左右。我实测下来如果只有单张 24GB 卡跑 14B 的 INT4 量化模型是比较舒服的平衡点留出余量给 KV Cache 和并发。32B 以上就得上多卡或者更激进的量化质量损失开始明显。推理框架我推荐vLLM或llama.cpp二选一。vLLM 吞吐高、支持连续批处理适合有并发需求的场景llama.cpp 部署简单、CPU 也能跑、量化格式丰富适合单机轻量场景。内网里 vLLM 的坑在于它依赖一堆 CUDA 相关的 wheel离线安装时版本对齐很折磨我后面会专门讲。提示内网选模型不要盲目追大。我见过有人硬上 70B结果单次推理 30 秒Agent 的多轮工具调用直接超时。7B 到 14B 的量化模型配合好的提示词工程在多数企业任务上够用。2.3 工具层为什么 MCP 是内网 Agent 的关键拼图MCP 全称 Model Context Protocol你可以把它理解成Agent 和外部工具之间的 USB 接口。在没有 MCP 之前每个 Agent 要调数据库、调文件系统、调内部 API都得写一套专属的适配代码工具一多就是灾难。MCP 把这些能力抽象成标准协议Agent 只要会说 MCP就能接任何实现了 MCP 的工具服务。内网场景下 MCP 的价值被放大了。因为内网工具往往是异构的——有老掉牙的 SOAP 接口、有只能命令行调用的脚本、有需要特定认证的内部系统。如果每个都硬编码进 Agent代码会烂成一团。用 MCP 把它们统一封装成 ServerAgent 侧只维护一份客户端逻辑扩展性完全不一样。MCP 的核心概念就三个Resources资源只读数据、Tools工具可执行动作、Prompts提示模板。Agent 通过标准化的 JSON-RPC 跟 MCP Server 通信Server 负责把请求翻译成对内部系统的实际操作。这个抽象层是内网 Agent 工程能规模化的前提。2.4 Skills把领域知识沉淀成可复用资产Skills 这个词最近很热本质上是把特定任务的提示词、工具组合、执行流程打包成一个可复用的能力单元。比如生成周报是一个 Skill查询库存并生成补货建议是另一个 Skill。Agent 面对任务时先匹配 Skill再按 Skill 定义的流程执行。内网里 Skills 的意义在于知识沉淀。一个老师傅知道怎么处理某类工单你把这套经验写成 SkillAgent 就能复现。Skills 通常以文件形式存在Markdown 或 YAML 描述 配套脚本天然适合内网的版本管理和摆渡分发。我一般把 Skills 分成三层原子 Skill单个工具调用、组合 Skill多工具编排、领域 Skill带业务规则的完整流程。分层的好处是复用原子 Skill 能被多个组合 Skill 引用改一处全局生效。3. 离线依赖闭环内网工程的第一道生死关3.1 依赖摆渡的完整流程内网装不了包这是所有痛苦的根源。我的标准做法是外网准备、离线打包、内网还原三步走。外网准备阶段在一台跟内网目标机器操作系统版本、Python 版本、架构完全一致的机器上操作。这一步极其关键我踩过最惨的坑就是外网用 Ubuntu 22.04 打包内网是 CentOS 7glibc 版本不兼容一堆 wheel 装不上。所以第一件事是确认内网机器的uname -a、python --version、pip --version。打包命令的核心是pip download# 在外网机器上执行下载所有依赖到本地目录 pip download -r requirements.txt -d ./offline_packages \ --platform manylinux2014_x86_64 \ --python-version 310 \ --only-binary:all:这里--platform和--python-version必须跟内网目标严格匹配。--only-binary:all:强制只下载预编译 wheel避免下载源码包导致内网编译失败。如果某些包没有对应平台的 wheel就得单独处理要么找替代包要么在外网交叉编译好再拷进去。内网还原时pip install --no-index --find-links./offline_packages -r requirements.txt--no-index禁止访问任何在线源--find-links指向本地包目录。这样即使内网有残留的 pip 配置指向外网也不会触发网络请求。3.2 CUDA 与深度学习框架的版本对齐这是内网 Agent 工程里最容易翻车的部分。PyTorch、CUDA、cuDNN、驱动四者版本必须严格对齐错一个就是CUDA error: no kernel image is available。我的对齐策略是以驱动版本为锚点倒推。先在内网机器上跑nvidia-smi看驱动版本和它支持的最高 CUDA 版本。然后选一个不超过这个上限的 CUDA 版本再选对应这个 CUDA 编译的 PyTorch wheel。驱动版本支持最高 CUDA推荐 PyTorch535.x12.22.1.x / 2.2.x525.x12.02.0.x / 2.1.x470.x11.41.13.x下载 PyTorch 时一定要用官方指定的 index URL比如https://download.pytorch.org/whl/cu121这样拿到的 wheel 是预编译好对应 CUDA 的。离线打包时把这个 index 下的包全下下来。注意vLLM 对 PyTorch 和 CUDA 版本极其敏感它的 wheel 通常绑定特定 torch 版本。装 vLLM 之前先把 torch 版本定死然后找匹配的 vLLM wheel不要反过来。3.3 模型权重的摆渡与校验模型权重动辄几个 GB 到几十 GB摆渡是个体力活。我的做法是分片压缩 校验和。# 外网侧分片压缩 tar -czf model.tar.gz -C ./model_dir . split -b 2G model.tar.gz model_part_ # 生成校验文件 sha256sum model_part_* checksums.txt内网侧先校验再合并sha256sum -c checksums.txt cat model_part_* model.tar.gz tar -xzf model.tar.gz -C ./model_dir校验这一步千万别省。我有一次摆渡 40GB 权重中间一个分片损坏加载时报了个莫名其妙的 shape mismatch排查了大半天才发现是文件坏了。从那以后校验和成了我的肌肉记忆。4. MCP 服务在内网的落地实操4.1 MCP Server 的最小实现MCP Server 本质是一个实现了标准协议的进程对外暴露 Resources、Tools、Prompts。用 Python 写一个最小 Server 大概长这样from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent app Server(internal-tools) app.list_tools() async def list_tools(): return [ Tool( namequery_inventory, description查询内部库存系统, inputSchema{ type: object, properties: { sku: {type: string, description: 商品编码} }, required: [sku] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name query_inventory: result do_internal_query(arguments[sku]) return [TextContent(typetext, textresult)] async def main(): async with stdio_server() as (read, write): await app.run(read, write, app.create_initialization_options())这个 Server 通过 stdio 跟 Agent 通信Agent 启动时把它作为子进程拉起。内网里 stdio 传输最省事不涉及端口和网络配置。4.2 把异构内部系统封装成 MCP Tool内网工具千奇百怪封装的核心思路是在 MCP Server 内部做适配对外只暴露干净的接口。比如一个只能命令行调用的老系统Server 内部用subprocess调它解析输出转成结构化文本返回。一个需要认证的内部 APIServer 内部维护 token 刷新逻辑Agent 完全无感。一个数据库查询Server 内部管理连接池避免每次调用都重连。我封装过一个特别恶心的场景内部系统只提供 Windows 客户端没有 API。最后的方案是在一台 Windows 机器上跑一个 MCP Server用 UI 自动化脚本操作客户端Server 通过内网 HTTP 暴露给 Linux 上的 Agent。虽然丑但能跑通这就是内网工程的现实。提示MCP Server 的粒度要适中。太细会导致 Agent 要调几十次工具才能完成一个任务太粗则失去灵活性。我的经验是一个 Tool 对应一个业务动作比如查询订单是一个 Tool取消订单是另一个而不是把整个订单系统塞进一个 Tool。4.3 MCP 通信方式的选择stdio 还是 SSEMCP 支持多种传输方式内网里主要用两种stdio和SSEServer-Sent Events。stdio 适合 Agent 和 Server 在同一台机器、Server 生命周期跟 Agent 绑定的场景。优点是零网络配置、启动简单。缺点是 Server 崩溃会拖垮 Agent且无法跨机器共享。SSE 适合 Server 独立部署、多个 Agent 共享的场景。Server 跑成一个 HTTP 服务Agent 通过 URL 连接。内网里 SSE 要注意端口规划和防火墙策略但一旦跑通扩展性远好于 stdio。我的选择逻辑单机单 Agent 用 stdio集群多 Agent 用 SSE。混合场景可以两者并存核心工具用 SSE 共享私有工具用 stdio 本地拉起。5. Skills 工程化从提示词到可复用能力5.1 Skill 的文件结构设计一个规范的 Skill 应该包含描述文件、提示词模板、以及可选的配套脚本。我用的结构是这样skills/ inventory_replenish/ SKILL.md # 描述、触发条件、执行流程 prompt.md # 提示词模板 scripts/ calc_safety_stock.py config.yaml # 参数配置SKILL.md是核心用自然语言描述这个 Skill 干什么、什么时候触发、需要哪些工具、执行步骤是什么。Agent 加载 Skills 时先读这个文件做匹配。# 库存补货建议 ## 触发条件 用户询问某商品是否需要补货或要求生成补货计划。 ## 所需工具 - query_inventory - query_sales_history - calc_safety_stock ## 执行流程 1. 调用 query_inventory 获取当前库存 2. 调用 query_sales_history 获取近 30 天销量 3. 调用 calc_safety_stock 计算安全库存 4. 对比当前库存与安全库存生成建议这种结构的好处是人可读、机可解析。新同事看一遍就知道这个 Skill 怎么工作Agent 也能从中提取执行逻辑。5.2 Skill 的匹配与调度机制Agent 面对一个任务怎么知道该用哪个 Skill我实践下来有两套机制。第一套是关键词匹配简单粗暴但有效。Skill 的SKILL.md里定义触发关键词Agent 收到任务后做字符串匹配命中就加载。适合 Skill 数量少几十个以内的场景。第二套是向量检索把所有 Skill 的描述向量化任务来了先做语义检索取 Top-K 候选再让模型选。适合 Skill 上百个的场景。内网里做向量检索需要本地 embedding 模型我一般用 BGE 系列的小模型几百 MBCPU 也能跑。调度上要注意Skill 的优先级和互斥。有些 Skill 不能同时激活比如查询模式和修改模式的 Skill 同时加载会让 Agent 行为混乱。我在 Skill 配置里加了exclusive_group字段同组的 Skill 只能激活一个。5.3 用 Skills 沉淀领域知识的实战案例讲个真实案例。某制造企业内部有个设备故障诊断流程老师傅凭经验听声音、看参数就能判断故障类型。我们把这套经验拆成了 5 个原子 Skill 和 1 个组合 Skill。原子 Skill 包括读取设备实时参数、查询历史故障记录、匹配故障特征库、生成诊断报告、推送工单。组合 Skill 定义诊断流程先读参数再查历史匹配特征库如果置信度高就生成报告否则推送人工工单。上线后Agent 处理常见故障的准确率到了 80% 以上老师傅只需要处理疑难杂症。关键是这套 Skill 是可迭代的——每次老师傅纠正了 Agent 的判断我们就更新特征库Agent 越来越准。提示Skill 的迭代要有版本管理。内网里用 Git 做本地仓库就行每次修改打 tag出问题能回滚。我见过有人直接改线上 Skill 文件改崩了没法恢复血的教训。6. 并发与性能内网 Agent 扛并发的实战调优6.1 并发瓶颈到底在哪很多人一上来就优化模型推理其实内网 Agent 的并发瓶颈往往不在模型而在工具调用的串行等待。一个任务要调 5 个工具每个工具平均 2 秒串行就是 10 秒模型推理可能只占 1 秒。所以优化的第一优先级是工具调用并行化。MCP 协议本身支持并发调用Agent 框架要能把无依赖的工具调用并发发出去。比如查询库存和查询销量没有依赖关系可以同时发等两个都回来再算安全库存。第二优先级是连接复用。MCP Server 到内部系统的连接要池化别每次调用都新建连接。数据库连接池、HTTP 连接池都是标配。第三优先级才是模型推理优化。vLLM 的连续批处理能把并发吞吐拉高好几倍但前提是你的请求能批起来。如果 Agent 是串行发请求批处理也救不了。6.2 实测并发参数与压测方法我在一台 4090 上做过压测模型是 14B INT4vLLM 部署。测试不同并发下的表现并发数平均延迟吞吐 (tokens/s)显存占用11.2s4512GB41.8s14016GB83.5s21020GB168.2s23023GB可以看到并发到 8 以后延迟上升明显吞吐增长放缓。这就是显存和计算资源的边界。生产环境我一般把并发控制在 4 到 8 之间留出余量应对突发。压测工具用locust或自己写脚本都行关键是模拟真实任务分布。别只压单轮问答要压带工具调用的多轮任务否则测出来的数字没意义。6.3 限流、降级与超时策略内网资源有限必须有保护机制。限流Agent 入口做令牌桶限流超过阈值的请求排队或拒绝。我一般按 GPU 显存反推最大并发再打个 7 折作为限流阈值。降级模型服务挂了怎么办我的做法是准备一个规则引擎兜底简单任务走规则复杂任务才走模型。模型不可用时自动切到规则模式保证核心功能不中断。超时每个工具调用都要设超时别让一个卡死的工具拖垮整个 Agent。我一般设 10 秒超时后返回错误让 Agent 决定重试还是放弃。模型推理超时设 30 秒超过就中断。import asyncio async def call_tool_with_timeout(tool, args, timeout10): try: return await asyncio.wait_for(tool.call(args), timeouttimeout) except asyncio.TimeoutError: return {error: tool_timeout, tool: tool.name}这套组合拳下来Agent 在资源受限的内网里也能稳定扛住日常负载。7. 常见问题与排查技巧实录7.1 依赖与模型加载类问题问题ImportError: libcudart.so.12: cannot open shared object file这是 CUDA 运行时库没找到。排查顺序先ldconfig -p | grep cudart看系统里有没有没有就说明 CUDA toolkit 没装或路径没配。内网里最省事的做法是把 CUDA 库路径加到LD_LIBRARY_PATH或者干脆用 conda 装一个自带 CUDA 运行时的环境。问题模型加载报shape mismatch或unexpected key九成是权重文件损坏或版本不匹配。先校验文件 sha256再确认模型权重和推理框架版本匹配。我遇到过用新版 vLLM 加载旧版权重的情况报错信息完全看不出是版本问题折腾很久。问题pip install报Could not find a version that satisfies the requirement离线安装时这个错误通常是 wheel 的平台标签不匹配。用pip debug --verbose看当前环境支持的平台标签再对比下载的 wheel 文件名。不匹配就重新下载对应平台的。7.2 MCP 通信类问题问题Agent 启动 MCP Server 后无响应先确认 Server 进程是否真的起来了ps aux | grep mcp看一眼。如果进程在但无响应多半是 stdio 缓冲问题。Python 的 stdout 默认带缓冲MCP 通信要强制刷新。在 Server 入口加sys.stdout.reconfigure(line_bufferingTrue)或启动时加-u参数。问题SSE 模式下 Agent 连不上 Server排查三步Server 是否监听正确端口netstat -tlnp、防火墙是否放行、Agent 配置的 URL 是否正确。内网里经常是防火墙问题尤其是跨网段访问。问题工具调用返回乱码编码问题。MCP 默认 UTF-8但内部系统可能返回 GBK。在 Server 里统一做编码转换别指望 Agent 侧处理。7.3 性能与稳定性类问题问题Agent 跑一段时间后变慢先看显存是不是泄漏了。vLLM 长时间运行可能有 KV Cache 碎片定期重启服务能缓解。再看工具连接池是不是满了连接没释放会耗尽池子。问题并发高了以后任务失败率上升大概率是超时设置太紧。并发高时每个请求的排队时间变长原来的超时阈值不够用。动态调整超时或者加排队机制。问题Skill 匹配错误Agent 用了不该用的 Skill检查 Skill 的触发关键词是否过于宽泛。我遇到过查询这个词被三个 Skill 同时命中Agent 随机选了一个。解决办法是给关键词加权重或者用更具体的触发条件。7.4 问题速查表现象可能原因排查动作模型加载失败权重损坏/版本不匹配校验 sha256核对版本MCP 无响应stdio 缓冲/进程未起检查进程加 -u 参数工具调用超时内部系统慢/连接池满看连接池调超时并发失败率高超时太紧/资源不足动态超时限流Skill 匹配错关键词冲突加权重细化触发条件显存溢出并发过高/泄漏降并发定期重启8. 内网 Agent 工程的可观测性建设内网里没有现成的 APM 工具可观测性得自己搭。我的最小方案是结构化日志 本地指标 简单看板。日志用 JSON 格式每条记录包含时间戳、任务 ID、Agent 状态、工具调用、耗时、结果。这样出问题能快速定位是哪个环节慢。日志写到本地文件按天轮转别写数据库内网数据库资源紧张。指标用 Prometheus 的 Python 客户端暴露本地起一个 Prometheus 抓取Grafana 做看板。核心指标包括任务成功率、平均延迟、工具调用分布、模型推理耗时、显存占用。这套东西在内网里跑完全没问题都是本地服务。from prometheus_client import Counter, Histogram task_total Counter(agent_task_total, Total tasks, [status]) task_duration Histogram(agent_task_duration_seconds, Task duration) tool_calls Counter(agent_tool_calls_total, Tool calls, [tool_name])看板上我最关注三个图任务成功率趋势、P95 延迟趋势、工具调用热力图。成功率掉了说明有系统性问题延迟涨了说明资源紧张工具热力图能看出哪些工具是瓶颈。提示内网日志要注意脱敏。Agent 处理的可能是敏感业务数据日志里别记原始内容记哈希或摘要就行。这是合规底线。9. 我踩过的几个大坑与经验总结第一个坑是过早引入多 Agent。我一开始就搞了 Planner、Executor、Reviewer 三个 Agent 协作结果调试成本爆炸一个任务出问题要追三个 Agent 的日志。后来退回单 Agent Skills 架构反而稳定高效。多 Agent 不是不能用但要在单 Agent 确实扛不住复杂任务时才上。第二个坑是忽视 Skill 的版本管理。早期直接改线上 Skill 文件有次改错了一个计算逻辑Agent 连续给出错误建议等发现时已经影响了一批工单。现在所有 Skill 改动都走 Git改完先在测试环境验证再合并到生产。第三个坑是模型选型贪大。为了追求效果上了 32B 模型结果单次推理 5 秒多轮任务直接超时。换成 14B 量化模型后配合更好的提示词效果没差多少速度翻了三倍。内网场景下响应速度往往比模型能力更重要。第四个坑是没做工具调用的幂等。Agent 重试机制触发后同一个创建工单工具被调了两次产生了重复工单。后来所有写操作工具都加了幂等键重试时先查再写。这些坑的共同点是都是工程问题不是 AI 问题。内网 Agent 工程的本质是把 AI 能力塞进一个受限的工程环境里工程功底比 AI 知识更决定成败。最后分享一个实用技巧内网里准备一个应急 Skill 包包含最基础的几个工具文件读写、简单查询、日志查看当复杂 Skill 出问题时能快速降级到基础能力保证 Agent 不完全瘫痪。这个包我建议单独维护别跟业务 Skill 混在一起出问题时能快速定位和恢复。