model-deployment

ML 模型部署

通过适当的服务提供和监控，将训练好的模型部署到生产环境。

部署选项

方法	用例	延迟
REST API	Web 服务	中
批处理	大规模处理	不适用
流式处理	实时	低
边缘部署	设备端	很低

FastAPI 模型服务

from fastapi import FastAPI
from pydantic import BaseModel
import joblib
import numpy as np

app = FastAPI()
model = joblib.load('model.pkl')

class PredictionRequest(BaseModel):
    features: list[float]

class PredictionResponse(BaseModel):
    prediction: float
    probability: float

@app.get('/health')
def health():
    return {'status': 'healthy'}

@app.post('/predict', response_model=PredictionResponse)
def predict(request: PredictionRequest):
    features = np.array(request.features).reshape(1, -1)
    prediction = model.predict(features)[0]
    probability = model.predict_proba(features)[0].max()
    return PredictionResponse(prediction=prediction, probability=probability)

Docker 部署

FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY model.pkl .
COPY app.py .

EXPOSE 8000
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

模型监控

class ModelMonitor:
    def __init__(self):
        self.predictions = []
        self.latencies = []

    def log_prediction(self, input_data, prediction, latency):
        self.predictions.append({
            'input': input_data,
            'prediction': prediction,
            'latency': latency,
            'timestamp': datetime.now()
        })

    def detect_drift(self, reference_distribution):
        # Compare current predictions to reference
        pass

部署检查清单

• 已在测试集上验证模型
• 已记录 API 端点
• 健康检查端点
• 已配置身份验证
• 已设置日志记录和监控
• 已建立模型版本管理
• 已记录回滚流程

快速入门：分 6 步部署模型

# 1. Save trained model
import joblib
joblib.dump(model, 'model.pkl')

# 2. Create FastAPI app (see references/fastapi-production-server.md)
# app.py with /predict and /health endpoints

# 3. Create Dockerfile
cat > Dockerfile << 'EOF'
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py model.pkl ./
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]
EOF

# 4. Build and test locally
docker build -t model-api:v1.0.0 .
docker run -p 8000:8000 model-api:v1.0.0

# 5. Push to registry
docker tag model-api:v1.0.0 registry.example.com/model-api:v1.0.0
docker push registry.example.com/model-api:v1.0.0

# 6. Deploy to Kubernetes
kubectl apply -f deployment.yaml
kubectl rollout status deployment/model-api

预防已知问题

1. 未进行健康检查 = 服务中断

问题：负载均衡器将流量发送到不健康的 Pod，导致 503 错误。

解决方案：实现存活探针和就绪探针：

# app.py
@app.get("/health")  # Liveness: Is service alive?
async def health():
    return {"status": "healthy"}

@app.get("/ready")  # Readiness: Can handle traffic?
async def ready():
    try:
        _ = model_store.model  # Verify model loaded
        return {"status": "ready"}
    except:
        raise HTTPException(503, "Not ready")

# deployment.yaml
livenessProbe:
  httpGet:
    path: /health
    port: 8000
  initialDelaySeconds: 30
readinessProbe:
  httpGet:
    path: /ready
    port: 8000
  initialDelaySeconds: 5

2. 容器中出现找不到模型的错误

问题：容器启动时出现 FileNotFoundError: model.pkl。

解决方案：确认 Dockerfile 已复制模型文件，且路径正确：

# ❌ Wrong: Model in wrong directory
COPY model.pkl /app/models/  # But code expects /app/model.pkl

# ✅ Correct: Consistent paths
COPY model.pkl /models/model.pkl
ENV MODEL_PATH=/models/model.pkl

# In Python:
model_path = os.getenv("MODEL_PATH", "/models/model.pkl")

3. 未处理输入验证 = 500 错误

问题：无效输入导致 API 因未处理的异常而崩溃。

解决方案：使用 Pydantic 自动验证：

from pydantic import BaseModel, Field, validator

class PredictionRequest(BaseModel):
    features: List[float] = Field(..., min_items=1, max_items=100)

    @validator('features')
    def validate_finite(cls, v):
        if not all(np.isfinite(val) for val in v):
            raise ValueError("All features must be finite")
        return v

