机器学习生产化实战：从模型服务到可观测部署

1. 项目概述：这不是“跑通模型”，而是让模型在真实世界里活下来

“From Notebook to Production: Running ML in the Real World (Part 4)”——这个标题本身就像一句行话暗号，老手一眼就懂：前面三篇已经蹚过了数据清洗、特征工程、模型训练和验证的浅水区，而这一part，是真正把脚踩进泥里，开始面对生产环境那套冷酷又琐碎的生存法则。它不讲怎么调高0.5%的AUC，而是直击一个所有ML工程师最终都绕不开的硬核问题：你花三个月在Jupyter里调得闪闪发光的模型，一旦脱离本地GPU和干净数据集，放进每天要处理百万级请求、数据格式随时漂移、上游服务可能凌晨三点挂掉的线上系统里，它还能不能呼吸？会不会直接窒息？会不会在半夜三点给你发告警邮件，而你连日志都看不懂？我做过不下二十个从实验室走向产线的模型落地项目，最深的体会是：模型的准确率决定它能不能被录用，而它的可观测性、可维护性和容错能力，才真正决定它能干多久、干得多稳。这篇内容的核心关键词——ML production（机器学习生产化）、model serving（模型服务化）、real-world deployment（真实场景部署）、MLOps pipeline（MLOps流水线）——每一个都不是抽象概念，而是由无数个具体选择堆砌起来的生存策略：选什么服务框架不是比谁名字响亮，而是看它能不能在你公司那台跑了八年、内存只有32G的老K8s节点上不OOM；做模型监控不是为了画几张好看Dashboard，而是要在用户投诉前五分钟，从延迟毛刺里嗅出特征漂移的气味。它适合三类人：刚从学校出来、还在用model.predict()当万能钥匙的新人，需要提前建立对“生产”二字的敬畏；正在被线上模型事故追着跑的算法工程师，急需一套可立即上手的排查路径；还有技术决策者，想搞清楚为什么团队花了大价钱买MLOps平台，却还是在用Excel手动记录模型版本。这不是一篇教你“如何优雅地写代码”的文章，而是一份写满血渍与胶带的现场维修手册。

2. 内容整体设计与思路拆解：为什么“部署”不是终点，而是运维的起点

2.1 从“能跑”到“敢跑”的思维断层

很多团队卡在Part 4的根本原因，不是技术不会，而是思维没转过来。在Notebook里，“能跑”意味着print(model.predict(X_test))输出了一串数字；在生产里，“敢跑”意味着你敢在黑五促销期间，把模型嵌入到支付风控链路里，且承诺99.99%的可用性。这两者之间横亘着一条巨大的鸿沟，而这条鸿沟的宽度，恰恰由四个维度共同定义：可靠性（Reliability）、可观测性（Observability）、可复现性（Reproducibility）、可演进性（Evolvability）。Part 4的设计逻辑，就是围绕这四个支柱展开的闭环建设，而不是简单地把.pkl文件扔进Docker容器。我见过太多项目，在模型服务化阶段就埋下雷：比如用joblib保存了包含绝对路径的pandas.DataFrame对象，上线后因为路径不存在直接报错；或者在训练时用了sklearn最新版的HistGradientBoostingClassifier，但生产服务器只装了旧版，import就失败。这些都不是“bug”，而是环境契约的缺失。因此，整个方案的设计起点，不是“怎么封装”，而是“怎么定义契约”。我们选择以容器镜像（Docker Image）为唯一可信交付物，把模型、代码、依赖、甚至Python解释器版本全部固化进去。这意味着，你在本地docker build成功，就等于在生产环境docker run成功——这是可复现性的物理基础。而之所以不选更轻量的Serverless函数，是因为真实业务中，模型推理往往伴随着复杂的预处理（如实时解析Protobuf消息、调用外部API补全用户画像）和后处理（如按业务规则聚合多模型结果），这些逻辑如果硬塞进无状态函数里，会迅速变成难以调试的意大利面条。

2.2 服务框架选型：为什么放弃TensorFlow Serving，拥抱FastAPI+Uvicorn

