MLflow mlflow.metrics 模块完全指南内置指标、GenAI 评分指标与自定义评估指标【免费下载链接】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本指南以 MLflow 开源仓库中的 mlflow.metrics API 参考文档 为骨架系统讲解mlflow.metrics模块的核心概念与实战用法EvaluationMetric与MetricValue的数据结构、按model_type自动计算的内置指标回归、分类、文本、问答、检索以及基于 LLM-as-a-Judge 的 GenAI 指标answer_similarity、relevance等。读完本文你将能够熟练使用mlflow.evaluate()完成模型定量与定性评估并能通过make_metric、make_genai_metric打造贴合自身业务的自定义指标。一、模块定位如何量化与定性衡量你的模型mlflow.metrics模块帮助你对模型进行定量quantitative与定性qualitative的双重衡量。定量方面它提供了从 scikit-learn、HuggingFace evaluate、textstat 等成熟库封装而来的回归、分类、文本可读性、检索排序等指标定性方面它提供了一组使用 LLM 作为评判者LLM-as-a-Judge的 GenAI 指标用于评估生成文本的语义相似度、正确性、忠实度与相关性。这些指标统一以EvaluationMetric对象的形式存在并被mlflow.evaluate()API 消费要么根据model_type参数自动计算要么通过extra_metrics参数显式传入。EvaluationMetric 类定义 位于mlflow/models/evaluation/base.py而mlflow.metrics模块mlflow/metrics/init.py中则导出全部内置指标的工厂函数以及MetricValue、make_metric、genai子模块等公共接口。从源码结构看模块由三大块构成mlflow/metrics/base.py定义MetricValue数据结构与标准聚合函数mlflow/metrics/metric_definitions.py内置非 GenAI 指标的底层 eval_fn 实现mlflow/metrics/genai/GenAI 指标的工厂函数、评测提示词模板与 LLM 调用封装。二、两个核心数据结构EvaluationMetric 与 MetricValue2.1 EvaluationMetricEvaluationMetric是描述如何计算一个指标的封装对象其核心字段包括字段说明eval_fn实际计算指标的函数签名形如eval_fn(predictions, targets, metrics, **kwargs)name指标名称greater_is_better指标是否越大越好long_name指标长名称如mse的长名root_mean_squared_errorversion指标版本如v1metric_details指标的计算说明包括评测提示词全文metric_metadata附加元数据字典genai_metric_args用户调用make_genai_metric时传入的参数快照用于后续反序列化还原指标对象其中eval_fn的完整签名如下见 EvaluationMetric 文档字符串def eval_fn( predictions: pandas.Series, # 模型预测结果 targets: pandas.Series, # 可选真实标签 metrics: Dict[str, MetricValue], # 可选默认评估器已计算出的其他指标 **kwargs, # 输入数据、模型输出、其他指标或 evaluator_config 中指定的参数 ) - float | MetricValue: ...2.2 MetricValue评估结果统一存储在MetricValue数据类中定义见 mlflow/metrics/base.py#L16-L38它包含三个字段scores逐行per-example的评分列表justifications逐行的评分理由GenAI 指标中由评判 LLM 给出aggregate_results聚合结果字典键为聚合方式名mean、variance、p90等值为聚合数值。MetricValue在初始化时有一个重要的自动行为如果aggregate_results为None且scores全部为数值则会自动用standard_aggregations计算标准聚合。standard_aggregationsmlflow/metrics/base.py#L8-L13定义为def standard_aggregations(scores): return { mean: np.mean(scores), variance: np.var(scores), p90: np.percentile(scores, 90), }即默认对逐行数值评分计算均值、方差、P90 分位数三个聚合值。三、评估结果的落库方式按照 mlflow.metrics.rst 的说明评估结果通过MetricValue保存后MLflow 会做如下处理聚合结果作为 run 的 metrics标量指标记录到 MLflow run 中逐行结果作为 artifacts工件以评估表evaluation table的形式记录到 MLflow run 中便于后续在 UI 中查看每个样本的得分与理由。因此一次mlflow.evaluate()结束后你既能在指标面板看到聚合数值也能在评估表里逐条审查模型输出与评分依据。四、内置指标工厂函数按 model_type 自动计算mlflow.metrics提供了一系列工厂函数每个函数返回一个现成的EvaluationMetric。这些指标会根据mlflow.evaluate()的model_type参数被自动计算。model_type的取值与指标对应关系由默认评估器决定详见 mlflow.evaluate API 文档。以下按文档结构分组介绍。4.1 回归指标Regressor Metrics工厂函数对应指标greater_is_bettermae()平均绝对误差Falsemse()均方误差Falsermse()均方根误差Falser2_score()决定系数R²Truemax_error()最大残差误差Falsemape()平均绝对百分比误差False这些指标底层直接调用 scikit-learn 的对应实现见 mlflow/metrics/metric_definitions.py例如_mae_eval_fn内部就是sklearn.metrics.mean_absolute_error(targets, predictions)。需要注意回归指标只有在提供了targets时才会计算源码中均有if targets is not None and len(targets) ! 0的前置判断。值得留意的是rmse的底层实现_root_mean_squared_errormetric_definitions.py#L287-L299优先使用 scikit-learn 1.4 的root_mean_squared_error若导入失败则回退到mean_squared_error(..., squaredFalse)兼顾了不同 sklearn 版本的兼容性。4.2 分类指标Classifier Metrics工厂函数对应指标说明precision_score()精确率0~1 聚合分recall_score()召回率0~1 聚合分f1_score()F1 分数2 × (precision × recall) / (precision recall)三个指标的底层实现metric_definitions.py#L334-L375均透传了pos_label1、averagebinary、sample_weight等 scikit-learn 参数默认按二分类处理。4.3 文本指标Text Metrics文本可读性指标基于textstat库计算适用于评估模型输出文本的易读程度ari_grade_level()自动可读性指数Automated Readability Index输出大致在 0~15 区间的年级水平flesch_kincaid_grade_level()Flesch-Kincaid 年级水平同样是 0~15 左右的数值。两者greater_is_betterFalse可读性越低年级水平意味着文本越简单。若环境中未安装textstat底层 eval_fn 会打印提示并跳过该指标见 metric_definitions.py#L127-L164。4.4 问答指标Question Answering Metricsmodel_typequestion-answering会计算以上全部Text Metrics并额外包括以下指标工厂函数说明exact_match()基于 sklearnaccuracy_score的精确匹配仅输出 0~1 聚合分rouge1()基于 unigram 的相似度0~1越高越相似rouge2()基于 bigram 的相似度rougeL()基于最长公共子序列rougeLsum()基于句子级最长公共子序列toxicity()毒性检测使用roberta-hate-speech-dynabench-r4模型0~1越接近 1 越毒默认毒性阈值 0.5token_count()基于 tiktokencl100k_base分词器统计 token 数latency()逐条预测耗时bleu()BLEU 分数0~1考虑 n-gram 精确率与简短惩罚各指标的底层实现细节metric_definitions.pyROUGE 系列通过 HuggingFaceevaluate库计算传入use_aggregatorFalse获得逐行分数后再做标准聚合toxicity额外计算有毒文本占比ratio聚合值metric_definitions.py#L103-L124token_count依赖 tiktoken。对于离线air-gapped环境可通过设置TIKTOKEN_CACHE_DIR环境变量指定本地缓存目录避免运行时下载 tokenizer 文件见 mlflow/metrics/init.py#L51-L85latency要求每行串行预测才能计时因此会显著拖慢评估流程mlflow/metrics/init.py#L36-L47bleu对空 target/prediction 行会以 0 分占位并记录警告metric_definitions.py#L538-L593。版本提示从当前仓库源码看toxicity、token_count、latency、bleu、exact_match、ROUGE 系列、文本指标以及下文介绍的检索/GenAI 指标均带有deprecated(since3.4.0)装饰器指向mlflow.metrics.genai.utils._MIGRATION_GUIDE迁移指南而回归指标mae/mse/rmse/r2_score/max_error/mape与分类指标precision_score/recall_score/f1_score未标记废弃。使用旧接口时建议关注版本迁移说明。4.5 检索指标Retriever Metricsmodel_typeretriever的内置指标包括precision_at_k(k)、recall_at_k(k)、ndcg_at_k(k)三个工厂函数默认retriever_k3。推荐的数据集格式评估文档检索模型时建议数据包含三列输入查询input queries检索到的相关文档 IDretrieved relevant doc IDs真实相关文档 IDground-truth doc IDs。其中文档 ID是唯一标识文档的字符串或整数每行的检索/真实文档 ID 列应是一个 doc ID 的列表或 numpy 数组。此外也可以不提供静态预测列而是通过model参数传入一个函数该函数接收包含查询与真实相关文档 ID 的 Pandas DataFrame返回一个带检索文档 ID 列的 DataFrame。三个参数说明targets字符串指定真实相关文档 ID 所在列名predictions字符串指定检索文档 ID 所在列名静态数据集或 model 函数返回的 DataFrame 中retriever_k正整数指定每个查询考虑的前 k 个检索文档数默认 3。修改retriever_k的两种方式文档原例完整保留方式一传入模型函数并通过evaluator_config指定retriever_kmlflow.evaluate( modelretriever_function, datadata, targetsground_truth, model_typeretriever, evaluatorsdefault, evaluator_config{retriever_k: 5} )方式二使用静态数据集并通过extra_metrics显式传入不同 k 值的指标mlflow.evaluate( datadata, predictionspredictions_param, targetstargets_param, model_typeretriever, extra_metrics[ mlflow.metrics.precision_at_k(5), mlflow.metrics.precision_at_k(6), mlflow.metrics.recall_at_k(5), mlflow.metrics.ndcg_at_k(5) ] )注意文档原文提示在第二种方式中建议省略model_type否则默认评估器仍会额外计算precision3和recall3与显式传入的precision5、precision6、recall5、ndcg_at_k5叠加产生多余的指标。这一默认行为在 默认评估器实现 中可得到印证当model_typeretriever时评估器会从evaluator_config中弹出retriever_k默认 3并自动加入precision_at_k(retriever_k)、recall_at_k(retriever_k)、ndcg_at_k(retriever_k)三个指标。各指标的评分规则源自各工厂函数与底层 eval_fn 的文档/实现见 mlflow/metrics/init.py 与 metric_definitions.pyprecision_at_k逐行输出 0~1 的检索精确率。设x min(k, 检索到的 doc ID 数)则precision_at_k 前 x 个文档中相关文档数 / x若未检索到任何相关文档得分为 0。recall_at_k若未提供真实 doc ID 且未检索到文档得 1 分视为完全正确若未提供真实 doc ID 但检索到了文档得 0 分其他情况recall_at_k 前 k 个文档中唯一相关文档数 / 真实 doc ID 总数。ndcg_at_k基于 sklearnndcg_score并使用二值相关性真实文档相关度为 1否则为 0在 sklearn 实现之上补充了四个边界规则无真实 doc ID 且未检索到文档 → 1 分无真实 doc ID 但检索到文档 → 0 分有真实 doc ID 但未检索到文档 → 0 分检索结果中出现重复 doc ID 且重复 ID 在真实集合中时重复项会被当作不同文档处理例如真实[1, 2]、检索[1, 1, 1, 3]等价于真实[10, 11, 12, 2]、检索[10, 11, 12, 3]来计分。三个工厂函数都要求k为正整数否则会记录警告并跳过指标metric_definitions.py#L378-L384。NDCG 的边界处理与重复文档展开逻辑可在_ndcg_at_k_eval_fn与_prepare_row_for_ndcgmetric_definitions.py#L428-L460中查看。五、用 make_metric 自定义评估指标当内置指标无法满足需求时可以通过make_metric工厂函数创建自定义EvaluationMetric。make_metric定义于 mlflow/models/evaluation/base.py#L324它接收一个自定义eval_fn与元信息生成一个可被mlflow.evaluate()的extra_metrics参数直接使用的指标对象。其典型用法是在eval_fn中拿到predictions与可选的targets、metrics、inputs等计算出逐行scores并返回MetricValue聚合结果可由MetricValue自动计算也可手动指定。六、GenAI 指标用 LLM 当裁判GenAIgenai指标是mlflow.metrics中面向生成式文本模型的指标它们调用一个 LLM 来评判模型输出文本的质量。这类指标使用第三方 LLM 服务如 OpenAI时须遵守该 LLM 服务的使用条款。6.1 内置 GenAI 指标mlflow.metrics.genai子模块mlflow/metrics/genai/init.py导出以下工厂函数工厂函数评判维度需要的数据列answer_similarity()输出与ground_truthtargets列的语义相似度targetsanswer_correctness()输出相对ground_truth的准确性建立在 answer_similarity 之上targetsfaithfulness()输出相对context的事实一致性忽略输入contextanswer_relevance()输出相对输入是否切题输入relevance()输出相对输入与context的相关性、显著性、适用性context各指标底层通过版本化的评测提示词类实现见 mlflow/metrics/genai/prompts/v1.py例如AnswerSimilarityMetric、FaithfulnessMetric、RelevanceMetric等每个类都带有grading_context_columns如[targets]或[context]、default_model与默认parameters。默认评判模型为openai:/gpt-4v1 提示词中的default_model。这些指标均提供了model、metric_version、examples、parameters、extra_headers、proxy_url、max_workers默认 10 个并发 worker等可定制参数。若指定的metric_version不存在工厂函数会抛出MlflowException。以answer_similarity为例targets必须作为输入数据集或模型输出的一部分提供可通过mlflow.evaluate()的targets参数或evaluator_config中的col_mapping映射到其他列名。以下为文档中的完整示例EvaluationExample用于少样本引导评判模型import mlflow from mlflow.metrics.genai import EvaluationExample, answer_similarity eval_df pd.DataFrame( { inputs: [ What is MLflow?, ], ground_truth: [ MLflow is the largest open source AI engineering platform for agents, LLM applications, and ML models. It was developed by Databricks, a company that specializes in data and AI solutions. MLflow is designed to address the challenges that data scientists and AI engineers face when developing, evaluating, and deploying AI applications., ], } ) example EvaluationExample( inputWhat is MLflow?, outputMLflow is the largest open source AI engineering platform for agents, LLM applications, and ML models, including tracing, evaluation, prompt management, experiment tracking, and deployment., score4, justificationThe definition effectively explains what MLflow is its purpose, and its developer. It could be more concise for a 5-score., grading_context{ ground_truth: MLflow is the largest open source AI engineering platform for agents, LLM applications, and ML models. It was developed by Databricks, a company that specializes in data and AI solutions. MLflow is designed to address the challenges that data scientists and AI engineers face when developing, evaluating, and deploying AI applications. }, ) answer_similarity_metric answer_similarity(examples[example]) results mlflow.evaluate( logged_model.model_uri, eval_df, targetsground_truth, model_typequestion-answering, extra_metrics[answer_similarity_metric], )6.2 查看指标的计算详情metric_detailsEvaluationMetric的metric_details属性记录了指标的计算方式包括完整的评分提示词。按文档示例可以这样查看import mlflow from mlflow.metrics.genai import relevance my_relevance_metric relevance() print(my_relevance_metric.metric_details)在make_genai_metric的实现中metric_details会被设置为评测提示词模板的字符串形式见 mlflow/metrics/genai/genai_metric.py#L672-L681方便用户透明地审查裁判的评分标准。6.3 EvaluationExample少样本示例EvaluationExamplemlflow/metrics/genai/base.py用于在 LLM 评估中存储少样本示例字段包括input、output、score、justification与grading_context可以是列名到上下文字符串的字典或单个上下文字符串。其__str__会将示例格式化为 Example Input / Example Output / Additional information used by the model / Example score / Example justification 的提示词片段供评判模型参考。使用 GenAI 指标时强烈建议传入examples列表作为评分参照。6.4 用 make_genai_metric 与 make_genai_metric_from_prompt 定制 LLM 裁判指标当内置 GenAI 指标不适用时可以用make_genai_metricmlflow/metrics/genai/genai_metric.py#L365自定义。它的核心参数参数说明name指标名称definition指标的语义定义grading_prompt评分标准rubric提示词examples可选EvaluationExample列表version可选当前支持v1model评判模型 URI如openai:/gpt-4grading_context_columns评分上下文列名单个或列表来自数据集/预测输出也可是其他已算指标名include_input是否将输入纳入评分提示词默认 Trueparameters评判 LLM 的参数默认temperature0.0、max_tokens200、top_p1.0建议温度固定为 0.0 保证结果一致aggregations聚合方式支持min、max、mean、median、variance、p90默认[mean, variance, p90]greater_is_better默认 Truemax_workers评判并发数默认 10extra_headers/proxy_url额外的请求头与代理 URL适用于经代理服务而非直连 LLM 厂商的场景make_genai_metric_from_promptgenai_metric.py#L204则更进一步它只使用你提供的judge_prompt不拼接任何预写系统提示词适合内置评分提示词覆盖不到的场景。提示词可使用 f-string 语法引用变量对应变量须在生成的指标 eval_fn 中以关键字参数传入。定义好的自定义指标配置会被序列化为genai_custom_metrics.json工件保存使评估结果可复现、可审计。两个自定义指标工厂的核心计算流程从 genai_metric.py 源码可推断将逐行输入、输出与评分上下文格式化为评分 payload → 通过ThreadPoolExecutor线程名前缀MlflowGenAiEvaluation并发调用评判模型 → 解析返回的score与justification先尝试 JSON 解析失败则用正则兜底→ 计算聚合结果并封装为MetricValue。6.5 恢复历史评估中的自定义指标retrieve_custom_metricsretrieve_custom_metrics(run_id, nameNone, versionNone)可以从某个评估 run 的工件中反序列化恢复用户通过make_genai_metric/make_genai_metric_from_prompt创建的自定义指标对象支持按名称和版本过滤。如果评估 run 中没有自定义指标定义会返回空列表并给出警告。反序列化时会校验序列化时的 MLflow 版本版本不一致会发出UserWarninggenai_metric.py#L688-L716。6.6 环境变量与网关路由使用 GenAI 指标前必须为所用 LLM 服务设置相应的环境变量使用 OpenAI API必须设置OPENAI_API_KEY使用 Azure OpenAI还须设置OPENAI_API_TYPE、OPENAI_API_VERSION、OPENAI_API_BASE与OPENAI_DEPLOYMENT_NAME如果通过 gateway 路由调用如endpoints:/或gateway:前缀的模型 URI则无需设置上述环境变量认证信息由网关配置统一管理可参考 mlflow/metrics/genai/model_utils.py 中score_model_on_payload对gateway前缀的处理逻辑。在 UI 层面LLM 评估结果如Relevance、follows_instructions等指标的逐条 Pass/Fail 状态与百分比可在 MLflow UI 的 Evaluation results / Traces 页面查看七、完整实战路径与延伸阅读一个典型的评估流程可以归纳为准备评估数据集inputs、targets检索场景还需检索/真实 doc ID 列按model_type选定自动指标回归/分类/问答/检索需要时用extra_metrics追加自定义或 GenAI 指标调用mlflow.evaluate()通过evaluator_config调整retriever_k、col_mapping等细节从返回结果中读取聚合指标run metrics与逐行评估表artifacts并结合metric_details审查评分依据。想深入理解底层实现可以继续阅读以下仓库文件指标工厂与导出mlflow/metrics/init.py非 GenAI 指标的 eval_fn 实现mlflow/metrics/metric_definitions.pyGenAI 指标工厂mlflow/metrics/genai/genai_metric.py、mlflow/metrics/genai/metric_definitions.py评测提示词版本mlflow/metrics/genai/prompts/v1.py默认评估器对retriever_k的处理mlflow/models/evaluation/evaluators/default.py相关测试用例tests/metrics/test_metric_definitions.py、tests/metrics/genai/test_genai_metrics.py、tests/evaluate/test_default_evaluator.py需要注意的是当前仓库中相当一部分mlflow.metrics内置指标与 GenAI 指标带有deprecated(since3.4.0)标记官方通过_MIGRATION_GUIDE提供了迁移说明在实际工程中选用接口时请结合所用 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 mlflow.metrics 模块完全指南：内置指标、GenAI 评分指标与自定义评估指标
MLflow mlflow.metrics 模块完全指南内置指标、GenAI 评分指标与自定义评估指标【免费下载链接】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本指南以 MLflow 开源仓库中的 mlflow.metrics API 参考文档 为骨架系统讲解mlflow.metrics模块的核心概念与实战用法EvaluationMetric与MetricValue的数据结构、按model_type自动计算的内置指标回归、分类、文本、问答、检索以及基于 LLM-as-a-Judge 的 GenAI 指标answer_similarity、relevance等。读完本文你将能够熟练使用mlflow.evaluate()完成模型定量与定性评估并能通过make_metric、make_genai_metric打造贴合自身业务的自定义指标。一、模块定位如何量化与定性衡量你的模型mlflow.metrics模块帮助你对模型进行定量quantitative与定性qualitative的双重衡量。定量方面它提供了从 scikit-learn、HuggingFace evaluate、textstat 等成熟库封装而来的回归、分类、文本可读性、检索排序等指标定性方面它提供了一组使用 LLM 作为评判者LLM-as-a-Judge的 GenAI 指标用于评估生成文本的语义相似度、正确性、忠实度与相关性。这些指标统一以EvaluationMetric对象的形式存在并被mlflow.evaluate()API 消费要么根据model_type参数自动计算要么通过extra_metrics参数显式传入。EvaluationMetric 类定义 位于mlflow/models/evaluation/base.py而mlflow.metrics模块mlflow/metrics/init.py中则导出全部内置指标的工厂函数以及MetricValue、make_metric、genai子模块等公共接口。从源码结构看模块由三大块构成mlflow/metrics/base.py定义MetricValue数据结构与标准聚合函数mlflow/metrics/metric_definitions.py内置非 GenAI 指标的底层 eval_fn 实现mlflow/metrics/genai/GenAI 指标的工厂函数、评测提示词模板与 LLM 调用封装。二、两个核心数据结构EvaluationMetric 与 MetricValue2.1 EvaluationMetricEvaluationMetric是描述如何计算一个指标的封装对象其核心字段包括字段说明eval_fn实际计算指标的函数签名形如eval_fn(predictions, targets, metrics, **kwargs)name指标名称greater_is_better指标是否越大越好long_name指标长名称如mse的长名root_mean_squared_errorversion指标版本如v1metric_details指标的计算说明包括评测提示词全文metric_metadata附加元数据字典genai_metric_args用户调用make_genai_metric时传入的参数快照用于后续反序列化还原指标对象其中eval_fn的完整签名如下见 EvaluationMetric 文档字符串def eval_fn( predictions: pandas.Series, # 模型预测结果 targets: pandas.Series, # 可选真实标签 metrics: Dict[str, MetricValue], # 可选默认评估器已计算出的其他指标 **kwargs, # 输入数据、模型输出、其他指标或 evaluator_config 中指定的参数 ) - float | MetricValue: ...2.2 MetricValue评估结果统一存储在MetricValue数据类中定义见 mlflow/metrics/base.py#L16-L38它包含三个字段scores逐行per-example的评分列表justifications逐行的评分理由GenAI 指标中由评判 LLM 给出aggregate_results聚合结果字典键为聚合方式名mean、variance、p90等值为聚合数值。MetricValue在初始化时有一个重要的自动行为如果aggregate_results为None且scores全部为数值则会自动用standard_aggregations计算标准聚合。standard_aggregationsmlflow/metrics/base.py#L8-L13定义为def standard_aggregations(scores): return { mean: np.mean(scores), variance: np.var(scores), p90: np.percentile(scores, 90), }即默认对逐行数值评分计算均值、方差、P90 分位数三个聚合值。三、评估结果的落库方式按照 mlflow.metrics.rst 的说明评估结果通过MetricValue保存后MLflow 会做如下处理聚合结果作为 run 的 metrics标量指标记录到 MLflow run 中逐行结果作为 artifacts工件以评估表evaluation table的形式记录到 MLflow run 中便于后续在 UI 中查看每个样本的得分与理由。因此一次mlflow.evaluate()结束后你既能在指标面板看到聚合数值也能在评估表里逐条审查模型输出与评分依据。四、内置指标工厂函数按 model_type 自动计算mlflow.metrics提供了一系列工厂函数每个函数返回一个现成的EvaluationMetric。这些指标会根据mlflow.evaluate()的model_type参数被自动计算。model_type的取值与指标对应关系由默认评估器决定详见 mlflow.evaluate API 文档。以下按文档结构分组介绍。4.1 回归指标Regressor Metrics工厂函数对应指标greater_is_bettermae()平均绝对误差Falsemse()均方误差Falsermse()均方根误差Falser2_score()决定系数R²Truemax_error()最大残差误差Falsemape()平均绝对百分比误差False这些指标底层直接调用 scikit-learn 的对应实现见 mlflow/metrics/metric_definitions.py例如_mae_eval_fn内部就是sklearn.metrics.mean_absolute_error(targets, predictions)。需要注意回归指标只有在提供了targets时才会计算源码中均有if targets is not None and len(targets) ! 0的前置判断。值得留意的是rmse的底层实现_root_mean_squared_errormetric_definitions.py#L287-L299优先使用 scikit-learn 1.4 的root_mean_squared_error若导入失败则回退到mean_squared_error(..., squaredFalse)兼顾了不同 sklearn 版本的兼容性。4.2 分类指标Classifier Metrics工厂函数对应指标说明precision_score()精确率0~1 聚合分recall_score()召回率0~1 聚合分f1_score()F1 分数2 × (precision × recall) / (precision recall)三个指标的底层实现metric_definitions.py#L334-L375均透传了pos_label1、averagebinary、sample_weight等 scikit-learn 参数默认按二分类处理。4.3 文本指标Text Metrics文本可读性指标基于textstat库计算适用于评估模型输出文本的易读程度ari_grade_level()自动可读性指数Automated Readability Index输出大致在 0~15 区间的年级水平flesch_kincaid_grade_level()Flesch-Kincaid 年级水平同样是 0~15 左右的数值。两者greater_is_betterFalse可读性越低年级水平意味着文本越简单。若环境中未安装textstat底层 eval_fn 会打印提示并跳过该指标见 metric_definitions.py#L127-L164。4.4 问答指标Question Answering Metricsmodel_typequestion-answering会计算以上全部Text Metrics并额外包括以下指标工厂函数说明exact_match()基于 sklearnaccuracy_score的精确匹配仅输出 0~1 聚合分rouge1()基于 unigram 的相似度0~1越高越相似rouge2()基于 bigram 的相似度rougeL()基于最长公共子序列rougeLsum()基于句子级最长公共子序列toxicity()毒性检测使用roberta-hate-speech-dynabench-r4模型0~1越接近 1 越毒默认毒性阈值 0.5token_count()基于 tiktokencl100k_base分词器统计 token 数latency()逐条预测耗时bleu()BLEU 分数0~1考虑 n-gram 精确率与简短惩罚各指标的底层实现细节metric_definitions.pyROUGE 系列通过 HuggingFaceevaluate库计算传入use_aggregatorFalse获得逐行分数后再做标准聚合toxicity额外计算有毒文本占比ratio聚合值metric_definitions.py#L103-L124token_count依赖 tiktoken。对于离线air-gapped环境可通过设置TIKTOKEN_CACHE_DIR环境变量指定本地缓存目录避免运行时下载 tokenizer 文件见 mlflow/metrics/init.py#L51-L85latency要求每行串行预测才能计时因此会显著拖慢评估流程mlflow/metrics/init.py#L36-L47bleu对空 target/prediction 行会以 0 分占位并记录警告metric_definitions.py#L538-L593。版本提示从当前仓库源码看toxicity、token_count、latency、bleu、exact_match、ROUGE 系列、文本指标以及下文介绍的检索/GenAI 指标均带有deprecated(since3.4.0)装饰器指向mlflow.metrics.genai.utils._MIGRATION_GUIDE迁移指南而回归指标mae/mse/rmse/r2_score/max_error/mape与分类指标precision_score/recall_score/f1_score未标记废弃。使用旧接口时建议关注版本迁移说明。4.5 检索指标Retriever Metricsmodel_typeretriever的内置指标包括precision_at_k(k)、recall_at_k(k)、ndcg_at_k(k)三个工厂函数默认retriever_k3。推荐的数据集格式评估文档检索模型时建议数据包含三列输入查询input queries检索到的相关文档 IDretrieved relevant doc IDs真实相关文档 IDground-truth doc IDs。其中文档 ID是唯一标识文档的字符串或整数每行的检索/真实文档 ID 列应是一个 doc ID 的列表或 numpy 数组。此外也可以不提供静态预测列而是通过model参数传入一个函数该函数接收包含查询与真实相关文档 ID 的 Pandas DataFrame返回一个带检索文档 ID 列的 DataFrame。三个参数说明targets字符串指定真实相关文档 ID 所在列名predictions字符串指定检索文档 ID 所在列名静态数据集或 model 函数返回的 DataFrame 中retriever_k正整数指定每个查询考虑的前 k 个检索文档数默认 3。修改retriever_k的两种方式文档原例完整保留方式一传入模型函数并通过evaluator_config指定retriever_kmlflow.evaluate( modelretriever_function, datadata, targetsground_truth, model_typeretriever, evaluatorsdefault, evaluator_config{retriever_k: 5} )方式二使用静态数据集并通过extra_metrics显式传入不同 k 值的指标mlflow.evaluate( datadata, predictionspredictions_param, targetstargets_param, model_typeretriever, extra_metrics[ mlflow.metrics.precision_at_k(5), mlflow.metrics.precision_at_k(6), mlflow.metrics.recall_at_k(5), mlflow.metrics.ndcg_at_k(5) ] )注意文档原文提示在第二种方式中建议省略model_type否则默认评估器仍会额外计算precision3和recall3与显式传入的precision5、precision6、recall5、ndcg_at_k5叠加产生多余的指标。这一默认行为在 默认评估器实现 中可得到印证当model_typeretriever时评估器会从evaluator_config中弹出retriever_k默认 3并自动加入precision_at_k(retriever_k)、recall_at_k(retriever_k)、ndcg_at_k(retriever_k)三个指标。各指标的评分规则源自各工厂函数与底层 eval_fn 的文档/实现见 mlflow/metrics/init.py 与 metric_definitions.pyprecision_at_k逐行输出 0~1 的检索精确率。设x min(k, 检索到的 doc ID 数)则precision_at_k 前 x 个文档中相关文档数 / x若未检索到任何相关文档得分为 0。recall_at_k若未提供真实 doc ID 且未检索到文档得 1 分视为完全正确若未提供真实 doc ID 但检索到了文档得 0 分其他情况recall_at_k 前 k 个文档中唯一相关文档数 / 真实 doc ID 总数。ndcg_at_k基于 sklearnndcg_score并使用二值相关性真实文档相关度为 1否则为 0在 sklearn 实现之上补充了四个边界规则无真实 doc ID 且未检索到文档 → 1 分无真实 doc ID 但检索到文档 → 0 分有真实 doc ID 但未检索到文档 → 0 分检索结果中出现重复 doc ID 且重复 ID 在真实集合中时重复项会被当作不同文档处理例如真实[1, 2]、检索[1, 1, 1, 3]等价于真实[10, 11, 12, 2]、检索[10, 11, 12, 3]来计分。三个工厂函数都要求k为正整数否则会记录警告并跳过指标metric_definitions.py#L378-L384。NDCG 的边界处理与重复文档展开逻辑可在_ndcg_at_k_eval_fn与_prepare_row_for_ndcgmetric_definitions.py#L428-L460中查看。五、用 make_metric 自定义评估指标当内置指标无法满足需求时可以通过make_metric工厂函数创建自定义EvaluationMetric。make_metric定义于 mlflow/models/evaluation/base.py#L324它接收一个自定义eval_fn与元信息生成一个可被mlflow.evaluate()的extra_metrics参数直接使用的指标对象。其典型用法是在eval_fn中拿到predictions与可选的targets、metrics、inputs等计算出逐行scores并返回MetricValue聚合结果可由MetricValue自动计算也可手动指定。六、GenAI 指标用 LLM 当裁判GenAIgenai指标是mlflow.metrics中面向生成式文本模型的指标它们调用一个 LLM 来评判模型输出文本的质量。这类指标使用第三方 LLM 服务如 OpenAI时须遵守该 LLM 服务的使用条款。6.1 内置 GenAI 指标mlflow.metrics.genai子模块mlflow/metrics/genai/init.py导出以下工厂函数工厂函数评判维度需要的数据列answer_similarity()输出与ground_truthtargets列的语义相似度targetsanswer_correctness()输出相对ground_truth的准确性建立在 answer_similarity 之上targetsfaithfulness()输出相对context的事实一致性忽略输入contextanswer_relevance()输出相对输入是否切题输入relevance()输出相对输入与context的相关性、显著性、适用性context各指标底层通过版本化的评测提示词类实现见 mlflow/metrics/genai/prompts/v1.py例如AnswerSimilarityMetric、FaithfulnessMetric、RelevanceMetric等每个类都带有grading_context_columns如[targets]或[context]、default_model与默认parameters。默认评判模型为openai:/gpt-4v1 提示词中的default_model。这些指标均提供了model、metric_version、examples、parameters、extra_headers、proxy_url、max_workers默认 10 个并发 worker等可定制参数。若指定的metric_version不存在工厂函数会抛出MlflowException。以answer_similarity为例targets必须作为输入数据集或模型输出的一部分提供可通过mlflow.evaluate()的targets参数或evaluator_config中的col_mapping映射到其他列名。以下为文档中的完整示例EvaluationExample用于少样本引导评判模型import mlflow from mlflow.metrics.genai import EvaluationExample, answer_similarity eval_df pd.DataFrame( { inputs: [ What is MLflow?, ], ground_truth: [ MLflow is the largest open source AI engineering platform for agents, LLM applications, and ML models. It was developed by Databricks, a company that specializes in data and AI solutions. MLflow is designed to address the challenges that data scientists and AI engineers face when developing, evaluating, and deploying AI applications., ], } ) example EvaluationExample( inputWhat is MLflow?, outputMLflow is the largest open source AI engineering platform for agents, LLM applications, and ML models, including tracing, evaluation, prompt management, experiment tracking, and deployment., score4, justificationThe definition effectively explains what MLflow is its purpose, and its developer. It could be more concise for a 5-score., grading_context{ ground_truth: MLflow is the largest open source AI engineering platform for agents, LLM applications, and ML models. It was developed by Databricks, a company that specializes in data and AI solutions. MLflow is designed to address the challenges that data scientists and AI engineers face when developing, evaluating, and deploying AI applications. }, ) answer_similarity_metric answer_similarity(examples[example]) results mlflow.evaluate( logged_model.model_uri, eval_df, targetsground_truth, model_typequestion-answering, extra_metrics[answer_similarity_metric], )6.2 查看指标的计算详情metric_detailsEvaluationMetric的metric_details属性记录了指标的计算方式包括完整的评分提示词。按文档示例可以这样查看import mlflow from mlflow.metrics.genai import relevance my_relevance_metric relevance() print(my_relevance_metric.metric_details)在make_genai_metric的实现中metric_details会被设置为评测提示词模板的字符串形式见 mlflow/metrics/genai/genai_metric.py#L672-L681方便用户透明地审查裁判的评分标准。6.3 EvaluationExample少样本示例EvaluationExamplemlflow/metrics/genai/base.py用于在 LLM 评估中存储少样本示例字段包括input、output、score、justification与grading_context可以是列名到上下文字符串的字典或单个上下文字符串。其__str__会将示例格式化为 Example Input / Example Output / Additional information used by the model / Example score / Example justification 的提示词片段供评判模型参考。使用 GenAI 指标时强烈建议传入examples列表作为评分参照。6.4 用 make_genai_metric 与 make_genai_metric_from_prompt 定制 LLM 裁判指标当内置 GenAI 指标不适用时可以用make_genai_metricmlflow/metrics/genai/genai_metric.py#L365自定义。它的核心参数参数说明name指标名称definition指标的语义定义grading_prompt评分标准rubric提示词examples可选EvaluationExample列表version可选当前支持v1model评判模型 URI如openai:/gpt-4grading_context_columns评分上下文列名单个或列表来自数据集/预测输出也可是其他已算指标名include_input是否将输入纳入评分提示词默认 Trueparameters评判 LLM 的参数默认temperature0.0、max_tokens200、top_p1.0建议温度固定为 0.0 保证结果一致aggregations聚合方式支持min、max、mean、median、variance、p90默认[mean, variance, p90]greater_is_better默认 Truemax_workers评判并发数默认 10extra_headers/proxy_url额外的请求头与代理 URL适用于经代理服务而非直连 LLM 厂商的场景make_genai_metric_from_promptgenai_metric.py#L204则更进一步它只使用你提供的judge_prompt不拼接任何预写系统提示词适合内置评分提示词覆盖不到的场景。提示词可使用 f-string 语法引用变量对应变量须在生成的指标 eval_fn 中以关键字参数传入。定义好的自定义指标配置会被序列化为genai_custom_metrics.json工件保存使评估结果可复现、可审计。两个自定义指标工厂的核心计算流程从 genai_metric.py 源码可推断将逐行输入、输出与评分上下文格式化为评分 payload → 通过ThreadPoolExecutor线程名前缀MlflowGenAiEvaluation并发调用评判模型 → 解析返回的score与justification先尝试 JSON 解析失败则用正则兜底→ 计算聚合结果并封装为MetricValue。6.5 恢复历史评估中的自定义指标retrieve_custom_metricsretrieve_custom_metrics(run_id, nameNone, versionNone)可以从某个评估 run 的工件中反序列化恢复用户通过make_genai_metric/make_genai_metric_from_prompt创建的自定义指标对象支持按名称和版本过滤。如果评估 run 中没有自定义指标定义会返回空列表并给出警告。反序列化时会校验序列化时的 MLflow 版本版本不一致会发出UserWarninggenai_metric.py#L688-L716。6.6 环境变量与网关路由使用 GenAI 指标前必须为所用 LLM 服务设置相应的环境变量使用 OpenAI API必须设置OPENAI_API_KEY使用 Azure OpenAI还须设置OPENAI_API_TYPE、OPENAI_API_VERSION、OPENAI_API_BASE与OPENAI_DEPLOYMENT_NAME如果通过 gateway 路由调用如endpoints:/或gateway:前缀的模型 URI则无需设置上述环境变量认证信息由网关配置统一管理可参考 mlflow/metrics/genai/model_utils.py 中score_model_on_payload对gateway前缀的处理逻辑。在 UI 层面LLM 评估结果如Relevance、follows_instructions等指标的逐条 Pass/Fail 状态与百分比可在 MLflow UI 的 Evaluation results / Traces 页面查看七、完整实战路径与延伸阅读一个典型的评估流程可以归纳为准备评估数据集inputs、targets检索场景还需检索/真实 doc ID 列按model_type选定自动指标回归/分类/问答/检索需要时用extra_metrics追加自定义或 GenAI 指标调用mlflow.evaluate()通过evaluator_config调整retriever_k、col_mapping等细节从返回结果中读取聚合指标run metrics与逐行评估表artifacts并结合metric_details审查评分依据。想深入理解底层实现可以继续阅读以下仓库文件指标工厂与导出mlflow/metrics/init.py非 GenAI 指标的 eval_fn 实现mlflow/metrics/metric_definitions.pyGenAI 指标工厂mlflow/metrics/genai/genai_metric.py、mlflow/metrics/genai/metric_definitions.py评测提示词版本mlflow/metrics/genai/prompts/v1.py默认评估器对retriever_k的处理mlflow/models/evaluation/evaluators/default.py相关测试用例tests/metrics/test_metric_definitions.py、tests/metrics/genai/test_genai_metrics.py、tests/evaluate/test_default_evaluator.py需要注意的是当前仓库中相当一部分mlflow.metrics内置指标与 GenAI 指标带有deprecated(since3.4.0)标记官方通过_MIGRATION_GUIDE提供了迁移说明在实际工程中选用接口时请结合所用 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），仅供参考