AI 应用机器学习模型优化【免费下载链接】coremltoolsCore ML tools contain supporting tools for Core ML model conversion, editing, and validation.项目地址https://gitcode.com/gh_mirrors/co/coremltools点击查看免费下载导读本文围绕 coremltools 提供的 XGBoost 专用转换器讲解如何把训练好的 XGBoost 模型含Booster、XGBRegressor、XGBClassifier及 JSON dump 文件转换为 Core ML 格式.mlmodel并落盘保存。文章以官方文档 docs-guides/source/xgboost-conversion.md 为主线结合仓库内转换器源码、树集成构建器与测试用例完整展开ct.converters.xgboost.convert()的全部参数、分类/回归两种模式的行为差异、底层 JSON 解析与 protobuf 生成机制。读完本文你将能独立完成从 XGBoost 训练产物到可部署 Core ML 模型的端到端转换并具备排查转换异常的能力。一、XGBoost 转换器定位经典模型转换的独立入口coremltools 的转换体系分为两类统一转换 APIct.convert()面向神经网络模型支持 TensorFlow 1.x / 2.x、PyTorchTorchScript、Torch Exported等来源见 统一转换 API 说明经典模型独立转换器面向树模型等传统机器学习模型包括 LibSVM、Scikit-learn 与XGBoost。XGBoost 转换器位于coremltools.converters.xgboost模块入口函数为ct.converters.xgboost.convert()。该模块不经过 MIL 中间表示而是直接把 XGBoost 树结构解析为 Core ML 的TreeEnsembleprotobuf 规格因此输出的是传统的treeEnsembleRegressor/treeEnsembleClassifier模型类型旧版.mlmodel格式。从 coremltools/converters/init.py 可以看到libsvm、lightgbm、sklearn、xgboost四个经典转换器与统一入口_converters_entry.convert一同被导出而 coremltools/converters/_converters_entry.py 中的ct.convert()仅处理 TF/PyTorch 模型不接收 XGBoost 对象——因此 XGBoost 转换必须使用ct.converters.xgboost.convert()这一专门入口。二、最小转换示例文档中的核心代码官方文档 xgboost-conversion.md 给出了最小可用流程全文以这两步为骨架# Convert it with default input and output names import coremltools as ct coreml_model ct.converters.xgboost.convert(model) # Saving the Core ML model to a file. coreml_model.save(my_model.mlmodel)这里model是已经训练完成的 XGBoost 模型对象xgboost.Booster、xgboost.XGBRegressor或xgboost.XGBClassifier。convert()返回一个coremltools.models.MLModel实例可直接调用.save()保存为.mlmodel文件供 Xcode、Core ML 框架加载部署。注意省略参数时使用默认配置——默认以regressor模式转换、输出名称为target、内部使用 32 位浮点若模型本身没有特征名见下文 feature_names 说明省略参数会直接报错。三、convert() 完整参数解析在 coremltools/converters/xgboost/_tree.py 中定义了转换函数签名def convert( model, feature_namesNone, targettarget, force_32bit_floatTrue, moderegressor, class_labelsNone, n_classesNone, ):各参数含义与行为如下参数类型默认值说明modelBooster/XGBRegressor/XGBClassifier/str必填已训练的 XGBoost 模型对象或磁盘上 XGBoost JSON dump 文件路径feature_nameslist[str]或strNone暴露给 Core ML 模型的输入特征名None表示使用模型自带特征名targetstrtargetCore ML 模型输出特征的名称force_32bit_floatboolTrue为True时内部阈值与叶子值强制按 32 位浮点处理modestrregressorregressor或classifier决定生成回归还是分类树集成class_labelslist[int]或NoneNone分类标签列表为None时使用0到n_classes-1的整数序列n_classesint或NoneNone分类类别数为None时从模型或class_labels推断3.1 feature_names特征名来源与缺失时的行为feature_names的取值规则源码 coremltools/converters/xgboost/_tree_ensemble.pyNone使用模型自身保存的feature_names显式列表按列表顺序对应 XGBoost 的特征顺序同时会把名字写回模型对象model.feature_names feature_names供后续 dump 解析时建立「特征名 → 特征索引」映射见feature_map {f: i for i, f in enumerate(model.feature_names)}。两个容易踩坑的边界情况模型无特征名且未传参当feature_names is None且model.feature_names is None时直接抛出ValueError: The XGBoost model does not have feature names. They must be provided in convert method.——训练时建议通过DMatrix(..., feature_names[...])显式指定特征名。从文件路径转换时必须传特征名若model是 JSON 文件路径feature_names不能为None否则抛出ValueError: feature names must be provided in convert method if the model is a path on file system.源码 coremltools/converters/xgboost/_tree_ensemble.py。因为 JSON dump 本身只含「特征名 → 分割特征」字符串需要外部列表才能还原索引。另外转换器内置了_booster_feature_names_workaround源码 coremltools/converters/xgboost/_tree_ensemble.py用于规避 XGBoost 旧版本get_dump(dump_formatjson)生成畸形 JSON dump 的问题它会先校验传入的特征名与模型内置特征名一致用np.testing.assert_array_equal断言再通过model.copy()/deepcopy复制一份并清空feature_names避免污染原始模型对象。这也是仓库测试 test_boosted_trees_classifier.py 与 test_boosted_trees_regression.py 中「特征名含制表符、引号、换行等特殊字符仍可成功转换」的原因。3.2 target输出特征命名target指定 Core ML 模型预测输出回归值或预测类别的名称默认target。测试用例中普遍以target或自定义名称如output_name作为输出名并断言spec.description.predictedFeatureName output_name见 test_boosted_trees_regression.py。分类模式下除了predictedFeatureName指向的类别输出还会附带一个默认名为classProbability的类别概率字典输出。3.3 force_32bit_float浮点精度与数值一致性XGBoost 内部以 float32 存储分割阈值和叶子值但从 JSON dump 解析出来时被读成 64 位 double。为让 Core ML 树集成编译器正确识别 float32 并保持与 XGBoost 推理一致的数值行为转换器在force_32bit_floatTrue时做显式回退# 分支节点分割阈值 feature_value float(_np.float32(feature_value)) # 叶子节点值 value float(_np.float32(value))对应源码注释位于 coremltools/converters/xgboost/_tree_ensemble.py 与 coremltools/converters/xgboost/_tree_ensemble.py。不建议关闭该选项否则转换出的模型可能在边界样本上与原始 XGBoost 预测出现微小数值差异。3.4 moderegressor 与 classifier 的行为差异mode决定树集成构建器的选择源码校验逻辑coremltools/converters/xgboost/_tree_ensemble.pyaccepted_modes [regressor, classifier] if mode not in accepted_modes: raise ValueError(mode should be in %s % accepted_modes)回归模式默认使用TreeEnsembleRegressor(feature_names, target)默认预测值设为0.5set_default_prediction_value(0.5)所有叶子激活值在此基础上累加对应源码 coremltools/converters/xgboost/_tree_ensemble.py输出单一doubleType回归值。分类模式使用TreeEnsembleClassifier(feature_names, class_labels, target)二分类默认预测值[0.0]后处理变换为Regression_Logistic即对累加分数施加逻辑斯蒂变换(1 e^{-v})^{-1}多分类默认预测值[0.0] * n_classes后处理变换为Classification_SoftMax即对各类别分数施加 softmax 得到归一化概率对应源码 coremltools/converters/xgboost/_tree_ensemble.py 与后处理变换定义 coremltools/models/tree_ensemble.py。多分类时还会有一个关键细节tree_index xgb_tree_id % n_classes源码 coremltools/converters/xgboost/_tree_ensemble.py即第i棵树的叶子值只写入对应类别维度的索引这与 XGBoost 多分类「每类一组树」的组织方式一致而叶子值写入时也做了value {tree_index: value}的多维映射coremltools/converters/xgboost/_tree_ensemble.py。3.5 class_labels 与 n_classes类别配置仅在modeclassifier时生效传入XGBClassifier时n_classes自动取自model.n_classes_若同时给了class_labels其长度必须等于n_classes_否则抛ValueErrorclass_labelsNone时退化为list(range(n_classes))源码 coremltools/converters/xgboost/_tree_ensemble.py传入Booster如xgboost.train()的产物时二者至少提供其一都未提供则抛ValueError: You must provide class_labels or n_classes when not providing the XGBClassifier只给class_labels时n_classes len(class_labels)只给n_classes时class_labels range(n_classes)源码 coremltools/converters/xgboost/_tree_ensemble.py。仓库测试 test_boosted_trees_classifier.py 演示了用xgboost.train({}, dtrain)训练原始 Booster 后以modeclassifier, n_classesself.n_classes完成多分类转换的完整做法。四、支持的模型对象与 JSON 文件输入convert()的model参数支持三种输入类型检查见 coremltools/converters/xgboost/_tree_ensemble.py输入类型转换路径说明xgboost.core.Boosterget_dump(with_statsTrue, dump_formatjson)底层 Boosterxgboost.train()直接产物xgboost.XGBRegressor先校验 objective再get_booster()/booster()sklearn 风格回归封装xgboost.XGBClassifier取n_classes_再get_booster()sklearn 风格分类封装strJSON 文件路径直接json.load(f)需同时提供feature_names且文件不存在时抛TypeError: Invalid path4.1 XGBRegressor 的 objective 限制转换XGBRegressor时会检查其objective源码 coremltools/converters/xgboost/_tree_ensemble.pyif objective in [reg:gamma, reg:tweedie]: raise ValueError(Regression objective %s not supported for export. % objective)reg:gammaGamma 回归与reg:tweedieTweedie 回归的叶子输出无法用 Core ML TreeEnsemble 的加法语义表达因此被明确拒绝。仓库测试 test_boosted_trees_regression.py 专门验证了这两种 objective 会抛出ValueError。常见的reg:squarederror、reg:logistic等则不受影响。4.2 模型/模式匹配校验转换器对模型类型与mode的匹配做严格校验XGBRegressormodeclassifier→ValueError: mode is classifier but provided a regressorXGBClassifiermoderegressor→ValueError: mode is regressor but provided a classifier传入其他类型如 sklearn 的GradientBoostingRegressor、OneHotEncoder→TypeError: Unexpected type. Expecting XGBoost model.。这些边界在 test_boosted_trees_classifier.py 与 test_boosted_trees_regression.py 中均有覆盖。4.3 从 JSON 文件转换测试 test_boosted_trees_classifier.py 展示了从文件转换的标准做法xgb_model_json tempfile.NamedTemporaryFile(xgb_tree_model_classifier.json).name xgb_json_out self.xgb_model.get_dump(with_statsTrue, dump_formatjson) with open(xgb_model_json, w) as f: json.dump(xgb_json_out, f) spec xgb_converter.convert( xgb_model_json, feature_names, output_name, modeclassifier, n_classesself.n_classes, ).get_spec()注意json.dump时不要启用dump_format之外的参数文件中应保存get_dump(dump_formatjson)返回的列表结构每棵树一个 JSON 对象且必须通过feature_names显式提供特征名。五、底层原理从 JSON dump 到 TreeEnsemble protobuf整个转换不经过 MIL 中间表示核心是把 XGBoost 的 JSON dump 逐树递归翻译成 Core ML TreeEnsemble 规格5.1 调用链总览ct.converters.xgboost.convert(model, ...) └─ _tree.convert() # 参数包装、MLModel 封装 └─ _tree_ensemble.convert_tree_ensemble() ├─ 类型归一化Booster / sklearn wrapper → get_booster ├─ feature_names 校验与 workaround ├─ model.get_dump(with_statsTrue, dump_formatjson) ├─ TreeEnsembleRegressor / TreeEnsembleClassifier 构建器 │ └─ 设置默认预测值、后处理变换 └─ 逐树 recurse_json() # 递归解析分支/叶子节点 └─ mlkit_tree.add_branch_node() / add_leaf_node() └─ ct.models.MLModel(spec) # 包装成 MLModel └─ 写入 coremltools / xgboost 版本元数据convert()在 coremltools/converters/xgboost/_tree.py 中把convert_tree_ensemble()返回的 protobuf spec 包进ct.models.MLModel(...)并写入两条 user-defined 元数据coremltools版本与xgboostversion来源标记便于追溯模型生成环境。5.2 recurse_json递归翻译规则recurse_json源码 coremltools/converters/xgboost/_tree_ensemble.py逐节点处理 XGBoost JSON 树分支节点无leaf键提取split特征名经feature_map转成整数索引、split_condition分割阈值、yes/no真假子树节点 id分支模式固定为BranchOnValueLessThan小于阈值走 true 分支missing与yes相等时设置missing_value_tracks_true_childTrue从而正确保留 XGBoost 的缺失值默认路径语义叶子节点含leaf键取leaf数值按force_32bit_float做 float32 回退多分类模式下再映射到对应类别索引维度若有cover字段调用get_dump(with_statsTrue)才包含会作为relative_hit_rate写入节点可用于可视化/权重分析随后递归遍历children以child[nodeid]作为下一层节点 id。5.3 树集成构建器TreeEnsembleRegressor/TreeEnsembleClassifier定义在 coremltools/models/tree_ensemble.pyset_default_prediction_value(values)写入basePredictionValue作为所有叶子累加的基准值回归默认0.5分类默认0.0系列set_post_evaluation_transform(value)设置postEvaluationTransform二分类用Regression_Logistic、多分类用Classification_SoftMaxadd_branch_node(tree_id, node_id, feature_index, feature_value, branch_mode, true_child_id, false_child_id, ...)与add_leaf_node(tree_id, node_id, value, ...)逐节点填充TreeEnsemble_pb2规格。最终mlkit_tree.spec即Model_pb2.Model的 protobuf 表示由convert_tree_ensemble返回后交给MLModel封装。六、实战从训练到部署的完整流程综合文档示例与仓库测试模式推荐一个可复制的完整流程import xgboost import coremltools as ct # 1. 训练 XGBoost 模型务必显式设置特征名 dtrain xgboost.DMatrix(X_train, labely_train, feature_namesfeature_names) model xgboost.train(params, dtrain) # 2. 转换为 Core ML 分类模型Booster 需给出类别数 coreml_model ct.converters.xgboost.convert( model, feature_namesfeature_names, targettarget, modeclassifier, n_classesnum_classes, ) # 3. 保存并加载验证 coreml_model.save(my_model.mlmodel) loaded ct.models.MLModel(my_model.mlmodel) preds loaded.predict({name: X_test[:, i] for i, name in enumerate(feature_names)})要点回顾转换前检查 xgboost 已安装——_HAS_XGBOOST为False时调用会抛RuntimeError: xgboost not found. xgboost conversion API is disabled.源码 coremltools/converters/xgboost/_tree_ensemble.py依赖探测在 coremltools/_deps/init.py特征名缺失时显式传入feature_names且顺序必须与训练时一致分类任务优先直接传XGBClassifier自动带出n_classes_或用Boostern_classes数值精度对比验证可参考仓库数值测试 test_boosted_trees_classifier_numeric.py转换后模型对训练集样本预测的概率与原始 XGBoostpredict_proba的max_probability_error 1e-3可作为转换正确性的验收标准部署端加载.mlmodel时输入为doubleType标量特征见测试对spec.description.input的断言预测时需按特征名传入字典。七、更多资料官方文档入口XGBoost 转换指南、转换器 API 参考转换器源码coremltools/converters/xgboost/_tree.py、coremltools/converters/xgboost/_tree_ensemble.py树集成构建器coremltools/models/tree_ensemble.py测试用例test_boosted_trees_classifier.py、test_boosted_trees_regression.py、test_boosted_trees_classifier_numeric.py依赖探测逻辑coremltools/_deps/init.py赞分享AI 应用机器学习模型优化【免费下载链接】coremltoolsCore ML tools contain supporting tools for Core ML model conversion, editing, and validation.项目地址https://gitcode.com/gh_mirrors/co/coremltools点击查看免费下载相关推荐coremltools LibSVM 模型转换指南convert() 用法、参数详解与源码级原理coremltools LibSVM 模型转换指南convert 用法、参数详解与源码级原理 本文以 coremltools 仓库中的 libsvm convAI 应用机器学习模型优化coremltools 将 XGBoost 模型转换为 Core MLconvert() API 完整实战指南coremltools 将 XGBoost 模型转换为 Core MLconvert API 完整实战指南 导读 本文以 coremltools 仓库中 XAI 应用机器学习模型优化coremltools 模型转换将模型转换为 ML Program 的完整指南coremltools 模型转换将模型转换为 ML Program 的完整指南 ML Program mlprogram 是 Core ML 自第一版神经AI 应用机器学习模型优化上一篇如何用Kimi K2构建自动代码修复工具SWE-bench Verified实战下一篇3步实现LaMa模型评估全自动化从脚本到批量处理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考