企业官网建设流程全解析

1. 隔离内网下 AI Agent 工程实战的整体思路拆解

1.1 为什么“隔离内网”是 AI Agent 落地最真实的战场

聊 AI Agent 工程化，很多人第一反应是公有云 API、在线大模型、各种 SaaS 工具链。但真正在企业里干过交付的人都清楚，大量核心业务系统跑在物理隔离或逻辑隔离的内网环境里，外网访问受限，第三方服务不可达，连 pip install 都要走内部镜像源。这种环境下要把 AI Agent 跑起来，难度和公网 Demo 完全不是一个量级。

我前后参与过几个内网 AI Agent 项目，涉及智能问答、流程自动化、代码辅助、运维巡检等场景。踩过的坑包括但不限于：模型权重无法下载、依赖包版本冲突、MCP 服务无法注册、Agent 调度链路断在某个内网节点上。这些问题的共同点是——公网教程里几乎不会讲，因为公网环境默认你什么都能访问。

所以这篇内容面向的是这样一类人：你所在的环境有网络隔离要求，但业务方又希望用 AI Agent 提升效率；你手上有 GPU 服务器或至少一台能跑推理的机器；你需要在没有外网的情况下完成模型部署、Agent 编排、工具调用、服务注册这一整条链路。如果你正好处在这个场景里，下面的内容应该能帮你少走不少弯路。

1.2 内网 AI Agent 的核心架构选型逻辑

内网环境和公网环境最大的区别在于：所有外部依赖都必须内部化。这直接决定了架构选型。

先看模型层。公网方案通常是调 API，内网方案只有两条路：一是本地部署开源模型，二是走内部统一推理网关。本地部署要考虑显存、量化、推理框架；走网关则要考虑协议兼容性和并发承载。我的经验是，如果团队有运维能力，优先走内部推理网关，因为模型更新、扩缩容、监控都由专门团队负责，Agent 侧只需要对接标准接口。如果团队规模小，那就本地部署，用 vLLM 或类似框架起服务，量化到 INT4 或 INT8 控制显存占用。

再看 Agent 编排层。公网常用 LangChain、LangGraph、AutoGen 这些框架，内网同样可以用，但要注意依赖包必须提前离线下载。我的做法是在有外网的机器上用 pip download 把整个依赖树拉下来，打成离线包，再传到内网安装。这一步看起来简单，实际上经常因为平台差异（比如外网是 x86，内网是 ARM）导致 wheel 包不兼容，需要提前确认目标平台的架构和 Python 版本。

最后看工具调用层。这是内网 AI Agent 最容易出问题的环节。公网 Agent 可以随便调搜索、调地图、调各种 API，内网 Agent 能调的工具非常有限。MCP（Model Context Protocol）在这里的价值就体现出来了——它提供了一套标准化的工具注册和调用协议，让 Agent 可以在不修改核心逻辑的情况下接入内部工具。但 MCP 服务本身也需要在内网部署，而且要考虑服务发现、鉴权、超时重试这些工程问题。

1.3 内网环境下的关键约束与应对策略

内网环境有几个硬约束，必须在架构设计阶段就考虑进去。

第一是网络隔离导致的依赖获取困难。不只是 Python 包，还包括模型权重、Docker 镜像、系统库。我的建议是建立一个“离线资源仓库”，把所有可能用到的资源提前同步进去。模型权重用对象存储或共享文件系统存放，Docker 镜像用内部 Registry，Python 包用内部 PyPI 镜像。这个仓库的维护成本不低，但一次投入长期受益。

第二是安全策略导致的端口和协议限制。内网通常有防火墙策略，不是所有端口都能互通。Agent 和 MCP 服务之间的通信端口需要提前申请开通。另外，有些内网环境禁止 HTTP 明文传输，必须走 HTTPS，这就要求内部 CA 证书体系要完善。我遇到过因为证书问题导致 MCP 服务注册失败的情况，排查了很久才发现是自签名证书不被信任。

第三是运维监控的缺失。公网服务有完善的 APM 和日志系统，内网往往只有基础的服务器监控。AI Agent 的调用链路长，涉及模型推理、工具调用、结果聚合多个环节，没有链路追踪很难定位问题。我的做法是在 Agent 框架里内置结构化日志，把每个环节的耗时、输入输出、异常信息都记录下来，集中收集到内部日志平台。这样出问题时能快速定位是模型慢、工具超时还是编排逻辑有 bug。

2. 核心细节解析与实操要点

2.1 模型部署：从权重到推理服务的完整链路