模型服务框架的选择，是Part 4里第一个也是最重要的技术决策点。市面上常见选项有TensorFlow Serving、Triton Inference Server、Seldon Core、KServe，以及看似“简陋”的FastAPI。很多人第一反应是选TF Serving，毕竟名字里就带着“Serving”。但我在三个不同规模的项目里实测过，它的优势只在一种场景下成立：你100%使用TensorFlow/Keras训练模型，且模型结构极其标准（如纯CNN、纯RNN），同时你的团队有专职SRE负责维护其复杂的Bazel构建和配置体系。一旦模型里混入了PyTorch自定义算子，或者你需要在推理前加一段用requests调用内部用户服务的逻辑，TF Serving的配置YAML就会膨胀到200行，且任何一处缩进错误都会导致服务静默失败，日志里只有一句Failed to load model。而FastAPI+Uvicorn的组合，胜在“透明”和“可控”。它本质上就是一个Web API框架，所有逻辑——从接收JSON请求、解析、调用模型、到返回结果——都写在你自己的Python代码里。这意味着：

• 调试成本极低：本地python main.py就能启动服务，打断点、打日志、查变量，和开发普通Web接口毫无区别；
• 扩展性极强：想在预测前加缓存？@lru_cache一行搞定；想做AB测试分流？在路由函数里加个if random.random() > 0.5:就行；
• 运维友好：Uvicorn本身就是ASGI服务器，天然支持K8s的健康检查探针（/healthz端点），且内存占用稳定在200MB以内，不像TF Serving动辄吃掉1.5G内存。
  当然，它也有代价：你需要自己实现模型热加载、批处理（batching）、GPU显存管理。但这些恰恰是“真实世界”的必修课。比如模型热加载，我们不用轮询文件修改时间这种低效方式，而是监听Linux inotify事件，当检测到新模型文件写入完成（IN_MOVED_TO事件），再触发torch.load()并原子性地替换全局模型引用。这个过程耗时不到300ms，且全程不阻塞请求队列。这比依赖某个框架的“自动重载”功能，更能让你看清每一毫秒发生了什么。

2.3 监控体系设计：从“有没有在跑”到“跑得健不健康”

生产环境的监控，绝不是给Prometheus配几个http_request_duration_seconds指标就完事。真正的ML监控，必须穿透HTTP层，深入到模型行为本身。我们搭建了三层监控体系：

• 基础设施层：CPU、内存、GPU显存、网络IO——这是底线，确保机器没宕机；
• 服务层：QPS、P99延迟、HTTP 5xx错误率、模型加载耗时——这是服务健康度，回答“API是否可用”；
• 模型层：这才是Part 4的灵魂。我们强制要求每个模型服务必须暴露三个核心指标：
  1. inference_latency_ms：单次预测耗时，分P50/P90/P99统计；
  2. feature_drift_score：基于KS检验计算的输入特征分布偏移得分，阈值设为0.2，超限即告警；
  3. prediction_stability_ratio：过去1000次请求中，预测结果与前一次完全一致的比例，骤降说明模型输出变得“飘忽”，可能是数据污染或模型损坏。
     这些指标不是摆设。去年双十一，我们的推荐模型prediction_stability_ratio在凌晨2点从99.8%骤降至62%，同时feature_drift_score飙升至0.7。我们立刻切流，回溯发现上游用户行为日志服务因扩容失败，将click_time字段错误地填充为Unix纪元时间（1970年），导致所有时间特征坍缩为同一值。如果没有这个稳定性指标，问题会持续到用户大规模投诉，而我们只用了7分钟就定位并修复。这印证了一个朴素真理：在生产环境里，模型的“行为一致性”，比它的“绝对准确率”更值得优先守护。

3. 核心细节解析与实操要点：把抽象原则变成可触摸的代码和配置

3.1 Docker镜像构建：从“能运行”到“可审计”的质变

