企业官网建设流程全解析

上个月我在一个项目现场驻场，机器是现成的，显卡也够，但网络环境是物理隔离的——外网完全不通，所有代码、模型、依赖都要靠移动介质一点一点往里搬。这时候要在隔离内网里落地一个 AI Agent 系统，和平时在开发环境里调云端大模型API完全是两码事。团队里好几个同学第一反应是"先装个 Ollama 跑起来再说"，但真正做下来才发现，模型能跑只是第一步，Agent 编排、依赖离线化、知识库构建、并发压测，每一步都有坑等着你。

这篇文章就是基于这次实际项目做的复盘。我会把"隔离内网下 AI Agent 工程实战"这条线完整捋一遍：从整体架构选型，到模型层、依赖层、Agent 编排层、知识库层，再到并发与生产化，最后是踩过的坑复盘。适合正在做企业私有化部署、信创环境适配、或者任何"不能上网但必须上AI"场景的工程同学参考。

1. 隔离内网与 AI Agent 的碰撞面：先想清楚难在哪

1.1 "离线"环境的真实面貌

很多同学一听到"隔离内网"，默认就是"没网而已"。但实际上，隔离内网的环境远比想象中复杂，通常包含下面几个特征：

• 物理隔离或逻辑隔离：有的网络和公网之间完全断连，数据只能通过U盘、光盘、网闸摆渡等方式单向导入；有的则是应用层受限，比如白名单域名、代理过滤，但基本等价于不可用。
• 软件白名单管控：不能随便装软件，很多机器连 gcc、make 都没有，装个带编译的包会让人崩溃。
• 系统版本老旧：内网机器的操作系统版本、glibc 版本、内核版本往往落后主流好几年，Python 3.11 在某些老系统上根本编译不过去。
• 没有域名解析保障：内网 DNS 解析规则经常很迷，自建 registry、私有 PyPI 的服务名解析就可能出问题。

这些东西单独看都不致命，但叠加在一起，就会让"在公网上三分钟搞定的事"变成"在内网里折腾三天"。

1.2 四个维度的核心矛盾

我在项目里梳理了一下，隔离内网部署 AI Agent 的核心矛盾集中在四个方面：

1. 模型参数进不来。一个 7B 的模型量化后也要 4~6GB，13B 甚至 14B 模型轻轻松松 10GB 以上，更大的模型动辄上百 GB。怎么安全可靠地把模型文件拷进内网，本身就是个工程问题。
2. 依赖和镜像无法在线拉取。Python 包、CUDA 组件、容器镜像，平时一条命令搞定，离线后必须提前准备 wheelhouse 和镜像包。而且依赖是有传递依赖的，漏掉一个就得重新摆渡一次，代价非常高。
3. Agent 的外部能力全部失效。AI Agent 最典型的能力是调用工具、搜索网页、访问第三方 API。隔离内网里这些外部能力都不存在，Agent 只能依赖内网已有的系统接口和知识库，工具边界被大大压缩。
4. 联调排错的路径变长。公网环境下出问题可以随时装个新的调试工具、查在线文档、拉最新代码；内网里所有排错都依赖日志和已有知识，试错成本很高。

这四个维度基本决定了：隔离内网里做 Agent，不能照着公网方案"平移"，而是要在架构设计阶段就把离线约束考虑进去。

1.3 技术栈选型：先给结论

基于上面的分析，我们最终敲定的技术栈是这样一套组合：

这里有个很重要的原则：所有组件必须优先选"自带 OpenAI 兼容 API"和"支持离线一键启动"的。比如推理服务选 vLLM 而非沿用原本的 transformers pipeline，就是因为 vLLM 自带/v1/chat/completions接口，LangChain、LangGraph 里很多封装都能直接复用。

2. 模型层落地：从模型文件到可用的离线推理服务

2.1 模型文件的离线导入与校验

模型文件的导入是整个项目里最不能出错的一步。因为一旦模型文件在传输过程中损坏，torch.load会在莫名其妙的地方报 shape mismatch，排查起来非常痛苦。

我们的做法是在可联网的机器上先建一个"模型暂存区"，按模型名和版本建目录，逐个下载后固定三样东西：

