AI应用架构图：可执行的系统施工蓝图

1. 这不是画PPT，是给AI系统搭骨架

“图解AI应用架构设计”——这六个字一出来，很多人第一反应是：又要看一堆方框箭头、云朵数据库、虚线连接线的PPT了？别急，先放下对“架构图”的刻板印象。我干这行十年，从最早手绘UML图贴在白板上，到后来用draw.io拖拽组件，再到今天用Mermaid写代码生成拓扑图，踩过太多把“图解”当装饰的坑。真正能落地的AI应用架构图，从来不是汇报材料里的静态截图，而是一张可执行、可验证、可演进的系统施工蓝图。它得回答清楚三件事：数据从哪来、模型在哪跑、结果怎么用；它得标出每个模块的边界、接口协议、容错策略和性能瓶颈点；它得让算法工程师知道该调哪个API，让运维同事明白要监控哪几个指标，让产品经理一眼看出用户请求走哪条路径、卡在哪一环。

核心关键词“图解”二字，本质是用视觉语言降低系统复杂度的认知门槛，但前提是图里每一个节点都对应真实存在的服务、配置或代码逻辑。比如你画一个“大模型推理服务”，不能只写个方框加个名字，必须注明：用的是vLLM还是Triton？部署在K8s还是裸机？GPU型号和显存占用是多少？输入token长度限制多少？超时时间设为几秒？这些参数不写进图里，这张图就只是幻灯片。而“AI应用架构”这个短语，重点在“应用”——不是纯研究型的模型训练Pipeline，而是面向真实业务场景、承载用户请求、需要7×24小时稳定运行的生产系统。它必然涉及模型服务化、前后端协同、数据闭环、安全合规、成本控制等一整套工程实践。适合谁看？不是只给CTO看的战略图，而是给一线开发、测试、运维、产品共同使用的协作底图。我见过最有效的架构图，是贴在团队共享屏幕上的实时更新版本，上面连“当前Redis缓存命中率低于70%”这种告警状态都用颜色标注。所以这篇内容，我们不讲理论，不堆概念，直接拆解一张能真正指导开发、部署、排障的AI应用架构图该怎么画、为什么这么画、哪些地方最容易画错。

2. 架构图不是装饰画，是系统设计的决策记录本

2.1 为什么必须用图来表达AI应用架构？

AI应用和传统Web应用最大的区别在于它的“不确定性”——模型输出不可完全预知、推理延迟波动大、数据漂移会悄无声息地腐蚀效果。这种不确定性，让文字描述变得苍白无力。举个例子：如果文档里写“用户查询经过预处理后送入大模型”，这信息量几乎为零。但一张图里，你能清晰看到：用户请求先打到API网关，再经Nginx做限流，然后由Python微服务做Query清洗（去噪、纠错、实体识别），接着通过gRPC调用部署在A10 GPU上的vLLM服务，返回结果后由另一个服务做后处理（格式标准化、敏感词过滤），最后才返回前端。这条路径上，每个环节的输入输出、协议、超时、重试策略、监控埋点，都能在图中用不同颜色、线型、图标直观呈现。

更关键的是，架构图是跨角色共识的锚点。算法同学说“模型精度够了”，后端同学说“QPS扛不住”，运维同学说“GPU显存总爆”，产品同学说“响应太慢用户流失”。这些争论，往往源于对系统全貌理解的偏差。一张准确的架构图，能把所有人拉到同一张地图上：你看，瓶颈不在模型本身，而在中间那个Python清洗服务——它用单线程同步调用外部API，成了整个链路的木桶短板。图一摆出来，问题根源立刻浮现，讨论焦点自然转向如何重构清洗服务。我带过的项目里，凡是跳过架构图直接写代码的，90%会在联调阶段暴露出接口定义不一致、数据格式错位、重试逻辑冲突等低级错误，返工成本是前期画图时间的5倍以上。图不是为了好看，是为了把隐性的设计决策显性化、可追溯、可验证。