构建一个生产级模型服务镜像，关键在于“最小化”和“确定性”。我们摒弃了常见的FROM python:3.9-slim基础镜像，改用FROM continuumio/miniconda3:4.12.0，原因有三：一是Conda能精确锁定C++底层库（如libgfortran）版本，避免pip install numpy时因系统glibc版本不匹配导致的段错误；二是Conda环境可导出为environment.yml，比requirements.txt更能保证跨平台一致性；三是镜像体积更小——实测一个含PyTorch 1.12+CUDA 11.3的环境，Conda镜像仅1.2GB，而同等pip镜像达2.1GB。构建脚本Dockerfile的核心片段如下：

# 使用多阶段构建，分离构建环境与运行环境 FROM continuumio/miniconda3:4.12.0 AS builder COPY environment.yml . RUN conda env create -f environment.yml && \ conda clean --all -f -y && \ rm -rf /opt/conda/pkgs/* FROM continuumio/miniconda3:4.12.0 # 复制构建好的环境，而非重新安装 COPY --from=builder /opt/conda/envs/ml-prod /opt/conda/envs/ml-prod # 创建非root用户，提升安全性 RUN useradd -m -u 1001 -g 101 mluser && \ chown -R mluser:101 /opt/conda/envs/ml-prod USER mluser # 复制应用代码与模型 COPY --chown=mluser:101 src/ /app/ COPY --chown=mluser:101 models/production/model_v2.1.pt /app/models/ WORKDIR /app # 激活环境并设置PATH SHELL ["conda", "run", "-n", "ml-prod", "/bin/bash", "-c"] CMD ["uvicorn", "main:app", "--host", "0.0.0.0:8000", "--port", "8000", "--workers", "4"]

这个设计的关键细节在于环境复用。传统做法是在运行镜像里再次conda env create，这会导致每次构建都重复下载GB级包，且无法利用Docker层缓存。而多阶段构建将环境创建过程隔离在builder阶段，运行镜像只复制编译好的二进制文件，构建时间从12分钟缩短至90秒，且镜像SHA256哈希值完全由environment.yml内容决定——这意味着，只要环境定义不变，无论在哪台机器上构建，产出的镜像都是比特级相同的。这是可复现性的基石。另外，强制使用非root用户（UID 1001）并非形式主义：K8s集群默认启用PodSecurityPolicy，禁止容器以root运行，否则调度会直接失败。我曾在一个项目里因忽略此点，导致服务在测试环境跑得好好的，上线时卡在Pending状态整整一天，最后发现是安全策略拦截。

3.2 FastAPI服务骨架：不只是API，更是模型生命周期的控制器

一个健壮的模型服务，其核心不应是“预测函数”，而是一个模型生命周期管理器。我们在main.py中定义了清晰的模块职责：

# main.py from fastapi import FastAPI, HTTPException, Depends from pydantic import BaseModel from typing import List, Optional import torch import logging from model_loader import ModelManager # 自研模型加载器 from metrics_collector import MetricsCollector # 自研指标收集器 app = FastAPI(title="Recommendation Model Service") # 全局单例，管理模型加载、卸载、热更新 model_manager = ModelManager( model_path="/app/models/production/model_v2.1.pt", device="cuda" if torch.cuda.is_available() else "cpu" ) # 指标收集器，对接Prometheus metrics_collector = MetricsCollector() class PredictionRequest(BaseModel): user_id: str item_ids: List[str] context: dict # 动态上下文，如时间戳、设备类型 class PredictionResponse(BaseModel): predictions: List[float] model_version: str inference_time_ms: float @app.post("/predict", response_model=PredictionResponse) async def predict(request: PredictionRequest): try: # 1. 预处理：这里可插入任意业务逻辑 features = await preprocess(request) # 异步调用，不阻塞 # 2. 模型推理：由ModelManager统一调度 predictions, latency_ms = model_manager.predict(features) # 3. 后处理：如结果归一化、业务规则过滤 final_preds = postprocess(predictions, request.context) # 4. 上报指标 metrics_collector.record_inference(latency_ms, len(request.item_ids)) return PredictionResponse( predictions=final_preds, model_version=model_manager.current_version, inference_time_ms=latency_ms ) except Exception as e: logging.error(f"Prediction failed for user {request.user_id}: {e}") raise HTTPException(status_code=500, detail="Internal server error") # 健康检查端点，供K8s探针调用 @app.get("/healthz") def health_check(): return {"status": "ok", "model_loaded": model_manager.is_ready()}