• 模型文件本身的 SHA256 校验值；
• 配置文件 config.json 中的关键参数摘要；
• HuggingFace 上下载时记录的原始文件列表。

下载工具我建议用huggingface_hub的 CLI，不要用浏览器手动点，因为它会带上每个文件的 sha256 校验信息，方便后续比对：

huggingface-cli download Qwen/Qwen2.5-14B-Instruct-AWQ \ --local-dir /data/models/Qwen2.5-14B-Instruct-AWQ \ --resume-download

下载完成后再跑一遍本地校验：

cd /data/models/Qwen2.5-14B-Instruct-AWQ && \ find . -type f -exec sha256sum {} \; > /data/models/sha256.txt

拷贝进内网后，第一件事就是拿这份 sha256.txt 做比对，确认所有文件完整。这一步一定不能省。我们有一次就是因为 U 盘文件系统问题导致一个分片损坏，少了 200MB，加载模型时直接报pytorch_model.bin.index.json里的权重缺失，排查了大半天才定位到是文件拷贝不完整。

另外，模型量化版本的选择也要提前想好。如果显卡是 24GB 显存这个级别，14B 模型用 AWQ 或 GPTQ 4bit 量化是合理选择；如果是 48GB 甚至更高，可以上 BF16 全精度版本。千万不要在内网机器上去跑量化转换流程——autoawq这类工具的依赖非常重，离线环境下装起来很被动。

2.2 Ollama还是vLLM：按并发与显存选型

隔离内网项目里经常出现一个争论：到底用 Ollama 还是 vLLM？我的建议是看阶段、看并发：

• 试点阶段、单用户调试、资源有限：用 Ollama。它把模型服务封装得非常好，一条ollama serve就能起服务，内置 OpenAI 兼容接口，离线安装也简单，适合先跑通流程。
• 生产阶段、多用户并发、对时延有要求：用 vLLM。它的 Continuous Batching、PagedAttention 对并发吞吐的提升非常明显，同样一张卡，vLLM 能撑住的并发数是 transformers pipeline 的数倍。

我在项目里见过一个很典型的例子：同样的 14B AWQ 模型，在 24GB 显卡上用 transformers 直接起服务，8 个并发就把显存打满、响应开始排队；换成 vLLM 后，max-num-seqs调到 32，显存占用反而更平滑，首 token 时延也能稳定在 1.5 秒以内。

如果是在隔离内网里做生产系统，我会直接推荐 vLLM，不要犹豫。

2.3 CUDA、驱动与推理依赖的离线安装

这一节是隔离内网项目里最容易翻车的地方，没有之一。

首先是显卡驱动。很多内网机器虽然装了驱动，但版本很老，而 vLLM 对 CUDA 版本有明确要求。我们遇到过一台机器，nvidia-smi显示驱动版本 450，而 vLLM 要求 CUDA 11.8 以上，导致 vLLM 在初始化时直接 complaining about CUDA capability。后来是找到了对应老驱动的 CUDA 11.8 配套版本才跑通。

其次是vLLM 的 pip 依赖。vLLM 的依赖列表非常长，包括torch、transformers、tokenizers、safetensors等一堆包，而且不同版本之间还有严格兼容关系。离线安装时不能只下载 vLLM 本身，要把整棵依赖树都准备好。我强烈建议在一台和机房"同构"的联网机器上，用同一套 Python 版本先做一次安装验证，把所有 wheel 包收集好，再搬到内网。

pip download vllm==0.6.6 \ --dest /data/wheelhouse \ --python-version 310 \ --only-binary=:all:

这里要注意--only-binary=:all:，强制只要 wheel 包，不要源码包。否则内网机器一旦没有编译工具链，源码安装会当场失败。

2.4 推理服务的稳定性和扩展性检查

离线部署完成后，不能光验证"能跑通一个对话"就宣布成功。我建议做一个更完整的验证清单：

1. 连续调用 100 次/v1/chat/completions，确认没有内存泄漏和显存持续增长；
2. 测试不同并发下的首 token 时延和生成吞吐，画出资源基线；
3. 验证max-model-len、gpu-memory-utilization等参数，确认显存分配合理；
4. 确认模型服务支持优雅重启，因为内网环境里没有那么多自动化运维工具，重启要尽量无痛。

