产品文档

01快速开始 Quick Start

SparkX MMM 是自助式营销组合建模（Marketing Mix Modeling）平台，帮助团队上传营销与业务数据、运行 MMM 分析、读取渠道 ROI 与贡献、优化预算分配，并生成 AI 辅助解读。

最快的工作流：

1. 创建项目。
2. 上传 CSV 或 Excel 文件。
3. 确认字段映射。
4. 运行 Instant Mode 获取初步结果。
5. 查看 ROI、贡献度、响应曲线、adstock、诊断与 AI 洞察。
6. 使用 Budget Planner 测试预算重新分配。
7. 需要更严谨的统计验证时，用 Expert Mode 或 Champion Mode 重新运行。

02数据准备 Data Preparation

支持的文件格式

.csv / .xlsx / .xls，最大 50 MB。

CSV 格式

每行一个时间周期。周粒度数据推荐用于 MMM，因为它在信号量、季节性和运行时间之间取得平衡。

week_start,revenue_usd,google_spend,meta_spend,tiktok_spend,tv_spend,email_spend,promo_flag,holiday_flag
2026-01-01,128500,12000,9000,3000,25000,1500,0,1
2026-01-08,132200,12500,9200,3200,24000,1600,0,0

必需与推荐列

03字段映射 Field Mapping

上传后 SparkX 自动检测列角色：

自动检测基于列名和数据特征。建模前务必检查映射。

常见修正

• 将 sales / gmv / orders 映射为 KPI。
• 将所有付费花费列映射为 media_spend。
• 将 holiday、promo 等二元事件列映射为 control。
• 忽略 ID、备注、活动名称等非周期级指标列。

04数据质量检查 Data Quality

SparkX 在模型执行前检查数据集。严重问题会阻止模型运行。

• 缺少日期或 KPI 映射。
• 行数过少。
• 缺失值。
• 重复时间段。
• 花费或 KPI 字段非数值。
• 渠道无变化。
• 可疑的峰值或不连续。

05Instant 模式 Instant Mode

Instant Mode 是获取首个 MMM 结果的最快方式，专为探索、数据验证和方向性预算决策设计。使用快速 frequentist 引擎（通常为 Ridge + adstock + saturation 变换），秒级到分钟级出结果。

9 步透明 Pipeline

Instant Mode 全程自动执行以下 9 步，每一步可见、可追问：

适用场景

• 新数据集上手验证。
• 需要秒级/分钟级结果。
• 验证字段映射和数据质量。
• 在运行 Bayesian 引擎前获取基线。

输出

• 渠道 ROI 与置信区间。
• 贡献度占比。
• 响应曲线与饱和度。
• Adstock 半衰期。
• 模型拟合诊断。
• 预算优化输入。
• AI 执行摘要。

06Expert 模式 6 步向导 Expert Mode

Expert Mode 是正式 MMM 运行的引导式工作流。

Step 1：创建项目并上传数据

创建项目，选择 KPI 类型、时间粒度，上传数据集。SparkX 将上传文件存储为数据集版本。

版本策略：replace（替换活跃版本）、append（合并新行）、new_root（新版本谱系）。

Step 2：探索数据

• 概览：行数、列数、日期范围、缺失率。
• 时间趋势：KPI 与媒体花费随时间变化。
• 相关性：媒体与 KPI 相关矩阵。
• 分布：花费分布与异常值。

Step 3：确认字段映射

检查并更新每列角色。有效模型需要 date、KPI 和 media_spend 映射。

Step 4：配置分析

KPI 类型（revenue / orders / conversions / 其他）；时间粒度（daily / weekly / monthly）；地域开关；渠道与控制变量；日历或节假日控制。

Step 5：选择引擎与参数

选择单个引擎或运行 Champion Mode 对比多引擎。Bayesian 引擎需要 n_chains ≥ 2、n_iterations ≥ 100（推荐 1000+）。可选设置包括先验、lift-test 校准、adstock 提示、饱和约束及引擎特定配置。

Step 6：运行、监控与审阅

SparkX 以后台子进程启动模型执行，可关闭页面稍后返回。状态流转：pending → preprocessing → sampling → completed / failed。完成后查看 Results、Budget Planner、AI Insights 与 Data Science Diagnostics。

077 引擎参考 Engine Reference

SparkX 提供多种引擎，覆盖不同速度、严谨度和可解释性需求。

引擎选择建议

• 先用 Ridge 或 SparkX TVP。
• 决策需要可信区间和收敛诊断时用 PyMC 或 Bayesian MCMC。
• 需要 Robyn 式自动超参搜索（无 R）时用 Nevergrad。
• 行业标准基线比较时用 Robyn。
• 同一数据集对比多引擎时用 Champion Mode。

08结果解读 Results

结果页围绕 5 个核心标签页组织。

ROI 与贡献度

