Transformers 安全加载指南：safetensors 权重校验、trust_remote_code 远程代码风险与漏洞报告机制

Transformers 安全加载指南safetensors 权重校验、trust_remote_code 远程代码风险与漏洞报告机制【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers本文基于 Transformers 仓库的 SECURITY.md 安全策略文档展开系统讲解从 Hugging Face Hub 加载他人上传的模型权重与模型代码时存在的两类核心风险——不安全格式的权重文件如 pickle和可执行任意逻辑的远程建模代码并结合src/transformers/modeling_utils.py、src/transformers/dynamic_module_utils.py的源码实现说明use_safetensors、trust_remote_code、revision三个关键参数的实际行为帮助你在生产环境中构建一套可复制的安全模型加载流程并掌握 Transformers 项目漏洞的正确报告渠道。安全策略总览模型与代码都来自远端SECURITY.md 开宗明义地指出Transformers 是开源软件且与 Hugging Face Hub 深度耦合。虽然你可以离线使用预先下载的模型权重但该库最大的便利正是一行代码从远端下载、使用和管理模型。文档对此给出了明确的安全前提When downloading artefacts that have been uploaded by others on any platform, you expose yourself to risks.从源码结构看这一风险分为两条独立的链路权重链路Remote artefactsfrom_pretrained解析并反序列化他人上传的权重文件。若权重以 pickle 等可执行序列化格式存储加载即意味着执行其中任意字节码可能导致任意的代码执行。代码链路Remote code对于 Transformers 尚未内置的架构模型仓库会附带自定义的modeling.py等模块文件加载时会动态下载并 import 到当前 Python 进程中执行。下面的章节分别沿这两条链路展开先给出 SECURITY.md 的官方建议再用仓库源码印证参数在不同取值下的真实行为。远程权重工件为什么必须优先 safetensors官方建议SECURITY.md 的 Remote artefacts 一节给出的核心建议是上传和下载模型时强烈推荐使用safetensors格式。文档特别说明这是 the default prioritized by the transformers library且该格式被专门开发以防止在你的系统上执行任意代码为避免从不安全格式例如 pickle加载模型应使用use_safetensors参数设置为该模式后若仓库中不存在.safetensors文件transformers 会在加载模型时直接报错而不是静默回退到不安全的.bin文件。源码印证use_safetensors的三种取值与解析优先级在from_pretrained的参数文档中use_safetensors被定义为bool类型、默认值为None见 modeling_utils.py。真正的解析发生在权重解析函数_get_resolved_checkpoint_files中modeling_utils.py其行为可以概括为取值本地目录场景的行为远端仓库场景的行为use_safetensorsTrue只查找model.safetensors/model.safetensors.index.json找不到即抛出OSError同上仓库完全没有 safetensors 文件时抛出 cannot be loaded withsafetensors. Please do not setuse_safetensorsTrue 的错误use_safetensorsFalse只查找pytorch_model.bin及其分片索引只查找pytorch_model.bin绝不触碰 safetensors 文件use_safetensorsNone默认优先查找 safetensors 文件找不到再回退到.bin优先下载 safetensors若远端仓库根本没有 safetensors 文件会自动回退到pytorch_model.bin关键代码路径如下modeling_utils.py本地目录加载时use_safetensors is not False分支先检查model.safetensors与分片索引model.safetensors.index.jsonnot use_safetensors分支才检查pytorch_model.bin而当use_safetensors显式为True且两种 safetensors 文件都不存在时直接raise OSError(...)modeling_utils.py——这正是 SECURITY.md 所说no .safetensors file is present, transformers will error when loading the model的实现。远端仓库加载时modeling_utils.py先按model.safetensors请求缓存文件未命中再试分片索引仍找不到且use_safetensorsTrue时抛出OSError。值得注意的是在use_safetensorsNone的默认模式下如果仓库只有 PyTorch 权重代码会触发auto_conversion定义于 safetensors_conversion.py尝试请求自动转换转换失败才回退到pytorch_model.bin。也就是说默认优先 safetensors 在实现层面是双重的既优先请求 safetensors 文件也在可行时把旧格式权重转换为 safetensors 缓存。可复制的安全加载示例结合文档建议与上述实现一个符合官方安全推荐的加载方式如下from transformers import AutoModelForCausalLM # 仅接受 safetensors仓库中没有 .safetensors 文件时直接报错 # 从机制上杜绝加载 picklepytorch_model.bin带来的反序列化风险 model AutoModelForCausalLM.from_pretrained( some-user/some-model, use_safetensorsTrue, # 若为 None默认则会回退到 .bin 权重 revisionv1.0.0, # 锁定特定版本见下文 )需要说明的适用前提use_safetensorsTrue只保证不会加载 pickle 权重它无法防护模型仓库中携带的自定义建模代码——那属于下面一节的远程代码风险。远程代码trust_remote_codeTrue的使用纪律官方建议SECURITY.md 的 Remote code / Modeling 一节指出Transformers 支持大量模型架构但它同时也是你的 Python 运行时与 Hub 上模型仓库之间的桥梁。对于这类携带自定义代码的模型必须设置trust_remote_codeTrue才能使用在使用该参数时务必always核验建模文件的内容官方推荐同时指定revision以确保你受到保护免受仓库后续更新的影响。源码印证远程代码的判定与执行链路仓库中处理远程代码的入口集中在 dynamic_module_utils.py。整条链路可以概括为判定是否信任 → 下载并缓存模块 → 动态 import 执行判定层resolve_trust_remote_codedynamic_module_utils.py该函数解析trust_remote_code参数默认值为None。其逻辑是当检测到模型带有远程代码has_remote_code但本地无对应代码not has_local_code且用户未显式传trust_remote_codeTrue时抛出错误提示 Please pass the argumenttrust_remote_codeTrueto allow custom code to be run.dynamic_module_utils.py在交互式终端且未显式设置时会打印警告并弹出Do you wish to run the custom code? [y/N]提示用户拒绝则按False处理dynamic_module_utils.py。从源码结构看这意味着默认行为是拒绝执行远程代码——安全性靠的是显式 opt-in而不是默认放行。下载与执行层get_cached_module_file/get_class_from_dynamic_moduleget_cached_module_filedynamic_module_utils.py负责把仓库中的模块文件如modeling_xxx.py经cached_file下载到模块缓存目录HF_MODULES_CACHE随后动态导入。get_class_from_dynamic_moduledynamic_module_utils.py的文档警告写得非常直白Calling this function will execute the code in the module file found locally or downloaded from the Hub. It should therefore only be called on trusted repos.也就是说一旦信任链被打开仓库里的.py文件会在你的进程中原样执行——这正是 SECURITY.md 要求always verify the content of the modeling files的底层原因。此外get_cached_module_file在下载后还会执行check_imports(resolved_module_file)dynamic_module_utils.py检查该模块引入的第三方依赖这也是审计自定义代码时需要留意的一个环节。revision锁定层get_cached_module_file与get_class_from_dynamic_module均接受revision参数dynamic_module_utils.py且其文档明确 revision can be a branch name, a tag name, or a commit id。权重解析侧同样以revision默认main见 modeling_utils.py作为下载基准。指定 revision 后权重与建模代码都被固定到同一提交点避免了 main 分支被上游修改导致行为漂移或被篡改 的风险——这与 SECURITY.md 的推荐一一对应。可复制的远程代码加载流程综合 SECURITY.md 的纪律与源码行为加载含自定义代码的模型建议按以下步骤操作from transformers import AutoModelForCausalLM, AutoTokenizer repo some-user/custom-arch-model # 第 1 步在 Hub 页面上人工审查仓库中的 modeling_*.py / configuration_*.py 内容 # 第 2 步以锁定 revision 的方式显式信任加载 model AutoModelForCausalLM.from_pretrained( repo, trust_remote_codeTrue, # 必须先审查建模文件再开启 revisionmain, # 或某个 commit id / tag防止仓库更新影响复现 )要点复述trust_remote_codeTrue不是随便传一下而是在确认建模代码无害之后才允许的显式授权而revision是抵御仓库事后被改的唯一版本锚点两者应配套使用。漏洞报告渠道SECURITY.md 的 Reporting a Vulnerability 一节给出了两条官方渠道通用漏洞提交至securityhuggingface.co由 Hugging Face 安全团队审阅并给出后续步骤建议开源软件专项漏洞注意Huntr是面向开源软件的漏洞披露项目vulnerability disclosure program针对开源部分的漏洞可走该渠道报告。如果你的问题是某个模型仓库中的自定义代码可疑更恰当的做法是不加载该代码不设置trust_remote_codeTrue并向该仓库/平台报告而不是在生产环境中执行后再排查。安全检查清单把 SECURITY.md 的建议浓缩为一张可执行的加载前检查表检查项官方依据实现位置仓库权重是否为 safetensors 格式加载时传use_safetensorsTrue以拒绝 pickle 权重Remote artefacts 一节_get_resolved_checkpoint_filesmodeling_utils.py是否包含自定义建模代码若包含是否已逐行审查modeling_*.pyRemote code 一节get_class_from_dynamic_module执行警告dynamic_module_utils.py开启trust_remote_code前是否理解执行任意模块代码的含义源码文档警告dynamic_module_utils.py是否通过revision锁定权重与代码版本抵御仓库更新We recommend setting a revisionrevision参数dynamic_module_utils.py发现疑似漏洞时的上报路径Reporting a Vulnerability 一节SECURITY.md一句话总结在 Transformers 中安全不是单一参数能解决的而是safetensors 权重 拒绝默认 pickle 回退use_safetensorsTrue 人工审查远程代码 显式trust_remote_codeTruerevision版本锁定这五件事的组合上述组合在当前仓库的加载实现中均有对应的代码路径可以逐条验证。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考