PyTorch/Hugging Face 训练中 int64 序列化错误的深度解决方案在深度学习模型训练过程中特别是使用 PyTorch 和 Hugging Face Transformers 库时经常会遇到TypeError: Object of type int64 is not JSON serializable的错误。这个错误通常发生在训练过程中尝试将 NumPy 的 int64 类型数据序列化为 JSON 格式时。本文将深入探讨这个问题的根源并提供五种实用的解决方案。1. 问题背景与错误分析当使用 Hugging Face 的 Trainer 进行模型训练时系统会自动记录训练指标并保存为 JSON 格式。如果计算指标如准确率、精确率等返回的是 NumPy 的 int64 类型就会触发这个错误。典型错误场景def compute_metrics(eval_pred): predictions, labels eval_pred predictions np.argmax(predictions, axis1) accuracy (predictions labels).sum() # 返回的是numpy.int64 return {accuracy: accuracy} # 这里会报错错误原因Python 的标准 JSON 序列化器无法处理 NumPy 的特殊数据类型Hugging Face 的 Trainer 内部使用 JSON 记录训练日志常见的 NumPy 非 JSON 可序列化类型包括int64、float32、float64 等2. 五种解决方案详解2.1 直接类型转换最简单方案最直接的解决方案是将 NumPy 类型显式转换为 Python 原生类型def compute_metrics(eval_pred): predictions, labels eval_pred predictions np.argmax(predictions, axis1) accuracy int((predictions labels).sum()) # 显式转换为int return {accuracy: accuracy}优点实现简单直接不需要额外代码缺点需要手动处理每个可能返回 NumPy 类型的计算在复杂指标计算时代码会显得冗长2.2 自定义 JSON 编码器创建一个自定义的 JSON 编码器来处理 NumPy 类型import json import numpy as np from transformers import Trainer class NumpyEncoder(json.JSONEncoder): def default(self, obj): if isinstance(obj, np.integer): return int(obj) elif isinstance(obj, np.floating): return float(obj) elif isinstance(obj, np.ndarray): return obj.tolist() else: return super().default(obj) # 在Trainer中使用自定义编码器 trainer Trainer( modelmodel, argstraining_args, train_datasettrain_dataset, eval_dataseteval_dataset, compute_metricscompute_metrics, json_encoderNumpyEncoder # 指定自定义编码器 )优点一次性解决所有 NumPy 类型的序列化问题可扩展性强可以添加更多特殊类型的处理缺点需要了解 Trainer 的高级配置在某些情况下可能影响性能2.3 修改 compute_metrics 返回值在 compute_metrics 函数内部确保所有返回值都是 JSON 可序列化的def compute_metrics(eval_pred): predictions, labels eval_pred predictions np.argmax(predictions, axis1) # 计算各种指标 accuracy np.mean(predictions labels) precision, recall, f1, _ precision_recall_fscore_support( labels, predictions, averagebinary ) # 确保所有值都是Python原生类型 return { accuracy: float(accuracy), precision: float(precision), recall: float(recall), f1: float(f1) }最佳实践对每个返回的数值都进行类型转换使用 float() 处理可能的小数值对于整数使用 int()2.4 使用自定义 TrainerCallback通过 TrainerCallback 在日志记录前转换数据类型from transformers import TrainerCallback class NumpyFixCallback(TrainerCallback): def on_log(self, args, state, control, logsNone, **kwargs): if logs: for k, v in logs.items(): if isinstance(v, (np.integer, np.floating)): logs[k] v.item() # 在Trainer中添加callback trainer Trainer( modelmodel, argstraining_args, train_datasettrain_dataset, eval_dataseteval_dataset, compute_metricscompute_metrics, callbacks[NumpyFixCallback()] # 添加回调 )优势不需要修改 compute_metrics 函数集中处理所有日志数据的类型问题不影响模型训练逻辑2.5 修改日志配置高级方案对于高级用户可以完全自定义日志记录行为from transformers import TrainingArguments # 自定义训练参数 training_args TrainingArguments( output_dir./results, logging_strategysteps, logging_steps10, # 禁用自动的JSON日志记录 disable_json_loggingTrue, # 其他参数... ) # 然后实现自己的日志记录逻辑适用场景需要完全控制日志格式使用自定义的日志系统处理特殊的数据类型需求3. 常见机器学习库返回值类型参考下表总结了常见机器学习库返回的指标数据类型库/方法返回类型JSON可序列化NumPy 聚合函数 (sum, mean)numpy.int64/numpy.float64否sklearn.metrics 函数numpy.float64否evaluate 库的 compute()Python dict with native types是PyTorch tensor.item()Python int/float是Pandas Series.agg()取决于操作可能是numpy类型可能否最佳实践建议优先使用 evaluate 库计算指标对于自定义指标确保最终返回 Python 原生类型在复杂计算流水线中尽早进行类型转换4. 错误排查流程当遇到序列化错误时可以按照以下步骤排查定位错误源头检查错误堆栈确定是哪个指标导致的检查 compute_metrics查看返回字典中的每个值验证类型添加调试打印检查类型print(type(accuracy)) # 检查类型隔离测试单独测试指标计算部分的类型逐步修复应用上述解决方案中最适合的一个5. 高级技巧与注意事项5.1 性能考虑类型转换会带来一定的性能开销特别是在大规模数据上。建议在训练循环外进行尽可能多的预处理避免在 compute_metrics 中进行重复的类型转换对于固定模式的数据可以预先定义转换规则5.2 混合类型处理当处理包含多种类型的复杂数据结构时def convert_types(obj): if isinstance(obj, np.integer): return int(obj) elif isinstance(obj, np.floating): return float(obj) elif isinstance(obj, np.ndarray): return obj.tolist() elif isinstance(obj, dict): return {k: convert_types(v) for k, v in obj.items()} elif isinstance(obj, (list, tuple)): return [convert_types(x) for x in obj] else: return obj5.3 单元测试建议为确保解决方案的可靠性建议添加类型检查的单元测试def test_metrics_serializable(): predictions np.array([[0.1, 0.9], [0.8, 0.2]]) labels np.array([1, 0]) metrics compute_metrics((predictions, labels)) # 测试所有返回值都可JSON序列化 import json try: json.dumps(metrics) except TypeError: pytest.fail(返回值包含不可JSON序列化的类型)在实际项目中这些解决方案可以组合使用根据具体场景选择最合适的方法。关键是要理解数据类型在训练流程中的传递过程并在适当的位置进行类型转换。