2.2 真实架构图的四个致命误区

很多团队画的架构图，表面看着专业，实际全是“皇帝的新衣”。我整理了最常见的四类陷阱，都是血泪教训：

第一类：抽象层级混乱。图里同时出现“用户”、“React前端”、“Kubernetes集群”、“CUDA驱动”、“Transformer层”……这就像在一张城市地图上，既标出北京三环路，又标出某栋楼里第三层第四个插座的位置。正确的做法是分层建模：业务层（用户旅程、功能模块）、应用层（服务、API、数据库）、基础设施层（容器、网络、GPU）。每一层图只展示该层关心的实体和依赖，层与层之间用明确的接口契约（如REST API规范、消息Schema）连接。我见过最典型的反例，是把PyTorch模型代码片段直接截图贴在架构图里——这已经不是架构图，是代码审查清单了。

第二类：忽略非功能性需求。图里密密麻麻全是服务方框，却找不到一个标着“SLA: 99.95%”、“P95延迟<800ms”、“日志保留30天”的标签。非功能性需求（性能、可用性、安全性、可观测性）不是附加项，而是架构设计的约束条件。比如，要求“用户查询5秒内返回”，这就决定了你不能把大模型推理放在跨城专线另一端的GPU集群上；要求“用户数据不出本地机房”，就排除了所有公有云SaaS模型服务。这些硬性约束，必须以可视化方式嵌入架构图，否则设计就是空中楼阁。

第三类：静态快照，脱离演进。一张图定终身，上线后再也不更新。现实是，AI应用迭代极快：昨天用的Llama2-7B，今天换成Qwen1.5-4B，明天可能接入RAG增强；上周还在用PostgreSQL存向量，这周就切到Milvus。架构图必须是活的文档，每次关键变更（模型升级、服务拆分、中间件替换）都要同步更新图，并附上变更原因和影响范围。我们团队的做法是，把架构图源文件（Mermaid代码）和部署脚本、CI/CD流水线放在一起管理，图一改，自动触发相关服务的健康检查。

第四类：责任归属模糊。图里所有连线都是双向箭头，所有服务都标着“负责XX功能”，但没人知道当某个服务超时失败时，该找谁。真正的架构图必须明确标注每个组件的Owner（个人或团队）、SLI/SLO指标、应急预案入口。比如“向量检索服务”旁边，要小字注明：“Owner: 搜索组；SLO: 查询成功率≥99.9%；降级方案：超时300ms切回关键词搜索；联系人：@zhangsan”。没有责任边界的架构图，就是一张无法追责的废纸。

2.3 图解的核心价值：从“能跑”到“可控、可优化、可扩展”

一张合格的AI应用架构图，最终要服务于三个目标：可控、可优化、可扩展。

• 可控，意味着任何异常都能快速定位。当用户投诉“回答总是重复”，图能帮你立刻锁定是RAG检索模块没返回相关文档，还是大模型生成模块的temperature参数设得太低。图里每个服务都应标注关键监控指标（如vLLM的vllm:gpu_cache_usage_ratio），每条链路都应标出熔断阈值（如Hystrix的失败率>50%触发降级）。
• 可优化，意味着性能瓶颈一目了然。图中用不同粗细的连线表示流量权重（粗线=高频路径），用红色高亮标出已知瓶颈（如“文本向量化服务CPU使用率常达95%”），用虚线标出未来优化方向（如“计划将向量化迁移至专用GPU节点”）。我们曾靠一张图发现，80%的流量其实只访问3个核心API，其余20个API常年闲置——果断下线，节省了40%的服务器成本。
• 可扩展，意味着新增能力不破坏现有结构。比如要加多模态支持，图能清晰显示：只需在“输入预处理”模块旁新增“图像编码器”服务，通过标准消息队列接入，无需改动下游所有服务。图里预留的“扩展点”（Extension Point）标识，就是系统生命力的保障。

