小时级机器学习应用构建实战：从数据到API的极简流水线

1. 项目概述：这不是“速成课”，而是把机器学习从实验室搬进真实业务的实战流水线

“How I Build Machine Learning Apps in Hours… and More!”——这个标题里藏着一个被太多教程刻意模糊的关键事实： 真正拖慢ML落地的，从来不是模型训练本身，而是数据准备、接口封装、状态管理、错误兜底、日志追踪、资源监控这一整套“非模型”工程链条 。我做AI产品交付十年，亲手带过37个从0到1的ML应用上线项目，其中21个在48小时内完成MVP部署，最近一次是给一家区域连锁药店做的“临期药品智能预警看板”，从拿到原始销售与库存Excel表，到内部员工扫码就能查预警结果的Web页面上线，耗时3小时52分钟。它没用任何黑科技，核心就三件事：用Pandas做极简但鲁棒的数据清洗管道、用FastAPI搭零配置HTTP服务、用Streamlit写前端逻辑而非UI。很多人误以为“几小时建ML App”等于跳过工程规范，恰恰相反——它要求你对每个环节的 最小可行实现边界 有肌肉记忆式的判断。比如，当客户说“要能预测下周销量”，老手第一反应不是调参，而是问：“预测结果谁看？看完了下一步动作是什么？失败时系统该沉默还是报警？” 这些问题的答案，直接决定你该用Flask还是Gradio、该存CSV还是SQLite、该加验证还是加重试。本文不讲算法原理，只拆解我在真实战场中反复验证过的、可复制的“小时级ML应用构建心法”：如何用一套固定动作，把90%的常见业务场景（销量预测、文本分类、图像质检、异常检测）压缩进一个下午的工作流。适合刚学完scikit-learn想接活的工程师、需要快速验证AI价值的产品经理，以及被“模型上线难”卡住的算法同学——你不需要成为全栈，但必须清楚每个环节的“安全开关”在哪。

2. 整体设计思路：放弃“完美架构”，锁定“最小闭环”

2.1 为什么是“小时级”？先破除三个认知陷阱

很多团队卡在第一步，根本原因是对“ML App”的定义存在严重偏差。我见过最典型的三种误判：

• 陷阱一：“App=完整产品”
  错。真实业务中，95%的初期需求本质是“一个能跑通的决策辅助工具”。比如财务部要“自动识别报销单中的发票金额”，它的最小闭环不是开发OCR+NLP+审批流，而是：上传PDF → 返回一个JSON { "invoice_amount": 238.5, "confidence": 0.92 } → 财务人工核对后点“确认”。这个闭环里，模型可以是现成的EasyOCR+正则提取，服务用Flask一行命令启动，前端就是curl命令。我坚持用“能被业务方在自己电脑上双击运行”作为MVP验收标准——这意味着所有依赖必须打包进单个文件，数据库不能是远程PostgreSQL，而是一个本地SQLite或甚至纯内存dict。

• 陷阱二：“必须用Docker/K8s”
  错。Docker解决的是“环境一致性”，但小时级项目最大的敌人是“等待”。当你花20分钟写Dockerfile，却因公司内网镜像源超时卡住，整个节奏就崩了。我的实操原则是： 本地开发环境即生产环境 。用conda或venv创建隔离环境，pip install -r requirements.txt后，直接python app.py启动。唯一例外是当客户明确要求部署到其Linux服务器时，我才用docker build . -t ml-app && docker run -p 8000:8000 ml-app——但这个Dockerfile永远只有3行：FROM python:3.9-slim、COPY . /app、CMD ["python", "app.py"]。K8s？那是第3个版本才考虑的事。

• 陷阱三：“模型必须SOTA”
  错。在真实业务中，“可用性”远大于“准确性”。我给某制造厂做的“螺丝松动声纹检测”，初版用Librosa提取MFCC特征+RandomForest，准确率82%，但误报率低于0.5%（因为产线工人宁可多停机检查也不愿漏检）。后来换ResNet-18微调到94%，但误报率升到3.7%，反被退回——因为每次误报都导致整条产线停机3分钟。所以我的模型选型铁律是： 先用最简单模型跑通全流程，再按业务容忍度迭代 。scikit-learn > XGBoost > PyTorch Lightning，除非业务指标明确要求端侧推理（此时才切ONNX Runtime）。

2.2 核心架构：三层洋葱模型，每层只解决一个问题

我将小时级ML App抽象为严格分层的洋葱结构，每层只暴露必要接口，绝不越界：

