企业官网建设流程全解析

1. 隔离内网下的 AI Agent 工程化落地：从零搭建到稳定运行

在完全隔离的内网环境里跑 AI Agent，和在外网环境里跑完全是两码事。外网环境里，你随手pip install一个包、拉一个镜像、调一个云端 API，几分钟就能跑通一个 Demo。但到了隔离内网，没有外网出口、没有公共镜像源、没有云端大模型接口，甚至连pip和npm都得靠离线包搬运，这时候你会发现，真正卡住你的从来不是 Agent 的算法逻辑，而是工程链路怎么在“断网”的前提下完整闭环。

我前后在三个不同规模的内网环境里落地过 AI Agent 项目，踩过的坑从依赖缺失、模型权重搬运、MCP 服务注册失败，到 Skills 加载路径错乱、并发一上来就雪崩，几乎把能踩的都踩了一遍。这篇内容就是把这些经验系统性地整理出来，讲清楚在隔离内网下，一个可用的 AI Agent 工程到底该怎么搭、怎么调、怎么扛住并发。不管你是刚接触 AI Agent 的新手，还是已经在外网跑通过 Demo、准备往内网迁移的老手，都能从里面找到可以直接抄作业的部分。

核心关键词会贯穿全文：AI Agent、MCP、内网、工程实战、Skills。我会从整体架构设计讲到具体参数配置，从依赖离线化讲到并发压测，尽量把每个“为什么这么做”都讲透，而不是只丢一堆命令让你自己猜。

2. 内网 AI Agent 的整体架构设计与选型思路

2.1 为什么内网 Agent 不能照搬外网方案

外网环境下搭 AI Agent，绝大多数人的路径是这样的：选一个云端大模型 API（比如各种在线推理服务），用 LangChain 或类似框架串起来，工具调用直接走 HTTP 请求，MCP 服务本地起一个进程注册进去，Skills 从官方市场直接拉。整条链路依赖大量外部服务，任何一个环节断网，整个 Agent 就瘫了。

内网环境的核心约束有三个：没有外网出口、没有公共依赖源、算力和存储资源有限。这三个约束直接决定了架构必须做减法。你不能指望 Agent 去调云端模型，必须把模型权重搬到内网本地部署；你不能指望pip install自动解决依赖，必须提前把所有 wheel 包和系统库打包搬运；你也不能指望 MCP 服务从公网注册，必须在内网自建注册中心或者用本地进程通信。

我见过太多团队在内网迁移时翻车，根本原因就是架构设计阶段还在用外网思维。比如有人直接把外网的requirements.txt拷进内网，结果发现里面一半的包依赖编译工具链，内网机器上连gcc都没装。还有人把 MCP 服务配置写成公网地址，内网一跑就超时，排查半天才发现是网络层根本不通。

所以内网 Agent 架构设计的第一原则是：所有外部依赖必须提前离线化，所有网络通信必须限定在内网可达范围内。这不是优化项，是生死线。

2.2 分层架构：把 Agent 拆成可独立部署的模块

我在内网落地时采用的是一种分层架构，把整个 Agent 系统拆成四层，每层可以独立部署、独立升级，互不干扰。这种设计的好处是，当某一层出问题时，你能快速定位，而不是面对一个黑盒干瞪眼。

模型推理层是整个系统的算力底座。内网环境下，你大概率只能用开源模型本地部署，比如用 vLLM 或者类似的推理框架起一个服务。这里的关键是显存预估和量化选型。一个 7B 参数的模型，FP16 精度大概需要 14GB 显存，INT8 量化后降到 7GB 左右，INT4 能压到 4GB 以内。如果你的内网机器只有一张 16GB 显存的卡，那 7B FP16 勉强能跑但并发一上来就爆，这时候就得考虑量化或者换更小的模型。

Agent 编排层负责把用户请求拆解成可执行的任务序列，调度工具调用，管理对话上下文。这一层我建议用成熟的框架，但一定要把框架的所有依赖提前离线化。LangChain、LangGraph 这类框架依赖包很多，内网安装时经常缺这个少那个，提前用pip download把所有依赖拉到本地目录，再整体搬运是最稳妥的做法。