提示：vLLM 启动时建议固定--gpu-memory-utilization 0.9以下，留出余量给 KV Cache 的抖动，否则在高并发时容易出现 OOM 导致的进程崩溃。

3. 依赖与运行环境离线化：搭一套不联网也能用的交付物

3.1 wheelhouse：Python依赖的离线安装方案

隔离内网里最基础也最容易被低估的就是 Python 依赖管理。项目刚开始时有人直接在联网机器上pip freeze导出一个 requirements.txt，然后到内网pip install -r requirements.txt，结果就是各种Could not find a version that satisfies the requirement。

正确做法是在联网的构建机上，用和最终运行环境一致的 Python 版本，把所有依赖下载成本地 wheelhouse 目录：

pip install pip-tools pip-compile requirements.in -o requirements.lock pip download -r requirements.lock \ --dest /data/wheelhouse \ --only-binary=:all:

requirements.lock把所有传递依赖的精确版本都钉死了，比手工维护的 requirements.txt 可靠得多。到内网机器上，安装就变成了：

pip install --no-index --find-links=/data/wheelhouse -r requirements.lock

这一步有个经验：wheelhouse 目录不要压缩，直接以目录形式拷贝进内网。因为内网机器上如果我们把 wheelhouse 打成一个 tar.gz，解压过程中一旦出现乱码或文件损坏，后面 pip 安装会非常隐晦地报错。目录拷贝虽然慢，但稳。

3.2 Docker镜像离线迁移与私有仓库搭建

如果内网环境允许使用 Docker，那镜像的离线迁移能省掉大量环境兼容问题。做法是：

1. 在外网构建机上把整个运行环境的镜像打好；
2. docker save成 tar 包，拷贝进内网；
3. 内网docker load导入。

docker save agent-base:v1.0 | gzip > agent-base-v1.0.tar.gz # 内网机器上 docker load -i agent-base-v1.0.tar.gz

但如果服务多了，tar 包管理很快就变得混乱。更稳妥的方案是在内网搭一个私有 Docker Registry，把镜像都 push 进去，各台机器从内网 registry 拉取。注意内网机器的/etc/docker/daemon.json要配置好insecure-registries，否则 registry 的 HTTP 协议会被 Docker 默认拒绝。

3.3 一致性校验：让离线交付可复现

隔离内网里，运维和开发往往是脱节的，开发在联网环境，运维在内网，两边对"环境一致"的判断经常靠感觉。我后来养成了一个习惯：每次交付都附带一份环境一致性清单，包含 sha256 校验和、版本号、构建时间三要素。

这样即使过了两个月，内网机器需要扩节点或者重装，也能照着这份清单复现，而不是靠"当时就是在这台机器上装的"这种模糊记忆。

4. Agent编排层：LangGraph与无Function Calling的工具调用

4.1 为什么用LangGraph而不是链式调用

"AI Agent"这个词大家已经听了很多，但真正在做企业级落地时，我一直坚持用 LangGraph 而不是那种简单的"先调大模型，再调工具，再调大模型"的链式代码。

原因很简单：隔离内网里的 Agent 必须可控制、可审核、可回滚。LangGraph 的核心模型是有状态图，每个节点是一个具体的处理单元，节点之间的跳转由条件边决定。这意味着我们可以很直观地把业务流程画成状态机，并且在任意节点插入人工审核步骤。

举个例子，我们有个需求是"Agent 根据用户请求查询内网订单系统并生成报表"。用链式调用写出来，工具调用和结果处理是揉在一起的；用 LangGraph 写出来，查询订单是一个节点，生成报表是另一个节点，中间可以加一个human_approve节点，让有权限的人确认之后再往下走。这对于内网系统的合规要求来说非常重要。

4.2 没有Function Calling也能"调工具"的三种做法

这是项目里被问得最多的问题。很多人以为 AI Agent 必须依赖模型的 Function Calling 能力才能调工具，但在隔离内网里，我们部署的本地模型未必支持 Function Calling，或者支持得不够稳定。这时候有三条路可以走：

