FrankS-IntelLab/agentic-kaggle-skill

Agentic Kaggle 技能

运作循环

首先将每个竞赛视为验证问题，然后才是建模问题。默认目标平台是 Kaggle，因此优先使用 Kaggle 原生的笔记本/脚本、数据集、模型工件、竞赛提交和评分收据。对于代码竞赛，除非竞赛文档另有说明，否则假定最终的笔记本/内核将由 Kaggle 针对隐藏数据重新运行。

1. 阅读竞赛页面，将提交模式分类为经典文件提交或代码/笔记本评分，然后检查规则、数据使用条款、共享政策、数据字典、指标、提交格式、训练/测试构建提示和泄漏警告。
2. 如果实时竞赛情报工具可用，在进行主要架构选择之前，检查顶尖的公开笔记本解决方案和相关讨论活动；将其视为线索，而非权威。
3. 确定任务类型：二分类、多分类、多标签、回归、排序、图像、分割、文本、时间序列、分组实体或混合类型。
4. 在特征工程或建模之前设计折（fold）。优先将折列保存到训练数据中，以便每次实验使用相同的比较表面。
5. 构建最简单的、指标正确的基线，并生成折外预测以及一个有效的提交。
6. 一旦基线可靠，主动规划更强大的架构：多样化的模型族、特征/嵌入生成器、增强/伪标签/蒸馏阶段、校准/后处理，以及集成或堆叠器。
7. 通过验证门进行迭代：尽可能一次只测试一个有意义的更改，但当多个独立的生产者笔记本创建了可通过折外分数或集成多样性进行比较的不同工件时，并行启动它们。
8. 当本地计算可能内存不足或耗时过长时，将繁重的训练、推理、嵌入生成、图像/文本实验或高风险内存任务卸载到 Kaggle 笔记本/脚本。
9. 对于复杂的架构，将工作拆分为一个小型 Kaggle 流水线：首先运行多个独立的生产者笔记本/脚本，将每个有用的生产者输出保存为私有的 Kaggle 数据集，然后运行一个消费者笔记本/脚本，该脚本附加这些数据集并创建最终的折外/测试/提交输出。当生产者训练模型时，其检查点、分词器/配置、折元数据、折外/测试预测和清单应作为 Kaggle 数据集导出；下游笔记本从 /kaggle/input/... 加载模型。
10. 向 Kaggle 提交最终生成提交的工件进行评分，并检索产生的提交状态/分数。
11. 如果 Kaggle 返回代码竞赛错误或模糊的评分失败，进入调试循环：检索可用日志，分类可能的失败模式，防御性地修补，重新运行最终内核，重新提交，并重复直到获得评分或明确受阻。
12. 跟踪每次运行的本地交叉验证、远程 Kaggle 运行状态、Kaggle 提交分数、公开排行榜、私有风险备注、种子、代码版本、数据版本和工件路径。
13. 仅使用无折内泄漏生成的折外预测进行集成。

资源地图

• 阅读 references/method-map.md 以了解该技能背后的中立工作流映射。
• 在将竞赛代码、笔记本、数据集、模型、工件或报告发布到活跃团队或工作区之外之前，请阅读 references/information-sharing-policy.md。
• 当 Kaggle 竞赛标识符、URL、标题、公开排行榜上下文、开放解决方案或讨论活动可能影响方法时，请阅读 references/competition-intel.md。
• 在选择折、指标、阈值或泄漏检查时，请阅读 references/cross-validation-and-metrics.md。
• 有关分类变量、特征工程、选择和超参数调优，请阅读 references/tabular-workflow.md。
• 有关图像、分割和 NLP 竞赛方法，请阅读 references/image-text-workflow.md。
• 当目标是 Kaggle 代码竞赛、隐藏重新运行、最终笔记本评分流程或生产者和消费者笔记本之间的模型工件交接时，请阅读 references/kaggle-code-competition-pipeline.md。
• 当更强的解决方案可能需要多个模型族、分阶段特征/嵌入/模型生产者、伪标签、蒸馏、后处理、混合、堆叠或并行 Kaggle GPU 笔记本时，请阅读 references/advanced-notebook-architecture.md。
• 当本地运行负担重、需要 GPU、需要访问 Kaggle 数据或必须收集远程笔记本结果时，请阅读 references/kaggle-offload.md。
• 当使用多个 Kaggle 笔记本、中间数据集、笔记本输出源或 kagglehub 时，请阅读 references/kaggle-pipeline-datasets.md。
• 在停止工作之前，请阅读 references/submission-endgame.md；直到 Kaggle 评分已尝试并收集了结果，或记录了具体的障碍之前，此技能才算完成。
• 当 Kaggle 代码竞赛提交失败、超时、内存不足、未产生分数或报告模糊的隐藏运行/评分错误时，请阅读 references/code-competition-debugging.md。
• 有关项目布局、折外工件、堆叠、混合和可重复性，请阅读 references/ensembling-and-reproducibility.md。
• 仅当用户要求历史案例研究、Hermes 时代模式或来自此存储库的具体竞赛经验时，才阅读 references/research/ 或 examples/。
• 运行 scripts/scaffold_competition.py 以创建竞赛工作区。
• 运行 scripts/make_folds.py 以向训练 CSV 添加折列。
• 运行 scripts/prepare_kaggle_kernel.py 以创建带有元数据和可检索实验日志的 Kaggle 内核文件夹。
• 运行 scripts/prepare_kaggle_dataset.py 以创建版本化中间工件数据集的元数据和命令。