内网部署模型，第一步是获取权重。以常见的开源模型为例，权重文件动辄几十 GB，通过外网下载再拷贝到内网是常规操作。但要注意权重文件的完整性校验，我遇到过拷贝过程中断导致文件损坏的情况，加载时报错很难排查。建议用 sha256 校验，确认无误后再进行下一步。

第二步是选择推理框架。内网环境推荐 vLLM 或 TGI，两者都支持连续批处理和 PagedAttention，吞吐量比原生 Transformers 高很多。如果显存有限，可以用 GPTQ 或 AWQ 量化版本。以 7B 模型为例，FP16 需要约 14GB 显存，INT4 量化后只需约 4GB，一张消费级显卡就能跑起来。

第三步是服务化。用 vLLM 的 OpenAI 兼容接口起服务，命令大概是这样：

python -m vllm.entrypoints.openai.api_server \ --model /path/to/model \ --served-model-name internal-model \ --host 0.0.0.0 \ --port 8000 \ --tensor-parallel-size 1 \ --max-model-len 8192

这里有几个参数需要根据实际情况调整。--tensor-parallel-size是多卡并行数，单卡就设 1。--max-model-len是最大上下文长度，设太大占显存，设太小可能截断对话。--gpu-memory-utilization默认 0.9，如果显存紧张可以降到 0.8。

注意：内网部署模型时，务必确认 CUDA 驱动版本和推理框架要求的版本匹配。我遇到过驱动版本过低导致 vLLM 无法启动的情况，升级驱动又涉及内网审批流程，耽误了好几天。

2.2 MCP 服务在内网的注册与发现

MCP 是 Anthropic 提出的开放协议，用于标准化 AI 模型与外部工具的交互。在内网环境里，MCP 服务的部署和注册需要额外考虑几个问题。

首先是服务发现。公网可以用 DNS 或服务网格，内网如果规模不大，直接用静态配置就行。在 Agent 的配置文件里写死 MCP 服务的地址和端口，简单可靠。如果服务较多，可以搭一个轻量的注册中心，比如 Consul 或 Nacos，但要注意这些组件本身也需要内网部署和维护。

其次是鉴权。内网不等于安全，该有的鉴权还是要做。MCP 协议支持在请求头里带 Token，可以在内网网关层做统一校验。我的做法是给每个 Agent 分配一个内部 Token，MCP 服务校验 Token 的有效性和权限范围。这样即使内网有横向移动的风险，也能限制影响范围。

然后是超时和重试。内网网络虽然稳定，但 MCP 服务本身可能因为负载高而响应慢。Agent 侧要设置合理的超时时间，一般建议 30 秒，超过就降级或报错。重试策略要谨慎，对于非幂等的工具调用不要自动重试，否则可能产生重复操作。

下面是一个 MCP 服务注册的配置示例：

{ "mcpServers": { "internal-search": { "url": "http://mcp-gateway.internal:8080/search", "token": "internal-token-xxx", "timeout": 30000, "retry": 1 }, "internal-db": { "url": "http://mcp-gateway.internal:8080/db", "token": "internal-token-yyy", "timeout": 60000, "retry": 0 } } }

提示：MCP 服务的 URL 建议走内部网关，不要直接暴露后端服务地址。网关层可以做鉴权、限流、日志，后端服务只需要关注业务逻辑。

2.3 Skills 机制在内网 Agent 中的落地方式

Skills 是近期 AI Agent 领域的热门概念，本质上是把特定领域的能力封装成可复用的模块，Agent 在需要时动态加载。内网环境下，Skills 的落地有几个关键点。

第一是 Skills 的存储和分发。公网可以从官方市场或 GitHub 拉取 Skills，内网必须自建 Skills 仓库。可以用 Git 仓库或对象存储，每个 Skill 是一个独立的目录，包含描述文件、代码、依赖声明。Agent 启动时从仓库拉取 Skills 列表，按需加载。

第二是 Skills 的依赖管理。一个 Skill 可能依赖特定的 Python 包或系统工具，内网安装这些依赖是个麻烦事。我的做法是在 Skill 的元数据里声明依赖，Agent 加载 Skill 时检查依赖是否满足，不满足就报错并提示需要安装哪些包。这样比运行时才发现 ImportError 要好得多。

第三是 Skills 的版本控制。Skills 会迭代，不同版本的 Agent 可能依赖不同版本的 Skill。建议在 Skill 目录里放一个 version 文件，Agent 加载时校验版本兼容性。如果 Skill 有破坏性变更，要升大版本号，避免旧 Agent 加载新 Skill 导致异常。

