Hugging Face Hub Pickle文件安全扫描完整教程
在HuggingFace平台中，Pickle文件反序列化存在代码执行风险。通过文件和版本页面查看pickle标签及安全/不安全状态，点开不安全文件查看HFPicklescan等扫描结果，区分安全、无问题与不是模型，并单独查看Pickle导入。切勿下载或运行标记为不安全的文件。
在 Hugging Face Hub 的模型仓库中，如果看到 pickle 标签，不要将其视为普通的文件类型标记。Pickle 是一种基于操作码的序列化格式，反序列化时可能导入模块、调用内置函数，甚至直接执行文件中的代码。首次查看这类文件时，不要把绿色的 Safe 当作绝对安全的保证。正确做法是先找到对应文件，理解 HF Picklescan 给出的导入结论，再决定是否继续信任该文件。
这里使用 Hugging Face 团队成员维护的公开测试仓库进行演示。整个过程只在 Hub 页面操作，不下载也不反序列化测试文件。公开仓库无需登录即可访问，私有或受限仓库则需要读取权限。提前准备好目标仓库地址、要核对的分支或修订版本，并确认浏览器能正常打开 Files and versions 页面即可。
明确 Pickle 扫描范围
入口位置：打开目标模型仓库，点击仓库名称下方的 Files and versions 进入。文件表格位于分支选择器和提交信息的下方。
主要操作：逐行查看文件名右侧的 pickle 标签，并将其与 Safe、Unsafe 状态对应。扫描范围不限于扩展名为 pkl 的文件，测试仓库中的 pytorch_model.bin 和 danger.dat 也带有 pickle 标签。
成功标志：已列出所有带 pickle 标签的文件，并记住当前所在分支。红色 Unsafe 表示需要停下来仔细查看详情；灰绿色 Safe 仅说明本次扫描未发现问题，不代表文件永远安全。
失败处理：若只看到 Model card，说明未进入文件页面。若文件旁无状态显示，可能是扫描仍在进行、处于排队状态或出现异常。稍等片刻后刷新当前修订版本再查看，不要将空白状态当作扫描通过。
此图首先关注文件名右侧的 pickle 标签，用于指示“哪些文件需要按 Pickle 风险检查”；Safe 或 Unsafe 仅显示当前扫描状态。这两类标签不能互相替代。
查看 Unsafe 文件的完整扫描面板
入口位置：在 Files and versions 表格中，打开一个标有 Unsafe 且带有 pickle 标签的文件。以 danger.dat 为例，状态按钮位于文件操作栏右侧。
主要操作：点击 Unsafe，展开 File Security Scans 面板。先核对面板顶部文件名是否正确，然后逐行查看每个扫描器的结果和说明。此例中，JFrog、Protect AI 和 HF Picklescan 均显示 Unsafe，ClamAV 还显示可疑代码执行签名；HF Picklescan 的说明是文件包含可能不安全的导入。
成功标志：能说清是哪个文件、哪个扫描器、哪条结果触发了警告，而非仅记得红色标签。看到 HF Picklescan 报 Unsafe 后，不再下载和运行该文件。
失败处理：若点击后面板未展开，确认点击的是操作栏内的 Unsafe，而非页面上的普通文字。若面板底部被屏幕遮挡，向下滚动页面，直至 HF Picklescan 那一行和说明完整显示；不要只看面板上半部分就猜测 Pickle 结论。
此图最关键的是最下方 HF Picklescan 的 Unsafe 结果及“可能不安全的导入”说明。上方其他扫描器结果可作为交叉佐证，但无法替代 Pickle 导入检查本身。
对照 Safe 文件理解结果含义
入口位置：返回同一仓库的文件表格，打开带有 pickle 标签、状态为 Safe 的 pytorch_model.bin，然后点击操作栏内的 Safe。
主要操作：在 File Security Scans 面板中找到 HF Picklescan 项。当前公开样本显示 No issue；VirusTotal、Protect AI 和 ClamAV 也显示 No issue，而 JFrog 显示 not a model。
成功标志：能区分三种不同信息：Safe 是文件整体汇总状态，No issue 是单个扫描器未发现问题，not a model 说明该项检查不适用。三者均不代表“文件已被证明绝对安全”。
失败处理：若面板内文件名与目标文件不符，关闭面板并重新进入正确文件。若某个扫描器未显示 No issue，按页面实际显示记录，不要自行补充结论；若有新提交，需重新核对当前修订版本。
此安全样本图用于辅助校准解读：HF Picklescan 的 No issue 仅说明扫描器在当前文件中未发现问题，JFrog 的 not a model 也只说明该检查不适用，两者不可混为一谈。
单独查看 Pickle 导入情况
入口位置：打开任意带 pickle 标签的文件详情页，在 Safe 或 Unsafe 状态旁找到 pickle 按钮。以 supposedly_safe.pkl 为例。
主要操作：点击 pickle 标签，展开 Pickle imports 面板。该测试文件当前显示 No problematic imports detected，即导入扫描未发现被列为有问题的导入项。
成功标志：弹出的面板标题为 Pickle imports，内容与当前文件对应。将此结果与 File Security Scans 结果分开理解：前者专门显示 Pickle 导入信息，后者是多个安全扫描器的汇总结果。
失败处理：若点击后未弹出面板，先确认文件确实带有 pickle 标签，然后重新加载文件详情页。若面板列出具体导入项或警告，不要在自己电脑上反序列化“验证”；应依据文件来源、发布者和当前修订版本信息判断，或选择可信替代文件，或干脆不用。
这里的 No problematic imports detected 仅是一次静态导入检查的结果，可用于排除已知可疑导入，但无法替代对仓库作者、提交历史及文件用途的信任判断。
扫描器检测内容
官方说明指出，Hub 会对 pytorch_model.bin 等 Pickle 文件运行 Pickle Import 扫描，并将检测到的导入项显示在文件旁。扫描使用 Python 标准库中的 pickletools.genops 读取操作码，不会实际执行被检查的 Pickle 文件。这也是为何仅通过网页即可看到导入线索，而无需将可疑文件下载到本地。
风险主要出现在反序列化阶段。Pickle 的操作码既能导入模块，也可能通过 eval、exec 等内置功能执行代码。扫描器可识别部分危险信号，但官方明确表示并非万无一失。即使页面显示 Safe 或 No issue，仍需确认文件来自可信发布者、当前修订版本未被替换，且不运行用途不明的文件。
完成检查清单
- 已进入 Files and versions 页面，并记住当前分支或修订版本。
- 已找出所有带 pickle 标签的文件，未仅按扩展名筛选。
- Unsafe 文件已展开 File Security Scans 面板，并阅读 HF Picklescan 的具体说明。
- Safe 文件已展开扫描面板，能区分 Safe、No issue 和 not a model 的含义。
- 已点击 pickle 标签查看 Pickle imports，未将“未发现有问题导入”当作绝对安全。
- 状态缺失时已等待并刷新，未将空白状态当作扫描通过。
- 未下载、运行或反序列化被标记为 Unsafe 的文件。
- 4 张步骤截图均能正常打开，分别对应文件范围、危险结果、安全对照和导入详情四部分。