所以，“图解”不是把系统画出来，而是把系统的决策逻辑、约束条件、演化路径画出来。它是一份活的契约，一份技术债的记账本，一份新成员入职的速成指南。接下来，我们就从一张真实的AI问答应用架构图开始，逐层拆解每个模块的设计原理、选型依据和实操细节。

3. 一张真实AI问答应用架构图的逐层拆解

3.1 整体分层视图：业务层、应用层、基础设施层

我们以一个典型的B端智能客服问答系统为例（非Demo，是已上线服务）。这张图不是凭空想象，而是基于真实生产环境提炼。它严格遵循三层分层原则，每层聚焦不同关注点：

业务层（蓝色区域）：站在用户视角，描述“做什么”。包含：用户终端（Web/App）、核心业务流程（提问→理解→检索→生成→反馈）、关键业务实体（知识库、用户会话、意图分类）。这一层不出现任何技术名词，全是业务语言。比如“知识库”不叫“Milvus Vector DB”，就叫“企业FAQ知识库”；“意图分类”不写“BERT微调模型”，就写“用户问题意图识别”。

应用层（绿色区域）：站在开发者视角，描述“怎么做”。这是架构图的主体，包含所有可部署的服务单元、数据存储、消息中间件。每个服务都标注了技术栈（如“Python FastAPI”、“Go Gin”）、部署形态（StatefulSet/K8s Deployment）、关键配置（如“vLLM实例：2xA10, max_model_len=4096”）。服务间连线标注协议（HTTP/gRPC/Kafka）和关键参数（如“gRPC超时：3s”、“Kafka Topic：user_query_events”）。

基础设施层（灰色区域）：站在运维视角，描述“在哪做”。包含：K8s集群（标注Region/AZ）、GPU资源池（A10/V100混合）、对象存储（MinIO/S3）、网络拓扑（VPC、Service Mesh Istio）。这一层不画具体服务，只画资源池和网络边界，体现资源隔离和安全域划分。

三层之间用虚线框明确分隔，跨层依赖用带箭头的虚线连接，并标注契约（如“业务层依赖应用层提供‘问答API’，SLA：P95<1.2s”）。这种分层，确保每个角色只关注自己该管的部分，又清楚上下游的接口约定。

3.2 应用层核心模块详解：为什么这样设计？

3.2.1 API网关：不只是流量入口，更是第一道防线

图中最上游的“API Gateway”服务，绝非简单的反向代理。我们选用Kong（而非Nginx），核心原因是它原生支持AI场景的特殊需求：

• 动态路由：根据用户Token中的权限等级，自动将请求路由到不同模型集群（VIP用户走A10集群，普通用户走T4集群）；
• 精细化限流：不是按IP限流，而是按“用户ID+模型类型”组合限流（防止单个用户刷爆Qwen模型，不影响Llama2调用）；
• 请求改写：自动注入TraceID、用户会话ID到Header，供下游服务链路追踪；
• 熔断降级：当vLLM服务健康检查失败时，自动切换到备用规则引擎（基于关键词匹配的轻量级Fallback）。

配置示例（Kong declarative config）：

services: - name: ai-qa-service url: http://vllm-service.default.svc.cluster.local:8000 routes: - name: vllm-route paths: ["/v1/chat/completions"] plugins: - name: rate-limiting config: minute: 60 # VIP用户每分钟60次 policy: local - name: circuit-breaker config: failure_threshold: 5 timeout: 30000 # 30秒 reset_timeout: 300 # 5分钟

提示：网关层必须做“请求瘦身”。我们强制要求前端传入的messages数组，单条content长度不得超过2000字符，超长自动截断并记录告警。否则，一个恶意构造的超长Prompt，会直接打满vLLM的KV Cache，导致整个集群雪崩。

3.2.2 模型服务集群：vLLM为何成为事实标准？

