scikit-learn

Scikit-learn

概述

此技能为使用 scikit-learn 执行机器学习任务提供全面指导。scikit-learn 是业界标准的传统机器学习 Python 库。可将此技能用于分类、回归、聚类、降维、预处理、模型评估，以及构建可用于生产环境的 ML 流水线。

安装

已针对 scikit-learn 1.8.0（稳定版；2025 年 12 月）进行测试。需要 Python 3.11–3.14（1.8 及更高版本提供适用于自由线程版 CPython 3.14 的 wheel）。

安装 PyPI 软件包 scikit-learn（不要安装 PyPI 上已弃用的 sklearn 软件包）。在代码中将其导入为 sklearn。

# Install scikit-learn using uv
uv pip install "scikit-learn>=1.7"

# Optional: plotting utilities and bundled script dependencies
uv pip install "scikit-learn[plots]" matplotlib seaborn

# Commonly used with
uv pip install pandas numpy

检查版本：

import sklearn
print(sklearn.__version__)

何时使用此技能

在以下情况下使用 scikit-learn 技能：

• 构建分类或回归模型
• 执行聚类或降维
• 为机器学习预处理和转换数据
• 使用交叉验证评估模型性能
• 使用网格搜索或随机搜索调整超参数
• 为生产工作流创建 ML 流水线
• 比较适用于某项任务的不同算法
• 处理结构化（表格）数据和文本数据
• 需要可解释的传统机器学习方法

快速入门

分类示例

from sklearn.model_selection import train_test_split
from sklearn.preprocessing import StandardScaler
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import classification_report

# Split data
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, stratify=y, random_state=42
)

# Preprocess
scaler = StandardScaler()
X_train_scaled = scaler.fit_transform(X_train)
X_test_scaled = scaler.transform(X_test)

# Train model
model = RandomForestClassifier(n_estimators=100, random_state=42)
model.fit(X_train_scaled, y_train)

# Evaluate
y_pred = model.predict(X_test_scaled)
print(classification_report(y_test, y_pred))

包含混合数据的完整流水线

from sklearn.pipeline import Pipeline
from sklearn.compose import ColumnTransformer
from sklearn.preprocessing import StandardScaler, OneHotEncoder
from sklearn.impute import SimpleImputer
from sklearn.ensemble import GradientBoostingClassifier

# Define feature types
numeric_features = ['age', 'income']
categorical_features = ['gender', 'occupation']

# Create preprocessing pipelines
numeric_transformer = Pipeline([
    ('imputer', SimpleImputer(strategy='median')),
    ('scaler', StandardScaler())
])

categorical_transformer = Pipeline([
    ('imputer', SimpleImputer(strategy='most_frequent')),
    ('onehot', OneHotEncoder(handle_unknown='ignore'))
])

# Combine transformers
preprocessor = ColumnTransformer([
    ('num', numeric_transformer, numeric_features),
    ('cat', categorical_transformer, categorical_features)
])

# Full pipeline
model = Pipeline([
    ('preprocessor', preprocessor),
    ('classifier', GradientBoostingClassifier(random_state=42))
])

# Fit and predict
model.fit(X_train, y_train)
y_pred = model.predict(X_test)

核心能力

references/core_capabilities.md 中记录了五个能力领域，各主题的详细说明见 references/supervised_learning.md、 references/unsupervised_learning.md、 references/model_evaluation.md、 references/preprocessing.md 和 references/pipelines_and_composition.md：

1. 监督学习 — 分类和回归估计器系列。
2. 无监督学习 — 聚类、分解和流形学习。
3. 模型评估与选择 — 指标、交叉验证和超参数搜索。
4. 数据预处理 — 缩放、编码、插补和特征选择。
5. 流水线与组合 — Pipeline 和 ColumnTransformer。

始终在 Pipeline 中拟合预处理步骤，这样每个交叉验证折都会重新拟合；在拆分数据前进行缩放或插补，会将测试信息泄漏到训练过程中。

两个完整的工作流示例见 references/common_workflows.md。

示例脚本

分类流水线

运行完整的分类工作流，包括预处理、模型比较、超参数调优和评估：

uv run python scripts/classification_pipeline.py

此脚本演示：

• 处理混合数据类型（数值型和类别型）
• 使用交叉验证比较模型
• 使用 GridSearchCV 调优超参数
• 使用多个指标进行全面评估
• 分析特征重要性

聚类分析

执行聚类分析，包括算法比较和可视化：

uv run python scripts/clustering_analysis.py

此脚本演示：

• 查找最佳聚类数量（肘部法、轮廓分析）
• 比较多种聚类算法（K-Means、DBSCAN、Agglomerative、Gaussian Mixture）
• 在没有真实标签的情况下评估聚类质量
• 使用 PCA 投影可视化结果

参考文档

此技能包含全面的参考文件，可深入了解特定主题：

快速参考

文件： references/quick_reference.md

• 常见导入模式和安装说明
• 常见任务的快速工作流模板
• 算法选择速查表
• 常见模式和注意事项
• 性能优化技巧