[最外层] 用户交互层 → 解决“怎么用”
  ├─ Streamlit（内部工具/演示）
  ├─ Gradio（快速分享给非技术人员）
  └─ FastAPI + Swagger UI（需集成到现有系统）

[中间层] 服务编排层 → 解决“怎么稳”
  ├─ 输入校验（Pydantic模型强制类型/范围检查）
  ├─ 状态缓存（LRU_cache或Redis，避免重复计算）
  └─ 错误兜底（统一异常处理器，返回业务友好错误码）

[最内层] 模型执行层 → 解决“怎么准”
  ├─ 模型加载（joblib/pickle，冷启动<1s）
  ├─ 数据预处理（硬编码pipeline，拒绝fit_transform）
  └─ 后处理（置信度过滤、结果归一化、业务规则注入）

这个结构的价值在于：当业务方说“要把预测结果同步到钉钉”，你只需在服务编排层加一个钉钉Webhook调用，完全不影响模型层；当算法同学更新了模型文件，你只需替换model.pkl，其他层零修改。我曾用同一套架构，在2小时内将“客服工单情感分析”从单机版升级为支持10并发的API服务——只改了3行代码：把 @st.cache 换成 @lru_cache(maxsize=128) ，加了 uvicorn.run(app, host="0.0.0.0", port=8000) 。

2.3 工具链选择：为什么是这四个组合？

工具不是越多越好，而是要形成“条件反射式组合”。我十年踩坑后锁定的黄金四件套：

特别说明Streamlit的妙用：它本质是“Python脚本的GUI外壳”。你写 app.py 时，所有逻辑仍是纯Python—— model.predict(X) 、 pd.read_csv("data.csv") 照常写，只是用 st.button("运行预测") 替代 if __name__ == "__main__": 。这意味着你的MVP代码，未来可无缝迁移到FastAPI：把 st.text_input() 换成 request.body ，把 st.write(result) 换成 return JSONResponse(result) ，函数主体一行不用改。

3. 核心细节解析：从数据到API的七步极简流水线

3.1 第一步：数据入口——永远用CSV/Excel，拒绝API对接

业务方给的数据，90%是Excel或CSV。试图说服他们提供API或数据库权限，只会浪费2小时。我的标准动作是：

1. 创建 data/ 目录，放原始文件（如 sales_2024_q1.xlsx ）
2. 写 ingest.py ，用pandas读取并做三件事：
   • 强制列名小写并下划线（ "Order Date" → "order_date" ）
   • 将空值转为 np.nan （非字符串 "NULL" ）
   • 日期列用 pd.to_datetime() 标准化（ errors="coerce" 容忍脏数据）

# ingest.py
import pandas as pd
import numpy as np

def load_sales_data(filepath: str) -> pd.DataFrame:
    df = pd.read_excel(filepath)
    # 统一列名：小写+下划线
    df.columns = [col.strip().lower().replace(' ', '_') for col in df.columns]
    # 处理空值
    df = df.replace('', np.nan)
    # 强制转换日期（错误值变NaT）
    if 'order_date' in df.columns:
        df['order_date'] = pd.to_datetime(df['order_date'], errors='coerce')
    return df

# 测试：确保能跑通
if __name__ == "__main__":
    data = load_sales_data("data/sales_2024_q1.xlsx")
    print(f"Loaded {len(data)} rows. Sample:\n{data.head(2)}")

提示：永远在 ingest.py 里加 if __name__ == "__main__": 测试块。这是防止后续 train.py 导入时报错的保险丝——我吃过亏：某次客户Excel里混入了合并单元格， read_excel 默认报错，但没测试块就直接进训练流程，导致模型训练中断却找不到源头。

3.2 第二步：特征工程——硬编码Pipeline，拒绝fit_transform

这是最易被忽视的致命点。很多教程教 StandardScaler().fit_transform(X_train) ，但在生产中， fit_transform 意味着你必须保存scaler对象，并在预测时用同一对象 transform(X_test) 。一旦训练/预测环境分离（如训练在Mac，预测在Linux），浮点精度差异会导致结果漂移。我的解决方案是： 所有预处理逻辑写成纯函数，不依赖fit状态 。

以销量预测为例，特征工程只有三步：

1. 时间特征：从 order_date 提取 day_of_week , is_weekend , month_sin/cos
2. 统计特征：用滑动窗口计算过去7天销量均值、标准差
3. 分类编码： product_category 用 pd.Categorical().codes 转数字（非One-Hot，避免维度爆炸）

