autocarver

AutoCarver 只需几行代码，就能将原始数值、类别和有序列转换为有监督、抗漂移且易于理解的分箱。别再因手动分箱不理想而损失模型性能，也别再等到生产监控时才发现过拟合分箱。

• 通过搜索，而非目测 — 动态规划搜索会根据 Tschuprow's T（默认值）或 Cramér's V 对候选分组进行排序，并遵循你的 min_freq 和 max_n_mod 设置。
• 从设计上保证稳健 — 每个候选分组都必须通过留出的开发集（以及可选的 CV 折）验证，否则就会被否决；这一过程在 fit 时完成，而不是等到监控阶段。
• 定义 → 分箱 → 建模 — 声明你的 Features，对分箱器执行 fit，再调用 transform：整个特征集只需一次有监督处理即可完成分箱，无需为每个特征单独创建一个 notebook。针对每种目标类型使用一个分箱器：BinaryCarver、MulticlassCarver、OrdinalCarver、ContinuousCarver（回归），且 API 完全相同。
• AI 辅助 — 本地 MCP 服务可让你的大模型助手通过工具调用筛选并分箱列，全程在你的计算机上运行。

在 Titanic 快速入门示例中，Fare 从分箱前的 72 个取值合并为 2 个箱，同时与生存情况的关联度提高：Tschuprow's T 从原始值 0.18 升至分箱后的 0.29。

适用于信用评分、欺诈检测和风险建模。

🆕 最新动态

📊 交叉验证稳健性。 fit 现在支持 cv 参数，可在开发集之外（或替代开发集）提供额外的留出稳健性视图： carver.fit(X, y, cv=5)。接受整数、任意 scikit-learn 划分器或显式索引对，并通过 sklearn.model_selection.check_cv 解析——各折会否决过拟合组合，但绝不会重新排序（排名仍以完整训练集为基准）。请参阅交叉验证折。

🤖 LLM 与 MCP 集成。 AutoCarver 现在内置本地 Model Context Protocol 服务：让支持 MCP 的助手（VS Code Copilot、Claude Desktop、Cursor，……）读取数据文件，然后通过工具调用来判定列的类型，并针对目标变量对其进行分箱。该服务完全在你的计算机上运行——你的数据集绝不会发送给 AutoCarver 或任何外部服务（只有你自己的 LLM 提供商能看到助手分享的内容）。分箱质量取决于 LLM，因此在投入生产使用前，请让人工确认特征定义。请参阅 LLM 与 MCP 指南。

pip install "autocarver[mcp]"

完成配置后，只需向助手提出：

判定 titanic.csv 中各列的类型，并针对 Survived 对其进行分箱。

助手会推断特征类型、提出分箱方案，并返回汇总表——无需手动编写代码。

{
  "servers": {
    "autocarver": {
      "command": "python",
      "args": ["-m", "AutoCarver.mcp"]
    }
  }
}

{
  "servers": {
    "autocarver": {
      "command": "uv",
      "args": ["run", "python", "-m", "AutoCarver.mcp"]
    }
  }
}

安装

pip install autocarver

快速开始

你已经有了一个 DataFrame 和一个目标变量——开始之前，第一项就已完成：

• 加载数据
• 划分训练集 / 开发集
• 按类型声明特征
• 拟合 carver，并在开发集上验证
• 检查分箱结果
• 持久化

接下来只需使用下方代码片段——在 Titanic 数据集上进行二分类：

from pathlib import Path

import pandas as pd
from sklearn.model_selection import train_test_split

from AutoCarver import BinaryCarver, Features

# 1. Load data
url = "https://web.stanford.edu/class/archive/cs/cs109/cs109.1166/stuff/titanic.csv"
data = pd.read_csv(url)
target = "Survived"

# 2. Train / dev split, stratified on the target
train, dev = train_test_split(data, test_size=0.33, random_state=42, stratify=data[target])

