中大型私有化 Agent 平台
运维工程师跟学手册

定位：不深写 Agent 业务代码，但能把私有化大模型平台「装得上、跑得稳、算得清、出事知道怎么办」。少量脚本用 Cursor 完成。

学习方式：每个单元都按同一结构—— 「这是什么 → 中大公司为什么这么干 → 主流产品选型 → 你必须搞懂的知识点 → 本周动手 → Cursor 怎么帮你」。建议边读边在自己实验室（或公司测试环境）勾完成。

边界：本手册只教防御性运维与平台建设（限流、观测、配额、密钥、发布回滚）。不涉及攻击、越权探测、绕过审核等内容。

一、中大型公司主流私有化技术栈（你要认全）

公有云「开通一个大模型 API」在中大型私有化里通常不够：数据不出域、模型可审计、成本可摊销、工具可落内网。业界常见分层如下：

层级	干什么	主流私有化方案（2025–2026）
模型推理	把模型变成 HTTP 服务	vLLM、SGLang、TensorRT-LLM、华为 MindIE；模型多用 Qwen / DeepSeek / 内源微调
模型网关	统一鉴权、路由、限流、多模型	LiteLLM Proxy、One-API / New-API、Higress AI、APISIX AI 插件
应用/Agent 平台	编排、工具、工作流、人机协同	Dify 私有化、RAGFlow、FastGPT、自研 LangGraph/Temporal
向量与检索	RAG 知识库	Milvus、Elasticsearch 向量、Qdrant；偶见 pgvector
可观测	Trace、Token、质量	Langfuse 自建、Prometheus+Grafana、Loki/ELK、OpenTelemetry
基础设施	GPU 与编排	Kubernetes + NVIDIA GPU Operator；Harbor；GitLab/Argo CD
密钥与配置	不出库、可轮换	HashiCorp Vault / 公司统一配置中心；Prompt 当配置发布

你不必每个都精通安装，但要能说清：每一层挂了会出现什么业务现象、你先看哪块面板、怎么降级。

二、参考架构（脑子里先有一张图）

# 中大型私有化 Agent 典型链路（示意）

用户/业务系统
    │
    ▼
API 网关 / WAF（公司统一入口）
    │
    ▼
Agent 应用层（Dify / 自研） ──► 工具服务（工单/CRM/检索，内网）
    │                              │
    │                              ▼
    │                         出站策略 / 域名白名单
    ▼
LLM Gateway（LiteLLM / Higress）── 鉴权 · 限流 · 路由 · 计费打点
    │
    ├──────────────► 本地推理集群（vLLM on K8s GPU）
    └──────────────► （可选）专线到合规云模型

旁路：Langfuse / Prometheus ◄── 全链路 TraceId、Token、延迟
旁路：向量库 Milvus ◄── 知识同步任务（清洗/切分/embedding）
旁路：Vault ◄── API Key / 工具凭证

本周必做（30 分钟）

在纸上或画图工具画出你们公司（或目标架构）对应组件，标出「谁负责」
标出三个故障点：GPU OOM、网关 429、向量库打满
用 Cursor 让它根据这张图生成一份 Markdown 架构说明，你改到符合实际

单元 1 · 私有化推理服务（vLLM 等）

基础设施GPU

1.1 这是什么

推理服务把离线训练好的权重变成在线 API（常兼容 OpenAI 接口）。中大型公司几乎都会自建或采购一体机，而不是只靠公有 API。

vLLM 是当前最主流的开源高吞吐推理引擎之一：PagedAttention、连续批处理、OpenAI 兼容接口。SGLang 在 Agent/长输出场景也很多。国产一体机常见 MindIE / 厂商推理套件。

1.2 你必须搞懂的知识点

显存与并发：显存不够 → OOM；并发过高 → TTFT（首 Token 时延）飙升。
关键参数：max_model_len（上下文）、tensor parallel、gpu_memory_utilization、量化（AWQ/GPTQ/FP8）。
吞吐指标：tokens/s、请求队列长度、KV cache 占用率、拒绝率。
与网关关系：业务不直连 Pod IP，统一经 LLM Gateway。
滚动升级：换模型版本要双部署或百分比切流，防「全体换模当天事故」。

1.3 中大公司怎么落地

做法	说明
按场景分池	对话池 / 长文池 / 嵌入（embedding）池分开，避免互相挤占
大小模型搭配	简单路由走小模型，复杂再上大模型（省钱+降延迟）
HPA 谨慎	GPU Pod 扩缩慢，常配合队列与限流，而不是无限扩
健康检查	不只进程活着，还要「能完成一次最小 completion」

跟学内容清单（概念过关）

