ktransformers/kt-kernel/python/cli/STANDALONE_VERIFY_README.md

独立模型验证脚本 (Standalone Model Verifier)

这是一个独立的 Python 脚本,用于验证本地模型文件的完整性。它会将本地的 safetensors 文件与 HuggingFace 仓库中的官方 SHA256 校验和进行对比。

功能特性

• ✅ 并行计算本地文件的 SHA256 哈希值 (最多使用 16 个进程)
• ✅ 从 HuggingFace 获取官方 SHA256 校验和
• ✅ 支持私有仓库 (通过 HF_TOKEN 环境变量)
• ✅ 支持 HuggingFace 镜像 (通过 HF_ENDPOINT 环境变量)
• ✅ 详细的验证报告,包括通过/失败/缺失文件统计
• ✅ 可选的详细模式,显示每个文件的完整 SHA256 值

依赖要求

pip install huggingface-hub

使用方法

基本用法

python standalone_verify.py <本地模型路径> <HF仓库ID>

示例

1. 验证公开模型

python standalone_verify.py /path/to/local/model deepseek-ai/DeepSeek-V3

2. 验证特定分支/版本

python standalone_verify.py /path/to/model org/model-name --revision v1.0

3. 详细模式 (显示每个文件的完整 SHA256)

python standalone_verify.py /path/to/model org/model-name --verbose

4. 使用 HF_TOKEN 验证私有模型

export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx
python standalone_verify.py /path/to/model org/private-model

或者一行命令:

HF_TOKEN=hf_xxx python standalone_verify.py /path/to/model org/private-model

5. 使用 HuggingFace 镜像

export HF_ENDPOINT=https://hf-mirror.com
python standalone_verify.py /path/to/model org/model-name

参数说明

位置参数

• local_path: 本地模型目录的路径
• repo_id: HuggingFace 仓库 ID (格式: 组织/模型名, 例如 deepseek-ai/DeepSeek-V3)

可选参数

• --revision, -r: 指定仓库的分支或版本 (默认: main)
• --verbose, -v: 显示详细的 SHA256 对比信息
• --help, -h: 显示帮助信息

环境变量

• HF_TOKEN: HuggingFace API token (用于访问私有仓库)
• HF_ENDPOINT: 自定义 HuggingFace endpoint (例如: https://hf-mirror.com)

输出示例

验证通过

============================================================
Model Integrity Verification
============================================================
Local path:  /path/to/model
Repository:  deepseek-ai/DeepSeek-V3
Revision:    main
============================================================

Fetching file list from deepseek-ai/DeepSeek-V3 (revision: main)...
Found 152 safetensors files
Fetching SHA256 hashes from deepseek-ai/DeepSeek-V3...
✓ Fetched 152 file hashes from remote

Calculating SHA256 for local files...
Using 16 parallel workers for SHA256 calculation
  [1/152] ✓ model-00001-of-00152.safetensors (4985.2 MB)
  [2/152] ✓ model-00002-of-00152.safetensors (4998.1 MB)
  ...
✓ Calculated 152 local file hashes

Comparing 152 files...

  [1/152] ✓ model-00001-of-00152.safetensors
  [2/152] ✓ model-00002-of-00152.safetensors
  ...

============================================================
Verification Summary
============================================================
Total files:   152
✓ Passed:      152
✗ Failed:      0
✗ Missing:     0
============================================================

✅ VERIFICATION PASSED

All files verified successfully!

验证失败

============================================================
Verification Summary
============================================================
Total files:   152
✓ Passed:      150
✗ Failed:      1
✗ Missing:     1
============================================================

Files with hash mismatch:
  - model-00050-of-00152.safetensors

Missing files:
  - model-00151-of-00152.safetensors

❌ VERIFICATION FAILED

Some files are corrupted or missing. Consider re-downloading the model.

退出码

• 0: 验证通过
• 1: 验证失败或发生错误

核心功能说明

脚本的核心验证逻辑包括:

1. 获取远程 SHA256: 使用 huggingface_hub API 从仓库获取所有 safetensors 文件的官方 SHA256 校验和

2. 计算本地 SHA256: 使用多进程并行计算本地文件的 SHA256 哈希值,每个文件分块读取(8MB chunks)以支持大文件

3. 对比校验: 逐个对比本地和远程的 SHA256 值,检测以下问题:

   • 文件缺失
   • SHA256 不匹配 (文件损坏)

4. 生成报告: 输出详细的验证报告,包括每个文件的状态和总体统计

注意事项

• 脚本只验证 .safetensors 文件
• 大模型的 SHA256 计算可能需要几分钟时间
• 使用多进程并行计算可以显著加快速度
• 如果遇到网络问题,建议使用 HF_ENDPOINT 设置镜像地址

故障排除

问题: 连接 HuggingFace 超时

解决方案: 使用镜像

export HF_ENDPOINT=https://hf-mirror.com
python standalone_verify.py /path/to/model org/model-name

问题: 私有仓库访问被拒绝

解决方案: 设置 HF_TOKEN

export HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx
python standalone_verify.py /path/to/model org/private-model

问题: 缺少 huggingface_hub 包

解决方案: 安装依赖

pip install huggingface-hub

与 kt-cli 的关系

这个脚本是从 kt-cli 的 kt model verify 命令中提取出来的核心验证逻辑,去除了 TUI 界面和交互式修复功能,适合:

• 在 CI/CD 流程中进行自动化验证
• 编写自定义的模型管理脚本
• 快速验证模型完整性,无需完整的 kt-cli 环境

如果需要完整的交互式体验和自动修复功能,请使用 kt-cli 的 kt model verify 命令。