2.4 并发承载：内网 Agent 的性能瓶颈与优化

“AI Agent 怎么扛并发”是很多人关心的问题。内网环境的并发瓶颈通常不在网络，而在模型推理和工具调用。

模型推理方面，vLLM 的连续批处理能显著提升吞吐。实测下来，单张 A100 跑 7B 模型，并发 10 路对话时首 token 延迟约 200ms，吞吐约 500 tokens/s。如果并发再高，延迟会线性上升。优化手段包括：增加 GPU 数量做张量并行、用量化模型降低单次推理开销、对高频问题做缓存。

工具调用方面，MCP 服务本身要能扛住并发。如果 MCP 服务是同步阻塞的，Agent 并发高时会排队。建议 MCP 服务用异步框架实现，比如 FastAPI + asyncpg，数据库操作也走异步。另外，Agent 侧对工具调用做并发控制，比如限制同时最多 5 个工具调用在飞，避免打爆下游服务。

还有一个容易被忽略的点是连接池。Agent 和模型服务、MCP 服务之间的 HTTP 连接要复用，不要每次请求都新建连接。用 httpx 或 aiohttp 的连接池功能，设置合理的 max_connections 和 max_keepalive_connections。

3. 实操过程与核心环节实现

3.1 内网离线环境的依赖准备与安装

这一步是整个工程的基础，做不好后面全是坑。我的标准流程是这样的：

首先在有外网的机器上创建和目标内网机器一致的 Python 环境。用python -m venv建虚拟环境，然后pip download把所有依赖下载到本地目录：

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

这里--platform和--python-version要跟内网机器一致。如果内网是 ARM 架构，要改成manylinux2014_aarch64。--only-binary=:all:确保只下载 wheel 包，避免源码包在内网编译时缺系统库。

然后把 offline_packages 目录打包传到内网，在内网机器上安装：

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

--no-index禁止访问外网 PyPI，--find-links指定本地包目录。这样安装过程完全离线。

注意：有些包在 PyPI 上只有源码包没有 wheel，比如某些冷门库。这种情况下需要在内网机器上编译，要提前确认 gcc、make、python-dev 这些编译工具是否齐全。

3.2 Agent 核心编排逻辑的实现

Agent 的核心是一个循环：接收用户输入，调用模型推理，根据模型输出决定是否调用工具，调用工具后把结果返回给模型，继续推理，直到模型输出最终答案。

用 LangGraph 实现的话，大概是这样：

from langgraph.graph import StateGraph, END from typing import TypedDict, Annotated import operator class AgentState(TypedDict): messages: Annotated[list, operator.add] next_action: str def call_model(state): response = model.invoke(state["messages"]) return {"messages": [response]} def call_tool(state): last_message = state["messages"][-1] tool_name = last_message.tool_calls[0]["name"] tool_args = last_message.tool_calls[0]["args"] result = mcp_client.call(tool_name, tool_args) return {"messages": [{"role": "tool", "content": result}]} def should_continue(state): last_message = state["messages"][-1] if last_message.tool_calls: return "call_tool" return END workflow = StateGraph(AgentState) workflow.add_node("agent", call_model) workflow.add_node("tool", call_tool) workflow.set_entry_point("agent") workflow.add_conditional_edges("agent", should_continue) workflow.add_edge("tool", "agent") app = workflow.compile()

这段代码的关键在于should_continue这个条件判断：如果模型输出里有 tool_calls，就去调工具；否则结束。工具调用的结果以 tool 角色的消息追加到对话历史里，模型下一轮推理时能看到工具返回的内容。

实际工程中还要加很多东西：最大循环次数限制（防止死循环）、超时控制、异常处理、日志记录。我一般会设最大 10 轮工具调用，超过就强制结束并返回当前结果。

3.3 MCP 工具服务的开发与部署

MCP 工具服务本质上是一个 HTTP 服务，接收工具调用请求，执行具体逻辑，返回结果。用 FastAPI 写一个最简单的例子：

from fastapi import FastAPI, HTTPException, Header from pydantic import BaseModel app = FastAPI() class ToolRequest(BaseModel): tool_name: str arguments: dict @app.post("/call") async def call_tool(req: ToolRequest, authorization: str = Header(None)): if not validate_token(authorization): raise HTTPException(status_code=401, detail="Invalid token") if req.tool_name == "query_database": result = await query_database(req.arguments["sql"]) elif req.tool_name == "search_docs": result = await search_docs(req.arguments["keyword"]) else: raise HTTPException(status_code=404, detail="Tool not found") return {"result": result}