什么是 TTFT、TPOT、KV Cache，为什么运维要盯它们
上下文 8k/32k/128k 对显存与成本的影响（能粗算）
推理服务常见故障：OOM、排队爆炸、权重挂载失败、CUDA 驱动不匹配
读懂一份 vLLM 部署 YAML / Helm values 里的关键字段

动手（可用实验室单卡或公司测试集群）

部署一个最小 OpenAI 兼容推理（vLLM 或厂商文档最小集）。
用 curl 打 /v1/chat/completions，记录延迟。
故意把并发打高，观察延迟与错误，写 5 行「现象→原因→处理」。
用 Cursor 写：健康检查脚本（失败重试 3 次 + 告警文案）。

单元 2 · LLM 网关（统一出口）

平台核心限流计费

2.1 为什么中大公司必有网关

如果每个业务直接拿 Key 打模型：密钥满天飞、无法统一限流、无法分账、无法一键切备模。所以会有 LLM Gateway 作为唯一出口。

主流：

LiteLLM Proxy：兼容多厂家协议，私有化好部署，适合中台快速落地。
One-API / New-API：国内很常见，渠道与令牌管理友好。
Higress / APISIX：已有云原生网关团队时，AI 插件长在现有网关上。

2.2 你必须搞懂的知识点

虚拟 Key / 租户：业务用网关发的 Key，不是上游真实 Key。
RPM / TPM：每分钟请求数 / Token 数；私有化也要按租户限，防止一家拖死集群。
路由策略：按模型名、按标签、按失败自动 failover。
超时分层：连接超时、首包超时、整请求超时——和 Agent 多步调用强相关。
重试语义：幂等 GET 类可重试；非幂等工具调用慎重试（避免重复下单）。

2.3 标准能力清单（平台要具备）

能力	运维验收标准
鉴权	无效 Key 拒绝；可按应用吊销
限流	超限返回明确错误码；有监控
超时	默认值文档化；禁止无限等待
Failover	主推理池挂了可切备池或小模型
审计	谁、何时、哪个模型、多少 Token

动手 + Cursor

在测试环境起 LiteLLM 或 New-API，接一个本地/模拟 upstream。
配置两个「虚拟模型」：primary / backup。
用 Cursor 生成：压测脚本（逐步加压直到 429），输出「安全并发建议」。
写 Runbook 一页：上游 429 / 5xx / 超时 值班怎么处理。

# 概念示例：值班时你要会看的错误分层
4xx 参数/鉴权错  → 不重试，找业务或网关配置
429 限流         → 排队、降级、扩配额（先确认是谁打爆）
5xx/超时         → 看推理池指标；可 failover；避免无脑重试放大雪崩

单元 3 · 可观测、成本与「防干烧」

SRELangfuse

3.1 和传统服务有何不同

传统 API：看 QPS、错误率、延迟。Agent 还要额外看：

Token 消耗（钱）与单会话步数（死循环风险）
工具调用失败率（Agent 会反复重试）
链路深度（一轮用户请求背后可能十几次模型调用）

中大公司常见组合：Langfuse 自建（LLM 专用 Trace）+ Prometheus/Grafana（基础设施）+ 日志平台（ELK/Loki）。

3.2 黄金信号（请背下来）

信号	含义	告警思路
端到端成功率	用户是否拿到可用结果	跌破 SLO
P95 延迟	体验	对比基线突增
Token / 分钟	成本与异常消耗	同比/环比突增
平均步数 / 会话	是否跑飞	超阈值（如 >15）
工具错误率	下游依赖	分类：超时/5xx/校验失败
网关 429 比例	容量或滥用	按租户下钻

3.3 防干烧（平台闸门）

开发会设 max_steps；运维还要在平台层加：

应用日预算（80% 告警 / 100% 硬停或只读降级）
单会话 Token 上限
相同工具+相同参数连续调用熔断
重试预算（全局重试次数上限，防雪崩）

跟学内容

安装并逛一遍 Langfuse（或同类）UI：Trace、Generation、成本视图
规定你们字段规范：trace_id, session_id, model, prompt_tokens, completion_tokens, tool_name, latency_ms, error_type
Cursor 任务：从导出 JSON/CSV 汇总「昨日 Top10 烧 Token 的应用」脚本
定 3 条告警规则草稿（可先写在 Markdown，再落到监控系统）

单元 4 · Agent / RAG 应用平台（Dify、RAGFlow 等）

应用层

4.1 运维视角：你不管 Prompt 文采，管平台稳定性

中大型私有化很常见：

Dify：工作流、知识库、工具、多模型；Docker/K8s 私有化成熟。
RAGFlow：偏强文档解析与 RAG 效果。
自研：LangGraph + 内部工作流引擎（Temporal/自研状态机）。