这个骨架的精妙之处在于ModelManager的设计。它不是一个简单的torch.load()包装器，而是一个具备状态感知的控制器：

# model_loader.py import torch import threading from pathlib import Path from watchdog.observers import Observer from watchdog.events import FileSystemEventHandler class ModelManager: def __init__(self, model_path: str, device: str): self.model_path = Path(model_path) self.device = device self._model = None self._lock = threading.RLock() # 可重入锁，避免热更新时死锁 self.current_version = "unknown" self.is_loading = False self._load_model() # 初始化加载 self._start_watcher() # 启动文件监听 def _load_model(self): with self._lock: self.is_loading = True try: # 加载模型权重 state_dict = torch.load(self.model_path, map_location=self.device) # 实例化模型类（需与训练时一致） self._model = RecommendationModel().to(self.device) self._model.load_state_dict(state_dict) self._model.eval() # 关键！设为eval模式，禁用Dropout/BatchNorm self.current_version = self.model_path.stem.split('_')[-1] # 从文件名提取版本 logging.info(f"Model loaded: {self.current_version}") finally: self.is_loading = False def predict(self, features): with self._lock: if not self._model or self.is_loading: raise RuntimeError("Model not ready") start_time = time.time() with torch.no_grad(): # 禁用梯度，节省显存 output = self._model(features.to(self.device)) latency_ms = (time.time() - start_time) * 1000 return output.cpu().numpy(), latency_ms def _start_watcher(self): # 监听模型目录，当新模型文件写入完成时触发重载 event_handler = ModelReloadHandler(self.model_path.parent, self) observer = Observer() observer.schedule(event_handler, str(self.model_path.parent), recursive=False) observer.start()

这个设计解决了三个痛点：一是torch.no_grad()和.eval()的强制调用，避免推理时意外启用训练模式导致结果异常；二是细粒度的线程锁（RLock），允许同一线程多次获取锁，防止在热更新过程中因锁竞争导致服务假死；三是基于文件系统事件的热加载，比轮询高效百倍。更重要的是，它把“模型”从一个静态对象，变成了一个可观察、可控制、可审计的运行时实体。

3.3 特征漂移监控：用KS检验量化“数据变了”

特征漂移（Feature Drift）是生产模型失效的头号杀手，但很多团队仍停留在“看直方图”的原始阶段。Part 4要求我们用统计学方法给出量化答案。我们选择Kolmogorov-Smirnov（KS）检验，因为它不依赖数据分布假设，对样本量不敏感，且计算速度快。核心逻辑是：将线上实时请求的特征向量，与训练时的基准分布进行KS检验，计算KS统计量（0~1之间），值越大表示分布差异越显著。

# drift_detector.py import numpy as np from scipy import stats from collections import defaultdict class DriftDetector: def __init__(self, baseline_features: np.ndarray): """ baseline_features: (n_samples, n_features) 训练数据特征矩阵 """ self.baseline_stats = {} for i in range(baseline_features.shape[1]): # 对每个特征，计算基准分布的CDF（经验累积分布函数） self.baseline_stats[i] = np.sort(baseline_features[:, i]) def detect_drift(self, current_features: np.ndarray, threshold: float = 0.2) -> dict: """ 检测当前批次特征漂移 返回: {feature_idx: {'ks_stat': float, 'p_value': float, 'drifted': bool}} """ results = {} for i in range(current_features.shape[1]): # KS检验：比较当前特征分布 vs 基准分布 ks_stat, p_value = stats.ks_2samp( current_features[:, i], self.baseline_stats[i], alternative='two-sided' ) drifted = ks_stat > threshold results[i] = { 'ks_stat': float(ks_stat), 'p_value': float(p_value), 'drifted': drifted } return results # 在FastAPI服务中集成 @app.middleware("http") async def drift_monitoring_middleware(request: Request, call_next): # 仅对/predict请求采样1%进行漂移检测 if request.url.path == "/predict" and random.random() < 0.01: try: # 从请求体中提取特征（需根据实际schema调整） body = await request.json() features = extract_features_from_body(body) # 自定义函数 drift_results = drift_detector.detect_drift(features) # 上报漂移指标 for feat_idx, result in drift_results.items(): if result['drifted']: metrics_collector.record_drift(feat_idx, result['ks_stat']) except Exception as e: logging.warning(f"Drift detection failed: {e}") return await call_next(request)