工具与 MCP 层是内网 Agent 最容易出问题的部分。MCP（Model Context Protocol）本质上是一套让模型和外部工具通信的协议，外网环境下你可以直接连公网的 MCP 服务，但内网必须自建。我的做法是在内网起一个 MCP 注册中心，所有工具服务注册到内网地址，Agent 通过内网 IP 访问。这里要特别注意，任何配置里出现公网域名或 IP 都要改成内网地址，否则运行时会一直超时。

Skills 层是可复用的技能模块，比如“查询数据库”“生成报表”“发送通知”这类封装好的能力。内网环境下，Skills 不能从官方市场拉，必须提前下载好放到本地目录，Agent 启动时从本地路径加载。版本管理要严格，不同版本的 Skill 接口可能不兼容，建议用版本号目录隔离。

2.3 模型选型：内网环境下怎么挑一个能扛住的模型

内网模型选型要考虑三个维度：参数量、量化精度、推理框架兼容性。参数量决定能力上限，量化精度决定显存占用，推理框架兼容性决定你能不能顺利部署。

我的经验是，内网 Agent 场景下，7B 到 14B 参数的模型是甜点区。7B 模型在 INT4 量化下只需要 4GB 左右显存，一张消费级显卡就能跑，适合资源紧张的环境。14B 模型能力明显更强，但 INT4 量化后也要 8GB 以上显存，需要至少一张 16GB 的卡。再往上 32B、70B，内网单机基本扛不住，除非你有多个 GPU 做张量并行。

量化精度方面，INT4 是内网部署的性价比之选。相比 FP16，INT4 能把显存占用压到四分之一，推理速度也有提升，代价是精度损失。实测下来，INT4 量化的 7B 模型在工具调用、任务规划这类结构化任务上表现够用，但在需要精细语义理解的场景下会打折扣。如果你的任务对精度要求高，可以考虑 INT8，显存占用是 INT4 的两倍，但精度损失小很多。

推理框架我推荐 vLLM，它对量化模型支持好，并发吞吐也强。内网部署时，vLLM 的依赖也要提前离线化，包括 CUDA 相关的库。这里有个坑：vLLM 对 CUDA 版本有要求，内网机器的驱动版本如果太老，可能装不上。提前确认驱动版本，必要时升级驱动，这一步不能省。

3. 依赖离线化：内网工程化的第一道坎

3.1 Python 依赖的完整离线搬运方案

内网 Python 依赖离线化，核心思路是“在外网机器上下载所有依赖，打包搬运到内网，再离线安装”。听起来简单，但实际操作时坑很多。

第一步是在外网机器上准备一个和內网机器操作系统版本、Python 版本、CPU 架构完全一致的环境。这一步极其关键，因为 wheel 包是分平台和 Python 版本的，你在 Ubuntu 22.04 + Python 3.10 上下载的包，搬到 CentOS 7 + Python 3.8 上大概率装不上。我踩过这个坑，当时外网用的是 Python 3.11，内网是 3.9，结果一半的包因为 ABI 不兼容直接报错，只能重新下载。

确认环境一致后，用pip download把所有依赖下载到本地目录：

pip download -r requirements.txt -d ./offline_packages --platform manylinux2014_x86_64 --python-version 39 --only-binary=:all:

这里--platform和--python-version要和你内网环境匹配。--only-binary=:all:强制只下载二进制包，避免下载源码包后在内网编译时缺工具链。

下载完成后，把offline_packages目录整体打包，通过内网允许的方式搬运进去。内网安装时用：

pip install --no-index --find-links=./offline_packages -r requirements.txt

--no-index禁用在线索引，--find-links指定本地包目录。这样 pip 就只从本地找包，不会尝试联网。

注意：有些包依赖系统级的库，比如psycopg2依赖libpq-dev，lxml依赖libxml2-dev。这些系统库没法用 pip 离线化，必须提前在内网机器上装好。建议在外网环境里用ldd检查每个二进制依赖，把需要的系统库列一个清单，提前在内网装齐。

