1. 项目概述为什么要搞隔离内网下的 AI Agent先把话说透隔离内网里做 AI Agent跟你在自己电脑上跑一个 LangChain Demo 完全是两码事。公网上开发 Agent模型调云端 API依赖包 pip 一下装完出问题还能 Google 报错。但换到隔离内网——生产系统内网、政企专网、金融核心业务网这种环境一切都不一样了没有外网域名解析pip 源连不上模型权重下载不了甚至你内网机器装什么操作系统、开不开英伟达驱动、能不能执行 Docker 命令都要先过一遍机房坐席的审批流程。我这套实战方案目标场景是“纯物理隔离、无外网出口、机器有 NVIDIA GPU、业务系统在内网运行”的标准企业环境。业务诉求很直白让 Agent 能自动分析数据库巡检结果、自动生成日报、根据工单上下文调用内部 API 完成操作全程不出内网。最终落地技术栈是 FastAPI LangChain LangGraph模型侧用开源模型本地部署以 Qwen 系为例并用 vLLM 做推理加速。这套东西我已经在生产内网实际跑过走了不少弯路这篇文章把规划和细节完整拆开给你一份可以直接参照的落地手册。内容会覆盖四个核心层面离线环境的技术选型、依赖包和模型文件的搬运、LangGraph 编排业务 Agent 的完整流程、以及最重要的一环——在隔离网这种“无外网、无云端、全本地”条件限制下Agent 服务如何扛住并发访问。适合正在做政企项目、内网知识库 Agent、内网自动化运维助手的同学参考。如果你刚接触 Agent也能从中搞懂一套完整工程的架构思路和避坑清单。2. 隔离内网 AI Agent 的架构设计与技术选型2.1 离线部署 Agent 的整体架构分层隔离网环境做 Agent第一个要颠覆的认知是你不能假设任何东西可以在线获取从模型权重到 Python wheel 包到前端静态文件全部要提前准备成“离线安装包”。所以架构上我分成四层来设计模型推理层GPU 机器上跑 vLLM加载开源模型如 Qwen2.5-14B-Instruct暴露统一 OpenAI 兼容 API。这一层是 Agent 的“大脑”。Agent 编排层LangGraph 作为核心编排框架定义节点、状态流转和工具调用LangChain 的 Tools、Prompt 模板、OutputParser 做辅助。应用服务层FastAPI 提供 HTTP 接口负责接收业务系统的请求、做鉴权、把任务提交给 Agent 编排层并返回结果或任务 ID。任务缓冲层异步场景用 Celerybroker 用内网的 Redis 或 RabbitMQ处理耗时较长的 Agent 任务避免 HTTP 长连接把接入服务拖垮。这套分层背后的逻辑很明确把 Agent 的“状态编排”和“业务接入”剥离开。LangGraph 专注管好流程比如先查询数据库、再调用工单系统、最后汇总生成结论FastAPI 专注管好上游系统接入。事实上如果你的 Agent 只是一问一答不涉及多步工具调用用 FastAPI 单层也就够了。但一旦要做“让 AI 真的下地干活”的事情状态机编排是躲不开的。2.2 离线条件下模型部署方案选型模型推理层在隔离内网里可选方案不少我简单列一下我对比过的几个以及最终为什么选 vLLM方案优势劣势适配场景vLLM吞吐高、支持连续批处理、OpenAI 兼容接口对 GPU 驱动/CUDA 版本敏感生产环境高并发推理Ollama部署极简一条命令起服务并发吞吐中等接口自定义度低原型验证、小团队内部试用llama.cppCPU/GPU 都能跑极致精简吞吐一般、API 不全无 GPU 的离线环境Triton Inference Server企业级多模型管理配置复杂学习成本太高大型团队、多模型统一入口实测下来内网生产环境还是 vLLM 最稳。原因很简单它自带 PagedAttention连续批处理做得好同一个模型在多并发请求下吞吐远胜 Ollama 和 llama.cpp 的默认调度。另外一个关键点是 vLLM 直接暴露 OpenAI 兼容接口LangChain 的 ChatOpenAI 可以直接配置 base_url 指向内网 vLLM 服务零代码改动就把 Agent 底层模型接上了。模型选型上隔离内网环境一般没有条件跑几百 B 的大模型。我的经验是把参数量控制在 14B~32B 之间比如 Qwen2.5-14B-Instruct。如果业务场景是“只做意图识别工具调用”14B 足够如果要处理长篇知识库检索后的摘要生成建议 32B 起步但对应显存压力要提前算清楚。后面章节会专门展开显存和并发之间的关系。2.3 为什么用 LangGraph 而不是纯 LangChain很多初学者会把 Agent 写成“一个大 Prompt 让模型自己决定下一步”LangChain 原生 Agent 也是这个套路但这在隔离内网业务场景里会出大问题模型一旦乱调工具业务系统就可能出现脏数据没人敢担责。因此我坚持用 LangGraph 把流程写死——该调数据库查询的时候就调数据库查询该调工单系统的时候就调工单系统模型只负责“填写参数、判断分支”不负责“决定调用哪个系统”。LangGraph 的核心价值是四个字可控编排。它把流程拆成节点和边节点之间的状态用一个共享 dict 传递每个节点都是一个普通 Python 函数。比如“数据库巡检 Agent”就可以拆成意图识别节点 → 巡检参数提取节点 → 数据库查询节点 → 结果分析节点 → 报告生成节点。每个节点只做纯函数式操作上一节点输出作为下一节点输入异常可以在任意节点拦截。这在生产代码评审中非常加分因为安全团队看得懂、审得过。如果说 LangChain 是“工具箱”LangGraph 就是“流水线设计图”。内网项目往往要过等保测评、安全审计你在评审会上拿一张节点状态图讲流程比拿一段“灵活自决策”的 Agent Prompt 有说服力得多。3. 隔离内网的“搬家”工程依赖、模型与运行环境3.1 Python 依赖包的离线制备这一节是隔离网项目最容易翻车的环节没有之一。你的开发者用一台能上外网的机器写完代码然后要把全部依赖搬进内网但凡少一个 wheel 包内网机器上就会当场报 ModuleNotFoundError。解决办法是做一个完整的离线源。我这里给一套经过实战检验的操作流程先在联网机器上与内网目标机相同 Python 版本比如都基于 Python 3.10 或 3.11pip download -r requirements.txt -d ./offline_packages \ --platform manylinux2014_x86_64 \ --implementation cp \ --python-version 311 \ --only-binary:all:关键词是--only-binary:all:它强制只下载编译好的二进制包。因为在内网目标机上绝大多数机器没有编译工具链如果拉下来一堆 sdist 源码包内网 pip 安装时会现场编译然后失败。当然LangChain 系部分组件可能没有对应的 wheel这种情况下我会提前在联网机器上把源码包下载并在内网安装时准备好 GCC 工具链。进入内网后执行离线安装pip install --no-index --find-links./offline_packages -r requirements.txt这套流程的坑点在于pip 只会下载一个包的直接依赖不会递归解析完整的交叉依赖树。因此我的建议是先在联网机器上用pip freeze requirements.txt生成锁定版本清单再基于它执行 download。如果你手头没有现成工程也可以分层制作先把 torch、vllm 这类大件装好再把 LangChain、LangGraph、FastAPI 等业务依赖装完分两批进入内网。3.2 模型权重的离线搬运与加载内网模型有两个来源一是从公网 HuggingFace 下载后拷贝进内网二是用企业内部已有的模型库。HuggingFace 下载模型推荐用hf命令行工具比git lfs clone稳定得多支持断点续传hf download Qwen/Qwen2.5-14B-Instruct \ --local-dir ./qwen25-14b-instruct \ --exclude *.safetensors.index.json # 按需求选择下载完成后把整个模型目录 tar 打包传进内网。这里特别提醒一个容易被忽略的点模型文件夹里如果有cache目录或*.lock文件传到内网后要先清干净再加载否则偶尔会出现莫名其妙的 “Token indices sequence length is longer than the specified maximum sequence length” 这类问题。模型进来之后用 vLLM 起服务。我的启动脚本一般这样python -m vllm.entrypoints.openai.api_server \ --model /data/models/qwen25-14b-instruct \ --served-model-name qwen-agent \ --host 0.0.0.0 \ --port 8000 \ --gpu-memory-utilization 0.9 \ --max-model-len 32768 \ --enable-auto-tool-choice \ --tool-call-parser hermes--gpu-memory-utilization很关键。如果设太满比如 0.99多个并发请求同时进来时容易 OOM设太低又浪费显存。我实测 14B 模型在 4 张 24GB 显存卡上设 0.85~0.9 足够支撑日常并发。另外如果是纯内网无证书环境记得在启动前统一设置export HF_HUB_OFFLINE1防止 vLLM 初始化时尝试联网检查本地模型缓存。3.3 内网机器系统环境与基础设施准备隔离内网经常不是你想用什么就用什么。有些老机房机器还是 CentOS 7自带 Python 3.6这会让 vLLM 直接无法安装——因为它要求 Python 版本通常不低于 3.9。这里我建议优先在内网准备一台“开发交付机”系统统一用 Rocky Linux 9 或 Ubuntu 22.04 LTSPython 用 3.11/3.12NVIDIA 驱动版本不低于 535CUDA 用 12.1 以上。如果机房审批困难至少要做好 Docker 镜像交付的准备把 Python 环境和 vLLM 全部打进镜像里内网机器只需要有 NVIDIA Container Toolkit 就能跑。网络层面隔离网也有“内部网络”。FastAPI 服务、vLLM 服务、Redis 之间是通的所以域名是不需要的直接用内网 IP 加端口互相调用。但这种环境下时钟同步问题很容易被忽略——如果内网机器没有配置 NTP 服务器各节点系统时间相差超过几分钟JWT 鉴权和 Redis 会话过期策略会随机报错。建议从上往下先把 NTP 服务打通再部署任何应用这是我在几个项目里被坑过的最基础也最难受的问题。4. LangGraph 编排 Agent 的核心实现与业务接入4.1 Agent 业务场景定义以内网“数据库巡检报告助手”为例为了让流程更具体我拿一个真实场景来讲内网核心库每周要做巡检DBA 需要汇总数据库实例的状态信息、慢查询、表空间使用率然后生成一份 Word 报告发给领导。传统做法是 DBA 手工登录每台数据库执行 SQL再复制粘贴结果。我用 Agent 把它变成了一条自动流水线。场景拆解后Agent 需要具备的能力清单调用数据库查询工具连内网数据库执行只读 SQL调用慢查询分析工具读取指定时间窗内的慢查询记录对查询结果做简单总结提取“异常项”比如表空间超 80%生成 Markdown 格式巡检报告并调用接口转成 Word 文件整个流程是确定性的所以不是“对话式 Agent”更像“任务式 Agent”。用 LangGraph 表达这个确定性流程是最合适的选择。4.2 LangGraph 节点定义与状态流转设计LangGraph 的核心概念是 StateGraph。每个节点是一个异步函数或同步函数输入是全局状态 dict输出是更新后的部分状态。我定义一个简单的状态类型from typing import TypedDict, Optional class AgentState(TypedDict): task: str # 原始任务描述 db_instances: list # 需要巡检的数据库实例列表 sql_results: dict # 各实例查询结果 slow_query_results: dict # 慢查询分析结果 anomalies: list # 识别出的异常项 report_md: str # 生成的 Markdown 报告 status: str # 当前状态 error: Optional[str] # 错误信息状态机的节点大致这样组织from langgraph.graph import StateGraph, END def extract_params(state: AgentState) - AgentState: 从任务描述中提取数据库实例列表和巡检时间窗 # 这里用 LLM 做抽取Prompt 限定死输入 schema ... def query_database(state: AgentState) - AgentState: 对每个实例执行只读 SQL ... def analyze_slow_query(state: AgentState) - AgentState: 检查慢查询统计 ... def identify_anomalies(state: AgentState) - AgentState: 比对各实例指标找出异常项 ... def generate_report(state: AgentState) - AgentState: 汇总成 Markdown 报告 ...构图时的关键点是把模型参与的部分严格收敛到两处——参数抽取和异常总结。数据库查询、模式匹配、状态判断都交给代码不要让模型做全流程决策。这样做的稳妥性在多次内网试运行中完全得到了验证不管用户怎么表述任务Agent 都会按固定流程走绝不出现模型自己“灵机一动”调用一个外部系统的情况。LangGraph 的连线逻辑如下示意graph StateGraph(AgentState) graph.add_node(extract_params, extract_params) graph.add_node(query_database, query_database) graph.add_node(analyze_slow_query, analyze_slow_query) graph.add_node(identify_anomalies, identify_anomalies) graph.add_node(generate_report, generate_report) graph.set_entry_point(extract_params) graph.add_edge(extract_params, query_database) graph.add_edge(query_database, analyze_slow_query) graph.add_edge(analyze_slow_query, identify_anomalies) graph.add_edge(identify_anomalies, generate_report) graph.add_edge(generate_report, END) app graph.compile()4.3 FastAPI 服务层与 LangGraph 的桥接FastAPI 的一个常规用法是收到 HTTP 请求后直接同步调用 graph 的.invoke()方法然后把整个结果返回。但内网场景里上游系统常常需要“提交任务后立刻拿到 task_id再轮询结果”因为 Agent 流程即使再快如果包含多步数据库查询整体耗时也可能 20 秒以上。HTTP 长连接等待不仅让上游系统难做超时控制还容易把 FastAPI 的 worker 全部占满。所以我把接口拆成两个POST /api/agent/run提交任务返回task_idGET /api/agent/task/{task_id}查询任务状态和最终结果任务异步执行的方案用 CeleryFastAPI 只负责校验参数、封装请求体、把任务对象扔进 Redis 队列然后立即返回。Celery worker 在另一个进程里通过 LangGraph 的ainvoke()执行复杂任务。这样 FastAPI 进程永远保持“轻快”Uvicorn 本身的事件循环不会被 Agent 的长耗时任务卡死。这里有一个很容易犯的错FastAPI 的接口函数如果定义成def而不是async defFastAPI 会把它丢到线程池里执行每个请求占一个线程。如果线程池默认大小40被 Agent 任务占满系统的所有接口包括健康检查都会超时。我建议所有涉及 Agent 提交的接口用async def把耗时任务全部交给 CeleryFastAPI 主进程保持异步非阻塞。4.4 自定义 Tools内网工具接入的正确姿势LangGraph 节点内部需要调用外部系统时我推荐把调用封装成 LangChaintool而不是在节点里裸写请求。好处是统一做入参校验、统一做日志审计、统一做超时与重试。以数据库查询工具为例from langchain_core.tools import tool import pymysql tool def query_db(instance: str, sql: str) - str: 在指定数据库实例上执行只读SQL返回JSON格式结果 # 强制校验 SQL 只读前缀防止误操作写库 sql_upper sql.strip().upper() if not sql_upper.startswith(SELECT): return 错误仅允许 SELECT 查询 conn pymysql.connect( hostinstance_host_map[instance], port3306, userreadonly_user, passwordreadonly_pwd, connect_timeout10 ) try: with conn.cursor() as cursor: cursor.execute(sql) columns [col[0] for col in cursor.description] rows cursor.fetchall() return json.dumps([dict(zip(columns, row)) for row in rows], ensure_asciiFalse, defaultstr) finally: conn.close()这是我认为整套 Agent 工程里最重要的编程习惯工具函数必须自己兜底异常、校验输入、限制权限。因为在内网环境里Agent 一旦获得数据库连接能力安全边界就被推进到了代码层。我把这个 Rule 写进了项目规范所有工具调用函数禁止接收自由文本 SQL必须由节点函数根据结构化参数拼 SQL杜绝模型直接操控 SQL 文本。这是被安全评审逼出来的经验但后续在生产上救了不止一次。4.5 Web 端“智能体”接入让前端也能对话内网项目用户其实并不关心 Agent 的原理他们只关心能不能像 ChatGPT 一样在网页里输入文字拿结果。所以我额外提供了一套前端接入方案基于 Streamlit 或 Flask 写一个轻量对话页后端统一打到 FastAPI 接口。如果你希望对话体验更接近实时打字机效果FastAPI 再加一个 WebSocket 接口Celery 任务执行过程中不断向客户端推送节点状态这样用户能看到“正在查询数据库”“正在生成报告”体验远好于傻等几秒空白页。由于我很早把 FastAPI 和 LangGraph 拆成了独立服务前端接入完全复用现有接口任何业务系统只要有 HTTP 调用能力就能对接 Agent不需要额外改模型相关代码。这套“服务接口前置、Agent 引擎后置”的做法在面对多部门接入需求时特别省事。5. 并发性能优化隔离网下 Agent 到底怎么扛并发5.1 并发瓶颈分析模型推理、编排器与应用服务每次有人问我“AI Agent 怎么扛并发”我的第一反应不是甩结论而是先把瓶颈分层。隔离网下 Agent 链路长每一层都可能成为瓶颈模型推理层vLLM 的吞吐能力、显存大小决定最大并发上限Agent 编排层LangGraph 状态存储默认是内存在多线程并发下的线程安全性应用服务层FastAPI 进程数、Celery worker 数、Redis 连接池上限上游业务系统内网数据库/API 自身能承受的调用频率我在内网做过一次比较完整的压测条件如下单机 4 张 NVIDIA A80080GB跑 Qwen2.5-14B-InstructvLLM 设置最大并发 128Agent 编排是 LangGraph CeleryFastAPI 单机 4 个 worker。压测脚本用 Locust 模拟 50 个并发用户每个用户提交“生成某个实例的巡检报告”任务。压测得到的现象前 20 个并发请求系统 TPS 线性增长平均响应时间保持在 8 秒内并发超过 30 后响应时间快速恶化系统吞吐反而下降Redis 连接数飙升同时数据库连接被打满。这说明瓶颈已经不在 vLLM 推理而在底层业务系统的连接池容量。这个结果对工程调优有很强的指导意义Agent 扛并发不可能只靠把模型服务参数调大必须做全链路容量规划。5.2 vLLM 侧并发参数的实战调优vLLM 侧可以做的调优项不少我按优先级排序第一优先级是max-model-len的控制。很多人图的省事设置成 32768 甚至更长但内网业务的实际请求通常不会超过 4096 token。超长的上下文会显著增加每请求的 KV cache 显存占用直接压低并发上限。我建议先统计业务实际请求长度再设定合理值比如训练阶段先用 8192后续业务扩展再拉长。第二优先级是--gpu-memory-utilization。设 0.9 意味着预留少量显存给 CUDA context 和其他开销如果模型权重接近显存上限调 0.95 可能成功但并发时会 OOM。我在四卡并行时把 0.85 到 0.9 之间做了一个矩阵测试最终定格 0.88既稳定又不会让系统显得“跑不满”如果你使用tensor-parallel-size为 2 或 4显存利用率和吞吐的关系更要仔细测。第三优先级是--max-num-seqs。vLLM 内部最大同时处理的序列数默认值通常可以满足需求但如果你发现响应延迟增高但 GPU 利用率不高可以适当降低这个值减少排队或在显存有余量时调高以提升吞吐。这块的参数名在不同版本间略有差异模型服务起来后用页面或 API 检查真实显存分配最靠谱。实测下来在 vLLM 正确调优后模型推理层很少成为瓶颈真正的瓶颈会转移到下面要说的编排和服务层。5.3 FastAPI Celery 的并发架构与参数设置FastAPI 底层跑 Uvicorn而 Uvicorn 启动时默认单 worker。单 worker 在异步模型下可以支撑成百上千的 HTTP 长连接因为它不靠线程并发而是事件循环。但隔离内网工程上我仍建议用 Gunicorn 管理多 worker因为 Agent 接口虽然异步但中间有些同步库如 pymysql会短暂阻塞事件循环多个 worker 可以提供冗余gunicorn -w 4 -k uvicorn.workers.UvicornWorker \ --bind 0.0.0.0:8080 \ --timeout 120 \ main:app-w 4在 4 核机器上比较稳妥再高就没有收益了。--timeout 120一定要设置否则 Agent 后端处理超过 30 秒时Gunicorn 默认 30 秒会 kill worker导致任务丢失。这个参数是我踩过一次大坑后才养成的习惯——内网业务系统提交长任务时网关和 Gunicorn 的超时参数是必须联动调整的。Celery worker 的并发模型用--concurrency8如果你的机器核心数足够每个 worker 进程内用 prefork 模式跑任务。注意 Celery worker 和 FastAPI worker 不建议共用同一台机器的全部资源否则长任务会把 CPU 抢光影响接入服务的响应。5.4 LangGraph 并发调用的线程安全与状态隔离LangGraph 的StateGraph在编译成app后默认是线程安全的吗答案是有条件的每次invoke()都会创建一个独立的状态快照所以不同请求之间互不干扰这是 LangGraph 设计上的优势。但如果你在节点里使用了全局变量或共享连接对象并发调用就会踩坑。比如我在早期版本里把数据库连接写成一个模块级全局变量结果 20 个并发请求进来后连接池排队部分 SQL 查询直接超时。正确做法是把所有资源连接数据库、Redis、外部 API 客户端都放在节点函数内部创建或者使用线程专属的 connection factory。如果你是用ainvoke()异步调用节点里就不能用同步的 pymysql 直连否则会阻塞事件循环。这种场景建议改用aiomysql或在节点函数里使用run_in_executor。LangGraph 还有thread_id机制用来在多轮对话中维护会话状态。隔离内网场景如果 Agent 不是多轮对话型thread_id可以不传但如果要做“用户多轮追问”一定要在 FastAPI 层统一生成thread_id并透传给 LangGraph 的后台线程否则每个请求都是一个新会话上下文就断掉了。这块在 LangGraph 的config {configurable: {thread_id: xxx}}里维护实测在高并发短任务场景无冲突。5.5 并发压测方案与实测数据参考我给出一份可以参考的压测方案不涉及具体业务数据只说方法和量级。工具我推荐 Locust因为它是纯 Python能直接在隔离网内用也能把压测脚本写进自动化测试平台。压测核心关注三个指标任务提交接口的 TPS反映 FastAPI 层的吞吐能力任务从提交到完成的 P95 延迟反映 Agent 全链路耗时任务失败率反映系统在高压下的稳定性我实测过的一个典型数据上述 4×A800 14B 模型配置32 并发用户每用户每 5 秒提交一个巡检任务任务提交接口 TPS 约 45任务完成 P95 延迟 18.6 秒失败率 0.4%。如果把模型换成 7B 模型同样的配置下 P95 延迟可以降到 8 秒以内。压测时我特别观察了 vLLM 的 GPU 利用率曲线32 并发下 GPU 利用率稳定在 87% 到 94% 之间说明推理层没有被榨干但也没有明显空闲整体资源利用是健康的。如果业务期望更高的并发需要做两件事一是模型服务部署多副本在 vLLM 前端加一层内网负载均衡二是业务上做“限流”同一个人 10 秒内只能提交一个 Agent 任务。这两条加一起基本能扛住几百人的部门级使用场景。6. 隔离网实战中高频问题与排查实录6.1 模型服务启动失败与显存管理的坑vLLM 在内网启动失败是最常见的故障。网上报错信息五花八门但归纳下来就几类一类是 CUDA error: out of memory。很多人以为是显存不够其实经常是--gpu-memory-utilization设置过高留给 CUDA context 的空间不足。处理方式是把参数从 0.95 降到 0.88 再试如果模型权重本身就占掉 90% 显存那只能换更大显存卡或降低模型参数量。另一类是RuntimeError: NCCL error多卡并行时出现。原因多半是内网机器没有配置好 GPU 间通信依赖或者/dev/shm空间太小。vLLM 多卡模式需要跨进程共享显存和通信/dev/shm默认只有 64MB 会直接报错。解决方式是在容器里加--shm-size16g用物理机部署就要在启动脚本里把共享内存参数调大。这个坑排查起来很隐蔽因为系统日志不会直接告诉你“共享内存不够”只会报 NCCL 相关错误。还有一类是模型文件加载到一半卡住多半是内网磁盘 IO 速度太慢。模型文件动辄几十 GB如果不做预加载预热第一个请求会等很久。解决方式是在启动后主动发一个空请求触发模型加载配合健康检查脚本等模型真正就绪后再对外提供服务。6.2 LangChain/LangGraph 离线运行中的依赖与网络问题LangChain 生态里有一些组件默认会尝试访问外网即便你的业务不依赖外网也会在初始化时触发网络请求导致超时。比较典型的几个langchain_community里某些 document loader 初始化时检查user_agent发送匿名统计部分Embedding模型默认从公网下载模型配置HuggingFace 相关的AutoTokenizer加载本地模型时仍会尝试检查远端版本针对这类问题我统一做了离线约束在内网机器的环境变量里设置HF_HUB_OFFLINE1、TRANSFORMERS_OFFLINE1、LANGCHAIN_TRACING_V2false。特别地LANGCHAIN_TRACING_V2如果不显式关掉它会在后台尝试连接 LangSmith虽然失败不影响主流程但会引入无谓的延迟和烦人的报错日志。关于 LangChain 版本我强烈建议在requirements.txt里锁死大版本LangChain 生态的小版本更新频次极高内网环境一旦装上某个不符合预期的版本想在无网环境升级会很麻烦。我自己的项目锁的是langchain0.2.x、langgraph0.2.x、langchain-openai0.1.x这个组合在 Qwen 系模型上配合良好没有出现接口签名不兼容的问题。6.3 中文文本处理与大模型输出质量问题内网 Agent 在中文场景下容易出现两类问题。第一类是模型输出中的格式不稳定比如要求输出 JSON 却夹杂 Markdown 代码块或者字符编码混乱。对策是在 LangGraph 节点的 output parser 上做兜底先尝试严格 JSON 解析失败后用正则提取花括号内内容再解析再失败就返回“生成失败”状态而不是把错误文本传给下游。第二类是中文乱码排查方向一般不在模型而在数据库连接字符集设置。pymysql 连接时如果忘记指定charsetutf8mb4中文字段读回来就是乱码。这类问题排查起来很基础但内网环境里因为各节点系统 locale 设置不统一还真出现过几次。调 Prompt 时我还发现Qwen 系模型在system角色里描述工具调用规范时有时候会忽略约束反过来把它放进user消息里配合 few-shot 示例输出稳定性会明显提升。Agent 输出的可靠性才是生产系统的命门这块值得多花时间调 Prompt。6.4 常见问题速查表现象可能原因排查步骤与解决vLLM 启动报 CUDA OOMgpu-memory-utilization 过高或权重过大降到 0.85 重试检查是否多进程重复加载模型多卡并行报 NCCL 错误共享内存不足或缺少 GPU 间通信库容器加 --shm-size检查 nvidia-smi 拓扑第一个请求很慢模型未预热启动后发一次空请求触发加载等模型状态 readyLangChain 初始化卡顿后台尝试连接外网设置 LANGCHAIN_TRACING_V2false、HF_HUB_OFFLINE1数据库查询中文乱码连接字符集未指定pymysql 或连接串中追加 charsetutf8mb4Celery 任务丢失worker 被 kill 或没有配置 ack_late设置 task_acks_lateTrue调大 --timeout并发高时任务堆积瓶颈在底层系统连接池扩大数据库/API 连接池增加预校验逻辑拦截无效任务6.5 独家避坑经验从评审会到运维交接隔离网项目有一个公网项目永远不会遇到的环节安全评审和运维交接。我不想说太多流程上的空话只提三个让我记忆深刻的实战点。第一安全评审时一定不要只讲“Agent 多智能”。要让评审看到你如何控制工具调用边界模型能碰什么、不能碰什么节点之间数据如何流转出错有无兜底。LangGraph 的节点状态图直接打印成设计文档附在评审材料里通过率会高非常多。第二运维交接文档必须写清楚“离线启动顺序”。模型服务、Redis、Celery worker、FastAPI 服务这四者的启动有先后次序先 Redis再模型服务再 Celery worker最后 FastAPI。如果顺序反了Celery worker 会因为连不上 Redis 或 vLLM 而疯狂重试产生大量无用日志。把这个启动顺序写进运维手册比任何花哨架构图都有用。第三给所有对外接口做统一的返回结构和错误码。Agent 链路多任何一个节点失败上游业务系统都希望能拿到明确的错误标识而不是一段大模型生成的“抱歉我遇到了一些问题”。我们最终的实践是 FastAPI 层统一拦截 LangGraph 异常转成结构化错误码用户侧只看到友好提示详细堆栈走日志系统。这大幅降低了与业务系统联调时来回扯皮的成本。7. 个人实战后想补充的几点体会做隔离内网的 AI Agent算法和模型永远是其中最简单的一部分。真正花掉大量时间的是如何让模型在受限网络环境里稳定运行、如何构建可控可审计的 Agent 流程、如何在并发压力下保证系统不崩。我个人经历过在评审会前夜应急修并发问题、在隔离网里反复搬运依赖包的狼狈时刻也最终把一套系统稳定跑上生产。现在的体会很朴素内网环境更像一种“降维试炼”它逼你把所有依赖、接口、监控、兜底都做得极其明确不允许任何暧昧的“在线就好”。如果你想把这个项目继续往下扩展我会建议优先做两件事一是给 Agent 加一套完整的知识库RAG把运维文档、工单历史沉淀进去提高回答的领域专业性二是评估多 Agent 协同——把巡检、报告、通知拆成不同角色的 Agent通过 LangGraph 的并行分支和路由机制协作形成更接近“团队作战”的自动化能力。这两块在隔离内网里都完全可行而且随着企业数据积累得越来越厚它们带来的价值会越来越明显。隔离内网做 Agent真正约束你的从来不是模型智商而是工程严谨度。框架选型、依赖管理、并发架构、离线运维每一层都用确定性的工程手法去解决AI 落地也就没那么玄了。