# FastAPI auto-validates and returns 422 for invalid requests
@app.post("/predict")
async def predict(request: PredictionRequest):
    # Request is guaranteed valid here
    pass

4. 未监控漂移 = 性能悄然下降

问题：模型性能随时间下降，直到用户投诉才有人察觉。

解决方案：实现漂移检测（参见 references/model-monitoring-drift.md）：

monitor = ModelMonitor(reference_data=training_data, drift_threshold=0.1)

@app.post("/predict")
async def predict(request: PredictionRequest):
    prediction = model.predict(features)
    monitor.log_prediction(features, prediction, latency)

    # Alert if drift detected
    if monitor.should_retrain():
        alert_manager.send_alert("Model drift detected - retrain recommended")

    return prediction

5. 未设置资源限制 = 因 OOM 被终止

问题：Pod 被 Kubernetes OOMKiller 终止，导致服务中断。

解决方案：设置内存/CPU 限制和请求：

resources:
  requests:
    memory: "512Mi"  # Guaranteed
    cpu: "500m"
  limits:
    memory: "1Gi"    # Max allowed
    cpu: "1000m"

# Monitor actual usage:
kubectl top pods

6. 没有回滚计划 = 卡在有问题的部署上

问题：新模型版本存在错误，无法快速回退。

解决方案：为镜像添加版本标签，并保留之前的部署：

# Deploy with version tag
kubectl set image deployment/model-api model-api=registry/model-api:v1.2.0

# If issues, rollback to previous
kubectl rollout undo deployment/model-api

# Or specify version
kubectl set image deployment/model-api model-api=registry/model-api:v1.1.0

7. 同步预测 = 批处理缓慢

问题：逐个处理 10,000 次预测需要数小时。

解决方案：实现批量端点：

@app.post("/predict/batch")
async def predict_batch(request: BatchPredictionRequest):
    # Process all at once (vectorized)
    features = np.array(request.instances)
    predictions = model.predict(features)  # Much faster!
    return {"predictions": predictions.tolist()}

8. 未进行 CI/CD 验证 = 部署有问题的模型

问题：部署未通过基本测试的模型，导致生产环境故障。

解决方案：在 CI 流水线中进行验证（参见 references/cicd-ml-models.md）：

# .github/workflows/deploy.yml
- name: Validate model performance
  run: |
    python scripts/validate_model.py \
      --model model.pkl \
      --test-data test.csv \
      --min-accuracy 0.85  # Fail if below threshold

最佳实践

• 为所有内容添加版本：模型（语义化版本）、Docker 镜像和部署
• 持续监控：延迟、错误率、漂移和资源使用情况
• 部署前测试：单元测试、集成测试和性能基准测试
• 逐步部署：先进行金丝雀发布（10%），再全面推出
• 做好回滚准备：保留之前的版本，并记录回滚流程
• 记录预测：便于调试和检测漂移
• 设置资源限制：防止因 OOM 被终止和资源争用
• 使用健康检查：实现适当的负载均衡

何时加载参考资料

如需了解详细实现，请加载参考文件：

• FastAPI 生产服务器：加载 references/fastapi-production-server.md，了解完整的生产就绪型 FastAPI 实现，包括错误处理、验证（Pydantic 模型）、日志记录、健康检查/就绪探针、批量预测、模型版本管理、中间件、异常处理程序和性能优化（缓存、异步）

• 模型监控与漂移：加载 references/model-monitoring-drift.md，了解 ModelMonitor 实现，包括使用 KS-test 进行漂移检测、Jensen-Shannon 散度、Prometheus 指标集成、告警配置（Slack、email）、持续监控服务和仪表板端点

• 容器化与部署：加载 references/containerization-deployment.md，了解多阶段 Dockerfile、容器中的模型版本管理、Docker Compose 设置、使用 Nginx 进行 A/B 测试、Kubernetes 部署（滚动更新、蓝绿部署、金丝雀发布）、GitHub Actions CI/CD 和部署检查清单

• 机器学习模型的 CI/CD：加载 references/cicd-ml-models.md，了解完整的 GitHub Actions 流水线，包括模型验证、数据验证、自动化测试、安全扫描、性能基准测试、自动回滚和部署策略