默认 Kaggle 流程

从指标和验证开始：

• 本地复现竞赛指标，包括裁剪、变换、平均模式、阈值和样本权重。
• 在团队外部共享任何内容之前，检查竞赛是否允许公共代码、外部数据、预训练权重、生成的工件和公共存储库。
• 尽早分类 Kaggle 提交路径。如果是代码竞赛或笔记本评分工作流，请从一开始就将最终消费者笔记本设计为评分工件。
• 当可用时，使用 kaggle-competition-intel MCP 工具：top_open_solutions 用于查看按分数排序以及最新高投票数的笔记本，competition_discussions 用于在选择昂贵的基线之前查看最高投票数和最近活跃的讨论主题。
• 选择与隐藏测试分布匹配的折。分类使用分层，回归使用分箱分层，重复实体使用组分割，时间数据使用时间感知分割，当标签共现重要时使用多标签感知分割。
• 为每个模型保存折外预测。折外文件是进行错误分析、阈值调整、混合和堆叠的货币。
• 比较平均折分数和折方差，而不仅仅是最佳折。
• 在将其视为建模胜利之前，将与该技能不符的公开排行榜跃升视为验证问题。

然后按此顺序构建基线：

1. 仅指标或常数基线，以验证评分和提交格式。
2. 快速经典基线：表格数据的 LightGBM/CatBoost/XGBoost，文本的 TF-IDF 加线性模型，图像的预训练骨干网络。
3. 具有稳定折、干净工件和折外预测的强基线。
4. 带有运行日志和一个主要指标的特征/模型实验。
5. 在存在多个多样化且经过独立验证的模型后进行集成或堆叠。

当竞赛需要时，不要等待用户明确要求复杂性。在稳定的基线之后，如果公开解决方案、讨论情报、数据模态、指标压力或交叉验证平台表明单个笔记本/模型将表现不佳，则提议并执行更强大的分阶段架构。使架构受折外证据、工件清单和最终 Kaggle 评分的约束。

当运行可能超过本地 RAM/VRAM、需要 GPU/TPU 或需要仅限 Kaggle 的数据挂载时，准备运行 Kaggle 内核而不是在本地强制执行。远程运行必须生成 experiment_log.json、metrics.jsonl 和一个工件清单，以便在 kaggle kernels output 之后检索和解释结果。

当解决方案具有多个繁重阶段时，保持远程图浅显且可检查：

• 每波使用少于五个独立的生产者笔记本/脚本。
• 赋予每个生产者单一职责，例如特征生成、嵌入提取、折训练、检查点训练、模型蒸馏或推理。
• 对于代码竞赛，优先使用训练模型/检查点并将其导出为私有 Kaggle 数据集的生产者笔记本；最终消费者应附加这些数据集，从 /kaggle/input/... 加载模型，并执行安全的隐藏测试推理。
• 将生产者笔记本输出保存为版本化的私有 Kaggle 数据集，以实现持久重用，并作为下游笔记本的稳定输入；仅对不需要持久性/版本化的短期链使用直接的 kernel_sources。
• 运行一个最终的消费者笔记本/脚本，附加生成的数据集，读取其工件，写入最终的折外、测试预测、混合/堆叠报告和提交，然后将该最终工件/内核提交到 Kaggle 进行评分。
• 当更方便地以编程方式下载数据集、竞赛文件、笔记本输出或上传数据集版本时，在 Python 中使用 kagglehub。

