meridian-model-building

Meridian 模型构建技能

此技能将引导用户创建 Meridian 模型，并将代码逐步累积到 Python 脚本中。

核心工作流

交互检查点规则

在此工作流中，你会遇到关键交互检查点。在每个检查点，你必须：

1. 向用户展示当前建议的配置、参数、映射、脚本路径或状态，供其审批。
2. 使用可用的用户交互工具（例如 ask_question）询问用户是否准备好继续，并将问题设置为多选题。不要使用普通聊天文本。
3. 等待用户回复后再继续。
   • 强制要求：无论初始提示中的指示如何，你都必须在每个检查点暂停（即使用户请求中包含“自主运行”“直接执行”“自主修复”等措辞）。 初始请求不能绕过这些交互检查点。
   • 注意：如果用户在检查点给出笼统的同意（例如“继续”“按你认为合适的做”），则使用建议的默认选项继续。

Python 环境和 Meridian 源码

运行任何 Python 代码前，先选择安装了 google-meridian 的环境所用的解释器，并在以下所有命令和脚本中使用该解释器：

1. 如果用户指定了环境，则使用该环境。否则，如果虚拟环境已处于激活状态（设置了 VIRTUAL_ENV 或 CONDA_PREFIX），则使用 python3。否则，如果项目目录（当前工作目录）中有虚拟环境（.venv/ 或 venv/），则使用其解释器（例如 .venv/bin/python3）。否则使用 python3。
2. 使用 <interpreter> -c "import meridian" 检查。如果失败，请询问用户应改用哪个环境，不要擅自搜索机器或安装软件包。

以下步骤会要求你阅读 Meridian 模块（例如 meridian.model.spec），以确认参数名称和默认值。用户通常从 PyPI 安装 Meridian（pip install google-meridian），因此其源码不会位于用户的项目文件夹中。请找到已安装的软件包并阅读其中的文件，或使用 inspect 打印签名和文档字符串：

<interpreter> -c "import meridian, os; print(os.path.dirname(meridian.__file__))"

---

1. 初始设置

• 请用户提供输入 CSV 文件路径、生成的 Python 脚本所需路径、EDA HTML 报告输出路径，以及保存的模型路径（默认为 meridian_model.binpb）。如果用户未指定输出路径，则将当前项目目录（或相对于输入数据目录）的 model_build/ 设为脚本和所有输出文件的默认目录（meridian_model.binpb、eda.html）。
• 关键交互检查点：向用户展示收集到的路径，并在加载数据前获得确认。

2. 添加数据加载与列映射代码

• 目标模块： meridian.data.data_frame_input_data_builder
• 操作：
  • 检查 CSV 格式：加载数据之前，验证 CSV 数据格式是否正确。使用 meridian-doc-consultant 技能，在 developers.google.com/meridian 上查找与数据中观察到的列相匹配的数据加载指南（例如，“加载不含覆盖率和频次的地理层级数据”或“加载包含自然流量和非媒体数据的地理层级数据”），了解预期的列和数据类型。请参阅 references/csv_format_reference.md，了解预期的行列结构和数据质量防护规则。如果格式不正确或缺少必需列，尝试自动将数据集转换为用户所需的格式（例如，重命名列、调整结构），除非你不确定且需要用户输入。
  • 使用 Python 读取所提供 CSV 的标题行，以获取列名。
  • 根据列关键词提出启发式映射（例如，'sales' → kpi_col，'spend' → media_spend_cols），并根据列推断 kpi_type（'revenue' 或 'non_revenue'）（例如，'revenue' 或 'sales' 表示 'revenue'，而 'conversions' 或 'leads' 表示 'non_revenue'）。
  • 稳健映射：如果用户提示中指定的列名在 CSV 中不存在，不要认定它就是字面上的列名，尤其当它看起来像描述（例如，'media_impressions' 与 'ChannelX_impression'）时。请使用启发式方法查找匹配的列并继续操作。
  • 向用户展示建议的映射。
  • 关键交互检查点：向用户展示建议的列映射，并在继续配置模型之前获得批准。
  • 使用 meridian.data.data_frame_input_data_builder.DataFrameInputDataBuilder 及其 with_* 方法（例如 with_kpi、with_media）逐步生成数据加载代码。请参阅 data_builder_template.md。