3.2 模型权重的搬运与校验

模型权重文件通常很大，7B 模型 FP16 大概 14GB，INT4 量化后 4GB 左右。搬运方式取决于内网允许的介质，常见的有移动硬盘、内网文件服务器、或者专用的数据摆渡设备。

搬运前一定要做完整性校验。大文件在传输过程中损坏的概率不低，尤其是用移动硬盘多次拷贝时。我的做法是生成 SHA256 校验和，搬运到内网后重新计算比对：

# 外网生成校验和 sha256sum model_weights.bin > model_weights.sha256 # 内网校验 sha256sum -c model_weights.sha256

如果校验不通过，说明文件损坏，必须重新搬运。我遇到过好几次因为硬盘坏道导致模型文件损坏，加载时报奇怪的错误，排查半天才发现是文件本身的问题。

模型权重放好后，还要确认推理框架能正确加载。不同框架对权重格式要求不同，vLLM 支持 HuggingFace 格式，如果你的权重是其他格式，可能需要转换。转换工具也要提前离线化，别等到内网才发现缺工具。

3.3 MCP 服务的内网注册与配置

MCP 服务在内网部署时，最大的问题是注册中心。外网环境下，MCP 服务可以注册到公网注册中心，Agent 通过公网地址发现服务。内网没有公网，必须自建注册中心。

我的做法是在内网起一个轻量的注册服务，所有 MCP 工具服务启动时向它注册自己的内网地址和端口。Agent 启动时从注册中心拉取可用服务列表。注册中心本身可以用 Redis 或者简单的 HTTP 服务实现，关键是所有地址必须是内网可达的。

配置 MCP 服务时，要特别注意超时设置。内网网络虽然稳定，但如果某个工具服务响应慢，Agent 可能会一直等待。建议给每个 MCP 调用设置合理的超时，比如 30 秒，超时后返回错误而不是无限等待。

{ "mcp_servers": { "database_tool": { "url": "http://10.0.1.100:8080/mcp", "timeout": 30, "retry": 2 }, "file_tool": { "url": "http://10.0.1.101:8080/mcp", "timeout": 15, "retry": 1 } } }

提示：内网 IP 段要提前规划好，避免和现有服务冲突。我见过有人把 MCP 服务配到和数据库同一个 IP 段，结果端口冲突，排查了很久。

4. Skills 模块的内网加载与版本管理

4.1 Skills 的本地目录结构与加载机制

Skills 是 AI Agent 可复用能力的封装，内网环境下不能从官方市场拉取，必须提前下载好放到本地目录。我采用的目录结构是这样的：

skills/ ├── v1.0.0/ │ ├── database_query/ │ │ ├── manifest.json │ │ └── handler.py │ ├── report_generate/ │ │ ├── manifest.json │ │ └── handler.py ├── v1.1.0/ │ ├── database_query/ │ │ ├── manifest.json │ │ └── handler.py

每个 Skill 有一个manifest.json描述元信息，包括名称、版本、入参、出参、依赖。handler.py是具体实现。Agent 启动时扫描skills目录，根据配置加载指定版本的 Skill。

版本隔离很重要。不同版本的 Skill 接口可能不兼容，如果混在一起加载，运行时会出现参数对不上的错误。用版本号目录隔离，Agent 配置里指定用哪个版本，升级时切换目录即可，回滚也方便。

4.2 Skills 依赖的离线化处理

Skills 本身可能依赖额外的 Python 包或系统工具。比如一个“生成 PDF 报表”的 Skill 可能依赖reportlab，一个“图片处理”的 Skill 可能依赖Pillow。这些依赖也要提前离线化，和主程序的依赖一起打包。

我的做法是给每个 Skill 单独维护一个requirements.txt，在外网环境里把所有 Skill 的依赖合并下载，统一搬运。内网安装时，先装主程序依赖，再装 Skill 依赖，避免版本冲突。