# features.py
import numpy as np
import pandas as pd
from datetime import datetime

def add_time_features(df: pd.DataFrame) -> pd.DataFrame:
    """纯函数：添加时间周期性特征"""
    df = df.copy()
    df['day_of_week'] = df['order_date'].dt.dayofweek
    df['is_weekend'] = (df['order_date'].dt.dayofweek >= 5).astype(int)
    # 用sin/cos编码月份，避免1月和12月距离过大
    df['month_sin'] = np.sin(2 * np.pi * df['order_date'].dt.month / 12)
    df['month_cos'] = np.cos(2 * np.pi * df['order_date'].dt.month / 12)
    return df

def add_rolling_features(df: pd.DataFrame, window: int = 7) -> pd.DataFrame:
    """纯函数：添加滑动窗口统计特征"""
    df = df.sort_values('order_date').copy()
    # 按日期排序后，用expanding代替rolling（避免首几行NaN）
    df['sales_7d_mean'] = df['sales_amount'].expanding(window).mean()
    df['sales_7d_std'] = df['sales_amount'].expanding(window).std()
    return df.fillna(0)  # 填0而非均值，因0代表“无历史数据”

def encode_categories(df: pd.DataFrame, cols: list) -> pd.DataFrame:
    """纯函数：类别编码，返回codes而非dummy"""
    df = df.copy()
    for col in cols:
        if col in df.columns:
            df[col + '_code'] = pd.Categorical(df[col]).codes
    return df

注意： expanding(window).mean() 比 rolling(window).mean() 更鲁棒——它保证首行就有值（即第一个数自身），而 rolling 前 window-1 行全是NaN。业务方看到“预测结果第一行是NaN”会立刻失去信任，哪怕技术上合理。

3.3 第三步：模型训练——用GridSearchCV但限定搜索空间

“小时级”不等于放弃调参，而是用 经验驱动的窄域搜索 。我给不同场景预设了调参模板：

训练脚本 train.py 的核心逻辑：

# train.py
from sklearn.model_selection import GridSearchCV
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import classification_report
import joblib
import pandas as pd

# 1. 加载并预处理数据
df = pd.read_csv("data/processed.csv")  # 由ingest.py+features.py生成
X, y = df.drop("is_fraud", axis=1), df["is_fraud"]

# 2. 定义窄域参数网格（3x3=9种组合，秒级完成）
param_grid = {
    'n_estimators': [100, 200],
    'max_depth': [5, 10],
    'class_weight': ['balanced']
}

# 3. 训练并保存最佳模型
model = RandomForestClassifier(random_state=42)
grid = GridSearchCV(model, param_grid, cv=3, scoring='f1', n_jobs=-1)
grid.fit(X, y)

print("Best params:", grid.best_params_)
print("Best CV F1:", grid.best_score_)

# 4. 保存为joblib（非pickle，兼容性更好）
joblib.dump(grid.best_estimator_, "models/best_model.pkl")

实操心得：永远用 cv=3 而非 cv=5 。交叉验证折数增加1倍，耗时可能翻3倍（因数据重切分+模型重训）。在小时级项目中， cv=3 的F1评估已足够指导决策——毕竟你不是发顶会论文，而是让业务方今天就能用。

3.4 第四步：服务封装——FastAPI的5行核心代码

FastAPI的威力在于，它把“写API”简化为“写函数+加装饰器”。 app.py 的骨架永远是这5行：

# app.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import joblib
import pandas as pd

app = FastAPI(title="Sales Forecast API")

# 1. 定义输入数据结构（自动校验+Swagger文档）
class ForecastRequest(BaseModel):
    product_id: int
    store_id: int
    order_date: str  # ISO格式：2024-03-15

# 2. 加载模型（全局变量，启动时加载一次）
model = joblib.load("models/best_model.pkl")

@app.post("/forecast")
def predict(request: ForecastRequest):
    # 3. 数据预处理（复用features.py函数）
    df = pd.DataFrame([request.dict()])
    df = add_time_features(df)  # 来自features.py
    df = encode_categories(df, ["product_id", "store_id"])
    
    # 4. 模型预测
    try:
        pred = model.predict(df)[0]
        prob = model.predict_proba(df)[0].max()
        return {"prediction": int(pred), "confidence": float(prob)}
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Prediction failed: {str(e)}")

关键细节：