你要掌握的运维面：

组件依赖：API、Worker、Web、Postgres/Redis、对象存储、向量库
队列积压：Worker 不够 → 任务延迟；重试风暴 → 打爆模型
配置与密钥：模型供应商配置、工具 Webhook、回调地址
多租户与资源隔离：哪个工作空间在烧钱
版本升级：官方 changelog、数据库 migration、回滚预案

4.2 和「开发面试题」的映射（你会答运维版）

开发被问	你要会的平台答案
工具超时怎么兜底	平台默认超时、重试策略、死信队列、降级开关
多轮忘关键信息	会话存储、Redis 容量、摘要任务失败告警
死循环	工作流最大步数默认值不可关；异常会话告警
为何状态机	状态落库、可恢复、人工节点；队列与检查点备份

动手

用官方 Docker Compose 起 Dify 或 RAGFlow 测试环境（只在隔离环境）。
画出其容器/服务依赖图，标出数据卷与数据库。
模拟：停掉 Worker，观察队列与用户现象；写进 Runbook。
Cursor：生成「Dify 备份清单」（DB + 存储 + 向量相关）。

单元 5 · 向量库与知识管道

Milvus数据

5.1 你要学的不只是「装个 Milvus」

RAG 出问题，一半是效果（开发），一半是管道与容量（运维）：

同步任务失败 → 知识过期 → 模型一本正经胡说八道
索引重建期间查询变慢/失败
Embedding 模型一换，旧向量空间失效，必须全量回填
磁盘与内存打满 → 写入拒绝

5.2 知识点

集合（Collection）、分区、索引类型（如 HNSW/IVF）对延迟与召回的粗影响
在线查询 vs 离线导入的资源隔离
备份：向量数据 + 元数据（文档 ID 映射）必须一起
SLO：知识生效延迟（例如文档上传后 P95 < 1 小时——按业务定）

跟学

读一遍 Milvus 或 ES 向量官方「运维/监控」章节，摘 10 个指标
设计一张「知识更新」状态机：成功/失败/重试/人工
写恢复演练步骤：删测试集合 → 从备份恢复 → 抽检查询
Cursor：生成知识同步失败告警文案模板（含 trace/任务 ID）

单元 6 · Kubernetes、GPU 与发布

云原生

6.1 中大公司标配

K8s 调度 GPU：NVIDIA GPU Operator、设备插件、节点标签（卡型）
镜像仓库 Harbor；推理镜像巨大，要有拉取与缓存策略
发布：Helm / GitOps（Argo CD）；模型权重常挂对象存储或 PVC
资源配额：Namespace 级限制，防测试打爆生产池

6.2 运维必会场景

场景	你要会什么
GPU 驱动/CUDA 不匹配	看事件、节点条件、Operator 日志
显存碎片/OOM	降并发、调 batch、隔离长上下文服务
节点 Registation	污点、亲和性、卡型调度不到
发布回滚	应用版本与「模型路由配置」分开回滚
成本	GPU 利用率过低也是事故（浪费）

跟学

弄清你们（或实验集群）GPU 型号、驱动、Operator 是否安装。
学会用 kubectl 看 Pod 事件里和 NVIDIA 相关的失败。
把「模型路由配置」当成配置发布：改备模、回滚、审计。
Cursor：根据现有 Deployment 生成一份「发布检查清单」PR 模板。

单元 7 · 安全、合规与出站管控

底线

7.1 私有化不等于自动安全

密钥：Vault/KMS，禁止进 Git；可轮换、可吊销
数据：日志脱敏；Prompt 全量落盘要有制度
工具出站：Agent 调工具易变 SSRF 温床 → 域名白名单、禁内网元数据地址
内容审核：输入/输出审核服务可用性；失败策略 fail-closed / fail-open 要书面规定
审计：谁用了哪个模型、导出了什么知识

跟学

列出你们 Agent 能调用的全部工具出站域名，做成白名单草案
写清审核挂了时的业务策略（谁签字）
Cursor：生成「密钥轮换 Runbook」骨架（你填真实系统名）

单元 8 · 值班、SLO 与 Runbook

SRE

8.1 建议 SLO 例子（按公司改数字）

网关可用性 99.9%
推理服务可用性 99.5%（GPU 池可略低，靠降级）
P95 端到端延迟 < 约定值
审核服务可用性 99.9%（若 fail-closed）

8.2 最少 6 本 Runbook（直接学这些标题）

上游/本地推理大面积超时
网关 429 打满
Token 消耗突增（疑似死循环）
向量库磁盘/内存告警
审核服务不可用
Agent Worker 队列积压