如果不同 Skill 依赖同一个包的不同版本，这就麻烦了。Python 的依赖隔离做得不好，同一个环境里只能装一个版本。遇到这种情况，要么统一版本，要么用虚拟环境隔离。内网环境下我建议统一版本，因为虚拟环境管理成本高，而且 Agent 加载 Skill 时跨环境调用也麻烦。

4.3 Skills 的测试与验证

Skills 搬到内网后，不能直接上生产，必须先测试。我一般会写一个简单的测试脚本，逐个调用每个 Skill，验证入参出参是否符合预期。

import json from skills.loader import load_skill def test_skill(skill_name, version, test_input): skill = load_skill(skill_name, version) result = skill.execute(test_input) print(f"Skill: {skill_name} v{version}") print(f"Input: {json.dumps(test_input, ensure_ascii=False)}") print(f"Output: {json.dumps(result, ensure_ascii=False)}") print("---") test_skill("database_query", "v1.0.0", {"sql": "SELECT 1"}) test_skill("report_generate", "v1.0.0", {"template": "daily", "data": {}})

测试时要注意边界情况，比如空输入、超长输入、特殊字符。内网环境里数据往往比较特殊，外网测试通过不代表内网也能通过。

注意：Skills 测试要在内网真实环境里做，不要在外网模拟。内网的文件路径、数据库连接、权限配置都可能和外网不同，外网测试通过只是第一步。

5. 并发扛压：AI Agent 在内网怎么稳住

5.1 并发瓶颈到底在哪里

AI Agent 的并发瓶颈通常不在 Agent 编排层，而在模型推理层。Agent 编排层是轻量的逻辑处理，单机扛几百 QPS 没问题。模型推理层才是重头，每次推理都要占用 GPU 显存和计算资源，并发一上来就容易排队甚至 OOM。

我实测过一个 7B INT4 模型在单张 16GB 显卡上的表现：单请求推理延迟大概 1 到 2 秒，并发 4 个请求时延迟涨到 3 到 4 秒，并发 8 个时延迟超过 8 秒，并发 16 个直接 OOM。所以内网 Agent 的并发能力，本质上取决于模型推理层的吞吐。

除了模型推理，MCP 工具调用也可能成为瓶颈。如果某个工具服务响应慢，Agent 会一直等待，占用连接资源。并发高的时候，连接池耗尽，后续请求全部阻塞。

5.2 模型推理层的并发优化

模型推理层的并发优化，核心是批处理和量化。批处理是把多个请求合并成一个批次一起推理，充分利用 GPU 并行能力。vLLM 支持连续批处理，能动态合并请求，吞吐比单请求串行高好几倍。

量化方面，INT4 比 FP16 显存占用低，能支持更高并发。如果显存实在紧张，可以考虑用更小的模型，比如 3B 参数，虽然能力弱一些，但并发能力强很多。

配置 vLLM 时，关键参数是max_num_seqs和gpu_memory_utilization。max_num_seqs控制最大并发序列数，设太小并发上不去，设太大容易 OOM。gpu_memory_utilization控制显存使用比例，一般设 0.9 左右，留一点余量给系统。

python -m vllm.entrypoints.openai.api_server \ --model /path/to/model \ --max-num-seqs 16 \ --gpu-memory-utilization 0.9 \ --quantization awq

--quantization awq指定量化方式，AWQ 是常见的 INT4 量化方案。如果你的模型是 GPTQ 量化，改成--quantization gptq。

5.3 Agent 层的限流与降级

模型推理层优化到位后，Agent 层还要做限流和降级，防止突发流量把系统打垮。限流可以用令牌桶算法，控制每秒进入的请求数。降级是在系统压力大时，暂时关闭非核心功能，保证核心功能可用。

我的做法是在 Agent 入口加一个限流中间件，超过阈值的请求直接返回“系统繁忙，请稍后重试”，而不是让它排队等待。这样虽然会拒绝一部分请求，但能保证已进入的请求能正常处理，整体体验更好。

from ratelimit import limits, sleep_and_retry @sleep_and_retry @limits(calls=10, period=1) def handle_request(request): # 处理请求 pass