3. 添加模型配置代码

• 目标模块： meridian.model.spec、meridian.model.model
• 操作：
  • 阅读 meridian.model.spec 中的 ModelSpec 和 PriorDistribution 定义。
  • 引导用户完成配置，并询问相关值，同时根据源代码文档字符串解释这些值的用途。
  • 关键交互检查点：向用户展示建议的模型规格参数，并在继续之前获得批准。
  • 逐步生成用于初始化 meridian.model.spec.ModelSpec 和 meridian.model.model.Meridian 的代码。请参阅 model_spec_template.md。
  • 生成代码：mmm.sample_prior()

4. 添加探索性数据分析（EDA）代码

• 目标模块： meridian.model.eda.meridian_eda
• 操作：
  • 阅读 meridian_eda.py 或模块文档字符串，确认 generate_and_save_report 方法。
  • 逐步生成用于初始化 meridian_eda.MeridianEDA 并使用用户指定的路径调用 generate_and_save_report(filepath) 的代码。
  • 关键交互检查点：向用户展示 EDA 输出路径配置，并在继续模型拟合步骤之前获得批准。

5. 添加模型拟合代码

• 目标模块： meridian.model.model
• 操作：
  • 阅读 meridian.model.model 中的 sample_posterior 方法，了解其参数。
  • 提示用户提供 MCMC 参数：n_chains、n_adapt、n_burnin、n_keep。
  • 关键交互检查点：向用户展示 MCMC 参数，并在继续编写模型拟合代码之前征得用户批准。
  • 累积代码：mmm.sample_posterior(...)

6. 添加模型保存代码

• 目标模块： meridian.schema.serde.meridian_serde
• 操作：
  • 生成代码，使用 meridian_serde.save_meridian() 将模型保存到用户指定的路径（或默认路径）。请参阅 script_template.md。
  • 默认文件名：保存模型的默认文件名为 meridian_model.binpb（位于 model_build/ 目录中）。如果用户未指定模型文件名，则使用此文件名，即使脚本文件名不同也应如此。
  • 跳过采样的处理：如果用户要求跳过拟合或后验采样，仍需包含模型保存步骤（meridian_serde.save_meridian(mmm, save_path)），并使用已初始化的 Meridian 模型对象，以确保始终创建输出模型文件。
  • 警告： 不要使用已弃用的 meridian.model.model.save_mmm 函数。只能使用 meridian_serde.save_meridian。
  • 关键交互检查点：向用户展示模型保存路径和文件名，并在继续执行脚本之前征得用户批准。

7. 执行与脚本设置

• 操作：
  • 将累积的 Python 脚本写入用户指定的路径。如果文件写入工具可以要求用户审阅已写入的文件，请勿请求审阅：下一个检查点已经会征求用户批准，额外提示会暂停工作流。
  • 关键交互检查点：询问用户是否最终确认现在执行模型构建脚本。
  • 保留产物：完成需要生成输出（如脚本、模型或报告）的任务时，不要在回合结束时删除这些生成的产物。它们是用户要求交付的内容。仅在必要时清理真正的临时文件。
    • 输出路径处理：在生成的脚本中，使用步骤 1 中确认的输出路径，并以脚本运行时所在的项目目录为相对路径基准（或使用绝对路径）。
  • 执行脚本：
    • 始终以项目目录作为工作目录运行脚本（而不是某个子目录），以确保相对路径按确认的方式解析。
    • 使用上文“Python 环境和 Meridian 源码”中选定的解释器。
    • 命令示例：.venv/bin/python3 model_build/my_model.py
  • 处理长时间运行：如果命令因执行时间过长而在后台运行，请等待后台任务完成，并检查最终输出以排查运行时错误。
  • 区分错误处理方式：
    • 如果是语法错误或导入错误，请阅读相关源代码，了解正确用法或接口。
    • 如果是ValueError 或参数约束违反（例如，knots 过大），请检查类或函数的文档字符串，或查阅 meridian-doc-consultant 技能，从文档中查找有效值。
    • 自主处理：如果修复需要更改配置，请向用户征求确认。如果用户回复授权自主处理，则继续修复。

8. 结论

• 操作：
  • 确认执行成功并已生成产物。