部署时用 uvicorn 起服务，前面挂 Nginx 做反向代理和负载均衡。Nginx 配置里要注意设置合理的超时时间，proxy_read_timeout建议 60 秒以上，因为有些工具调用可能比较慢。

提示：MCP 服务的日志要记录每次调用的工具名、参数、耗时、结果状态。这些日志在排查问题时非常有用，比如发现某个工具频繁超时，就可以针对性优化。

3.4 内网环境下的联调与验证

所有组件部署完后，需要做端到端联调。我的验证清单是这样的：

1. 模型服务健康检查：curl 模型服务的 /health 接口，确认返回 200。
2. MCP 服务健康检查：curl MCP 网关的 /health 接口。
3. Agent 到模型服务的连通性：在 Agent 所在机器上 curl 模型服务地址。
4. Agent 到 MCP 服务的连通性：同样 curl 测试。
5. 单工具调用测试：直接调 MCP 服务，确认工具逻辑正常。
6. 端到端测试：给 Agent 发一个需要调用工具的问题，观察完整链路。

联调时最常见的问题是网络不通。内网防火墙策略可能只开通了部分端口，Agent 到模型服务通了，但到 MCP 服务不通。这时候要用 telnet 或 nc 逐个测试端口连通性。

另一个常见问题是证书问题。如果内网走 HTTPS，Agent 侧要信任内部 CA 证书。Python 的 requests 或 httpx 默认不信任自签名证书，需要把 CA 证书加到信任链里，或者设置 verify=False（仅限测试环境）。

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

4.1 模型推理相关问题排查

问题一：模型加载失败，报 CUDA out of memory。

排查思路：先确认显存总量和模型大小是否匹配。7B FP16 模型约需 14GB 显存，如果显卡只有 8GB，肯定不够。解决方案是用量化模型，或者用 CPU 推理（速度慢但能跑）。另外检查是否有其他进程占用显存，nvidia-smi看一下。

问题二：推理速度慢，首 token 延迟高。

排查思路：先看 GPU 利用率，如果利用率低，可能是批处理没生效。vLLM 默认开启连续批处理，但如果请求间隔太长，批处理效果不好。可以适当增加并发请求数。另外检查--max-model-len是否设得太大，上下文越长，推理越慢。

问题三：模型输出乱码或重复。

排查思路：检查 tokenizer 是否和模型匹配。有些模型需要特定的 tokenizer 配置，用错了会导致输出异常。另外检查 temperature 和 top_p 参数，设得太高容易乱说，设得太低容易重复。

4.2 MCP 服务调用相关问题排查

问题一：MCP 服务注册失败，Agent 找不到工具。

排查思路：先确认 MCP 服务本身是否正常，直接 curl 服务的健康检查接口。然后检查 Agent 配置里的 URL 和 Token 是否正确。如果 MCP 服务在另一台机器上，检查网络连通性和防火墙策略。

问题二：工具调用超时。

排查思路：先看 MCP 服务的日志，确认请求是否到达。如果到达了但处理慢，优化工具本身的逻辑，比如加数据库索引、减少不必要的计算。如果没到达，检查网络和网关配置。Agent 侧的超时时间也要合理设置，太短容易误报超时。

问题三：工具返回结果格式不对，模型无法理解。

排查思路：MCP 协议对返回格式有要求，确保返回的是 JSON 格式，并且字段名和模型期望的一致。如果工具返回的是自然语言文本，要包装成 JSON 的 content 字段。我遇到过工具直接返回字符串导致模型解析失败的情况，包装成{"result": "..."}就好了。

4.3 内网环境特有的坑与应对

坑一：时间不同步导致 Token 过期。

内网机器如果时间不同步，JWT Token 的签发和校验会出问题。确保所有机器都配置了 NTP 同步，时间误差控制在秒级以内。

坑二：DNS 解析失败。

内网如果没配 DNS，只能用 IP 访问。但 IP 会变，维护成本高。建议在内网搭一个轻量 DNS 服务，或者用 hosts 文件做静态解析。hosts 文件适合机器少的情况，机器多了还是 DNS 靠谱。

坑三：磁盘空间不足。

模型权重、日志、缓存都很占空间。部署前确认磁盘剩余空间，模型权重目录建议单独挂载大容量磁盘。日志要配置轮转，避免写满磁盘。

坑四：内网无法访问外部时间源。

有些内网完全隔离，NTP 也连不出去。这种情况下只能靠内部时间源，或者手动校准。时间不同步的影响前面说了，Token 过期、日志时间错乱都是问题。

