Robyn：持续且半自动化的 MMM

来自 Meta Marketing Science 的开源营销组合模型工具包

简介

• 什么是 Robyn？：Robyn 是 Meta Marketing Science 推出的一款实验性、半自动化且开源的营销组合建模（MMM）工具包。它利用多种机器学习技术（岭回归、用于超参数优化的多目标进化算法、用于趋势与季节性分解的时间序列分析、基于梯度的预算分配优化、聚类等），来定义媒体渠道的效率和效果，并探索广告库存率及饱和曲线。该工具包专为包含大量自变量的细粒度数据集而设计，因此特别适合拥有丰富数据源的数字广告和直接响应型广告主。

• 我们为何要开发它？：过去，MMM 是一种资源密集型技术，只有大型企业才能负担得起。随着测量领域对隐私保护需求的不断演变，现代 MMM 作为一种隐私友好的解决方案，其市场需求正日益增长。在 Meta Marketing Science，我们的使命是通过以数据和科学为基础的营销实践变革，帮助所有企业实现增长。这与我们致力于 democratizing MMM、使其为各类规模的广告主所用的愿景高度一致。借助 Project Robyn，我们希望为测量行业贡献力量，激发业界创新，并围绕 MMM 及整个营销科学的未来建立交流与创新的社区。

Robyn 同时提供 R 和 Python 版本。安装及使用指南见下文。请注意，当前的 Python 版本是由大语言模型翻译的测试版，可能存在一些 bug。

R 快速入门

1. 安装软件包

• 安装最新版本的 Robyn R 包：

## CRAN 版本
install.packages("Robyn")

## 开发版本
# 如果尚未安装 remotes 包，请先运行：install.packages("remotes")
remotes::install_github("facebookexperimental/Robyn/R")

• 如果下载时间过长，可能是因为您的网络连接较慢或不稳定。若在安装过程中遇到问题（参见 GitHub 问题 #309），可尝试设置 options(timeout=400)。

• Robyn 需要 Python 库 Nevergrad。如果在安装过程中遇到与 Python 相关的错误，请参考 逐步指南 以及此 问题，以获取更多信息。

• 对于 Windows 用户，若出现 openssl 错误，请参阅以下说明： 这里 和 这里 提供了安装和更新 openssl 的步骤。

2. 开始使用

• 使用此 demo.R 脚本作为分步指南，旨在覆盖大多数常见用例。请使用软件包中提供的模拟数据集测试该工具包。

• 访问我们的 网站，了解更多关于 Project Robyn 的详细信息。

• 加入我们的 公开群组，与其他用户交流并直接与 Robyn 团队互动。

• 在线学习 Meta 的 官方 Robyn 蓝图课程。

Python 快速入门（Beta）

Robyn 的 Python 版本基于 Robyn 的 R 包版本 3.11.1，采用面向对象编程原则和模块化架构重新编写，以构建一个稳健的解决方案。该版本由多种大语言模型和 AI 工作流（如 Llama）协助开发而成。如同任何基于 AI 的解决方案一样，在将代码从一种语言翻译到另一种语言的过程中，可能会遇到一些挑战。在此案例中，我们预计从 R 到 Python 的翻译过程中可能会出现一些问题。然而，我们坚信社区协作与开源贡献的力量。因此，我们向社区开放此项目，邀请大家参与并贡献力量。通过共同努力，我们可以解决可能出现的问题，从而提升 Robyn Python 版本的功能性和效率。我们期待您的参与，也期待该项目的持续改进。

1. 先决条件

• 您的计算机上必须安装 R。请从 R 官方网站 下载。
• 需要安装 glmnet R 包。

在 Windows 上安装 glmnet

# 打开 R 控制台（在命令提示符或 PowerShell 中运行）
R
# 然后在 R 控制台中安装 glmnet
install.packages("glmnet")
# 退出 R 控制台
q()

在 macOS/Linux 上安装 glmnet

# 打开终端并运行 R
R
# 然后在 R 控制台中安装 glmnet
install.packages("glmnet")
# 退出 R 控制台
q()

2. 设置 Python 环境

Windows

# 创建虚拟环境
python -m venv robyn-env

# 激活虚拟环境
robyn-env\Scripts\activate

macOS/Linux

# 创建虚拟环境
python3 -m venv robyn-env

# 激活虚拟环境
source robyn-env/bin/activate

3. 安装 Robyn

请选择以下任一安装方式：

# 从 PyPI 安装（推荐）
pip3 install robynpy

# 或者从源码安装开发版本
pip3 install -r requirements.txt

4. 开始使用

python/src/robyn/tutorials 目录包含使用附带的模拟数据集的常见场景教程。

运行 Python Robyn 有两种方式：

选项 1：使用 tutorial1.ipynb（推荐）

• 提供端到端的工作流，一键式解决方案
• 非常适合偏好极简设置的用户
• 使用 python/src/robyn/robyn.py 中的 API
• 包括特征工程、模型训练、聚类、生成概览报告以及预算分配
• 可以直接在笔记本中修改配置

选项 2：使用 tutorial1_src.ipynb（进阶）

• 提供更高的灵活性和对各个模块的控制能力
• 专为希望自定义工作流程的用户设计
• 直接通过参数调用各个模块
• 允许跳过特定组件（聚类/概览图表/预算分配）
• 需要理解底层逻辑

