从Jupyter到生产：机器学习模型的可运维性设计与实践

1. 项目概述：当Jupyter笔记本走出实验室，真正扛起线上业务的重担

“From Notebook to Production: Running ML in the Real World (Part 4)”——这个标题里藏着一个被无数数据科学家反复咀嚼、又悄悄咽下的现实：我们花了80%的时间在Jupyter里调参、画图、写注释，却只用20%的时间思考——这串代码，明天能不能在凌晨三点稳稳接住12万并发的订单预测请求？能不能在用户点击“立即购买”的0.3秒内，把最可能成交的SKU推到首屏？能不能在服务器内存只剩1.2GB时，不报错、不降级、不抖动地完成实时风控打分？这不是学术竞赛的排行榜，这是真实世界里的生产环境。它不认.ipynb后缀，不看plt.show()是否美观，只认SLA（服务等级协议）、P99延迟、OOM（内存溢出）次数和运维同事凌晨发来的那条微信：“模型服务挂了，老板在会议室等你。”本篇聚焦的是整个迁移链条中最容易被轻视、却最致命的一环：从可运行（Runnable）到可运维（Operable）的跃迁。它不是讲怎么把model.fit()打包成Docker镜像，而是讲清楚——当你的PyTorch模型在Kubernetes里跑了三天后，CPU使用率突然从35%飙升到98%，日志里只有一行WARNING:root:NaN loss detected，你该先查Prometheus指标，还是翻Git提交记录，抑或直接kubectl exec -it进容器抓内存快照？这才是Part 4的全部意义：它不教你怎么“上线”，它教你怎么“活下来”。

我带过三支AI工程团队，亲手把27个模型送进生产环境。最深的教训来自一个推荐模型：它在测试环境AUC 0.89，上线后首周转化率提升12%，团队庆功宴还没散场，监控告警就炸了——每小时有47次“特征时效性超阈值”告警。排查发现，特征管道里一个上游ETL任务因数据库锁表延迟了22分钟，但模型服务没做任何熔断，硬生生用22分钟前的特征做了实时打分。结果是：用户刚加购的手机壳，首页还在推同款——因为特征没更新。这种问题，Jupyter里永远测不出来。它需要你在代码里埋下“健康探针”，在部署配置里写死“最大容忍延迟”，在SLO文档里白纸黑字定义“特征新鲜度=距当前时间≤5分钟”。所以，别再把Part 4当成“部署收尾篇”，它是整条ML生命周期的“生存守则”。适合所有正在把第一个模型推上生产环境的算法工程师、MLOps初学者，以及那些被运维同事追着问“你们模型到底依赖啥端口、啥环境变量、啥磁盘配额”的技术负责人。你不需要会写K8s YAML，但必须能看懂livenessProbe为什么比readinessProbe多一个initialDelaySeconds；你不必精通Prometheus，但得知道model_inference_duration_seconds_bucket这个指标，比你昨天调的learning_rate更能决定老板下周要不要砍掉你的预算。

2. 核心设计逻辑：为什么“能跑通”和“能扛住”之间隔着一整个运维体系

2.1 拒绝“胶水式部署”：从脚本拼接到契约驱动的交付物

很多团队的“生产化”第一步，是写一个deploy.sh脚本：pip install -r requirements.txt→python app.py→nohup python app.py &。这就像用胶水把乐高积木粘成房子——看着立住了，但一阵风来就散架。Part 4的核心设计哲学，是彻底抛弃“胶水”，建立契约驱动的交付物（Contract-Driven Artifact）。它的本质是：模型服务不是一段代码，而是一份具备明确接口、资源承诺、健康标准的“数字合同”。

这份合同包含三个不可协商的条款：

1. 接口契约（Interface Contract）：不是“提供一个HTTP API”，而是明确定义POST /v1/predict的请求体JSON Schema（含字段类型、必填项、取值范围），响应体的HTTP状态码语义（200=成功且置信度≥0.6，422=输入特征缺失，503=内部队列积压＞1000），甚至规定gRPC的proto文件版本号。我见过最惨的案例：算法同学升级了模型，输出从{"score": 0.72}变成{"probability": 0.72, "class": "high_risk"}，但下游风控系统只解析score字段，结果所有高风险用户都被判为“低风险”。接口契约强制要求：任何变更必须通过OpenAPI 3.0规范生成，并经下游团队签字确认。