监督学习

文件： references/supervised_learning.md

• 线性模型（回归和分类）
• 支持向量机
• 决策树和集成方法
• K 近邻、朴素贝叶斯、神经网络
• 算法选择指南

无监督学习

文件： references/unsupervised_learning.md

• 所有聚类算法及其参数和使用场景
• 降维技术
• 离群点和新颖性检测
• 高斯混合模型
• 方法选择指南

模型评估

文件： references/model_evaluation.md

• 交叉验证策略
• 超参数调优方法
• 分类、回归和聚类指标
• 学习曲线和验证曲线
• 模型选择最佳实践

预处理

文件： references/preprocessing.md

• 特征缩放和归一化
• 对类别变量进行编码
• 缺失值插补
• 特征工程技术
• 自定义转换器

管道和组合

文件： references/pipelines_and_composition.md

• 管道的构建和使用
• 用于混合数据类型的 ColumnTransformer
• 用于并行转换的 FeatureUnion
• 完整的端到端示例
• 最佳实践

最佳实践

始终使用管道

管道可以防止数据泄漏并确保一致性：

# Good: Preprocessing in pipeline
pipeline = Pipeline([
    ('scaler', StandardScaler()),
    ('model', LogisticRegression())
])

# Bad: Preprocessing outside (can leak information)
X_scaled = StandardScaler().fit_transform(X)

仅在训练数据上拟合

切勿在测试数据上拟合：

# Good
scaler = StandardScaler()
X_train_scaled = scaler.fit_transform(X_train)
X_test_scaled = scaler.transform(X_test)  # Only transform

# Bad
scaler = StandardScaler()
X_all_scaled = scaler.fit_transform(np.vstack([X_train, X_test]))

分类任务使用分层拆分

保持类别分布：

X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, stratify=y, random_state=42
)

设置随机状态以确保可复现性

model = RandomForestClassifier(n_estimators=100, random_state=42)

选择合适的指标

• 平衡数据：准确率、F1 分数
• 不平衡数据：精确率、召回率、ROC AUC、平衡准确率
• 对成本敏感：定义自定义评分器

按需缩放特征

需要进行特征缩放的算法：

• SVM、KNN、神经网络
• PCA、带正则化的线性回归／逻辑回归
• K-Means 聚类

不需要进行特征缩放的算法：

• 基于树的模型（决策树、随机森林、梯度提升）
• 朴素贝叶斯

常见问题排查

ConvergenceWarning

问题： 模型未收敛 解决方案： 增大 max_iter 或缩放特征

model = LogisticRegression(max_iter=1000)

测试集上的表现不佳

问题： 过拟合 解决方案： 使用正则化、交叉验证或更简单的模型

# Add regularization
model = Ridge(alpha=1.0)

# Use cross-validation
scores = cross_val_score(model, X, y, cv=5)

大型数据集导致内存错误

解决方案： 使用专为处理大型数据设计的算法

# Use SGD for large datasets
from sklearn.linear_model import SGDClassifier
model = SGDClassifier()

# Or MiniBatchKMeans for clustering
from sklearn.cluster import MiniBatchKMeans
model = MiniBatchKMeans(n_clusters=8, batch_size=100)

更多资源

• 官方文档：https://scikit-learn.org/stable/
• 用户指南：https://scikit-learn.org/stable/user_guide.html
• API 参考：https://scikit-learn.org/stable/api/index.html
• 示例集：https://scikit-learn.org/stable/auto_examples/index.html

Agent 操作流程

1. 检查环境。 确认 Python 环境和库版本（python -c "import pkg; print(pkg.__version__)"），并检查数据的形状、类型和缺失值。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。任何会改变结果的值都应询问确认，不要猜测。
3. 先运行小规模版本。 先在样本或单个折上运行，并检查运行时间和内存占用。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 使用留出数据、固定随机种子和适当的指标；检查是否存在数据泄漏；报告不确定性（置信区间、不同随机种子下的标准差）。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及哪些方面仍不确定。

如果发生以下情况	请执行以下操作
内存不足或执行速度很慢	对数据进行子采样，使用分块或惰性计算，或缩小模型规模，并告知用户做了哪些调整。
这些说明中提到的函数、标志或端点在已安装的版本中不存在	查阅已安装版本的文档（help()、--help、官方文档），调整用法，并告知用户。切勿捏造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所采用的假设。

诚信准则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请如实说明。
• 切勿报告本次会话中未计算的指标；为每个数字展示生成该数字的代码路径。
• 此处与特定版本相关的细节可能已过时：请对照已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，先征得用户同意。

相关技能

• scanpy：标准的单细胞 RNA-seq 分析流程。
• aeon：时间序列机器学习任务（包括分类、回归、聚类、预测、异常检测等）应使用此技能。
• weights-and-biases：使用 Weights & Biases（W&B、wandb）记录和跟踪机器学习实验，包括指标、超参数、检查点、扫描、产物等。