MLflow PySpark ML 自动日志Autologging完整指南从mlflow.pyspark.ml.autolog到模型追踪实践【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflowMLflow 的mlflow.pyspark.ml模块是面向 Apache Spark MLlib 的自动日志集成它让你在调用Estimator.fit()训练 Spark ML 模型时无需手写任何追踪代码即可自动记录参数、指标、标签、数据集信息、模型工件与签名。本文以该模块的公开 API 文档为主线结合仓库源码mlflow/pyspark/ml/init.py、mlflow/pyspark/ml/_autolog.py与测试用例tests/spark/autologging/ml/test_pyspark_ml_autologging.py完整讲解其能力边界、配置参数、元估计器处理机制与最佳实践帮助你直接在 Spark 训练管道中接入 MLflow。模块定位与文档背景在 MLflow 的 API 参考体系中mlflow.pyspark.ml.rst 是一个基于 Sphinxautomodule指令的自动生成页面它声明.. automodule:: mlflow.pyspark.ml :members: :undoc-members: :show-inheritance:这意味着该文档页面的全部 API 内容都由mlflow.pyspark.ml模块源码实时提取核心入口就是autolog()函数。该模块位于mlflow/pyspark/ml/__init__.py注册的集成名称为pyspark.ml见 mlflow/pyspark/ml/init.py#L58并且mlflow.pyspark包通过from mlflow.pyspark import ml对外暴露见 mlflow/pyspark/init.py。此外模块还附带两个内部辅助文件负责特征列推断的 mlflow/pyspark/ml/_autolog.py以及内置模型白名单 mlflow/pyspark/ml/log_model_allowlist.txt。需要特别注意的是mlflow.pyspark.ml与mlflow.spark是两个不同层次的集成。mlflow.spark提供的是底层的mlflow.spark.log_model()/load_model()/autolog()等通用 Spark 模型接口mlflow.spark.autolog()目前为无操作占位而mlflow.pyspark.ml专为 PySpark ML 库的 Estimator 训练流程设计自动记录训练全生命周期信息。核心 APIautolog()完整参数详解mlflow.pyspark.ml.autolog()是模块对外唯一的公开 API签名见 mlflow/pyspark/ml/init.py#L802-L815autolog( log_modelsTrue, log_datasetsTrue, disableFalse, exclusiveFalse, disable_for_unsupported_versionsFalse, silentFalse, log_post_training_metricsTrue, registered_model_nameNone, log_input_examplesFalse, log_model_signaturesTrue, log_model_allowlistNone, extra_tagsNone, )各参数的语义与源码实现依据如下参数默认值作用源码依据log_modelsTrue训练出的模型若在白名单内则通过mlflow.spark.log_model()记录为 MLflow Model 工件False则只记录元数据init.py#L1067-L1119log_datasetsTrue将训练/评估数据集信息SparkDataset记录到 Trackinginit.py#L1012-L1024、#L1214-L1234disableFalseTrue时关闭该集成False时启用init.py#L803exclusiveFalseTrue时自动日志内容不写入用户创建的 fluent runFalse时写入当前活跃 runinit.py#L921-L923disable_for_unsupported_versionsFalseTrue时对未经测试或不兼容的 PySpark 版本禁用自动日志init.py#L924-L926silentFalseTrue时抑制 MLflow 在自动日志期间的事件日志与警告init.py#L927-L929log_post_training_metricsTrue捕获训练后调用Evaluator.evaluate的结果并写入模型关联的 runinit.py#L1248-L1262registered_model_nameNone指定时每次训练完成都会将模型注册为该名称的新版本不存在则创建init.py#L933-L935log_input_examplesFalse从训练集采集输入样例随模型工件一起记录init.py#L936-L938log_model_signaturesTrue记录模型输入/输出签名输入输出含非标量类型如pyspark.ml.linalg.Vector时签名不记录init.py#L939-L949log_model_allowlistNone覆盖内置模型白名单优先级高于 Spark 配置项init.py#L951-L953extra_tagsNone字典形式的额外标签设置到自动日志创建的每个托管 run 上init.py#L959该 API 要求Spark 3.0 及以上版本且非线程安全。测试用例中大量使用了mlflow.pyspark.ml.autolog()的各个参数组合例如autolog(extra_tags{test_tag: spark_autolog})见 test_pyspark_ml_autologging.py#L263、autolog(registered_model_name...)见 test_pyspark_ml_autologging.py#L1037等可作为参数用法的直接参考。自动日志记录的内容清单调用autolog()后当你执行Estimator.fit()pyspark.ml.feature下的特征器除外时MLflow 会自动记录以下内容参数Parameters通过estimator.params获取的全部参数若某个参数值本身也是 Estimator则嵌套 Estimator 的参数也会被记录嵌套参数键格式为{estimator_uid}.{param_name}。实现上由_get_instance_param_map()递归展开参数树init.py#L342-L391Pipeline 的stages会被展开为各阶段名称列表并递归记录各阶段参数CrossValidator/TrainValidationSplit的estimator与estimatorParamMaps会特殊处理后者以 JSON 工件形式保存其余Params类型参数值同样递归展开。参数记录通过_log_estimator_params()分块提交并对超长键/值做截断处理MAX_ENTITY_KEY_LENGTH、MAX_PARAM_VAL_LENGTH见init.py#L523-L528。标签TagsEstimator 类名如LinearRegression。全限定类名如pyspark.ml.regression.LinearRegression由_get_estimator_info_tags()生成init.py#L180-L189。训练后指标Post-training Metrics当训练完成后你调用任意 PySpark ML Evaluator 的evaluate()时MLflow 会把评估结果记录到与该模型关联的 run 中。指标键格式为{metric_name}[-{call_index}]_{dataset_name}metric_name来自Evaluator.getMetricName()同一指标被多次调用时从第 2 次起追加call_indexdataset_name取调用model.transform(dataset)时外层调用帧中数据集变量的名字若数据集是未命名中间表达式则记为unknown_dataset若多个数据集变量同名则从第 2 个起追加索引。这套机制的底层实现在_AutologgingMetricsManagerinit.py#L530-L745它维护预测结果对象 id → (数据集名, run_id)映射、评估数据集信息与评估器调用信息并通过weakref.finalize在预测结果对象被 GC 后清理 id避免 id 复用导致错误关联。三个 patch 点patched_fit/patched_transform/patched_evaluateinit.py#L1154-L1237构成了完整的「训练登记模型 → 预测登记结果 → 评估回填指标」链路。已知限制MLflow 无法为「对预测结果做进一步变换得到的派生对象」找到对应 run 信息。工件Artifacts一个带mlflow.sparkflavor 的 MLflow Model内含训练好的模型由mlflow.spark.log_model()记录。大模型可能因性能与存储空间考量不被自动记录。训练后指标调用相关的metric_info.json工件键为指标名值为对应评估器信息评估器类名与参数见log_post_training_metric()init.py#L723-L740。若模型属于CrossValidatorModel/TrainValidationSplitModel还会额外记录best_model工件init.py#L1120-L1124。元估计器Meta-estimator的处理机制当Pipeline、CrossValidator、TrainValidationSplit、OneVsRest等元估计器调用fit()时其内部对子估计器发起的fit()调用不会被重复记录——自动日志只在最外层fit()记录一次。这是通过_SparkTrainingSession会话隔离实现的见patched_fit中的with _SparkTrainingSession(estimatorself, allow_childrenFalse)init.py#L1159。元估计器场景下会额外记录一个estimator_info.json工件其hierarchy条目描述整个估计器的层次结构展开包含所有嵌套阶段如嵌套 Pipeline 的 stages。层级生成逻辑在_gen_stage_hierarchy_recursively()init.py#L255-L289中实现Pipeline →{name: ..., stages: [...]}OneVsRest →{name: ..., classifier: {...}}参数搜索估计器 →{name: ..., evaluator: {...}, tuned_estimator: {...}}含Params类型参数 →{name: ..., params: {...}}命名规则_get_uid_to_indexed_name_mapinit.py#L242-L252某类实例只出现一次时用类名出现多次时按深度优先遍历顺序追加_index后缀。参数搜索Parameter Search的专项记录对CrossValidator和TrainValidationSplit这类参数搜索元估计器自动日志除常规信息外还提供子 runchild runs为每组被探索的参数组合创建子 run记录该组参数与对应指标并通过mlflow.parent_run_id标签关联父 run_create_child_runs_for_parameter_searchinit.py#L394-L444。estimator_info.json扩展字段除hierarchy外还包含tuning_parameter_map_list调参使用的全部参数映射列表与tuned_estimator_parameter_map被调优估计器的参数映射两个条目。best_parameters.json记录搜索到的最优参数组合同时以best_{param_name}前缀的参数形式写入 runinit.py#L1057-L1065。search_results.csv包含params与metric两列的搜索结果表_log_parameter_search_results_as_artifactinit.py#L447-L462。其中指标来源在_get_param_search_metrics_and_best_index()init.py#L489-L520中区分CrossValidatorModel提供avg_{metric}与若存在std_{metric}TrainValidationSplitModel提供validationMetrics对应的{metric}。最优组合按评估器isLargerBetter()语义取 argmax/argmin。另外若以参数列表形式调用fit(params_list)即走fitMultiple路径自动日志会被跳过并给出警告_get_warning_msg_for_fit_call_with_a_list_of_paramsinit.py#L465-L471需改为对每个参数映射单独调用fit。模型白名单Allowlist机制log_modelsTrue时只有白名单内的模型才会被自动记录。判断逻辑见_should_log_model()init.py#L148-L177先精确匹配全限定类名也支持末尾单个*通配符的前缀匹配对OneVsRestModel检查其内部models[0]对PipelineModel要求所有Model类型的 stage 都通过白名单对参数搜索模型检查bestModel其余模型递归检查参数中嵌套的Model。内置白名单文件为 mlflow/pyspark/ml/log_model_allowlist.txt按分类列出分类LinearSVCModel、DecisionTreeClassificationModel、GBTClassificationModel、LogisticRegressionModel、RandomForestClassificationModel、NaiveBayesModel聚类BisectingKMeansModel、KMeansModel、GaussianMixtureModel回归AFTSurvivalRegressionModel、DecisionTreeRegressionModel、GBTRegressionModel、GeneralizedLinearRegressionModel、LinearRegressionModel、RandomForestRegressionModel特征化模型BucketedRandomProjectionLSHModel、ChiSqSelectorModel、CountVectorizerModel、IDFModel、ImputerModel、MaxAbsScalerModel、MinHashLSHModel、MinMaxScalerModel、OneHotEncoderModel、RobustScalerModel、RFormulaModel、StandardScalerModel、StringIndexerModel、VarianceThresholdSelectorModel、VectorIndexerModel、UnivariateFeatureSelectorModel复合/管道/调参模型OneVsRestModel、PipelineModel、CrossValidatorModel、TrainValidationSplitModelSynapseML 系列synapse.ml.cognitive.*、synapse.ml.exploratory.*、synapse.ml.featurize.*、synapse.ml.geospatial.*、synapse.ml.image.*、synapse.ml.io.*、synapse.ml.isolationforest.*、synapse.ml.lightgbm.*、synapse.ml.nn.*、synapse.ml.opencv.*、synapse.ml.stages.*、synapse.ml.vw.*内置白名单刻意排除了一些体积可能很大的模型例如 ALS 模型。自定义白名单的三种方式Spark 配置项在调用autolog()前初始化 SparkSession并设置spark.mlflow.pysparkml.autolog.logModelAllowlistFile指向一个换行分隔的全限定类名列表文件。读取逻辑见_read_log_model_allowlist()init.py#L94-L131若读取自定义文件失败会自动回退到内置白名单。log_model_allowlist参数直接传入可迭代对象覆盖默认白名单其优先级高于Spark 配置项init.py#L968-L971。白名单文件支持本地路径file://或无 scheme与远程 HTTP(S) 地址见_read_log_model_allowlist_from_file()init.py#L61-L91。未被白名单收录的模型会输出提示警告_get_warning_msg_for_skip_log_modelinit.py#L138-L145此时可显式调用mlflow.spark.log_model()记录。自定义白名单的完整用法可参考测试 tests/spark/autologging/ml/test_pyspark_ml_autologging_custom_allowlist.py。输入样例与模型签名输入样例log_input_examplesTrue时从训练集选取少量行INPUT_EXAMPLE_SAMPLE_ROWS作为输入样例。实现上先用get_feature_cols()mlflow/pyspark/ml/_autolog.py#L67-L96通过「逐个删除列再 transform 单行缓存子集、捕捉IllegalArgumentException」的方式推断特征列再经cast_spark_df_with_vector_to_array()mlflow/pyspark/ml/_autolog.py#L17-L35将向量列转为arraydouble后转成 Pandas DataFrame。模型签名log_model_signaturesTrue时通过_infer_spark_model_signature()init.py#L781-L799对空输入 DataFrame 执行 transform 推断输出 schema并保证默认预测列存在。限制目前仅支持标量 Spark 数据类型输入或输出含pyspark.ml.linalg.Vector等非标量类型时签名不会被记录源码中会打印警告见init.py#L1083-L1089。由于签名推断过程会修改模型例如设置输出列源码在推断前先spark_model.copy()复制模型以保留原对象init.py#L1091-L1098。自动日志的适用范围与跳过逻辑patched_fit对以下情况明确跳过自动日志直接对pyspark.ml.feature下的特征器调用fit()init.py#L1132-L1134但特征器作为 Pipeline 阶段被训练时仍会记录。以 list/tuple 形式的参数列表调用fit()即fitMultiple返回模型迭代器的情况init.py#L1135-L1139。自动日志通过safe_patch以manage_runTrue模式 patchEstimator.fit训练输入 DataFrame 会先persist(StorageLevel.MEMORY_AND_DISK)再记录元数据完成后unpersist()init.py#L1143-L1150。端到端使用示例以下示例演示如何启用自动日志并训练一个带调参的 Pipelineimport mlflow from pyspark.ml import Pipeline from pyspark.ml.classification import LogisticRegression from pyspark.ml.evaluation import BinaryClassificationEvaluator from pyspark.ml.feature import VectorAssembler from pyspark.ml.tuning import CrossValidator, ParamGridBuilder spark ... # 已初始化的 SparkSession mlflow.pyspark.ml.autolog( log_modelsTrue, log_input_examplesTrue, log_model_signaturesTrue, log_post_training_metricsTrue, ) features VectorAssembler(inputCols[f1, f2], outputColfeatures) lr LogisticRegression(featuresColfeatures, labelCollabel) param_grid ( ParamGridBuilder() .addGrid(lr.regParam, [0.01, 0.1]) .addGrid(lr.maxIter, [10, 20]) .build() ) evaluator BinaryClassificationEvaluator(labelCollabel) cv CrossValidator( estimatorlr, estimatorParamMapsparam_grid, evaluatorevaluator, numFolds3 ) with mlflow.start_run() as run: pipeline Pipeline(stages[features, cv]) pipeline_model pipeline.fit(train_df) # 训练后评估结果会自动写入关联 run metrics evaluator.evaluate(pipeline_model.transform(test_df))训练完成后你会在 run 下看到estimator_info.json含 hierarchy、tuning_parameter_map_list、best_parameters.json、search_results.csv、metric_info.json训练后指标、model与best_model工件、每个参数组合对应的子 run以及数据集、参数、标签和训练后指标。总结mlflow.pyspark.ml.autolog()为 PySpark ML 训练流程提供了零侵入的端到端追踪能力单次调用即可覆盖参数、标签、数据集、模型工件、签名、输入样例、元估计器层级与参数搜索全过程并通过可自定义的白名单机制灵活控制模型记录范围。其log_post_training_metrics机制patchModel.transform与Evaluator.evaluate更是将训练与评估阶段无缝衔接适合在 Spark 训练管道中作为标准的 MLflow 接入方式。【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MLflow PySpark ML 自动日志（Autologging）完整指南：从 `mlflow.pyspark.ml.autolog` 到模型追踪实践
MLflow PySpark ML 自动日志Autologging完整指南从mlflow.pyspark.ml.autolog到模型追踪实践【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflowMLflow 的mlflow.pyspark.ml模块是面向 Apache Spark MLlib 的自动日志集成它让你在调用Estimator.fit()训练 Spark ML 模型时无需手写任何追踪代码即可自动记录参数、指标、标签、数据集信息、模型工件与签名。本文以该模块的公开 API 文档为主线结合仓库源码mlflow/pyspark/ml/init.py、mlflow/pyspark/ml/_autolog.py与测试用例tests/spark/autologging/ml/test_pyspark_ml_autologging.py完整讲解其能力边界、配置参数、元估计器处理机制与最佳实践帮助你直接在 Spark 训练管道中接入 MLflow。模块定位与文档背景在 MLflow 的 API 参考体系中mlflow.pyspark.ml.rst 是一个基于 Sphinxautomodule指令的自动生成页面它声明.. automodule:: mlflow.pyspark.ml :members: :undoc-members: :show-inheritance:这意味着该文档页面的全部 API 内容都由mlflow.pyspark.ml模块源码实时提取核心入口就是autolog()函数。该模块位于mlflow/pyspark/ml/__init__.py注册的集成名称为pyspark.ml见 mlflow/pyspark/ml/init.py#L58并且mlflow.pyspark包通过from mlflow.pyspark import ml对外暴露见 mlflow/pyspark/init.py。此外模块还附带两个内部辅助文件负责特征列推断的 mlflow/pyspark/ml/_autolog.py以及内置模型白名单 mlflow/pyspark/ml/log_model_allowlist.txt。需要特别注意的是mlflow.pyspark.ml与mlflow.spark是两个不同层次的集成。mlflow.spark提供的是底层的mlflow.spark.log_model()/load_model()/autolog()等通用 Spark 模型接口mlflow.spark.autolog()目前为无操作占位而mlflow.pyspark.ml专为 PySpark ML 库的 Estimator 训练流程设计自动记录训练全生命周期信息。核心 APIautolog()完整参数详解mlflow.pyspark.ml.autolog()是模块对外唯一的公开 API签名见 mlflow/pyspark/ml/init.py#L802-L815autolog( log_modelsTrue, log_datasetsTrue, disableFalse, exclusiveFalse, disable_for_unsupported_versionsFalse, silentFalse, log_post_training_metricsTrue, registered_model_nameNone, log_input_examplesFalse, log_model_signaturesTrue, log_model_allowlistNone, extra_tagsNone, )各参数的语义与源码实现依据如下参数默认值作用源码依据log_modelsTrue训练出的模型若在白名单内则通过mlflow.spark.log_model()记录为 MLflow Model 工件False则只记录元数据init.py#L1067-L1119log_datasetsTrue将训练/评估数据集信息SparkDataset记录到 Trackinginit.py#L1012-L1024、#L1214-L1234disableFalseTrue时关闭该集成False时启用init.py#L803exclusiveFalseTrue时自动日志内容不写入用户创建的 fluent runFalse时写入当前活跃 runinit.py#L921-L923disable_for_unsupported_versionsFalseTrue时对未经测试或不兼容的 PySpark 版本禁用自动日志init.py#L924-L926silentFalseTrue时抑制 MLflow 在自动日志期间的事件日志与警告init.py#L927-L929log_post_training_metricsTrue捕获训练后调用Evaluator.evaluate的结果并写入模型关联的 runinit.py#L1248-L1262registered_model_nameNone指定时每次训练完成都会将模型注册为该名称的新版本不存在则创建init.py#L933-L935log_input_examplesFalse从训练集采集输入样例随模型工件一起记录init.py#L936-L938log_model_signaturesTrue记录模型输入/输出签名输入输出含非标量类型如pyspark.ml.linalg.Vector时签名不记录init.py#L939-L949log_model_allowlistNone覆盖内置模型白名单优先级高于 Spark 配置项init.py#L951-L953extra_tagsNone字典形式的额外标签设置到自动日志创建的每个托管 run 上init.py#L959该 API 要求Spark 3.0 及以上版本且非线程安全。测试用例中大量使用了mlflow.pyspark.ml.autolog()的各个参数组合例如autolog(extra_tags{test_tag: spark_autolog})见 test_pyspark_ml_autologging.py#L263、autolog(registered_model_name...)见 test_pyspark_ml_autologging.py#L1037等可作为参数用法的直接参考。自动日志记录的内容清单调用autolog()后当你执行Estimator.fit()pyspark.ml.feature下的特征器除外时MLflow 会自动记录以下内容参数Parameters通过estimator.params获取的全部参数若某个参数值本身也是 Estimator则嵌套 Estimator 的参数也会被记录嵌套参数键格式为{estimator_uid}.{param_name}。实现上由_get_instance_param_map()递归展开参数树init.py#L342-L391Pipeline 的stages会被展开为各阶段名称列表并递归记录各阶段参数CrossValidator/TrainValidationSplit的estimator与estimatorParamMaps会特殊处理后者以 JSON 工件形式保存其余Params类型参数值同样递归展开。参数记录通过_log_estimator_params()分块提交并对超长键/值做截断处理MAX_ENTITY_KEY_LENGTH、MAX_PARAM_VAL_LENGTH见init.py#L523-L528。标签TagsEstimator 类名如LinearRegression。全限定类名如pyspark.ml.regression.LinearRegression由_get_estimator_info_tags()生成init.py#L180-L189。训练后指标Post-training Metrics当训练完成后你调用任意 PySpark ML Evaluator 的evaluate()时MLflow 会把评估结果记录到与该模型关联的 run 中。指标键格式为{metric_name}[-{call_index}]_{dataset_name}metric_name来自Evaluator.getMetricName()同一指标被多次调用时从第 2 次起追加call_indexdataset_name取调用model.transform(dataset)时外层调用帧中数据集变量的名字若数据集是未命名中间表达式则记为unknown_dataset若多个数据集变量同名则从第 2 个起追加索引。这套机制的底层实现在_AutologgingMetricsManagerinit.py#L530-L745它维护预测结果对象 id → (数据集名, run_id)映射、评估数据集信息与评估器调用信息并通过weakref.finalize在预测结果对象被 GC 后清理 id避免 id 复用导致错误关联。三个 patch 点patched_fit/patched_transform/patched_evaluateinit.py#L1154-L1237构成了完整的「训练登记模型 → 预测登记结果 → 评估回填指标」链路。已知限制MLflow 无法为「对预测结果做进一步变换得到的派生对象」找到对应 run 信息。工件Artifacts一个带mlflow.sparkflavor 的 MLflow Model内含训练好的模型由mlflow.spark.log_model()记录。大模型可能因性能与存储空间考量不被自动记录。训练后指标调用相关的metric_info.json工件键为指标名值为对应评估器信息评估器类名与参数见log_post_training_metric()init.py#L723-L740。若模型属于CrossValidatorModel/TrainValidationSplitModel还会额外记录best_model工件init.py#L1120-L1124。元估计器Meta-estimator的处理机制当Pipeline、CrossValidator、TrainValidationSplit、OneVsRest等元估计器调用fit()时其内部对子估计器发起的fit()调用不会被重复记录——自动日志只在最外层fit()记录一次。这是通过_SparkTrainingSession会话隔离实现的见patched_fit中的with _SparkTrainingSession(estimatorself, allow_childrenFalse)init.py#L1159。元估计器场景下会额外记录一个estimator_info.json工件其hierarchy条目描述整个估计器的层次结构展开包含所有嵌套阶段如嵌套 Pipeline 的 stages。层级生成逻辑在_gen_stage_hierarchy_recursively()init.py#L255-L289中实现Pipeline →{name: ..., stages: [...]}OneVsRest →{name: ..., classifier: {...}}参数搜索估计器 →{name: ..., evaluator: {...}, tuned_estimator: {...}}含Params类型参数 →{name: ..., params: {...}}命名规则_get_uid_to_indexed_name_mapinit.py#L242-L252某类实例只出现一次时用类名出现多次时按深度优先遍历顺序追加_index后缀。参数搜索Parameter Search的专项记录对CrossValidator和TrainValidationSplit这类参数搜索元估计器自动日志除常规信息外还提供子 runchild runs为每组被探索的参数组合创建子 run记录该组参数与对应指标并通过mlflow.parent_run_id标签关联父 run_create_child_runs_for_parameter_searchinit.py#L394-L444。estimator_info.json扩展字段除hierarchy外还包含tuning_parameter_map_list调参使用的全部参数映射列表与tuned_estimator_parameter_map被调优估计器的参数映射两个条目。best_parameters.json记录搜索到的最优参数组合同时以best_{param_name}前缀的参数形式写入 runinit.py#L1057-L1065。search_results.csv包含params与metric两列的搜索结果表_log_parameter_search_results_as_artifactinit.py#L447-L462。其中指标来源在_get_param_search_metrics_and_best_index()init.py#L489-L520中区分CrossValidatorModel提供avg_{metric}与若存在std_{metric}TrainValidationSplitModel提供validationMetrics对应的{metric}。最优组合按评估器isLargerBetter()语义取 argmax/argmin。另外若以参数列表形式调用fit(params_list)即走fitMultiple路径自动日志会被跳过并给出警告_get_warning_msg_for_fit_call_with_a_list_of_paramsinit.py#L465-L471需改为对每个参数映射单独调用fit。模型白名单Allowlist机制log_modelsTrue时只有白名单内的模型才会被自动记录。判断逻辑见_should_log_model()init.py#L148-L177先精确匹配全限定类名也支持末尾单个*通配符的前缀匹配对OneVsRestModel检查其内部models[0]对PipelineModel要求所有Model类型的 stage 都通过白名单对参数搜索模型检查bestModel其余模型递归检查参数中嵌套的Model。内置白名单文件为 mlflow/pyspark/ml/log_model_allowlist.txt按分类列出分类LinearSVCModel、DecisionTreeClassificationModel、GBTClassificationModel、LogisticRegressionModel、RandomForestClassificationModel、NaiveBayesModel聚类BisectingKMeansModel、KMeansModel、GaussianMixtureModel回归AFTSurvivalRegressionModel、DecisionTreeRegressionModel、GBTRegressionModel、GeneralizedLinearRegressionModel、LinearRegressionModel、RandomForestRegressionModel特征化模型BucketedRandomProjectionLSHModel、ChiSqSelectorModel、CountVectorizerModel、IDFModel、ImputerModel、MaxAbsScalerModel、MinHashLSHModel、MinMaxScalerModel、OneHotEncoderModel、RobustScalerModel、RFormulaModel、StandardScalerModel、StringIndexerModel、VarianceThresholdSelectorModel、VectorIndexerModel、UnivariateFeatureSelectorModel复合/管道/调参模型OneVsRestModel、PipelineModel、CrossValidatorModel、TrainValidationSplitModelSynapseML 系列synapse.ml.cognitive.*、synapse.ml.exploratory.*、synapse.ml.featurize.*、synapse.ml.geospatial.*、synapse.ml.image.*、synapse.ml.io.*、synapse.ml.isolationforest.*、synapse.ml.lightgbm.*、synapse.ml.nn.*、synapse.ml.opencv.*、synapse.ml.stages.*、synapse.ml.vw.*内置白名单刻意排除了一些体积可能很大的模型例如 ALS 模型。自定义白名单的三种方式Spark 配置项在调用autolog()前初始化 SparkSession并设置spark.mlflow.pysparkml.autolog.logModelAllowlistFile指向一个换行分隔的全限定类名列表文件。读取逻辑见_read_log_model_allowlist()init.py#L94-L131若读取自定义文件失败会自动回退到内置白名单。log_model_allowlist参数直接传入可迭代对象覆盖默认白名单其优先级高于Spark 配置项init.py#L968-L971。白名单文件支持本地路径file://或无 scheme与远程 HTTP(S) 地址见_read_log_model_allowlist_from_file()init.py#L61-L91。未被白名单收录的模型会输出提示警告_get_warning_msg_for_skip_log_modelinit.py#L138-L145此时可显式调用mlflow.spark.log_model()记录。自定义白名单的完整用法可参考测试 tests/spark/autologging/ml/test_pyspark_ml_autologging_custom_allowlist.py。输入样例与模型签名输入样例log_input_examplesTrue时从训练集选取少量行INPUT_EXAMPLE_SAMPLE_ROWS作为输入样例。实现上先用get_feature_cols()mlflow/pyspark/ml/_autolog.py#L67-L96通过「逐个删除列再 transform 单行缓存子集、捕捉IllegalArgumentException」的方式推断特征列再经cast_spark_df_with_vector_to_array()mlflow/pyspark/ml/_autolog.py#L17-L35将向量列转为arraydouble后转成 Pandas DataFrame。模型签名log_model_signaturesTrue时通过_infer_spark_model_signature()init.py#L781-L799对空输入 DataFrame 执行 transform 推断输出 schema并保证默认预测列存在。限制目前仅支持标量 Spark 数据类型输入或输出含pyspark.ml.linalg.Vector等非标量类型时签名不会被记录源码中会打印警告见init.py#L1083-L1089。由于签名推断过程会修改模型例如设置输出列源码在推断前先spark_model.copy()复制模型以保留原对象init.py#L1091-L1098。自动日志的适用范围与跳过逻辑patched_fit对以下情况明确跳过自动日志直接对pyspark.ml.feature下的特征器调用fit()init.py#L1132-L1134但特征器作为 Pipeline 阶段被训练时仍会记录。以 list/tuple 形式的参数列表调用fit()即fitMultiple返回模型迭代器的情况init.py#L1135-L1139。自动日志通过safe_patch以manage_runTrue模式 patchEstimator.fit训练输入 DataFrame 会先persist(StorageLevel.MEMORY_AND_DISK)再记录元数据完成后unpersist()init.py#L1143-L1150。端到端使用示例以下示例演示如何启用自动日志并训练一个带调参的 Pipelineimport mlflow from pyspark.ml import Pipeline from pyspark.ml.classification import LogisticRegression from pyspark.ml.evaluation import BinaryClassificationEvaluator from pyspark.ml.feature import VectorAssembler from pyspark.ml.tuning import CrossValidator, ParamGridBuilder spark ... # 已初始化的 SparkSession mlflow.pyspark.ml.autolog( log_modelsTrue, log_input_examplesTrue, log_model_signaturesTrue, log_post_training_metricsTrue, ) features VectorAssembler(inputCols[f1, f2], outputColfeatures) lr LogisticRegression(featuresColfeatures, labelCollabel) param_grid ( ParamGridBuilder() .addGrid(lr.regParam, [0.01, 0.1]) .addGrid(lr.maxIter, [10, 20]) .build() ) evaluator BinaryClassificationEvaluator(labelCollabel) cv CrossValidator( estimatorlr, estimatorParamMapsparam_grid, evaluatorevaluator, numFolds3 ) with mlflow.start_run() as run: pipeline Pipeline(stages[features, cv]) pipeline_model pipeline.fit(train_df) # 训练后评估结果会自动写入关联 run metrics evaluator.evaluate(pipeline_model.transform(test_df))训练完成后你会在 run 下看到estimator_info.json含 hierarchy、tuning_parameter_map_list、best_parameters.json、search_results.csv、metric_info.json训练后指标、model与best_model工件、每个参数组合对应的子 run以及数据集、参数、标签和训练后指标。总结mlflow.pyspark.ml.autolog()为 PySpark ML 训练流程提供了零侵入的端到端追踪能力单次调用即可覆盖参数、标签、数据集、模型工件、签名、输入样例、元估计器层级与参数搜索全过程并通过可自定义的白名单机制灵活控制模型记录范围。其log_post_training_metrics机制patchModel.transform与Evaluator.evaluate更是将训练与评估阶段无缝衔接适合在 Spark 训练管道中作为标准的 MLflow 接入方式。【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考