2. 资源契约（Resource Contract）：拒绝“尽量少占内存”的模糊表述。必须量化：单实例服务在P95负载下，CPU使用率≤60%，内存占用≤1.8GB（含JVM/Python GC开销），磁盘I/O等待时间＜5ms。这个数字怎么来？不是拍脑袋。我们用locust模拟真实流量（复刻线上用户行为序列，而非简单QPS压测），在预发环境跑72小时，采集cAdvisor指标，取P95值向上取整15%作为安全冗余。曾有个NLP模型标称“内存占用＜1GB”，实测在批量推理时触发Linux OOM Killer——因为没算上Hugging Face tokenizer加载词表的峰值内存。资源契约逼你直面物理世界的限制。

3. 健康契约（Health Contract）：/healthz端点不能只返回{"status": "ok"}。它必须验证三项：a) 模型权重文件MD5与Git commit hash匹配（防误部署）；b) 连接下游特征存储的TCP握手成功且响应延迟＜200ms；c) 本地缓存的最新特征时间戳距当前≤300秒。少一项，/healthz就返回503，K8s自动剔除该实例。这才是真正的“自愈能力”，不是靠人盯监控，而是靠代码自己举手报告“我病了”。

提示：契约不是文档，是可执行的代码。我们用pydantic校验接口Schema，用cgroups限制容器资源上限，用pytest跑test_health_check.py作为CI/CD流水线的强制门禁。契约失效=构建失败，没有商量余地。

2.2 “不可变基础设施”不是口号：镜像即真相，环境即代码

“Write once, run anywhere”在ML领域是个巨大陷阱。同一个requirements.txt，在Mac M1上pip install torch装的是ARM64版，在Ubuntu 20.04上装的是x86_64版，模型推理结果因浮点运算微小差异导致AUC波动0.003——这在金融风控里就是合规红线。Part 4的解决方案是：镜像即真相（Image as Truth）。所有环境差异，必须收敛到Docker镜像层。

具体怎么做？我们废弃了FROM python:3.9-slim这种“基础镜像”，改用四层镜像架构：

