engagement-predictor是一个基于scikit-learn的 Ridge 回归机器学习模型，用来预测品牌-达人合作内容发布后的社交媒体互动率（engagement_score，即 点赞+评论+转发 除以 播放量）。它是 Viralst 应用的一个核心组件：在内容还没发布之前，就帮你估算这条内容大概能收获多少互动 📈

它解决什么问题？

做社媒营销的朋友都知道一个痛点：

• 品牌方想知道：这条 brief 交给达人后，大概能拿到多少互动？
• 达人想知道：这个选题、这个拍摄风格，值不值得接？

以前只能靠经验拍脑袋，而 engagement-predictor 的思路是：把投放方案（brief）和内容执行细节（时长、发布时间、文案等）量化成特征，用 Ridge 回归模型直接算出一个互动率数值。

模型接收两类信息：

原始数据可以在仓库中查看：dataset/briefs.csv（300 份投放方案）、dataset/contents.csv（2000 条内容）、dataset/brands.csv（30 个品牌）。

Ridge 回归是什么？一分钟搞懂

如果你听过"线性回归"，那么 Ridge 回归可以理解为它的加强版：

1. 线性回归：假设"互动率"是各个特征加权和的结果（语气好 +1%，热门音轨 +3%……），找到一组最贴合数据的权重。
2. 问题：特征一多，线性回归容易"钻牛角尖"，把噪声也学进去，换个数据就翻车（过拟合）。
3. Ridge 的解法：在目标函数里加一个 L2 正则项（系数平方和 × α），约束权重不要太大。α 越大，权重被压得越"温和"，模型越稳健。

打个比方：线性回归像记性太好、把老师随口一句玩笑也背下来的学生；Ridge 回归像一个会自动抓重点、不被偏题细节带偏的学生 🎯

本模型通过网格搜索 + GroupKFold 分组交叉验证（按 brief_id 分组，避免同一 brief 泄漏到训练集和测试集），最终选定的正则强度为α = 10.0。

模型是如何构建的？

模型并不是"一个光秃秃的 Ridge 分类器"，而是一条完整的Pipeline 流水线（序列化在 engagement_ridge.skops 中）：

原始特征 ──> OneHotEncoder（处理"语气/受众/风格"等类别特征） ──> StandardScaler（数值特征标准化） ──> Ridge 回归（输出互动率预测值）

• 使用skops.io序列化保存（比裸 pickle 更安全，加载时会检查类型白名单）
• 完整特征列表（共 58 列）定义在 config.json 的feature_columns字段中
• 特征工程的规范定义在应用仓库的src/engagement_predictor/features.py

效果如何？先看成绩单

在合成数据上，交叉验证结果如下：

R² 达到0.71，意味着模型解释了约 71% 的互动率波动；误差相比"闭眼猜平均值"的基线降低了近一半。对新手来说，记住三点就够了：α=10.0 控制过拟合、按 brief 分组做验证保证评测真实、R²>0.7 说明特征确实"有信息量" ✅

上手使用：3 步完成预测

依赖版本固定在 requirements.txt（scikit-learn 1.7.2 / skops 0.14.0 / numpy 1.26.4 / pandas 2.3.3）。核心用法很简单：

import skops.io as sio # 加载模型（skops 会校验类型白名单） model = sio.load("engagement_ridge.skops") # X 是列名与 config.json -> feature_columns 一致的 DataFrame prediction = model.predict(X) # 返回每条内容的预测互动率

在 Viralst 应用中，该模型通过ai/服务的POST /engagement/predict接口对外提供能力，无需自己搭推理服务。

⚠️ 诚实的局限性

这个仓库是一个合成数据 POC（概念验证），需要认清它的边界：

• 训练数据是training/generate_poc_data.py生成的 2000 行合成数据（30 品牌 / 300 brief / 2000 内容），特征与目标的真实关系是人为编码的，不反映真实平台的互动分布
• 特征质量依赖上游 LLM 从 brief 文档中抽取信息，抽取不准时预测质量会下降
• 尚未在训练集之外的真实品牌活动数据上验证

所以它的价值在于：端到端跑通了"特征工程 → 模型选择 → 评估 → 服务化"的完整管线，为接入真实数据打好了地基。

总结

• engagement-predictor =Ridge 回归 + 特征流水线，预测社媒内容的互动率
• Ridge 的本质：线性回归 + L2 正则化（α=10.0），防过拟合、更稳健
• 合成数据上 R²=0.71，误差比基线降低近 50%
• 想动手复现？按 requirements.txt 装好依赖，加载 engagement_ridge.skops，喂入符合 config.json 特征的 DataFrame 即可

5 分钟看懂了"输入 brief → 输出互动率"这件事，下一步就可以研究如何把真实投放数据接进这条管线了 🚀