这个实现的关键细节在于采样策略。我们不对每条请求都做KS检验（计算开销大），而是采用1%随机采样，既保证统计显著性，又将性能损耗控制在0.5ms以内。同时，extract_features_from_body函数必须与训练时的特征工程代码完全一致，包括缺失值填充策略、类别编码映射表等。我们通过将特征工程逻辑封装为独立Python包feature_engineering，并在训练和服务两个环境中使用同一版本，来保证一致性。去年一个项目因服务端特征工程代码未同步更新，导致age字段被错误地截断为0-100，KS检验在3小时内就捕获到该特征漂移，避免了数百万用户的推荐结果失真。

4. 实操过程与核心环节实现：从零搭建一个可上线的模型服务

4.1 环境准备与依赖管理：用Conda锁定一切不确定

生产环境最怕“在我机器上是好的”。要根除这种不确定性，必须从环境初始化就建立铁律。我们不使用pip install -r requirements.txt，而是严格依赖environment.yml，其内容示例如下：

# environment.yml name: ml-prod channels: - conda-forge - pytorch - defaults dependencies: - python=3.9.16 - pip - pytorch=1.12.1=py3.9_cuda11.3_cudnn8.3.2_0 - torchvision=0.13.1=py39_cu113 - numpy=1.21.6=py39hdbf815f_0 - pandas=1.4.4=py39hce5d04b_0 - scikit-learn=1.1.2=py39h0345492_0 - fastapi=0.85.1=pyhd8ed1ab_0 - uvicorn=0.19.0=pyhd8ed1ab_0 - prometheus-client=0.15.0=pyhd8ed1ab_0 - watchdog=2.1.9=pyhd8ed1ab_0 - pip: - opentelemetry-api==1.15.0 - opentelemetry-sdk==1.15.0 - opentelemetry-instrumentation-fastapi==0.34b0

这个文件的威力在于：

• 精确到build string：py39hdbf815f_0这样的后缀，确保安装的是conda-forge官方编译的、针对特定Python和系统版本的二进制包，杜绝源码编译带来的随机性；
• 渠道优先级明确：pytorch渠道在conda-forge之前，确保PyTorch相关包优先从其官方渠道安装，避免版本冲突；
• pip包受控：仅将必须用pip安装的包（如OpenTelemetry）列在pip:下，其余全部走conda，因为conda能更好地解决C++依赖的版本链。
  执行conda env create -f environment.yml后，会生成一个完全隔离的环境，其conda list输出可作为审计依据。我们要求所有开发、测试、生产环境，都必须基于同一份environment.yml构建，任何手动pip install都被CI流水线禁止。这套机制让我们在一次紧急上线中，仅用15分钟就复现了测试环境出现的CUDA out of memory错误——因为测试环境误装了pytorch=1.13，而environment.yml指定的是1.12.1，新版本在相同显存下内存占用高出18%。

4.2 模型服务开发：从Hello World到生产就绪的七步法

开发一个生产就绪的服务，我们遵循一套标准化的七步法，每一步都有明确的交付物和验收标准：

