ai-ml-data-science

数据科学工程套件

在选择模型前，先明确决策和预测时间戳；特征必须在评分时可用。

快速参考

需求	默认方向
可复现的 Python 工作流	uv 加脚本或便于使用 Git 的笔记本（使用 marimo 实现响应式、可比较差异的笔记本）
快速本地分析	DuckDB 加 Polars；调整旧示例前，请根据 Polars 文档 检查已安装的 API
数据契约	在数据集边界使用 Pandera 或 GX Core
表格数据基线	线性或逻辑回归模型加基于树的候选模型；只有在根据 references/modelling-patterns.md §3.1 核查许可和规模后，才添加表格基础模型
特征工程	明确且适用于训练和服务阶段的转换
无标签文本语料	嵌入 -> UMAP -> HDBSCAN -> c-TF-IDF；当不需要文档级标签时，使用 LLM 生成主题级标签
调优	仅在基线稳定后使用 Optuna
评估	切片、阈值、校准、不确定性
交接	模型卡、评估报告、失效模式、监控预期

何时使用此技能

• 探索数据集并检查建模可行性
• 设计特征流水线和防止数据泄漏的措施
• 选择和比较模型系列
• 在尚无分类体系或标注计划时，对无标签文本聚类并发现主题
• 构建可复现实验工作流
• 生成评估报告、模型卡和交接材料
• 审查实验是否真正达到可交付生产的状态
• 解释负责任 AI 建模机制：公平性与交叉性、隐私、可解释性、数据投毒、记忆、人类监督和环境权衡
• 设计通用多模态模型：对比式图文学习、融合、VQA／文档／视频系统、扩散控制、适配以及质量与延迟的权衡

转至其他技能

• 服务、再训练自动化、监控或事件响应 -> ai-mlops
• 预测和时间验证 -> ai-ml-timeseries
• 湖仓或批量摄取基础设施 -> data-lake-platform
• 流式基础设施（Kafka、Flink、CDC） -> data-streaming
• 提示词、微调或 LLM 系统设计 -> ai-llm 或 ai-rag

---

工作流

1. 在接触模型前，明确决策、目标、基线和预测时间戳。
2. 验证数据集的形状、归属和数据泄漏风险。
3. 首先构建最简单的可行基线。
4. 设计符合时间点要求的特征；只有在基线可信后，才比较更强的候选模型。
5. 使用相同的切分策略、指标定义和计算预算进行评估。
   对于图模型，在评估学习得到的／时序拓扑、自监督预训练或图解释时，加载 graph-model-evaluation；记录其中的切分、基线和健全性检查结果。
6. 生成交接材料，包含阈值、校准状态、失效模式和可复现性说明。

---

核心规则

• 明确写出预测时间戳
• 如果可能存在时间泄漏或实体泄漏，不要轻信随机切分
• 至少比较一个简单基线和一个更强的候选模型
• 将阈值设定、校准和不确定性视为决策的一部分
• 确保数据版本、特征版本、随机种子和切分逻辑可复现
• 将服务、再训练和监控相关工作转至 ai-mlops

预测时资格门控

对于每个特征，记录其源事件、事件时间、可用时间、转换版本和实体连接键。排除在声明的预测时间戳尚不存在的任何值。只有在匹配的实体和时间戳上通过时间点测试证明语义一致、保留转换版本血缘关系，并监控生产偏差时，离线回填和在线服务才可以采用不同实现。使用预期的拆分单位和决策阈值评估剩余流程，然后与最简单且可执行的基线进行比较。只有在明确预测的操作、弃权路径以及假阳性和假阴性的成本后，模型才能用于决策。

已知陷阱

• 当时间、实体、家庭、账户或会话泄漏的可能性较高时，仍使用随机训练集/测试集拆分。
• 使用预测时点之后才可获得的信息构建特征，然后称结果为“可用于生产”。
• 在基线和指标定义稳定之前就开始调整模型。
• 只报告 AUC 或一个汇总分数，而忽略阈值选择、校准、分层表现和运营权衡。
• 让笔记本状态成为真正的流程逻辑。隐藏的执行顺序和缓存状态会迅速破坏可复现性。
• 如果单个特征单独就能实现近乎完美的区分，或者领域专家会认为某项指标好得不切实际——首先应将其视为泄漏漏洞报告，其次才考虑是否是发现（参见 references/eda-best-practices.md 中的 Expert Instincts）。
• 对于反复出现的实体，拆分方式必须符合部署场景：若要泛化到未见实体，则使用分组留出；若再次为这些实体评分，时间拆分可以保留先前出现的实体。两种情况下，都要强制执行特征可用性约束，并在训练折内拟合预处理流程。
• 不核对当前安装版本，就凭记忆或旧教程引用库版本、基准数值或 API 用法——表格机器学习工具（Optuna、SHAP、scikit-learn、提升树库）在短短一年内就可能跨越存在破坏性变更的主版本。

模式选择

问题类型	方向
表格型或关系型	基线加基于树的模型对比
按时间排序的预测	转至 ai-ml-timeseries
传统文本或嵌入加分类器	留在此处
无标签文本、未知主题、主题发现	留在此处；参见 references/text-clustering-topic-modeling.md
LLM 工作流、提示词或 RAG	转至 ai-llm 或 ai-rag
部署、监控、重新训练	转至 ai-mlops
数据摄取或湖仓架构	转至 data-lake-platform
负责任 AI 概念和建模权衡	留在此处；运营控制转至 ai-mlops，测量和红队测试转至 ai-evals
多模态表示、融合、VQA/文档/视频、扩散机制	留在此处；生产和评估转至 ai-mlops 和 ai-evals