图中“Large Model Inference Service”模块，我们采用vLLM而非HuggingFace TGI或自研Flask服务，理由非常实在：

• 吞吐量碾压：实测同配置下，vLLM的QPS是TGI的3.2倍，是Flask+transformers的8倍以上。核心在于PagedAttention——它把KV Cache像操作系统管理内存一样分页，极大减少显存碎片，让A10这种中端卡也能跑7B模型；
• 动态批处理（Continuous Batching）：不用等凑满batch_size才推理，新请求来了就插队，显著降低P95延迟；
• 开箱即用的API：完全兼容OpenAI Chat Completions API，前端代码零改造。

部署细节：

• 每个vLLM Pod独占2块A10 GPU（避免多租户干扰）；
• --max-model-len 4096（模型最大上下文）；
• --block-size 16（PagedAttention分页大小，需与GPU显存匹配）；
• --tensor-parallel-size 2（2卡并行）；
• Prometheus exporter暴露关键指标：vllm:gpu_cache_usage_ratio（显存利用率）、vllm:request_waiting_time_seconds（排队等待时间）。

注意：vLLM的--swap-space参数慎用！它会把部分KV Cache换出到SSD，虽能提升并发数，但SSD IO延迟会导致P95飙升。我们线上禁用此选项，宁可少接请求，也要保延迟稳定。

3.2.3 RAG增强模块：向量检索不是加个Milvus就完事

图中“Retrieval Augmented Generation”模块，包含三个紧密耦合的子服务：

• Document Ingestion Service：负责PDF/Word/网页等原始文档的解析、分块（chunking）、向量化。关键点：分块策略不是固定512字符，而是按语义分割（用semantic-chunking库，基于句子嵌入相似度）；
• Vector Database (Milvus)：我们用Milvus 2.4，而非FAISS（单机）或Chroma（功能弱）。Milvus支持分布式、强一致性、丰富的索引类型（IVF_PQ适合海量数据，HNSW适合低延迟）。集群配置：2个QueryNode（处理检索）、3个DataNode（存储）、1个IndexNode（建索引）；
• Hybrid Search Service：不只做向量检索，还融合关键词检索（BM25）。因为纯向量检索对专有名词、缩写、数字不敏感。我们用rank_fusion算法加权合并两种结果，实测准确率提升22%。

一个典型RAG流程：用户问“报销流程需要哪些发票？”，Document Ingestion Service已将《财务制度V3.2》PDF解析为500个语义块并入库；Hybrid Search Service同时发起向量检索（Embedding Query）和BM25检索（关键词“报销 发票”），返回Top5文档块；这些块作为Context拼接到Prompt中，送入vLLM生成答案。

3.2.4 后处理与反馈闭环：让AI学会“反思”

图中最容易被忽视，却是价值最高的模块——“Post-processing & Feedback Loop”。它包含：

• Output Sanitizer：不是简单过滤敏感词，而是用规则+小模型双重校验。例如，检测到回答含“医疗建议”，立即触发人工审核流程（发送Slack告警）；检测到“法律条款”，自动插入免责声明；
• User Feedback Collector：在回答下方提供“有用/无用”按钮。点击“无用”时，强制弹出表单：“您希望得到什么信息？（必填）”。这些结构化反馈，直接进入“Feedback Queue”；
• Offline Evaluation Pipeline：每天凌晨，用反馈数据自动构建测试集，评估各模型在“无用”样本上的表现，生成报告。若某模型在“政策解读”类问题上“无用率”连续3天>15%，自动触发模型微调任务。

这个闭环，让系统不是静态的，而是持续进化的。我们上线3个月后，“无用率”从初期的35%降至8.7%，核心就靠这个模块。

3.3 基础设施层关键设计：GPU资源不是越多越好

3.3.1 GPU资源池化：A10与V100的混部策略

图中“GPU Resource Pool”标注了A10和V100两种卡。这不是随意选择，而是基于成本与性能的精确计算：