• BaseModel 定义输入结构，FastAPI自动做类型校验（如 order_date 不是ISO格式直接422错误）
• model 作为全局变量加载，避免每次请求都反序列化，冷启动<100ms
• try/except 捕获所有预测异常，返回结构化错误，而非让客户端看到Python traceback

启动命令： uvicorn app:app --reload --host 0.0.0.0 --port 8000 。打开 http://localhost:8000/docs ，Swagger UI自动生成交互式文档——业务方点点就能测试，无需写curl命令。

3.5 第五步：前端交互——Streamlit的3个魔法函数

Streamlit让“写前端”变成“写Python脚本”。 ui.py 只需关注三件事：

1. 输入收集 ：用 st.text_input() 、 st.date_input() 等生成控件
2. 调用API ：用 requests.post() 发请求（或直接调用本地模型函数）
3. 结果渲染 ：用 st.metric() 、 st.dataframe() 等展示

# ui.py
import streamlit as st
import requests
import pandas as pd

st.title("📦 销量预测工具（MVP版）")

# 1. 构建输入表单
with st.form("prediction_form"):
    col1, col2 = st.columns(2)
    with col1:
        product_id = st.number_input("商品ID", min_value=1, value=101)
    with col2:
        store_id = st.number_input("门店ID", min_value=1, value=201)
    order_date = st.date_input("预测日期", value=pd.to_datetime("2024-04-01"))
    submitted = st.form_submit_button("预测销量")

# 2. 提交后调用API（或本地模型）
if submitted:
    # 方案A：调用FastAPI（推荐，模拟真实调用）
    try:
        response = requests.post(
            "http://localhost:8000/forecast",
            json={"product_id": product_id, "store_id": store_id, "order_date": str(order_date)}
        )
        result = response.json()
        st.success(f"预测销量：{result['prediction']} 件")
        st.metric("置信度", f"{result['confidence']:.2%}")
    except Exception as e:
        st.error(f"调用失败：{e}")

    # 方案B：直接调用本地模型（调试用，注释掉上面requests部分）
    # from train import model
    # from features import add_time_features, encode_categories
    # df = pd.DataFrame([{"product_id": product_id, "store_id": store_id, "order_date": str(order_date)}])
    # df = add_time_features(df)
    # df = encode_categories(df, ["product_id", "store_id"])
    # pred = model.predict(df)[0]
    # st.success(f"预测销量：{pred} 件")

注意：Streamlit默认每次交互都重跑整个脚本。为避免重复加载模型，用 @st.cache_resource 装饰器（Streamlit 1.20+）：

@st.cache_resource
def load_model():
    return joblib.load("models/best_model.pkl")
model = load_model()

这样模型只加载一次，后续所有预测共享内存。

3.6 第六步：日志与监控——用SQLite记录每一次预测

没有日志的ML App是盲人开车。但ELK栈太重，我的方案是： 用SQLite建一张 predictions 表，每次预测插入一行 。

# logger.py
import sqlite3
from datetime import datetime

def init_db():
    conn = sqlite3.connect("logs/predictions.db")
    conn.execute("""
        CREATE TABLE IF NOT EXISTS predictions (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            timestamp TEXT NOT NULL,
            input_json TEXT NOT NULL,
            output_json TEXT NOT NULL,
            status TEXT NOT NULL,
            duration_ms REAL
        )
    """)
    conn.close()

def log_prediction(input_data: dict, output_data: dict, status: str, duration: float):
    conn = sqlite3.connect("logs/predictions.db")
    conn.execute(
        "INSERT INTO predictions (timestamp, input_json, output_json, status, duration_ms) VALUES (?, ?, ?, ?, ?)",
        (datetime.now().isoformat(), str(input_data), str(output_data), status, duration)
    )
    conn.commit()
    conn.close()

在 app.py 的 predict 函数中插入日志：

from logger import log_prediction
import time

@app.post("/forecast")
def predict(request: ForecastRequest):
    start_time = time.time()
    try:
        # ... 预测逻辑 ...
        duration = (time.time() - start_time) * 1000
        log_prediction(request.dict(), {"prediction": int(pred), "confidence": float(prob)}, "success", duration)
        return {"prediction": int(pred), "confidence": float(prob)}
    except Exception as e:
        duration = (time.time() - start_time) * 1000
        log_prediction(request.dict(), {}, "error", duration)
        raise HTTPException(status_code=500, detail=f"Prediction failed: {str(e)}")