---

核心模式

可复现的工作区

• 使用 uv 和显式依赖项
• 提交 uv.lock，并在 CI 中运行 uv sync --locked；对于 pandas 3.0 代码，写时复制和 str dtype 会改变行为（参见 references/eda-best-practices.md）
• 使用脚本优先或便于 Git 管理的笔记本入口点——对于响应式且可通过 Git diff 比较的笔记本，可考虑使用 marimo 替代 Jupyter；marimo 具有响应式特性（依赖单元格会自动重新运行），将笔记本保存为纯 Python 脚本，并消除隐藏状态导致的执行顺序问题
• 固定随机种子并明确拆分逻辑
• 记录数据集和特征假设

特征工程与契约

• 数值、类别、文本和基于时间的转换
• 时点可用性检查
• 可复用的编码器和有文档记录的新鲜度假设

评估与决策就绪度

• 主要指标及护栏
• 阈值策略
• 校准与不确定性处理
• 切片分析和定性错误审查

自主实验

只有在指标明确、搜索空间有界且每次运行成本足够低、可以自动保留或回退时，才使用由 Agent 驱动的实验循环。

---

模板

• assets/project/template-standard.md
• assets/project/template-quick.md
• assets/features/template-feature-engineering.md
• assets/eda/template-eda.md
• assets/evaluation/template-evaluation-report.md
• assets/evaluation/template-model-card.md
• assets/review/experiment-review-template.md

脚本

脚本	用途
scripts/ml_toolkit.py	根据模型规格 JSON 生成模型卡、泄漏检查和模型质量报告
scripts/leakage_scan.py	用于机器学习特征/目标列规格（JSON/JSONL）的静态泄漏扫描器。根据列元数据标记时间泄漏、目标泄漏和 ID 泄漏反模式。退出代码为 0 表示没有元数据标记；1 表示发现问题；2 表示输入格式错误或 I/O 失败。设置 prediction_time 可测试评分时的可用性；仅使用 label_time 是较弱的旧版截止时间。

典型用法：

python scripts/ml_toolkit.py card --input data/sample-model-spec.json
python scripts/ml_toolkit.py leakage --input data/sample-model-spec.json
python scripts/ml_toolkit.py report --input data/sample-model-spec.json --output report.md

ml_toolkit.py leakage 和 report 在结果为 WARN/FAIL（包括缺少时间截止值）时以代码 1 退出，在输入无效或发生 I/O 错误时以代码 2 退出。静态 PASS 需要在交接前验证行级可用性和数据集划分。扫描器要求 target 和 columns 非空；JSONL 每行使用一个完整规格，并拒绝格式错误的记录。请使用匹配的 ISO 时间（时区感知方式一致）或符号偏移 T±<integer><s|m|h|d>。模型规格字段请参阅 scripts/README.md。

导航

核心参考资料

• references/eda-best-practices.md
• references/feature-engineering-patterns.md
• references/data-contracts-lineage.md
• references/modelling-patterns.md
• references/evaluation-patterns.md
• references/graph-model-evaluation.md — 有界图预训练、解释、时序及推断拓扑评估约定
• references/class-imbalance-patterns.md
• references/hyperparameter-optimization.md
• references/text-clustering-topic-modeling.md — 模块化的 embed/UMAP/HDBSCAN/c-TF-IDF 流水线、表示模型重排序、按主题（而非按文档）进行 LLM 标注，以及何时优先选择纯 k-means
• references/interpretability-explainability.md
• references/responsible-ai-mechanics.md — 公平性/交叉性、差分隐私、可解释性、投毒/联邦学习、重新识别、水印、人工监督/申诉、版权/记忆，以及环境影响权衡
• references/multimodal-modeling.md — CLIP/SigLIP 目标、融合、VQA/文档/视频系统、扩散控制/多样性/加速、适配、延迟和成本
• references/reproducibility-checklist.md
• references/llm-data-pipeline.md — 面向 LLM 评估的污染检查（Min-K% 筛查、抗污染基准）；预训练语料整理（去重、过滤、去污染、混合）请先参阅 ai-data-curation-pretraining
• references/feature-freshness-streaming.md
• references/production-feedback-loops.md
• references/ml-diagrams.md — 经典 ML（k-means、逻辑回归、决策树、协同过滤）和神经网络架构（MLP、RNN、CNN、Transformer）的 Mermaid 图表目录；适用于嵌入文档、README、PR 描述

数据和外部参考资料

• data/sources.json
• data/sample-model-spec.json

相关技能

• ai-architecture-advisor — 在构建前判断何时使用树模型、深度学习或 LLM
• ai-mlops
• ai-ml-timeseries
• data-lake-platform
• ai-llm
• ai-rag
• huggingface-datasets — 现已收录于外部 huggingface-skills: 插件中

学习循环

当以往的决策或陷阱与当前情况相关时，如果存在 learnings.consolidated.md，请查阅该文件；仅在需要了解历史或该文件是可用的替代选项时，才使用 learnings.md。否则跳过这两个文件。

应用后，如果你遇到了值得记住的模式、值得避免的错误，或令你意外的领域知识，请通过 agents-skills-feedback-loop/scripts/append_learning.py 在 learnings.md 中追加一条带日期的项目。不要修改 SKILL.md 本身。