Python 封装快速入门（Robyn Python API 测试版）

Robyn Python API（测试版）于 2023 年 11 月 22 日首次发布，是一种基于管道的解决方案，需要先安装 Robyn R 包。当 Python 原生版本尚未可用或未更新时，它可以作为一种临时替代方案。请参阅使用指南 此处。

许可证

Meta 的 Robyn 采用 MIT 许可证，具体信息见 LICENSE 文件。

• 使用条款 - https://opensource.facebook.com/legal/terms
• 隐私政策 - https://opensource.facebook.com/legal/privacy
• 防御性公开文档 - https://www.tdcommons.org/dpubs_series/4627/

联系方式

• gufeng@meta.com，Gufeng Zhou，营销科学部门，Robyn 创建者
• igorskokan@meta.com，Igor Skokan，营销科学总监，开源项目负责人

Robyn 快速上手指南

Robyn 是由 Meta Marketing Science 开源的营销组合模型（MMM）工具，支持 R 和 Python。它利用机器学习技术（如岭回归、多目标进化算法等）自动分析媒体渠道效率、广告衰减率及饱和度曲线，特别适用于拥有丰富数据源的数字广告主。

环境准备

系统要求

• 操作系统：Windows / macOS / Linux
• 核心依赖：
  • R 语言：必须安装（即使使用 Python 版本也需要 R 作为底层支撑）。
  • Python：建议使用 Python 3.8+（用于运行 Python 原生版或 API 封装版）。

前置依赖检查

1. 安装 R：前往 CRAN 下载并安装最新版 R。
2. 安装 R 包 glmnet（Python 版必需）： 打开 R 控制台执行：

   install.packages("glmnet")
   

3. Python 依赖：
   • Robyn R 版依赖 Python 库 nevergrad。
   • Robyn Python 原生版（Beta）需配置虚拟环境。

注意：国内用户若下载缓慢，可在 R 中设置清华或中科大镜像源：

options(repos = c(CRAN = "https://mirrors.tuna.tsinghua.edu.cn/CRAN"))

---

安装步骤

方案 A：安装 R 版本（推荐，功能最稳定）

1. 安装 CRAN 正式版：

   install.packages("Robyn")
   

2. 或安装 GitHub 开发版（如需最新功能）：

   # 若未安装 remotes 包，先运行：install.packages("remotes")
   remotes::install_github("facebookexperimental/Robyn/R")
   

3. 常见问题处理：

   • 下载超时：在 R 中运行 options(timeout=400) 后再安装。
   • Windows OpenSSL 错误：需手动安装 OpenSSL 并配置环境变量（参考 StackOverflow 相关教程）。
   • Nevergrad 报错：确保已安装 Python 并在系统中可用。

方案 B：安装 Python 原生版本（Beta 测试版）

⚠️ 此版本由 LLM 辅助翻译，可能存在 Bug，适合进阶开发者贡献代码或尝鲜。

1. 创建并激活虚拟环境：

   • Windows:

     python -m venv robyn-env
     robyn-env\Scripts\activate
     

   • macOS/Linux:

     python3 -m venv robyn-env
     source robyn-env/bin/activate
     

2. 安装 Robyn Python 包：

   # 推荐从 PyPI 安装
   pip3 install robynpy
   
   # 或从源码安装开发版
   # pip3 install -r requirements.txt
   

方案 C：Python 调用 R 内核（API 封装版）

如果不想直接使用 Python 重写版，可通过 plumber 接口在 Python 中调用稳定的 R 版本。需先按方案 A安装 R 包，具体用法参考官方 robyn_api 笔记。

---

基本使用

R 语言使用示例

最快捷的方式是运行官方提供的演示脚本，该脚本包含模拟数据及完整流程（数据预处理、建模、聚类、预算分配等）。

1. 加载包并运行演示：

   library(Robyn)
   
   # 获取演示脚本路径 (需先下载 demo.R 文件或在线查看)
   # 建议直接复制官方 demo.R 内容到本地运行
   

2. 核心函数调用逻辑（简化版）：

   # 准备数据 (input_data 需符合特定格式，包含日期、响应变量、媒体花费等)
   # 运行模型
   robyn_model <- robyn(
     data = input_data,
     date_var = "ds",
     dep_var = "y",
     media_vars = c("paid_search", "display", "video"),
     plot = TRUE,
     output_folder = "Robyn_Results"
   )
   
   # 查看结果
   plot(robyn_model)
   

提示：强烈建议下载并运行官方 demo.R 脚本，它涵盖了绝大多数标准用例。

Python 原生版使用示例

1. 运行官方教程 Notebook： 进入安装目录下的 python/src/robyn/tutorials 文件夹。

2. 一键运行（推荐新手）： 打开 tutorial1.ipynb，该文件提供了端到端的流程：

   • 特征工程
   • 模型训练
   • 聚类分析
   • 生成单页报告 (One-pager)
   • 预算分配建议

   直接在 Jupyter 中修改配置单元格并运行所有 Cell 即可。

3. 模块化调用（进阶）： 使用 tutorial1_src.ipynb 可单独调用特定模块（如跳过聚类），适合需要自定义工作流的用户。

---

更多资源：

• 官方文档网站：Robyn Site
• 交流社区：Facebook Group
• 官方课程：Meta Blueprint