4.4 常见问题速查表

提示：内网环境排查问题，最重要的是逐层验证。从网络层到服务层到应用层，一层层确认。不要跳步，否则容易误判。

5. 内网 AI Agent 工程的扩展与演进

5.1 从单 Agent 到多 Agent 协作

单 Agent 能解决的问题有限，复杂任务需要多个 Agent 协作。比如一个负责理解需求，一个负责查资料，一个负责生成结果。内网环境下多 Agent 协作的挑战在于通信和协调。

通信可以用消息队列，比如 RabbitMQ 或 Kafka，内网部署这些组件不难。协调可以用一个 Orchestrator Agent 来分配任务和汇总结果。LangGraph 支持多 Agent 编排，可以定义多个节点，每个节点是一个 Agent，通过状态传递来协作。

多 Agent 的坑在于死锁和循环。Agent A 等 Agent B 的结果，Agent B 等 Agent A 的结果，就死锁了。要在编排逻辑里加超时和降级策略，避免无限等待。

5.2 Skills 生态的内网建设

Skills 的价值在于复用。内网建 Skills 仓库，把常用能力封装成 Skill，新项目直接引用，不用重复造轮子。Skills 的分类可以按领域分，比如数据库操作、文档处理、代码生成、运维巡检。

Skills 的维护要有规范。每个 Skill 要有清晰的文档，说明功能、参数、返回值、依赖。要有测试用例，确保 Skill 改动后功能正常。要有版本管理，破坏性变更要升大版本。

5.3 监控与可观测性建设

内网 AI Agent 的监控包括几个层面：基础设施监控（CPU、内存、GPU、磁盘）、服务监控（QPS、延迟、错误率）、业务监控（工具调用成功率、模型输出质量）。

基础设施监控可以用 Prometheus + Grafana，内网部署这套很成熟。服务监控可以在 Agent 和 MCP 服务里埋点，上报到 Prometheus。业务监控需要自定义指标，比如每次工具调用的耗时和结果状态，可以用结构化日志记录，然后用 ELK 或 Loki 做聚合分析。

可观测性的关键是链路追踪。一次 Agent 调用涉及模型推理、多次工具调用、结果聚合，没有链路追踪很难定位问题。可以用 OpenTelemetry 做埋点，把整个调用链的 Span 串起来。内网部署 Jaeger 或 Zipkin 做追踪后端。

5.4 安全与权限的持续加固

内网不等于安全，AI Agent 的权限控制很重要。Agent 能调哪些工具、能访问哪些数据，都要有明确的权限边界。

我的做法是最小权限原则：每个 Agent 只分配完成其任务所需的最小权限。比如一个只读查询的 Agent，就不给它写数据库的权限。MCP 服务侧做权限校验，Agent 侧做权限声明，两边匹配才能调用。

另外要审计。所有工具调用都要记录日志，包括谁调的、调了什么、什么时候调的、结果如何。审计日志要防篡改，可以写到只追加的存储里。这样出问题时能追溯，也能满足合规要求。

6. 一些实操心得与避坑建议

内网 AI Agent 工程，技术上的难点其实都能克服，真正耗时间的是流程和沟通。申请防火墙策略、审批软件安装、协调资源，这些事往往比写代码花的时间还多。我的建议是提前规划，把需要审批的事项列出来，尽早启动流程。

另一个心得是先跑通最小闭环，再逐步扩展。不要一上来就搞多 Agent、复杂工具链，先把“用户输入 -> 模型推理 -> 返回结果”这个最小闭环跑通，然后再加工具调用、加 Skills、加多 Agent。每加一个环节，都要验证，确保不出问题再继续。

还有就是要重视日志和监控。内网环境出问题时，没有日志就是抓瞎。我在项目初期就要求所有组件输出结构化日志，关键路径加 trace_id，这样排查问题时能快速定位。这个投入非常值得。

最后说一个具体的技巧：内网部署时，把所有服务的健康检查接口统一成 /health，返回 JSON 格式的状态信息。这样可以用一个脚本批量检查所有服务，省时省力。健康检查接口要轻量，不要查数据库或调外部服务，只返回进程状态和基本指标就行。

这个领域变化很快，新的模型、新的协议、新的工具层出不穷。但内网环境的核心约束不会变：离线、隔离、受限。把离线依赖管理、MCP 服务部署、Agent 编排、监控排查这几件事做扎实，就能应对大部分场景。后续如果业务有新的需求，比如接入更多工具、支持多模态、做更复杂的编排，都可以在这个基础上扩展。