实操心得：SQLite的 INSERT 在单线程下性能极高（>1000 QPS），且 logs/predictions.db 文件可直接用DB Browser for SQLite打开分析。我曾靠它发现一个隐藏Bug：某天凌晨3点大量预测失败，查日志发现是客户定时任务传入了非法日期格式——没有这行日志，问题会持续一周无人知晓。

3.7 第七步：打包分发——用PyInstaller生成单文件exe

让业务方“双击运行”是信任建立的第一步。 build.bat （Windows）或 build.sh （Mac/Linux）内容如下：

# build.sh
pip install pyinstaller
pyinstaller --onefile --name sales-forecast-app \
    --add-data "models;models" \
    --add-data "logs;logs" \
    --add-data "data;data" \
    ui.py

关键参数说明：

• --onefile ：打包成单个exe文件（Mac是app，Linux是bin）
• --add-data ：指定资源文件路径（PyInstaller不会自动包含 joblib 模型文件）
• ui.py ：入口脚本（Streamlit应用）

生成的 dist/sales-forecast-app 可直接发给客户。首次运行时，它会自动启动浏览器打开Streamlit界面——客户甚至不知道背后是Python。

提示：PyInstaller在Mac上打包需加 --macos-app-bundle ，且签名需Apple Developer账号。若无账号，用 --console 保留终端窗口，方便调试。

4. 实操过程全记录：从接到需求到交付的3小时52分钟

4.1 00:00-00:25 —— 需求澄清与数据探查（关键！）

客户微信发来消息：“王工，我们想预测下周各门店的奶粉销量，现在每天手工算，太慢了。” 我立刻回复三个问题：

• “预测结果谁看？看完了下一步动作是什么？” → 得知是区域经理每日晨会用，需导出Excel
• “历史数据在哪里？格式是？” → 发来一个 2024_Q1_Sales.xlsx ，含12列，其中 Date , Store_ID , Product_Name , Qty_Sold
• “‘奶粉’如何定义？是所有含‘奶粉’字样的商品，还是SKU白名单？” → 确认是SKU白名单，客户提供 formula_milk_skus.txt

行动：

• 创建项目目录： mkdir milk-forecast && cd milk-forecast
• 放入客户文件： cp ~/Downloads/2024_Q1_Sales.xlsx data/
• 写 explore.py 快速探查：

  import pandas as pd
  df = pd.read_excel("data/2024_Q1_Sales.xlsx")
  print("Shape:", df.shape)
  print("\nColumns:", df.columns.tolist())
  print("\nDate range:", df["Date"].min(), "to", df["Date"].max())
  print("\nTop products:", df["Product_Name"].value_counts().head(3))
  

  输出显示：数据有12,456行， Date 列是datetime，但 Product_Name 含“婴儿奶粉”“成人奶粉”“奶粉伴侣”，需清洗。

4.2 00:25-01:10 —— 数据清洗与特征工程（用pandas链式操作）

写 clean.py ，核心是三行链式操作：

# clean.py
import pandas as pd

df = (pd.read_excel("data/2024_Q1_Sales.xlsx")
      .assign(Date=lambda x: pd.to_datetime(x["Date"], errors="coerce"))
      .query("Date.notna()")  # 过滤无效日期
      .assign(Product_Category=lambda x: x["Product_Name"].str.contains("奶粉").map({True: "milk", False: "other"}))
      .query("Product_Category == 'milk'")  # 只留奶粉
      )

# 保存清洗后数据
df.to_csv("data/clean_milk.csv", index=False)
print(f"Cleaned {len(df)} milk records")

运行后得到 data/clean_milk.csv ，共3,218行。接着写 features.py ，加入滑动窗口销量统计：

# features.py
def add_rolling_features(df: pd.DataFrame) -> pd.DataFrame:
    df = df.sort_values("Date").copy()
    # 按门店+商品分组，计算7天滚动销量
    df["qty_7d_mean"] = df.groupby(["Store_ID", "Product_Name"])["Qty_Sold"].transform(
        lambda x: x.rolling(7, min_periods=1).mean()
    )
    return df.fillna(0)

4.3 01:10-01:45 —— 模型训练与验证（用XGBoost窄域搜索）

train.py 中定义参数网格：

from xgboost import XGBRegressor
from sklearn.model_selection import GridSearchCV

param_grid = {
    'n_estimators': [50, 100],
    'learning_rate': [0.05, 0.1],
    'max_depth': [3, 6]
}
model = XGBRegressor(random_state=42)
grid = GridSearchCV(model, param_grid, cv=3, scoring='neg_mean_absolute_error', n_jobs=-1)
grid.fit(X_train, y_train)
joblib.dump(grid.best_estimator_, "models/milk_forecast_xgb.pkl")

