使用HuggingFace Trainer搭配Ray Tune时报_thread.RLock序列化错误

TypeError: can't pickle _thread.RLock objects错误本质是Ray在调度超参数搜索任务时，需要把Trainer相关对象序列化后分发到多进程worker，此时遇到了不可序列化的线程锁对象。
Colab环境运行无报错是因为Colab默认单节点单进程运行Ray任务，不需要跨进程传递对象，跳过了序列化校验；远程服务器上Ray默认启动多进程调度，触发了校验逻辑。

常见触发场景：

• 全局作用域初始化了带线程锁的对象，比如全局日志器、未关闭的IO连接、tqdm进度条实例，或是自定义模型/数据集类内部内嵌了RLock属性
• transformers与Ray版本不兼容，低版本transformers的Ray集成层存在未处理的不可序列化字段
• 传入Trainer的自定义回调、评估函数持有不可序列化的对象

• 优先做版本兼容校验，这是90%同类问题的解：执行pip install --upgrade transformers ray[tune]，保证transformers>=4.21.0、Ray>=1.13.0
• 所有Trainer依赖的对象（模型、数据集、回调、评估函数等）都放到model_init函数内部初始化，不要在全局作用域定义。如果用到WandbCallback、MLflowCallback等第三方回调，也放在model_init内初始化后传入Trainer
• 调用hyperparameter_search前手动初始化Ray，添加序列化兼容配置：

import ray
ray.init(
    _system_config={
        "pickle_5_to_4": True,
        "enable_metrics_collection": False
    },
    include_dashboard=False
)

同时在hyperparameter_search参数中添加local_dir="./ray_results", log_to_file=True，避免日志对象被序列化

• 调试阶段可以强制Ray单进程运行验证逻辑：设置环境变量export RAY_DISABLE_LIBUV=1，并在hyperparameter_search参数中传入resources_per_trial={"cpu": 1, "gpu": 0}（按需调整GPU配置）

内容的提问来源于stack exchange，提问作者Grid