2. 环境准备与工具链搭建

本章聚焦于构建一套可复现、可扩展的模型部署基础设施。我们将依次完成 Python 虚拟环境、容器化引擎、编排平台、模型生命周期管理工具、API 服务框架以及持久化存储的安装与配置。所有组件均采用当前工业界主流版本，确保后续章节的实操一致性。

2.1 整体架构概览

下图展示了各工具在部署流水线中的角色与数据流向。模型从本地虚拟环境出发，经 MLflow 打包后构建为 Docker 镜像，由 Kubernetes 调度运行，并通过 FastAPI 对外暴露评分接口，最终将结果持久化至 PostgreSQL。

2.2 Python 虚拟环境配置

推荐使用 conda 作为环境管理工具，因其对二进制依赖（如 NumPy、SciPy）的处理更为稳健。以下命令创建名为 risk_model 的专用环境，并安装核心依赖。

# 创建 Python 3.10 虚拟环境
conda create -n risk_model python=3.10 -y

# 激活环境
conda activate risk_model

# 安装核心数据科学与 ML 库
pip install numpy==1.24.3 pandas==2.0.3 scikit-learn==1.3.0

# 安装模型部署工具链
pip install mlflow==2.5.0 fastapi==0.100.0 uvicorn==0.23.1

# 安装 PostgreSQL 驱动
pip install psycopg2-binary==2.9.6 sqlalchemy==2.0.19

2.3 Docker 安装与配置

Docker 用于将模型及其依赖打包为不可变镜像。以下步骤适用于 Ubuntu 22.04 环境。

2.4 Kubernetes 环境搭建

本地开发推荐使用 minikube 或 kind。本文采用 minikube，因其内置了仪表盘与存储插件，适合教学演示。

# 安装 minikube（Linux amd64）
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

# 启动集群（指定 2 核 4GB 内存）
minikube start --cpus=2 --memory=4096 --driver=docker

# 安装 kubectl 命令行工具
curl -LO "https://dl.k8s.io/release/v1.27.3/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/

# 验证集群状态
kubectl cluster-info
kubectl get nodes

2.5 MLflow 部署与配置

MLflow 提供模型追踪、注册与部署功能。我们使用 SQLite 作为后端存储（开发阶段），MinIO 作为工件存储（需额外部署）。

# 安装 MLflow（已在虚拟环境中安装）
# 启动 Tracking Server（默认端口 5000）
mlflow server \
  --backend-store-uri sqlite:///mlflow.db \
  --default-artifact-root ./mlruns \
  --host 0.0.0.0 \
  --port 5000

生产环境建议使用 PostgreSQL 作为后端存储，配置方式如下：

mlflow server \
  --backend-store-uri postgresql://mlflow_user:mlflow_pass@localhost:5432/mlflow_db \
  --default-artifact-root s3://mlflow-artifacts/ \
  --host 0.0.0.0 \
  --port 5000

2.6 FastAPI 服务初始化

FastAPI 作为模型推理的 HTTP 网关。以下是一个最小化服务骨架，后续章节将逐步完善。

# app.py
from fastapi import FastAPI
import mlflow.pyfunc

app = FastAPI(title="商户风险评分 API", version="1.0.0")

# 模型加载（占位）
model = None

@app.on_event("startup")
async def load_model():
    global model
    model = mlflow.pyfunc.load_model("models:/risk_model/Production")

@app.get("/health")
async def health_check():
    return {"status": "ok"}

@app.post("/predict")
async def predict(features: dict):
    prediction = model.predict([features])
    return {"score": prediction.tolist()}

# 启动命令
uvicorn app:app --host 0.0.0.0 --port 8000 --reload

2.7 PostgreSQL 安装与初始化

PostgreSQL 用于存储商户特征、模型评分结果以及 MLflow 元数据。以下为 Docker 方式快速部署。

# 拉取镜像并启动容器
docker run --name risk-postgres \
  -e POSTGRES_USER=risk_user \
  -e POSTGRES_PASSWORD=risk_pass \
  -e POSTGRES_DB=risk_db \
  -p 5432:5432 \
  -d postgres:15.3

# 验证连接
docker exec -it risk-postgres psql -U risk_user -d risk_db -c "SELECT version();"

初始化评分结果表：

CREATE TABLE IF NOT EXISTS scoring_results (
    id SERIAL PRIMARY KEY,
    merchant_id VARCHAR(64) NOT NULL,
    feature_hash VARCHAR(128),
    risk_score FLOAT NOT NULL,
    model_version VARCHAR(32),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_merchant_id ON scoring_results(merchant_id);
CREATE INDEX idx_created_at ON scoring_results(created_at);

2.8 工具链版本兼容性矩阵

下表汇总了各组件在本课程中使用的版本及其关键依赖关系，避免因版本不匹配导致部署失败。

2.9 环境验证脚本

执行以下命令快速验证所有组件是否就绪：

#!/bin/bash
echo "=== Python 环境 ==="
conda info --envs | grep risk_model

echo "=== Docker 版本 ==="
docker --version

echo "=== Kubernetes 节点 ==="
kubectl get nodes -o wide

echo "=== MLflow 服务 ==="
curl -s http://localhost:5000/health | python -m json.tool

echo "=== FastAPI 服务 ==="
curl -s http://localhost:8000/health | python -m json.tool

echo "=== PostgreSQL 连接 ==="
docker exec risk-postgres pg_isready -U risk_user