方案一：结构化输出 + 正则解析

在 prompt 里明确告诉模型："如果要调用工具，严格输出 JSON 格式，包含 action 和 action_input 两个字段。"然后我们在代码里用正则把 JSON 块提取出来，再分发到对应的工具函数。这是最朴素也最稳的办法。

方案二：JSON Schema 控制输出

让本地模型按照指定的 JSON Schema 输出完整结果。LLM 原生 API 里的response_format参数如果不可用，我们可以通过在 prompt 末尾附加一份 "You must output JSON matching this schema: ..." 的约束，再用json.loads做解析和校验。实测下来，Qwen 系列的模型对 JSON 约束的遵循程度还是不错的。

方案三：ReAct 风格的话术内嵌

不把工具调用结构化，而是让模型在回复文本里直接描述"我需要调用 XXX 工具获取 YYY 数据"。代码层做关键词匹配，命中后自动执行工具，再把结果追加到上下文里让模型继续生成。这个方法最轻量，但稳定性也最差，适合工具数量少、触发词明确的场景。

我在实际项目里用的是方案一为主，辅以方案二做输出校验。比如我们的工具调用解析函数大致长这样：

TOOL_ACTION_RE = re.compile( r'\{[^{}]*"action"[^{}]*"action_input"[^{}]*\}', re.DOTALL ) def parse_tool_call(text: str) -> ToolCall | None: for match in TOOL_ACTION_RE.findall(text): try: data = json.loads(match) if "action" in data and "action_input" in data: return ToolCall(action=data["action"], action_input=data["action_input"]) except json.JSONDecodeError: continue return None

注意这里的正则不要写得太严，否则模型输出的 JSON 里多一个字段就解析失败了。解析失败时的兜底逻辑也很重要——我们会在连续两次解析失败后，把上一次的工具调用结果拼进 prompt，强制模型继续生成，而不是无限重试。

4.3 用FastAPI把Agent包成服务

Agent 编排层最终要暴露成 HTTP 接口给前端或业务系统调用。我用 FastAPI 封装，主要是看中它的异步能力和 OpenAPI 文档自动生成能力。

一个比较典型的接口是流式对话接口：

@app.post("/v1/agent/chat") async def agent_chat(request: AgentChatRequest): async def event_stream(): async for chunk in graph.astream_events( {"messages": request.messages, "user_id": request.user_id}, version="v2" ): if chunk["event"] == "on_chain_end": yield f"data: {json.dumps(chunk['data'])}\n\n" return StreamingResponse(event_stream(), media_type="text/event-stream")

在隔离内网场景里，FastAPI 服务还要特别注意一件事：健康检查接口。内网负载均衡器、监控系统都依赖健康检查来探活，没有健康检查的服务一上线就会被流量打崩。我们后来强制要求所有服务都提供/health接口，里面要顺带检查推理服务、向量库这些下游依赖的状态。

5. 知识库离线构建：从Embedding到向量检索调优

5.1 中文Embedding模型的离线部署

Agent 要回答业务问题，光靠模型自身参数知识是不够的，必须挂知识库。知识库的第一步是文本向量化，这里中文场景我推荐bge-m3或bge-large-zh-v1.5。

Embedding 模型虽然不大，但一定不要和推理大模型放在同一个 GPU 上随便跑。原因是 Embedding 模型和生成模型对显存的占用模式完全不同，混跑容易出现显存碎片。我们的做法是把 embedding 模型单独部署在一个小容器里，用/embedding接口对外提供服务，加载一次后常驻内存。

离线部署 embedding 模型也一样要走 wheelhouse 流程，但它的依赖问题比 vLLM 少很多，主要是torch、transformers和sentence-transformers三件套。需要注意的是sentence-transformers版本和transformers版本存在兼容关系，锁定版本时不要随意升级。

5.2 文档解析与切分的实操细节

知识库的质量往往取决于文档预处理，而不是模型。这是我在项目里最大的感受之一。