每本固定结构：症状 → 影响面 → 立即止血 → 排查顺序 → 升级条件 → 复盘项。

示例：Token 突增止血（你要会背）

确认租户/应用（看板下钻）
对该应用降级：切小模型 / 关高耗工作流 / 临时下调配额
查平均步数与重复工具调用
抓 1～3 条 Trace 交给开发
复盘：平台是否缺默认 max_steps / 缺突增告警

用 Cursor 完成的实操任务包（运维够用）

目标不是成为全栈，而是每个单元都有一个你自己仓库里的小工具。

任务	产出	对应单元
推理健康检查	脚本：探测 `/v1/models` + 最小 chat	U1
网关压测至 429	报告：安全 RPM 建议	U2
成本日报	CSV/机器人：按应用汇总 Token	U3
Trace 导出	按 session_id 拉齐步骤	U3
平台备份清单	Markdown 检查表	U4
知识同步失败告警模板	告警文案 + 字段	U5
发布检查清单	MR/PR 模板	U6
6 本 Runbook 骨架	同一模板填空	U8

对 Cursor 的正确用法：你描述环境约束（私有化、K8s、禁公网），让它生成脚本 → 你审查密钥与危险命令 → 先在测试环境跑。不要让它直接「生产执行」。

8 周学习计划（每天约 1～1.5 小时）

周	学什么	验收（必须能演示/口述）
W1	架构图 + 技术栈认全 + 推理基础	画出私有化链路；解释 TTFT/KV Cache
W2	vLLM/推理部署与故障	健康检查脚本；OOM/排队处理口述
W3	LLM 网关	虚拟 Key、限流、failover 演示；429 Runbook
W4	Langfuse + 黄金指标	面板；成本日报脚本；3 条告警
W5	Dify/RAGFlow 运维面	依赖图；停 Worker 实验；备份清单
W6	Milvus/知识管道	指标列表；恢复演练步骤
W7	K8s GPU + 安全出站	发布回滚故事；白名单草案
W8	SLO + 6 Runbook + 面试	完整 Oncall 演练一次；对照表口述

面试口述稿（运维版，直接练）

开场定位（30 秒）：

「我是做中大型私有化大模型平台运维的。业务用 Dify/自研 Agent，模型走 vLLM，统一经网关限流与鉴权，观测用 Langfuse + Prometheus。我保证的是：调用可限流、链路可追踪、成本可熔断、配置可回滚、事故有 Runbook。」

被问工具超时时：

「平台默认超时分层；可重试错误才退避重试；网关与工具出站都有熔断；耗尽后降级或人工；全程 Trace 可重放。」

被问 Token 烧飞时：

「先按下应用配额止血，再查步数与重复工具调用，抓 Trace 交给开发，复盘是否缺平台默认 max_steps。」

被问和第 20 轮记忆时：

「我侧先看会话存储与摘要任务是否失败、上下文是否触顶被截断；再和开发一起看记忆分层与关键召回。」

一、中大型公司主流私有化技术栈（你要认全）

二、参考架构（脑子里先有一张图）

本周必做（30 分钟）

单元 1 · 私有化推理服务（vLLM 等）

1.1 这是什么

1.2 你必须搞懂的知识点

1.3 中大公司怎么落地

跟学内容清单（概念过关）

动手（可用实验室单卡或公司测试集群）

单元 2 · LLM 网关（统一出口）

2.1 为什么中大公司必有网关

2.2 你必须搞懂的知识点

2.3 标准能力清单（平台要具备）

动手 + Cursor

单元 3 · 可观测、成本与「防干烧」

3.1 和传统服务有何不同

3.2 黄金信号（请背下来）

3.3 防干烧（平台闸门）

跟学内容

单元 4 · Agent / RAG 应用平台（Dify、RAGFlow 等）

4.1 运维视角：你不管 Prompt 文采，管平台稳定性

4.2 和「开发面试题」的映射（你会答运维版）

动手

单元 5 · 向量库与知识管道

5.1 你要学的不只是「装个 Milvus」

5.2 知识点

跟学

单元 6 · Kubernetes、GPU 与发布

6.1 中大公司标配

6.2 运维必会场景

跟学

单元 7 · 安全、合规与出站管控

7.1 私有化不等于自动安全

跟学

单元 8 · 值班、SLO 与 Runbook

8.1 建议 SLO 例子（按公司改数字）

8.2 最少 6 本 Runbook（直接学这些标题）

示例：Token 突增止血（你要会背）

用 Cursor 完成的实操任务包（运维够用）

8 周学习计划（每天约 1～1.5 小时）

面试口述稿（运维版，直接练）

推荐学习资源类型（按私有化优先级）