• ROI 均值：每单位花费的预期回报。
• ROI 区间：估计的不确定性。
• 贡献百分比：归因于该渠道的 KPI 占比。
• 当前花费：模型使用的观测花费水平。
• 健康度评分：汇总质量指标（如可用）。

响应曲线

展示预测结果随花费变化的关系。曲线早期陡峭 = 增量响应强；曲线趋平 = 饱和。当前点在平坦区 = 额外花费边际回报低；当前点在趋平前 = 渠道有扩展空间。

Adstock

捕捉延后效应。半衰期长的渠道在花费结束后仍持续影响 KPI。用于理解快速衰减的绩效渠道 vs 长记忆品牌渠道。

贡献分解

将建模 KPI 分解为 baseline 和各渠道贡献的时间序列。用于解释峰谷、对比媒体驱动增长与基线需求、发现可能需要控制变量的时段。

诊断

展示模型是否可信：R-squared、MAPE、预测 vs 实际、残差、Bayesian 收敛指标（如可用）。

09预算优化 Budget Optimization

Budget Planner 基于拟合的响应曲线推荐约束下的分配方案。支持两种优化模式：

1. 给定预算最大化收入。
2. 给定收入目标最小化花费。

输入

• 总预算或目标收入。
• 渠道级 min / max 约束。
• 来自模型结果的当前分配。

输出

• 当前分配 vs 最优分配。
• 当前预测收入 vs 优化预测收入。
• 收入提升百分比。
• 渠道级建议。

场景模拟允许用户调整花费滑块并即时估算收入影响。保存的场景可后续对比。

10AI 洞察 AI Insights

Claude 驱动的自然语言解读，将模型输出转化为商业语言叙述。每个 section 可独立生成或重新生成。支持中英双语。

11数据科学诊断 Diagnostics

Analyst 视图面向数据科学审阅、模型审计与方法论透明度，包含 6 个标签页。

决策规则

• R-hat ≥ 1.1 的 Bayesian 运行不可用于决策。
• MAPE 超过 20% 视为警告。
• ROI 区间过宽 = 数据未能很好识别该渠道。
• 替换 Champion 前调查重大漂移。

12方法论 Methodology

SparkX MMM 估计媒体花费和非媒体因素如何解释业务 KPI 随时间的变化。

核心概念

• Adstock：媒体效应在花费发生后持续存在。
• Saturation：边际回报随花费增加而递减。
• Baseline：未被测量媒体渠道解释的 KPI。
• Controls：减少遗漏变量偏差的非媒体因素。
• Uncertainty：模型估计的区间。
• Backtesting：通过时间样本外验证。

模型结构

KPI(t) = baseline(t)
       + sum(channel_response(adstock(spend_channel(t))))
       + controls(t)
       + error(t)

SparkX 支持 frequentist、Bayesian、优化、时变和树模型方法。没有引擎能消除数据审查的需要。变化少、高共线性、历史短或缺少控制的渠道仍然难以估计。

推荐方法论工作流

1. 验证数据质量。
2. 运行 Instant Mode。
3. 检查曲线、贡献度和诊断。
4. 运行 Expert Mode 或 Champion Mode。
5. 审阅 posterior、robustness、backtest、drift 和 limitations。
6. 结合业务约束使用优化建议。
7. 重大预算变更尽量通过实验验证。

13FAQ Common Questions

需要多少数据？

最低 20 行可进行有意义的自动分析，但强烈推荐 52+ 周数据。历史越长，季节性、adstock 和饱和度估计越好。

用日、周还是月数据？

通常周粒度最佳。日数据噪声大，可能需要更强控制变量。月数据观测值少，除非有多年历史。

不同引擎为何产出不同 ROI？

引擎使用不同的假设、先验、正则化和优化策略。用 Champion Mode、诊断和回测判断哪个结果更稳定。

渠道 ROI 区间为何很宽？

数据集可能没有足够变化来识别该渠道。常见原因：花费不变、与另一渠道高相关、历史短或遗漏控制变量。

MMM 能证明因果性吗？

MMM 是观察性方法，不能单独完全证明因果。用 lift test、geo experiment 或 incrementality test 校准和验证重要渠道。

上传通过后运行为何失败？

模型运行使用活跃映射执行更严格的质量门控。关键数据质量问题可能阻止执行。修正映射或数据问题后重新运行。

什么是 Champion 模型？

Champion 是项目的选定最佳运行。可手动设置或在多引擎 Champion 搜索后选择。最新结果快捷方式优先 Champion 运行。

可以下载报告吗？

可以。SparkX 支持 PowerPoint 和 HTML 报告导出。

展示结果前应该做什么？

审阅 ROI、贡献度、响应曲线、诊断、稳健性、局限性和 AI 风险提醒。重大预算决策优先使用 Expert Mode 和回测验证。