文档解析阶段，PDF 和 Word 是最常见的两种格式。PDF 解析我推荐pymupdf，它对中文支持好、速度快；Word 用python-docx解析。两个库都要提前准备离线 wheel，注意pymupdf的 wheel 在不同架构下名字差异很大。

切分阶段最重要的参数有三个：chunk_size、chunk_overlap、separators。中文文本和英文不一样，不能简单按空格切。我们实践中效果比较好的规则是：

• 优先按章节标题切分（markdown 标题、PDF 里的大段标题）；
• 再按段落的双换行符切；
• 最后才用滑动窗口兜底，窗口大小根据模型最大 token 长度来定，比如 512 或 768，overlap 设为 80~100。

这里有一句经验之谈：切分不要贪大。很多人为了减少向量条数把 chunk 切到 1000 多个 token，结果召回时噪音极大，检索回来的一整段里只有一半是有效信息。宁可用 300~500 token 的小块，换取更精准的召回。

5.3 向量库选型：单机、分布式与已有设施

隔离内网里向量库的选择主要看规模和数据敏感度。我的建议是：

需要注意，Milvus 集群依赖 etcd、MinIO 等组件，离线部署的依赖链条比较长。如果内网运维能力一般，建议先上 Milvus 单机模式，后面再平滑迁移。

5.4 检索质量调优：召回、阈值与Rerank

向量检索不是"相似度大于 0.8 就返回"这么简单。在我们项目里，检索质量调优经历了三个阶段：

第一阶段，只看 top_k 相似度，结果经常答非所问； 第二阶段，把检索结果拼进 prompt 时加上来源标题和页码，模型回答质量立刻提升； 第三阶段，引入了 Rerank 模型做二次精排，把向量检索召回的前 20 条先粗筛，再用 rerank 模型精排前 5 条。

Rerank 模型同样需要离线部署。我们用的是一个小的中文 rerank 模型，挂在一个独立的推理服务里，每次查询多花几十毫秒，但回答准确率提升非常明显。对于隔离内网的 Agent 系统，这一步投入产出比极高。

6. 并发与生产化：单机Demo到内网服务的距离

6.1 服务拆分的资源规划

很多同学在隔离内网项目里喜欢"一台机器全搞定"——又是推理服务，又是 Agent API，又是向量库，还挂着前端。Demo 阶段可以，到了生产环境必须拆。

我的建议是至少拆成三层：

1. 推理服务层：独占 GPU 机器，部署 vLLM；
2. Agent 应用层：纯 CPU 机器跑 FastAPI + LangGraph，负责编排和工具调用；
3. 数据层：向量库、业务数据库、消息队列，各自独立部署。

这样拆的好处有二：其一，推理服务的显存抖动不会拖垮整个 Agent 服务；其二，Agent 应用层可以独立水平扩展，当并发上来了，加两台 CPU 机器就能扛。

6.2 AI Agent怎么扛并发：实测参数与调优

"AI Agent 怎么扛并发"这个问题的答案，绝不是一个参数能解决的，但我可以给出一套实测有效的组合拳。

第一层是推理服务的并发参数。vLLM 下这几个参数非常关键：

第二层是应用层的并发控制。FastAPI 本身是异步的，但 Agent 编排里的内部环节（调用工具、查询向量库）往往是同步阻塞的，所以必须在应用层做信号量限流，否则推理服务还没被打满，应用层的线程池先爆了。

from anyio import Semaphore agent_semaphore = Semaphore(20, max_waiters=50) @app.post("/v1/agent/chat") async def agent_chat(request: AgentChatRequest): async with agent_semaphore: # 进入 Agent 编排 ...

第三层是超时与重试机制。大模型生成时间本来就比普通接口长，Agent 一轮对话可能包含多个模型调用和工具调用，总耗时常超过 10 秒。这里必须设置合理的超时时间，并且对下游系统设计重试退避策略，否则一个循环调用就能把整个 Agent 拖死。

我们实际压测过一组数据：在单张 48GB 显卡上跑 14B AWQ 模型，max-num-seqs=32时，20 个并发的 Agent 对话请求，端到端平均耗时约 8 秒，推理服务 GPU 利用率约 85%，没有出现超时或 502。这个结果说明，在内网环境下，24GB~48GB 显卡 + vLLM + 应用层限流，足以支撑几十个用户的日常使用。