1. 定义API契约（OpenAPI Schema）：用pydantic.BaseModel编写PredictionRequest和PredictionResponse，生成Swagger文档，与前端/客户端团队对齐。这一步必须完成，才能进入下一步。
2. 实现最小可行服务（MVP）：仅包含/predict端点，模型用torch.nn.Linear占位，返回固定值。目标：curl -X POST http://localhost:8000/predict -d '{}'能返回200。耗时<1小时。
3. 集成真实模型：替换占位模型，添加model_manager.predict()调用，确保本地python main.py能正确加载.pt文件并返回合理结果。关键检查点：model.eval()是否调用、torch.no_grad()是否包裹。
4. 添加健康检查与指标：实现/healthz端点，集成Prometheus client，上报http_requests_total。目标：curl http://localhost:8000/healthz返回{"status":"ok"}，且Prometheus能抓取到指标。
5. 加入日志与错误处理：所有异常必须被捕获并记录详细堆栈，HTTPException用于业务错误（如参数校验失败），Exception用于系统错误（如模型加载失败）。日志格式统一为JSON，便于ELK采集。
6. 实现模型热加载：编写ModelReloadHandler，监听模型目录，触发model_manager._load_model()。验证：touch models/production/model_v2.2.pt后，服务日志应显示新版本加载成功，且后续请求返回新模型结果。
7. 压力测试与调优：使用locust模拟1000 QPS，监控P99延迟、内存增长、GPU显存占用。根据结果调整Uvicorn workers数量（通常设为CPU核心数*2）、--limit-concurrency参数。

这七步法的价值在于，它把一个模糊的“开发服务”任务，拆解为七个可验证、可交接、可审计的原子动作。每个步骤完成后，都必须有自动化测试覆盖。例如，步骤4的健康检查，我们编写了单元测试：

# test_health.py def test_health_endpoint(): response = client.get("/healthz") assert response.status_code == 200 assert response.json()["status"] == "ok" assert "model_loaded" in response.json()

这种“测试先行”的节奏，确保了代码质量从第一天起就在线，而不是等到上线前夜才疯狂补救。

4.3 K8s部署与配置：让服务在云原生环境里稳如磐石

将服务部署到Kubernetes，不是简单地写个Deployment.yaml就完事。我们采用一套经过生产验证的“黄金配置模板”，核心要素如下：

# k8s/deployment.yaml apiVersion: apps/v1 kind: Deployment metadata: name: ml-recommender labels: app: ml-recommender spec: replicas: 3 # 至少3副本，满足K8s滚动更新和故障转移 selector: matchLabels: app: ml-recommender template: metadata: labels: app: ml-recommender annotations: # 注入OpenTelemetry自动追踪 otel/instrumentation: "fastapi" spec: # 强制使用非root用户 securityContext: runAsNonRoot: true runAsUser: 1001 fsGroup: 101 containers: - name: model-server image: registry.example.com/ml-recommender:v2.1 imagePullPolicy: IfNotPresent ports: - containerPort: 8000 name: http # 资源限制：防止单个Pod吃光节点资源 resources: requests: memory: "1Gi" cpu: "500m" nvidia.com/gpu: "1" # 如需GPU limits: memory: "2Gi" cpu: "1000m" nvidia.com/gpu: "1" # 存活与就绪探针 livenessProbe: httpGet: path: /healthz port: 8000 initialDelaySeconds: 30 periodSeconds: 10 readinessProbe: httpGet: path: /healthz port: 8000 initialDelaySeconds: 5 periodSeconds: 5 # 就绪探针失败时，K8s会将Pod从Service Endpoint中移除 failureThreshold: 3 # 环境变量注入 env: - name: MODEL_PATH value: "/app/models/production/model_v2.1.pt" - name: LOG_LEVEL value: "INFO"

这个配置的每一个参数都有其深意：

• replicas: 3：不是拍脑袋定的。我们通过历史流量分析，确定单副本峰值QPS为350，而业务SLA要求99.9%的请求P99延迟<200ms。压测显示，当QPS超过400时，延迟开始劣化。因此3副本可支撑1050 QPS，留有20%余量应对流量突增。
• resources.limits.memory: "2Gi"：这是经过反复压测得出的黄金值。设得太低（如1.5Gi），Uvicorn worker会在高并发下OOM被K8s杀死；设得太高（如3Gi），则浪费资源，降低节点资源利用率。
• livenessProbe.initialDelaySeconds: 30：模型加载需要时间，特别是大型模型。30秒是保守估计，确保模型完全加载完毕后再开始健康检查，避免服务启动即被K8s重启的恶性循环。
• readinessProbe.failureThreshold: 3：允许3次探针失败，给模型热加载留出缓冲时间。当新模型正在加载时，探针短暂失败是正常的，不应立即剔除Pod。