• A10：24GB显存，INT8算力150 TOPS，功耗150W。适合7B-13B模型的在线推理，性价比极高；
• V100：32GB显存，FP16算力125 TOPS，功耗250W。适合30B+大模型或需要高精度计算的场景（如金融风控模型）。

混部策略：

• 所有A10节点加入inference-poolNamespace，运行vLLM服务；
• V100节点单独划为training-pool，只跑离线训练和批量推理；
• K8s调度器配置nodeSelector和tolerations，确保A10 Pod绝不调度到V100节点（反之亦然），避免资源争抢。

实操心得：GPU显存不是越大越好。我们曾用V100跑7B模型，显存只用掉40%，但QPS反而比A10低15%——因为V100的Tensor Core针对大矩阵优化，小模型无法充分利用。选卡，必须匹配模型规模。

3.3.2 网络与存储：延迟杀手往往藏在看不见的地方

图中“Service Mesh (Istio)”和“Object Storage (MinIO)”看似普通，实则暗藏玄机：

• Istio：启用mTLS强制加密所有服务间通信，但关闭了默认的Envoy Sidecar对gRPC流式响应的缓冲（streaming模式下缓冲会增加100ms+延迟）。我们在DestinationRule中显式配置：

  trafficPolicy: connectionPool: http: http1MaxPendingRequests: 1000 maxRequestsPerConnection: 1000 tcp: connectTimeout: 5s

• MinIO：用于存储原始文档和模型Checkpoint。我们部署在本地NVMe SSD集群上，而非网络存储。实测对比：读取1GB PDF，本地SSD耗时1.2s，NAS耗时8.7s。对于RAG文档加载，这8秒就是用户等待的全部时间。

4. 从图到代码：关键环节的实操实现与避坑指南

4.1 架构图落地第一步：用Mermaid写出可执行的源码

架构图必须是代码，而非图片。我们团队统一用Mermaid Live Editor（https://mermaid.live）编写，源码存于Git仓库/docs/architecture.mmd。好处是：可Review、可Diff、可CI检查、可一键渲染为PNG/PDF。

一个真实片段（简化版）：

flowchart TD A[Web Browser] -->|HTTPS| B[API Gateway Kong] B -->|gRPC| C[vLLM Service<br/>2xA10<br/>P95<800ms] B -->|HTTP| D[Hybrid Search Service] D -->|gRPC| E[Milvus Vector DB<br/>2 QueryNode<br/>3 DataNode] C -->|HTTP| F[Output Sanitizer] F -->|Kafka| G[Feedback Queue] classDef service fill:#4CAF50,stroke:#388E3C,color:white; classDef db fill:#2196F3,stroke:#0D47A1,color:white; classDef queue fill:#FF9800,stroke:#EF6C00,color:white; class C,D,F service; class E db; class G queue; click C "https://github.com/org/vllm-deploy" "vLLM部署文档"

关键技巧：click语法链接到真实代码仓库，让架构图成为导航入口；classDef统一配色，不同颜色代表不同责任域（绿色=计算服务，蓝色=存储，橙色=消息）；<br/>换行保持节点紧凑。每次PR提交，CI会自动检查Mermaid语法，并用mermaid-cli渲染成PNG插入Confluence。

4.2 vLLM服务部署：从镜像到上线的完整步骤

步骤1：构建定制化Docker镜像

官方vLLM镜像（vllm/vllm-cpu）不包含我们所需的依赖。我们基于nvidia/cuda:11.8.0-devel-ubuntu22.04构建：