# 3. Declare features by type
features = Features(
    categoricals=["Sex"],
    numericals=["Age", "Fare", "Siblings/Spouses Aboard", "Parents/Children Aboard"],
    ordinals={"Pclass": ["1", "2", "3"]},
)

# 4. Fit the carver (dev set drives the robustness checks)
carver = BinaryCarver(features=features)
train_processed = carver.fit_transform(train, train[target], X_dev=dev, y_dev=dev[target])
dev_processed = carver.transform(dev)

# 5. Inspect the carved buckets, target rate, and association
carver.summary

# 6. Persist for later use
carver.save(Path("titanic_carver.json"))

# 7. Load the carver back in
carver = BinaryCarver.load(Path("titanic_carver.json"))
dev_processed = carver.transform(dev)

min_freq 和 max_n_mod 是入门时唯一需要关注的两个参数——默认值（0.02 / 5）体现了常见的评分实践，而所有行为开关都集中在一个 ProcessingConfig 对象中。查看、调整，然后继续。

多分类任务可使用 MulticlassCarver（针对完整的 K 类目标，每个特征进行一次分箱），也可使用 OneVsRestCarver，为每个类别分别进行分箱；有序目标可使用 OrdinalCarver；回归任务可使用 ContinuousCarver——API 完全相同。若要根据目标关联度和特征间冗余进行特征预选，可将分箱后的输出传入 ClassificationSelector 或 RegressionSelector，并设置 features=carver.features（carver 会对自己的副本进行分箱，因此原始 features 会保持不变）。

你将获得什么

在下次模型评审前，值得回答两个问题：你能否向利益相关方说明当前模型的每个分箱边界是如何确定的？你能否证明每个边界在模型从未见过的数据上依然成立？AutoCarver 让这两件事都只需一行代码：

• 选择最佳分组，而非第一个可接受的分组——候选分组按 Tschuprow's T（默认）或 Cramér's V 排序，并保留在开发集上表现最佳的分组，因此不会停留在第一个看起来还不错的分组上。

• 在上线前避免悄然过拟合——只在训练样本中存在的分箱会在数据漂移下悄然退化。每种候选组合都会在开发集（以及可选的 CV 折）上验证：任何目标率发生反转或分桶低于 min_freq 的候选组合，都会在拟合时被拒绝，而不是等到监控时才被发现。

• 一等序数特征支持——OrdinalDiscretizer 会遵循你声明的类别顺序，因此代表性不足的类别会与最近的相邻类别合并，而不是按频率合并。

• 由你担任最终审核者——carver.features.summary 和 carver.features.history 会显示分箱定义、每个分箱的目标率／频率以及完整的分箱过程；如果你不同意某个边界，可以覆盖它，而 transform 会像应用其他分箱一样应用你的修改：

  feature = carver.features("Siblings/Spouses Aboard")  # any carved feature; labels are [0, 1, 2]
  feature.group([1], 2)  # merge two bins you consider equivalent
  

• 可解释的分桶——边界易于理解，便于审核、记录并用于评分卡。

• 降维——合并代表性不足的类别，并限制每个特征的分箱数（max_n_mod），在独热编码前尤其有用。

• 特征预筛选——ClassificationSelector／RegressionSelector 按特征与目标的关联程度排序，并根据特征间相关性进行筛选。

Titanic 数据集中的 Age，一次 BinaryCarver.fit 调用：将 84 个原始取值合并为 3 个分桶，生存率呈单调变化。

对比如何？

这三个库都兼容 sklearn 的 Pipeline；AutoCarver 还支持 JSON 往返持久化（carver.save("...json")）。AutoCarver（ClassificationSelector、RegressionSelector）和 optbinning（BinningProcess(selection_criteria=...)）都提供特征预筛选。完整的特征矩阵、并排的可运行代码片段，以及“如何选择”的指南，请参阅对比页面。

文档

完整参考资料、教程和端到端笔记本示例请见 ReadTheDocs。