如何解决PyCaret中add_metrics方法报错"Custom metric function must return a float"问题？

问题背景与现象

在使用PyCaret进行机器学习模型评估时，add_metrics方法允许用户添加自定义评估指标。但许多开发者会遇到如下典型错误：

ValueError: Custom metric function must return a float

该错误发生在尝试将自定义指标函数通过add_metrics注册到PyCaret环境时，系统检测到函数返回值不符合float类型要求。

根本原因分析

通过分析PyCaret 2.3.8版本源码发现，该错误源于以下技术细节：

指标验证机制：PyCaret在add_metric内部会调用_check_metric_return方法验证返回值类型
类型强制转换：即使用户函数返回numpy.float64等兼容类型，未显式转换为Python原生float也会触发错误
多输出处理：当函数返回包含多个值的元组或数组时，缺乏明确的类型处理逻辑

完整解决方案

方案1：显式类型转换

def custom_metric(y_true, y_pred):
    score = mean_squared_error(y_true, y_pred)
    return float(score)  # 关键转换

from pycaret.classification import *
exp = setup(data, target='label')
add_metric('mse2', 'My MSE', custom_metric)

方案2：装饰器标准化输出

def metric_output_decorator(func):
    def wrapper(*args, **kwargs):
        result = func(*args, **kwargs)
        return float(result)
    return wrapper

@metric_output_decorator
def custom_metric(y_true, y_pred):
    return mean_absolute_percentage_error(y_true, y_pred)

方案3：处理多指标场景

def composite_metric(y_true, y_pred):
    mae = float(mean_absolute_error(y_true, y_pred))
    mse = float(mean_squared_error(y_true, y_pred))
    return (mae, mse)  # PyCaret 3.0+版本支持元组返回

最佳实践建议

版本兼容性检查：PyCaret 3.0+对指标返回类型更宽容
单元测试验证：单独测试自定义指标函数返回值类型
类型提示：使用Python类型注解明确返回类型

高级调试技巧

当问题仍然存在时，可采用以下诊断方法：

调试方法	操作步骤
类型探查	print(type(metric_result))
源码追踪	from pycaret.utils import check_metric; inspect.getsource(check_metric)

版本差异说明

不同PyCaret版本对指标返回值的处理存在差异：

2.3.x版本：强制要求Python原生float
3.0+版本：接受numpy.float32/64等兼容类型