• Base Layer（基础层）：FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu20.04。固定CUDA/cuDNN版本，杜绝GPU驱动兼容性问题。
• Runtime Layer（运行时层）：预编译安装PyTorch 1.13.1+cu117（注意：CUDA版本必须比Base Layer低一级，这是NVIDIA官方兼容矩阵要求），并pip install --no-cache-dir所有非模型依赖（numpy,pandas,fastapi）。这一层每周构建一次，缓存到私有Harbor仓库，全公司共享。
• Model Layer（模型层）：COPY model/ /app/model/。仅包含model.pth、tokenizer.json、config.yaml。关键操作：RUN chmod 444 /app/model/*（只读权限），RUN md5sum /app/model/model.pth > /app/model/MODEL_HASH。模型文件一旦写入，禁止修改。
• App Layer（应用层）：COPY app/ /app/。包含main.py、Dockerfile、health_check.py。CMD ["gunicorn", "-c", "gunicorn.conf.py", "main:app"]。

为什么分四层？因为每一层的变更频率和影响范围完全不同。Base Layer年更，Runtime Layer月更，Model Layer按需日更，App Layer随时可更。当模型需要升级，只需重建Model Layer和App Layer，Base和Runtime复用——镜像拉取速度从12分钟降到47秒，CI/CD流水线稳定性从78%提升到99.2%。更重要的是，当你在生产环境发现bug，docker inspect <image_id>就能精确看到：它用的是哪版CUDA、哪个PyTorch commit、模型文件MD5是多少。环境不再是个黑盒，而是可追溯、可审计、可回滚的实体。

注意：绝对禁止在Dockerfile里写RUN pip install -r requirements.txt。这会导致每次构建都重新下载依赖，网络抖动时构建失败，且无法保证依赖版本一致性。所有依赖必须固化在Runtime Layer。

2.3 流量治理：不是“一刀切”，而是“分级熔断”的生存策略

生产环境最残酷的真相是：你永远无法100%保证上游稳定。特征服务可能因DB主从延迟返回陈旧数据；用户设备可能上传损坏的图片；第三方API可能返回格式错乱的JSON。如果模型服务对所有异常都抛500，整个业务链路就断了。Part 4引入三级熔断机制（Tiered Circuit Breaking），让服务在混沌中保持基本可用。

• L1：输入熔断（Input-Level）：在FastAPI的Depends()里嵌入InputValidator。它不只校验JSON Schema，还做业务规则检查：if user_id < 0: raise HTTPException(422, "user_id must be positive")；if len(image_bytes) > 10*1024*1024: raise HTTPException(413, "image too large")。L1失败直接返回4xx，不消耗模型计算资源。

• L2：特征熔断（Feature-Level）：模型加载时，预定义CRITICAL_FEATURES = ["user_age", "last_purchase_days"]。推理前，检查这些特征是否为空或超阈值（如user_age > 120）。若L2触发，不调用模型，直接走fallback_strategy——比如返回历史平均分，或调用轻量级规则引擎。我们用Redis记录L2触发频次，当1分钟内超100次，自动告警并降级整个服务。

• L3：模型熔断（Model-Level）：这是最后防线。在model.predict()外层包try...except，捕获torch.cuda.OutOfMemoryError、ValueError（NaN输入）、TimeoutError（模型推理超时）。L3触发时，服务不崩溃，而是：a) 记录完整错误上下文到ELK；b) 将当前请求加入dead_letter_queue供离线分析；c) 返回{"status": "degraded", "fallback_score": 0.5}。用户无感知，业务不中断。

这三级不是并列的，而是递进的漏斗。L1过滤85%的垃圾请求，L2保护模型核心逻辑，L3兜底极端故障。某次大促前，我们故意注入故障：将特征服务延迟设为15秒。结果L1/L2正常工作，L3触发率仅0.3%，整体服务P99延迟从120ms升至180ms，但成功率保持99.99%。这才是生产级的韧性。

3. 实操细节拆解：从代码到K8s，每个环节的魔鬼参数

3.1 模型服务代码：不只是predict()，更是“可观测性入口”

很多算法同学写的app.py只有20行：加载模型、定义API、启动服务。Part 4要求：每一行代码都必须回答“当它出问题时，我怎么定位？”。以下是经过生产验证的核心代码结构（FastAPI + PyTorch）：

# main.py from fastapi import FastAPI, Request, HTTPException, Depends from pydantic import BaseModel, Field import torch import time import logging from prometheus_client import Counter, Histogram, Gauge # 全局指标（注意：必须在模块顶层定义，否则多进程下指标混乱） INFERENCE_COUNTER = Counter('model_inference_total', 'Total number of inferences') INFERENCE_LATENCY = Histogram('model_inference_duration_seconds', 'Inference latency in seconds') MODEL_MEMORY_USAGE = Gauge('model_memory_usage_bytes', 'Current model memory usage in bytes') app = FastAPI(title="Fraud Detection Model") # 健康检查：验证模型、特征源、缓存 @app.get("/healthz") async def health_check(): # 1. 模型文件完整性 try: with open("/app/model/MODEL_HASH", "r") as f: expected_hash = f.read().strip().split()[0] actual_hash = get_file_md5("/app/model/model.pth") if actual_hash != expected_hash: raise Exception(f"Model hash mismatch: {actual_hash} != {expected_hash}") except Exception as e: logging.error(f"Model health check failed: {e}") raise HTTPException(503, "Model file corrupted") # 2. 特征源连通性（这里调用特征SDK的ping方法） try: feature_sdk.ping(timeout=2.0) except Exception as e: logging.error(f"Feature store ping failed: {e}") raise HTTPException(503, "Feature store unreachable") return {"status": "ok", "timestamp": int(time.time())} # 输入模型（强约束！） class PredictionRequest(BaseModel): user_id: int = Field(..., ge=1, le=2147483647, description="Valid user ID") transaction_amount: float = Field(..., ge=0.01, le=1000000.0, description="Amount in USD") device_fingerprint: str = Field(..., min_length=32, max_length=64, description="SHA256 hash") # 核心推理端点（带完整可观测性） @app.post("/v1/predict") async def predict(request: PredictionRequest, req: Request = Depends()): start_time = time.time() INFERENCE_COUNTER.inc() # 计数器+1 try: # L1输入熔断（已在Pydantic BaseModel中实现） # L2特征熔断：获取特征 features = await fetch_features(request.user_id) if not features or any(v is None for v in features.values()): logging.warning(f"L2 fallback triggered for user_id {request.user_id}") return {"score": 0.5, "reason": "feature_missing", "fallback": True} # L3模型熔断：实际推理 with torch.no_grad(): input_tensor = torch.tensor([list(features.values())], dtype=torch.float32) if torch.cuda.is_available(): input_tensor = input_tensor.cuda() INFERENCE_LATENCY.observe(time.time() - start_time) # 记录GPU推理延迟 result = model(input_tensor).cpu().item() else: INFERENCE_LATENCY.observe(time.time() - start_time) # CPU延迟 result = model(input_tensor).item() # 更新内存用量Gauge（关键！监控OOM前兆） if torch.cuda.is_available(): MODEL_MEMORY_USAGE.set(torch.cuda.memory_allocated()) else: MODEL_MEMORY_USAGE.set(get_process_memory()) return {"score": float(result), "request_id": req.headers.get("X-Request-ID", "unknown")} except torch.cuda.OutOfMemoryError as e: logging.error(f"CUDA OOM: {e}") raise HTTPException(503, "Model overloaded, please retry") except Exception as e: logging.exception("Unexpected error in predict") raise HTTPException(500, "Internal server error") finally: # 确保延迟统计完成 INFERENCE_LATENCY.observe(time.time() - start_time)

关键参数说明：

• INFERENCE_LATENCY的buckets必须自定义：buckets=(0.01, 0.05, 0.1, 0.2, 0.5, 1.0, 2.0, 5.0)。默认的指数桶（1,2,4,8...）对ML服务毫无意义——你要关注的是0.1秒和0.2秒的差异，不是1秒和2秒。
• MODEL_MEMORY_USAGE用Gauge而非Counter，因为它要反映瞬时值。我们每10秒采样一次，当连续3次＞1.5GB时触发告警。
• fetch_features()必须带超时（我们设为3.0秒），且超时后直接走L2 fallback，绝不让模型等待。

实操心得：不要用logging.info()打满日志。我们只在L2/L3熔断、异常捕获、健康检查失败时打ERROR或WARNING。正常推理日志全部关闭。日志量太大不仅吃磁盘，更会拖慢print()系统调用——实测关闭日志后P99延迟降低17ms。

3.2 Docker构建：如何让镜像体积从2.3GB压缩到487MB

一个未经优化的PyTorch模型服务镜像，常因以下原因膨胀：

• pip install缓存未清理
• .pyc字节码文件残留
• CUDA调试符号包（cuda-toolkit）被误装
• 模型权重文件未压缩（.pth是纯二进制，但可gzip）

我们的Dockerfile精简策略：

# 使用多阶段构建（Multi-stage Build） FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu20.04 AS builder # 安装编译依赖（仅构建阶段需要） RUN apt-get update && apt-get install -y --no-install-recommends \ build-essential \ python3-dev \ && rm -rf /var/lib/apt/lists/* # 创建非root用户（安全基线） RUN groupadd -g 1001 -f app && useradd -r -u 1001 -g app app USER app # 复制并安装依赖（注意：--no-cache-dir 和 --no-deps） COPY --chown=app:app requirements.txt . RUN pip3 install --no-cache-dir --no-deps --target /tmp/install \ torch==1.13.1+cu117 torchvision==0.14.1+cu117 -f https://download.pytorch.org/whl/torch_stable.html # 复制应用代码 COPY --chown=app:app app/ /tmp/app/ # 构建最终镜像 FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu20.04 # 只复制运行时必需的文件（最小化攻击面） COPY --from=builder /tmp/install /usr/local/lib/python3.9/site-packages/ COPY --from=builder /tmp/app /app/ # 清理无用文件（关键！） RUN apt-get clean && \ rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* && \ find /usr/local/lib/python3.9/site-packages -name "*.so" -not -name "libtorch*" -delete && \ find /usr/local/lib/python3.9/site-packages -name "__pycache__" -type d -exec rm -rf {} + # 设置工作目录和用户 WORKDIR /app USER 1001 # 验证模型文件（防止COPY损坏） RUN cd /app && \ gunzip -t model/model.pth.gz 2>/dev/null || { echo "Model file corrupt!"; exit 1; } CMD ["gunicorn", "-c", "gunicorn.conf.py", "main:app"]

效果对比：

注意：gunzip -t校验必须放在CMD之前。我们吃过亏：某次CI流水线网络抖动，COPY命令部分写入，模型文件损坏，但服务仍能启动——直到第一次推理才报OSError: invalid load key。现在，镜像构建失败率从12%降到0.3%。

3.3 Kubernetes部署：YAML不是配置，而是“服务生命契约”

K8s YAML文件常被当成“部署脚本”，这是巨大误区。Part 4要求：每一份YAML都是服务的“生命契约”（Life Contract），它声明的不是“怎么部署”，而是“服务存活的必要条件”。

以下是生产环境deployment.yaml的核心片段（已脱敏）：

apiVersion: apps/v1 kind: Deployment metadata: name: fraud-model-v2 labels: app: fraud-model version: v2 spec: replicas: 3 selector: matchLabels: app: fraud-model version: v2 template: metadata: labels: app: fraud-model version: v2 annotations: # 关键：镜像签名验证（防止恶意镜像） container.apparmor.security.beta.kubernetes.io/fraud-model: runtime/default # Prometheus指标抓取配置 prometheus.io/scrape: "true" prometheus.io/port: "8000" spec: serviceAccountName: model-sa # 绑定最小权限ServiceAccount securityContext: runAsNonRoot: true runAsUser: 1001 fsGroup: 1001 containers: - name: fraud-model image: harbor.example.com/ml/fraud-model:v2.3.1@sha256:abc123... # 资源契约：硬性限制，非请求 resources: limits: cpu: "2" memory: "2Gi" nvidia.com/gpu: "1" requests: cpu: "1" memory: "1.5Gi" nvidia.com/gpu: "1" # 健康契约：livenessProbe必须比readinessProbe严格 livenessProbe: httpGet: path: /healthz port: 8000 initialDelaySeconds: 60 # 模型加载需时间，不能太急 periodSeconds: 30 # 每30秒检查一次 timeoutSeconds: 5 # 超时5秒即失败 failureThreshold: 3 # 连续3次失败才重启 readinessProbe: httpGet: path: /healthz port: 8000 initialDelaySeconds: 30 # 比liveness早30秒，更快接入流量 periodSeconds: 10 # 更高频检查就绪状态 timeoutSeconds: 3 # 就绪检查更严格 successThreshold: 1 # 环境变量：所有配置外置化 env: - name: FEATURE_STORE_URL valueFrom: configMapKeyRef: name: model-config key: feature_store_url - name: MODEL_TIMEOUT_SEC value: "5.0" # 模型推理超时，单位秒 # 卷挂载：只读模型，可写日志 volumeMounts: - name: model-volume mountPath: /app/model readOnly: true - name: logs-volume mountPath: /app/logs volumes: - name: model-volume persistentVolumeClaim: claimName: model-pvc # 指向只读的NFS PV - name: logs-volume emptyDir: {} # 临时日志卷，Pod销毁即清空 --- # Service：定义服务发现 apiVersion: v1 kind: Service metadata: name: fraud-model-service spec: selector: app: fraud-model version: v2 ports: - port: 8000 targetPort: 8000 # 关键：启用外部IP（供Ingress或NodePort调用） type: ClusterIP --- # HorizontalPodAutoscaler：基于真实指标扩缩容 apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: fraud-model-hpa spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: fraud-model-v2 minReplicas: 2 maxReplicas: 10 metrics: - type: Pods pods: metric: name: model_inference_duration_seconds target: type: AverageValue averageValue: 100m # P95延迟＞100ms时扩容 - type: Resource resource: name: cpu target: type: Utilization averageUtilization: 70 # CPU＞70%时扩容

关键参数解读：

• initialDelaySeconds：livenessProbe设为60秒，因为模型加载（特别是BERT类大模型）可能耗时45秒。若设为10秒，Pod会因健康检查失败被无限重启。
• failureThreshold: 3：允许3次失败，避免网络抖动误杀。我们实测，设置为1时，因DNS解析偶尔超时，Pod每小时重启2次。
• averageValue: 100m：HPA扩缩容目标是P95延迟，不是平均延迟。平均延迟可能被长尾请求拉高，而P95更能反映用户体验。
• nvidia.com/gpu: "1"：显卡资源必须用limits指定，K8s才能正确调度到有GPU的节点。requests可设为0，但limits必须精确。

实操心得：永远用image@sha256:xxx而非image:tag。某次运维误删了latest标签，所有用image:latest的Deployment全部拉取失败。现在，CI流水线生成镜像后，自动将sha256哈希写入YAML并提交Git，确保部署可追溯。

4. 生产环境实战：从告警风暴到根因定位的完整排障链

4.1 典型故障场景复盘：CPU飙升98%背后的“幽灵线程”

故障现象：某日凌晨2:17，fraud-model-v2的CPU使用率从35%突增至98%，持续42分钟，期间P99延迟从120ms飙升至2.3秒，触发业务方告警。

排查路径（按时间顺序）：

1. 第一分钟（告警触发）：查看K8s Dashboard，确认是单个Pod异常（非全局），排除集群级问题。kubectl top pod fraud-model-v2-7d8f9c4b5-2xq9k显示CPU 98%，内存1.4GB（正常）。
2. 第二分钟（进程级）：kubectl exec -it fraud-model-v2-7d8f9c4b5-2xq9k -- ps aux --sort=-%cpu，发现python进程占97.2%，但top -H显示其线程ID（TID）中，有一个TID 12345持续占95% CPU。
3. 第三分钟（线程栈）：kubectl exec -it fraud-model-v2-7d8f9c4b5-2xq9k -- gdb -p 12345 -ex "thread apply all bt" -ex quit 2>/dev/null | grep -A 20 "torch"，输出关键栈帧：

   #0 0x00007f8a1b2c3e3d in cblas_sgemm () from /usr/local/lib/python3.9/site-packages/torch/lib/libtorch_cpu.so #1 0x00007f8a1b2c41a2 in at::native::addmm_out_cuda_impl () from /usr/local/lib/python3.9/site-packages/torch/lib/libtorch_cuda.so

   确认是CUDA矩阵乘法卡死。
4. 第五分钟（GPU状态）：kubectl exec -it fraud-model-v2-7d8f9c4b5-2xq9k -- nvidia-smi，发现GPU利用率0%，但Volatile GPU-Util显示100%——这是典型“GPU kernel hang”：CUDA kernel卡在某个指令，GPU显存未释放，但计算单元空转。
5. 第七分钟（根因）：检查/app/logs/下的error.log，发现凌晨2:16:58有RuntimeWarning: invalid value encountered in matmul。结合代码，定位到fetch_features()返回了一个含NaN的特征向量，torch.matmul()遇到NaN后进入死循环。

根本原因：上游特征服务在DB主从切换时，短暂返回了NULL值，而我们的L2特征熔断只检查None，未检查np.nan。pd.isna()未被调用。

修复方案：

• 紧急：kubectl delete pod fraud-model-v2-7d8f9c4b5-2xq9k，K8s自动重建。
• 永久：在fetch_features()后增加if pd.isna(features).any(): raise ValueError("NaN feature detected")，并升级L2熔断逻辑。
• 预防：在Prometheus中添加告警规则count by (pod) (rate(model_inference_duration_seconds_count{job="fraud-model"}[5m])) > 1000 and on(pod) (avg by (pod) (irate(process_cpu_seconds_total{job="fraud-model"}[5m]))) > 0.95，即高QPS+高CPU时告警。

注意：不要在生产环境用gdb长时间attach进程。我们已将gdb命令封装为debug-pod.sh脚本，执行后自动采集栈、内存、GPU状态并退出，全程＜8秒。

4.2 日志与指标协同分析：如何从10万行日志里30秒定位问题

生产环境日志量巨大，但90%的日志是噪音。Part 4的黄金法则是：日志是“事件快照”，指标是“趋势脉搏”，二者必须交叉验证。

我们建立的标准分析流程：

关键技巧：

• Trace ID必须透传：在FastAPI中，用X-Request-IDHeader生成唯一ID，并在所有日志、指标、特征查询中携带。我们用uvicorn的--access-log参数开启访问日志，其中包含%{X-Request-ID}i。
• 日志结构化：所有logging.error()必须传入extra={"trace_id": trace_id, "user_id": user_id, "features": features_dict}，Kibana可直接解析为字段。
• 指标命名规范：model_inference_duration_seconds_bucket{le="0.2"}中的le="0.2"表示“小于等于0.2秒”，这是Prometheus直方图的标准标签，用于计算P95。

实操心得：在Kibana中创建Saved Search，预设好trace_id、user_id、error等常用筛选器。新人入职第一天，就能用这个Saved Search在30秒内完成一次完整排障。

4.3 常见问题速查表：那些让你凌晨三点爬起来的“经典坑”