训练耗时42秒，最佳参数： {'learning_rate': 0.1, 'max_depth': 3, 'n_estimators': 100} ，CV MAE=2.38（单位：件）。用测试集验证： y_pred = model.predict(X_test); mae = mean_absolute_error(y_test, y_pred) → 2.41，符合预期。

4.4 01:45-02:30 —— FastAPI服务封装（含日志）

app.py 写完，启动 uvicorn app:app --host 0.0.0.0 --port 8000 ，访问 /docs 确认Swagger UI正常。用curl测试：

curl -X 'POST' 'http://localhost:8000/forecast' \
  -H 'Content-Type: application/json' \
  -d '{"store_id": 101, "product_name": "婴儿奶粉A", "forecast_date": "2024-04-01"}'
# 返回：{"prediction": 15, "confidence": 0.87}

同时确认 logs/predictions.db 有新记录。

4.5 02:30-03:20 —— Streamlit前端与打包

ui.py 写完，运行 streamlit run ui.py ，界面出现。测试输入，确认预测结果正确。然后执行打包：

pyinstaller --onefile --name milk-forecast \
    --add-data "models;models" \
    --add-data "logs;logs" \
    ui.py

生成 dist/milk-forecast （Mac）或 dist/milk-forecast.exe （Windows）。双击运行，自动打开浏览器，界面清爽。

4.6 03:20-03:52 —— 交付与培训（这才是关键！）

我把 dist/milk-forecast.exe 发给客户，附言：

“张经理，附件是奶粉销量预测工具。双击运行，填门店ID、商品名、预测日期，点‘预测’即可。结果会显示在下方，右上角有‘Export to Excel’按钮可导出。所有数据存在您电脑本地，不上传任何服务器。如需调整预测逻辑（比如加天气因素），随时联系我，1小时内可更新。”

客户回复：“已收到，刚试了三家店，和我们手工算的差不多！晨会就能用上了。”

5. 常见问题与排查技巧实录：那些没写在文档里的坑

5.1 问题速查表：高频故障与秒级修复

5.2 独家避坑技巧：来自血泪教训

• 技巧一：永远在requirements.txt里锁死pandas版本
  pandas>=1.5.0 看似安全，但 pandas==2.0.0 引入了 ArrowDtype ，某些旧Excel文件读取会报错。我的写法是： pandas==1.5.3 。用 pip freeze > requirements.txt 生成后，手动删掉 -e file:// 等本地路径行。

• 技巧二：用 st.cache_data 替代 st.cache
  Streamlit 1.20+废弃了 @st.cache ，改用 @st.cache_data （缓存函数返回值）和 @st.cache_resource （缓存大对象如模型）。若用错，缓存不生效，每次点击都重跑整个脚本。正确示范：

  @st.cache_data
  def load_data():
      return pd.read_csv("data/clean_milk.csv")
  
  @st.cache_resource
  def load_model():
      return joblib.load("models/milk_forecast_xgb.pkl")
  

• 技巧三：FastAPI的 response_model 是隐形杀手
  若定义 response_model=ForecastResponse ，但返回字典键名与模型字段不一致（如模型要 "pred" ，你返回 "prediction" ），FastAPI会静默丢弃该字段，返回空对象。我的做法是： 初期开发禁用 response_model ，用 return {...} 直返字典；稳定后再加，用 pydantic.BaseModel 严格校验 。

• 技巧四：PyInstaller打包后模型加载慢？加 --hidden-import
  joblib模型有时依赖 sklearn.utils._testing 等隐藏模块，PyInstaller扫描不到。若打包后首次预测卡顿5秒，加参数： pyinstaller --hidden-import sklearn.utils._testing ... 。更彻底的方案是：用 --collect-all sklearn ，但会增大exe体积。

5.3 性能瓶颈定位：当“小时级”变“天级别”

如果某个环节耗时远超预期，按此顺序排查：

1. 数据层 ： ingest.py 中 pd.read_excel() 是否在读取巨表？用 nrows=1000 参数先读1000行测试。
2. 特征层 ： add_rolling_features() 是否在 groupby 后用了 apply(lambda x: ...) ？改用 transform() 或 agg() 。
3. 模型层 ： model.predict() 是否在循环中调用？改为 model.predict(X_batch) 批量预测