完成定义

不要止步于计划、脚手架、训练好的模型、笔记本运行、下载的输出或本地验证分数。继续操作，直到满足以下条件之一：

• 竞赛提交已发送到 Kaggle，Kaggle 已处理，并且已检索并记录公开分数或提交状态。
• 代码竞赛的最终笔记本/内核已使用所有必需的生产者工件，已随其内核/版本引用一起提交，并且已检索并记录产生的提交状态/分数。
• 具体的外部障碍阻止了评分：缺少 Kaggle 凭据、规则未被接受、重试尝试后配额耗尽、竞赛关闭、评分禁用、仅需手动界面操作、不可用的内核版本或 Kaggle 服务故障。记录确切的障碍以及下一个需要执行的命令/操作。

验证选择

使用此快速映射：

• 平衡分类：StratifiedKFold。
• 不平衡分类：分层折加上对指标敏感的阈值调整或类别权重。
• 回归：对于普通目标使用 KFold，对于偏斜或多模态目标使用分箱分层折。
• 相同的用户、患者、产品、会话、文档或图像源出现多次：使用 GroupKFold 或分层组分割。
• 有序事件或预测：时间分割、扩展窗口验证或特定竞赛的时间段分割。
• 来自同一主题或场景的图像：在增强之前按主题/场景分组。
• 具有重复来源、作者、问题、产品或提示的文本：按源键分组。
• 数据量非常小：使用重复折或更多折，但保持最终模型选择纪律严格。

建模优先级

• 对于表格竞赛，除非数据主要是稀疏文本或高基数分类交互，否则首先优先使用树提升。当分类列是核心时，添加 CatBoost。
• 对于线性模型和神经网络，仔细缩放数值特征并编码分类变量。
• 对于树模型，从标签/计数/频率编码和合理的缺失值开始；通常不需要缩放。
• 对于目标编码，始终在折外计算编码，进行平滑处理，并且不暴露验证行目标值。
• 对于图像任务，在更改架构之前，先确保数据集、变换、标签、掩码和指标正确。
• 对于文本任务，即使使用 Transformer，也要保留 TF-IDF 基线；它速度快、可解释性强，并且通常可以很好地混合。
• 对于超参数搜索，仅在折和基线可靠后进行调优。结合早停法搜索学习率、深度/叶子数、正则化、采样和估计器数量。

竞赛卫生

• 保持原始数据只读。
• 除非竞赛规则和工件许可证明确允许公共再分发，否则将竞赛数据、私有数据集、模型检查点、下载的输出、提交、凭据和数据衍生工件排除在公共 Git 存储库之外。
• 将所有实验相关的值放入配置或命令行参数中。
• 尽可能为 Python、NumPy、框架和模型库设置随机种子。
• 使用运行 ID 保存模型文件、折外预测、测试预测、折分数、特征列表和提交文件。
• 对于卸载到 Kaggle 的作业，将可检索的日志和工件写入笔记本工作目录，包括运行 ID、git 提交、配置、折、指标、硬件、经过的时间、内存不足注释和输出文件路径。
• 对于多笔记本流水线，维护一个流水线清单，其中包含生产者内核引用、产生的数据集引用、数据集版本、工件模式、指标和最终消费者运行 ID。
• 默认将生产者数据集、内核和模型工件设为私有。仅在验证目标竞赛规则、数据许可证、第三方知识产权和用户意图后，才将它们公开。
• 记录提交消息、提交命令或内核/版本、Kaggle 提交时间戳、状态、公开分数（如有）以及 Kaggle 返回的任何错误。
• 对于模糊的代码竞赛失败，记录观察到的状态、可用日志、疑似失败类别、尝试的补丁和下一个重试命令。
• 绝不在样本内基础预测上训练堆叠器。
• 绝不在折边界之外使用验证目标来选择特征、目标编码器、缩放器、阈值或增强。
• 对于可重复的训练，优先使用脚本；对于探索和绘图，优先使用笔记本。

有用命令

Crea

…

[为翻译截断]