降级策略要根据业务定。比如一个 Agent 同时支持“查询”和“报表生成”两个功能，压力大时可以暂时关闭“报表生成”，只保留“查询”。降级开关可以做成配置项，运行时动态调整。

5.4 压测方案与指标监控

内网上线前一定要做压测，摸清系统的并发上限。压测工具可以用locust或者wrk，模拟不同并发数下的请求，观察延迟和错误率。

压测时要监控几个关键指标：请求延迟（P50、P95、P99）、错误率、GPU 显存占用、GPU 利用率、MCP 调用延迟。这些指标能帮你定位瓶颈在哪一层。

压测发现瓶颈后，针对性优化。如果是模型推理排队，增加max_num_seqs或者换更小的模型。如果是 MCP 延迟高，优化工具服务或者增加超时重试。

6. 常见问题与排查技巧实录

6.1 依赖安装失败：从报错到解决

内网装依赖失败是最常见的问题，报错五花八门。我整理了一个速查表，覆盖大部分场景。

我遇到最多的是No matching distribution found，根本原因就是外网下载时平台参数没设对。解决方法是确认内网机器的uname -m和python --version，下载时严格匹配。

6.2 MCP 服务注册失败排查

MCP 服务注册失败，通常有几个原因：网络不通、端口占用、配置错误。排查步骤是这样的：

1. 先用telnet或curl测试内网地址是否可达
2. 检查端口是否被占用，用netstat -tlnp | grep 端口
3. 检查配置文件里的地址是否正确，有没有误写公网地址
4. 查看服务日志，看有没有报错

我踩过一个坑：MCP 服务配置里写的是localhost，但 Agent 和 MCP 服务不在同一台机器上，localhost指向的是 Agent 本机，自然连不上。改成内网 IP 后解决。

6.3 Skills 加载失败：路径与版本问题

Skills 加载失败，常见原因是路径不对或版本不匹配。Agent 配置里指定的 Skills 目录，必须是绝对路径或者相对于 Agent 工作目录的正确路径。相对路径容易出错，建议用绝对路径。

版本问题也很常见。如果 Agent 配置里指定加载v1.0.0，但目录里只有v1.1.0，就会加载失败。升级 Skill 时，要同步更新 Agent 配置。

提示：Skills 目录的权限要设置好，Agent 运行用户必须有读权限。我见过因为权限问题导致 Skill 加载失败，排查了半天才发现是目录权限不对。

6.4 并发场景下的雪崩与恢复

并发高的时候，如果某个环节出问题，可能引发雪崩。比如模型推理 OOM 后，请求全部失败，Agent 不断重试，进一步加重负担，最终整个系统瘫痪。

防止雪崩的关键是快速失败和熔断。当某个服务错误率超过阈值时，熔断器打开，后续请求直接返回错误，不再调用该服务。等一段时间后，熔断器半开，尝试放少量请求，如果成功则恢复，失败则继续熔断。

from circuitbreaker import circuit @circuit(failure_threshold=5, recovery_timeout=30) def call_model(request): # 调用模型 pass

failure_threshold=5表示连续 5 次失败后熔断，recovery_timeout=30表示 30 秒后尝试恢复。这样能防止故障扩散，给系统恢复的时间。

7. 内网 Agent 工程化的个人体会

在内网做 AI Agent 工程，最深的体会是：外网能跑通不代表内网能跑通，内网能跑通不代表能稳定跑。外网环境里，很多问题被便捷的网络和丰富的资源掩盖了，到了内网全部暴露出来。依赖缺失、网络不通、权限不足、并发雪崩，每一个都可能让你卡好几天。

我的建议是，内网迁移一定要留足时间做依赖梳理和压测。不要指望一次成功，做好反复调试的准备。另外，文档要写清楚，每一步操作、每一个配置、每一个坑都记下来，下次迁移或者排查问题时能省很多事。

最后分享一个小技巧：内网环境里，把所有依赖、模型、Skills 的版本号统一记录在一个清单里，包括下载时间、校验和、来源。这样出问题时能快速定位是哪个环节的版本不对。这个习惯帮我省了很多排查时间，尤其是在多个内网环境之间切换时。