6.3 内网环境的可观测性与审计

隔离内网往往没有成熟的 APM 监控体系，但这不代表可以不做可观测性。我们在项目里落地了一套轻量方案：

• 所有 Agent 请求统一打印结构化日志（包含 request_id、user_id、模型调用次数、工具调用清单）；
• 所有工具调用记录操作留痕，写入审计表；
• 模型服务定期健康检查，异常自动告警到企业微信机器人。

审计这一点在隔离内网里尤其重要，因为 Agent 能访问的是内网真实业务系统，每一次工具调用都要对得上"谁在什么时间基于什么原因发起了这次查询"。

7. 踩坑实录：隔离内网部署中那些"文档不会告诉你"的问题

7.1 五个印象最深的坑

坑一：glibc 版本过低，Python 3.11 直接编译失败。内网机器系统是 CentOS 7，glibc 2.17，很多新版 wheel 包在 manylinux_2_17 以上才提供，导致 pip 找不到可用包。后来我们统一改用 Python 3.10，并手动收集 manylinux2014 兼容的 wheel，才把问题绕过去。教训是：提前确认内网机器的操作系统版本和 glibc 版本，再决定 Python 版本。

坑二：HuggingFace 的缓存目录导致模型文件重复占用磁盘。用huggingface-cli download下载时，模型文件会先落在~/.cache/huggingface/hub，再体现到--local-dir。如果没清理缓存，一个 14B 模型可能占用双倍磁盘空间。内网机器的磁盘往往不宽裕，拷贝前务必确认缓存目录的情况。

坑三：两个模型服务共用一个 Python 环境，torch 版本冲突。在试点阶段，推理服务和 embedding 服务装在同一台机器的同一个 conda 环境里，结果一个需要 torch 2.1，另一个需要 torch 2.3，升级后另一个直接起不来。教训是：隔离内网里一定要用虚拟环境隔离好每个服务，各管各的依赖。

坑四：内网 Docker pull 私有镜像时，因为 registry 地址解析失败反复重试。排查下来是内网机器的/etc/hosts没有配置 registry 的映射。虽然是个小问题，但在离线环境下很容易被忽略，而且报错信息看起来像网络不通，实际是域名解析问题。

坑五：离线安装sentence-transformers时，编译tokenizers需要 rust 工具链。当时我们准备不充分，以为所有包都有 wheel，结果tokenizers在某个 Python 版本下没有对应 wheel，被迫现场找 rust 工具链，非常狼狈。后来学乖了，所有包在构建机上强制--only-binary=:all:验证，不能只用pip download成功就完事。

7.2 交付物清单与部署节奏

基于这次项目的沉淀，我把隔离内网 AI Agent 的交付物整理成了一份标准清单，供大家参考：

• wheelhouse/：全部 Python 依赖的 wheel 包；
• images/：Docker 镜像 tar 包（如需要）；
• models/：大模型文件、embedding 模型、rerank 模型及 sha256 校验文件；
• requirements.lock：精确到版本的依赖锁定文件；
• deploy/：部署脚本、健康检查脚本、服务启动脚本；
• docs/：部署手册、版本兼容矩阵、常见问题处理手册。

部署节奏上，我的经验是"先小步跑通，再逐步放大"。第一次交付只要求达到"模型能对话 + Agent 能调用两个内网工具 + 知识库能检索"，第二周再补并发压测、监控告警和审计。千万不要在隔离内网里直接照搬公网那样搭建一个庞大复杂的系统，因为排错成本太高，一次失败的尝试可能就要等下一次拷文件才能继续。

几轮项目做下来，我最大的体会是：隔离内网部署 AI Agent，本质上拼的不是大模型技术，而是工程化流程的严谨程度。只要提前把依赖树、校验信息、部署脚本都沉淀成可复用的物料，内网和外网的差距其实没有想象中那么大。如果你们团队正准备在隔离环境里上 Agent，我建议先别急着跑代码，花一两天把上面这份清单过一遍，能省下后面好几周的填坑时间。