FROM nvidia/cuda:11.8.0-devel-ubuntu22.04 RUN apt-get update && apt-get install -y python3-pip python3-dev && rm -rf /var/lib/apt/lists/* COPY requirements.txt . RUN pip3 install --no-cache-dir -r requirements.txt # 包含vllm==0.4.2, transformers==4.41.0 COPY entrypoint.sh /entrypoint.sh ENTRYPOINT ["/entrypoint.sh"]

requirements.txt关键项：

vllm==0.4.2 transformers==4.41.0 torch==2.3.0+cu118 sentence-transformers==2.3.0 # 用于RAG的embedding

步骤2：K8s Deployment配置（核心参数）

apiVersion: apps/v1 kind: Deployment metadata: name: vllm-service spec: replicas: 3 selector: matchLabels: app: vllm-service template: metadata: labels: app: vllm-service spec: nodeSelector: kubernetes.io/os: linux gpu-type: a10 # 调度到A10节点 tolerations: - key: "nvidia.com/gpu" operator: "Exists" effect: "NoSchedule" containers: - name: vllm image: our-registry/vllm:0.4.2-a10 ports: - containerPort: 8000 resources: limits: nvidia.com/gpu: 2 # 独占2块A10 memory: 32Gi requests: nvidia.com/gpu: 2 memory: 32Gi command: ["python3", "-m", "vllm.entrypoints.api_server"] args: - "--model=/models/Qwen1.5-7B-Chat" - "--tensor-parallel-size=2" - "--max-model-len=4096" - "--block-size=16" - "--enable-prefix-caching" - "--disable-log-requests" # 生产环境关闭请求日志，防隐私泄露 env: - name: VLLM_ATTENTION_BACKEND value: "FLASHINFER" # A10卡用FlashInfer比默认更快

避坑指南：--disable-log-requests必须开启！否则vLLM会把用户完整Prompt写入日志，违反GDPR。我们曾因未关此选项，被安全审计扣分。

步骤3：健康检查与自动扩缩容

Liveness Probe用vLLM自带的/health端点，但Readiness Probe需自定义，因为/health只检查进程存活，不检查GPU是否Ready：

livenessProbe: httpGet: path: /health port: 8000 initialDelaySeconds: 60 periodSeconds: 30 readinessProbe: exec: command: - sh - -c - | # 检查GPU显存是否被vLLM正常占用 nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits | head -1 | awk '{if ($1 > 1000) print "ready"; else exit 1}' initialDelaySeconds: 120 periodSeconds: 60

HPA（Horizontal Pod Autoscaler）基于vllm:request_waiting_time_seconds指标：

apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: vllm-hpa spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: vllm-service minReplicas: 2 maxReplicas: 10 metrics: - type: Pods pods: metric: name: vllm_request_waiting_time_seconds target: type: AverageValue averageValue: 0.2 # P95等待时间超过200ms，扩容

4.3 RAG模块实操：从文档入库到检索生效

文档入库Pipeline（Airflow DAG）

# airflow/dags/rag_ingestion.py from airflow import DAG from airflow.operators.python import PythonOperator from datetime import datetime, timedelta def ingest_document(**context): doc_path = context['dag_run'].conf.get('doc_path') # 1. 解析PDF from pypdf import PdfReader reader = PdfReader(doc_path) text = "".join([page.extract_text() for page in reader.pages]) # 2. 语义分块 from semantic_chunkers import RegexChunker chunker = RegexChunker(chunk_size=512, overlap=128) chunks = chunker.chunk(text) # 3. 向量化并入库 from sentence_transformers import SentenceTransformer model = SentenceTransformer('paraphrase-multilingual-MiniLM-L12-v2') embeddings = model.encode(chunks) # 写入Milvus（省略连接代码） collection.insert([chunks, embeddings]) dag = DAG( 'rag_ingestion', default_args={'retries': 1}, schedule_interval=None, start_date=datetime(2024, 1, 1), ) ingest_task = PythonOperator( task_id='ingest_doc', python_callable=ingest_document, dag=dag, )

注意：paraphrase-multilingual-MiniLM-L12-v2模型虽小，但对中文语义捕捉足够好，且推理快。别用all-MiniLM-L6-v2，它对中文支持弱。

Hybrid Search服务（FastAPI）

# search_service/main.py from fastapi import FastAPI from milvus import Collection from rank_bm25 import BM25Okapi import numpy as np app = FastAPI() # 初始化Milvus Collection和BM25索引（从DB加载） milvus_collection = Collection("rag_docs") bm25_index = load_bm25_from_db() # 加载预计算的BM25索引 @app.post("/hybrid_search") def hybrid_search(query: str): # 1. 向量检索 query_embedding = embed_model.encode([query])[0] results_vector = milvus_collection.search( data=[query_embedding], anns_field="embedding", param={"metric_type": "COSINE", "params": {"nprobe": 10}}, limit=10 ) # 2. BM25检索 tokenized_query = query.split() scores_bm25 = bm25_index.get_scores(tokenized_query) top_bm25 = np.argsort(scores_bm25)[-10:][::-1] # 3. Rank Fusion fused_scores = {} for i, (id, score) in enumerate(results_vector[0]): fused_scores[id] = 0.7 * score + 0.3 * (scores_bm25[id] if id in scores_bm25 else 0) # 返回Top5 return sorted(fused_scores.items(), key=lambda x: x[1], reverse=True)[:5]

实操心得：Rank Fusion权重（0.7/0.3）是调参结果。纯向量检索召回率高但相关性差；纯BM25相关性好但泛化性差。加权融合后，NDCG@5提升31%。

5. 常见问题排查与独家避坑技巧实录

5.1 典型问题速查表

5.2 我踩过的五个深坑与解决方案

坑1：模型版本漂移无人知晓
现象：某天突然发现回答质量下降，回溯发现vLLM镜像Tag是latest，自动拉取了新版vLLM（0.4.1→0.4.2），其PagedAttention实现有细微差异。
→解决方案：所有镜像Tag必须用SHA256哈希（vllm:0.4.2@sha256:abc123...），CI流水线强制校验；在架构图中，每个服务旁标注Image: vllm:0.4.2@sha256:...。

坑2：K8s Service的headless与ClusterIP混用
现象：vLLM Pod间gRPC通信偶尔超时。
→真相：vLLM的--tensor-parallel-size=2要求2个Pod必须在同一节点（共享GPU），但我们用ClusterIP Service，K8s负载均衡把请求随机分发到不同节点。
→解决方案：为vLLM StatefulSet创建Headless Service（clusterIP: None），用DNS SRV记录直接解析Pod IP，确保Pod间直连。

坑3：Milvus的AutoIndex失效
现象：新文档入库后，检索速度极慢。
→根因：Milvus 2.4默认auto_id=true，但我们的文档ID是业务生成的UUID，导致AutoIndex未触发。
→修复：在Collection Schema中显式设置auto_id=false，并在insert时传入ids参数。

坑4：Prometheus指标采集丢失
现象：Grafana看板中vLLM指标为空。
→排查：发现vLLM的/metrics端点返回的是OpenMetrics格式，而我们的Prometheus配置了honor_labels: true，导致label冲突。
→解决：在Prometheus scrape config中添加honor_labels: false，并用relabel_configs重写job名称。

坑5：安全审计发现Prompt泄露
现象：审计报告指出，vLLM日志包含用户完整Prompt。
→紧急补救：立即在Deployment中添加--disable-log-requests；同时，在API网关层用Kong Plugin过滤X-Prompt-DebugHeader，防止前端误传调试信息。

5.3 架构图演进的三个阶段

一张架构图的生命，始于设计，终于废弃。我们总结出三个必经阶段：

• Phase 1：设计草图（Design Sketch）：用draw.io快速勾勒，聚焦核心路径和关键决策（如“选vLLM而非TGI”），不纠结样式，目的是对齐认知；
• Phase 2：生产蓝图（Production Blueprint）：转为Mermaid代码，嵌入所有真实配置（IP、端口、参数），链接