部署后，我们通过kubectl top pods实时监控资源消耗，并用kubectl logs -f ml-recommender-xxxxx查看实时日志。一次线上事故中，正是通过kubectl top发现某Pod内存使用率持续95%，而其他Pod正常，进而定位到该Pod所在节点的NVMe SSD出现坏道，导致模型文件读取缓慢，触发了大量重试，最终耗尽内存。没有这套精细化的资源配置和监控，问题会演变成整个集群的雪崩。

5. 常见问题与排查技巧实录：那些只有踩过坑才知道的真相

5.1 “模型加载成功，但预测结果全是NaN”——CUDA上下文丢失之谜

现象：服务启动日志显示Model loaded: v2.1，但首次/predict请求返回[nan, nan, nan]，且后续所有请求均如此。nvidia-smi显示GPU显存已被占用，但torch.cuda.memory_allocated()返回0。

排查路径：

1. 首先确认模型是否真的在GPU上：print(model.device)，输出cpu而非cuda:0；
2. 检查ModelManager.__init__()中device参数传递是否正确；
3. 进入容器执行python -c "import torch; print(torch.cuda.is_available())"，输出False。

根本原因：Docker默认不启用NVIDIA Container Toolkit。即使宿主机有GPU，容器内也无法访问。

解决方案：

• 宿主机安装nvidia-container-toolkit；
• 修改Docker daemon配置/etc/docker/daemon.json，添加：

  { "default-runtime": "runc", "runtimes": { "nvidia": { "path": "nvidia-container-runtime", "runtimeArgs": [] } } }

• 重启Docker：sudo systemctl restart docker；
• 部署时在K8sDeployment中添加runtimeClassName: nvidia。

提示：这个坑我们踩了两次。第一次在测试环境，花了3小时；第二次在生产环境，因为CI/CD流水线自动部署，我们直接在deployment.yaml里硬编码了runtimeClassName，并添加了预检脚本：kubectl get nodes -o wide | grep -q "nvidia"，失败则中断部署。

5.2 “P99延迟突然飙升，但CPU和GPU都空闲”——GIL锁与同步I/O的陷阱

现象：服务QPS稳定在800，但P99延迟从120ms飙升至2500ms，top显示CPU使用率不足30%，nvidia-smi显示GPU显存占用稳定，无波动。

排查路径：

1. 用py-spy record -p <pid> --duration 60生成火焰图，发现大量时间消耗在requests.api.request调用上；
2. 检查代码，发现预处理函数preprocess()中调用了requests.get("http://user-service/users/{user_id}")；
3. 确认user-service响应时间从20ms增至1800ms（因数据库慢查询）。

根本原因：Uvicorn是异步服务器，但requests是同步阻塞库。一个慢请求会阻塞整个Event Loop，导致所有后续请求排队等待。

解决方案：

• 替换为异步HTTP客户端httpx.AsyncClient；
• 将preprocess()改为async def，并用await client.get()；
• 在main.py中，app.post装饰器下的函数必须是async def，才能await异步操作。

# 正确的异步预处理 async def preprocess(request: PredictionRequest) -> torch.Tensor: async with httpx.AsyncClient() as client: resp = await client.get(f"http://user-service/users/{request.user_id}") user_profile = resp.json() # 构造特征向量... return features_tensor

注意：httpx的AsyncClient必须在每次请求中新建（如上例），或使用连接池（AsyncClient(limits=httpx.Limits(max_connections=100))），但绝不能全局单例，否则会引发连接泄漏。

5.3 “模型版本切换后，部分请求仍返回旧结果”——模型引用未原子更新

现象：触发模型热加载后，约10%的请求返回旧模型结果，其余90%返回新模型结果，且无规律。

排查路径：

1. 在ModelManager.predict()中添加日志：logging.info(f"Using model version: {self.current_version}")；
2. 查看日志，发现新旧版本日志交替出现；
3. 检查_load_model()方法，发现self._model赋值与self.current_version赋值不在同一原子操作中。

根本原因：线程竞态。线程A执行self._model = new_model后，尚未执行self.current_version = new_version时，线程B已进入predict()，读取到new_model