- 人工智能
- 大模型
- 模型优化
- 模型量化
- 模型压缩
【免费下载链接】Model-Optimizer
A unified library of SOTA model optimization techniques like quantization, distillation, pruning, neural architecture search, speculative decoding, etc. It compresses deep learning models for downstream deployment frameworks like TensorRT-LLM, TensorRT, vLLM, etc. to optimize inference speed.
本指南基于 Model-Optimizer 仓库中 credentials.md 编写，系统讲解 ModelOpt 量化（PTQ）、部署、评测与 SLURM 集群作业等典型工作流在本地与集群环境中所需的全部凭据配置：HuggingFace Token（HF_TOKEN）、NGC API Key 与 Docker Hub 登录。读完本文，你将掌握凭据的存量检查、两种持久化方式、NGC$oauthtoken特殊机制，以及缺失凭据时的典型故障定位方法，让srun --container-image、PTQ 校准数据下载等环节不再被 401 卡住。
凭据在 ModelOpt 工作流中的角色
Model-Optimizer 是一个统一的大模型优化库，覆盖量化、蒸馏、剪枝、NAS、投机解码等技术的完整流程。这些流程往往横跨本地工作站与远端 GPU 集群：
- PTQ（后训练量化）需要从 HuggingFace 拉取预训练模型与校准数据集，其中不少是gated（受限）资源；
- 量化、评测、部署通常跑在 Docker 或 SLURM 容器中，需要从NGC（
nvcr.io）或 Docker Hub 拉取镜像； - day-0 发布工作流（量化 → 评测 → 对比 → 发布决策）在正式启动 PTQ 之前，会先经过Setup 门禁，其中就包含凭据检查。
该文档被 PTQ、部署、评测与 slurm-setup 等多个 skill 交叉引用，属于公共支撑文件。在 day0-release 的 Step 1 Setup 门禁中明确规定：先确认凭据与集群可达性，任一环节失败即判SYSTEMIC并停止，绝不带着缺失的凭据启动 PTQ。
第一步：先检查环境里已有的凭据
配置任何东西之前，先确认用户机器上是否已有凭据——大多数情况下，hf auth login、docker login或之前的 SLURM 工作已经留下了配置。凡是已存在的项，直接跳过对应小节。
# HF token：环境变量，或来自 `hf auth login` 的持久化文件 [ -n "$HF_TOKEN" ] && echo "✓ HF_TOKEN set in env" [ -s ~/.cache/huggingface/token ] && echo "✓ HF token at ~/.cache/huggingface/token (from 'hf auth login')" # Docker / NGC 注册表凭据 grep -qE '"(nvcr\.io|https://index\.docker\.io)"' ~/.docker/config.json 2>/dev/null && echo "✓ Docker login present" # Enroot / pyxis 凭据（集群登录节点上，面向 SLURM 用户） grep -qE '^machine nvcr\.io ' ~/.config/enroot/.credentials 2>/dev/null && echo "✓ Enroot NGC entry present"关键认知：远程集群的凭据存放在集群上，而非你的工作站上。对于远程集群，通过 SSH 执行同样的检查（ssh <cluster-login> '<check>'）。这一原则在 environment-setup.md 与 remote-execution.md 中反复强调：工作站文件系统与集群存储并不互通，凭据、检查点都需要按各自所在环境单独确认。
HuggingFace Token（HF_TOKEN）
何时必需
HF_TOKEN是获取两类 gated 资源的凭证：
- 受限模型：如 Llama、Mistral 以及部分 Nemotron 变体；
- 受限数据集：如 GPQA、HLE 等评测/校准数据。
仓库中的实际消费点可以印证这一点。在 examples/hf_ptq/slurm/multinode_fsdp2_ptq.slurm 中明确注释：export HF_TOKEN={hf_token} # required for gated repos (or huggingface-cli login on host)；PTQ skill 也专门提示"某些校准数据集需要 HF 认证，请在作业环境中设置HF_TOKEN"。此外，PTQ 推荐的nemotron-post-training-v3校准数据混合体以及--calib_with_images所用的 VLM 数据集都属于代表性 gated 数据，缺少凭据时只能退回到cnn_dailymail这类公共数据作为兜底方案。
生成与两种持久化方式
在 https://huggingface.co/settings/tokens 生成 token。两种持久化方式可任选其一，也可同时使用：
方式一：hf auth login（推荐用于交互式使用）
pip install -U huggingface_hub hf auth login # 交互式粘贴 tokentoken 被写入~/.cache/huggingface/token。HuggingFace Python 客户端会自动读取该文件——transformers、datasets以及hfCLI 都直接使用此文件，无需在环境变量中再设HF_TOKEN。仓库的校准 notebook（examples/hf_ptq/notebooks/1_FP4-FP8_PTQ_Min-Max_Calibration.ipynb）同样演示了通过huggingface_hub.login()完成认证的方式。
方式二：环境变量（适合脚本、CI 与远程会话）
export HF_TOKEN=hf_...持久化到~/.bashrc或项目本地的.env文件中。注意：当两种方式同时存在时，HF_TOKEN环境变量优先。
仓库中远程评测配置也沿用了这一约定：evaluation skill 的recipes/env.example模板即为HF_TOKEN=hf_...，而 SLURM 作业中通过env_vars: { HF_TOKEN: host:HF_TOKEN }将宿主机环境变量透传给作业容器（详见 evaluation/references/slurm.md）。
NGC API Key（用于nvcr.io）
何时必需
拉取 NGC 镜像（nvcr.io/nvidia/pytorch:...、nvcr.io/nvidia/vllm:...）时必需，无论通过 Docker、srun --container-image还是 enroot。在 https://ngc.nvidia.com/setup/api-key 生成 API Key。
Docker 方式
docker login nvcr.io -u '$oauthtoken' -p <NGC_API_KEY>Enroot 方式（SLURM / pyxis）
在集群上的~/.config/enroot/.credentials中添加一条记录。该文件可能已包含其他注册表的凭据——务必追加而不是覆盖：
mkdir -p ~/.config/enroot CREDS=~/.config/enroot/.credentials touch "$CREDS" grep -q '^machine nvcr.io ' "$CREDS" || \ echo 'machine nvcr.io login $oauthtoken password <NGC_API_KEY>' >> "$CREDS" chmod 600 "$CREDS"关键陷阱：
$oauthtoken是 NGC 要求的字面字符串，不是 shell 变量。不要替换它，也不要让 shell 展开它——上面命令中的单引号正是为了保持字面值。
如果缺失此配置，srun --container-image=nvcr.io/...会在计算节点拉取镜像时报401 Unauthorized。这一点在 slurm-setup.md 中得到了直接呼应：pyxis/enroot 需要集群~/.config/enroot/.credentials中的注册表凭据，缺少时srun即失败。SLURM 场景中更稳妥的写法是通过 heredoc 追加多行格式：
cat >> ~/.config/enroot/.credentials << 'EOF' machine nvcr.io login $oauthtoken password <ngc_api_key> EOFDocker Hub 登录
仅当拉取公共镜像遇到速率限制时才需要：
docker login公共镜像拉取受 Docker Hub 限制（免费额度约每 6 小时每 IP 100 次拉取）。值得注意的是，slurm-setup 的故障排查表提示：如果 Docker Hub 认证缺失或触发限流，首选方案是改用 NGC 托管的替代镜像——NVIDIA 集群通常已预置 NGC 认证。例如vllm/vllm-openai:latest可替换为nvcr.io/nvidia/vllm:<YY.MM>-py3（NGC 镜像标签遵循YY.MM-py3格式，如26.03-py3）。不是所有 Docker Hub 镜像都有 NGC 等价物，此时要么补充 Docker Hub 凭据，要么将镜像预缓存为.sqsh文件。
凭据速查表
| 凭据 | 用途 | 设置方式 |
|---|---|---|
HF_TOKEN | Gated HF 模型 / 数据集 | 环境变量（export HF_TOKEN=...）或.env文件 |
| NGC API Key | nvcr.io镜像拉取 | docker login或~/.config/enroot/.credentials |
| Docker Hub | 公共镜像拉取限流规避 | docker login |
源码视角：凭据如何被工作流消费
从仓库源码结构看，凭据体系贯穿了整条自动化链路，可以归纳出三个核心消费场景：
1. PTQ 校准的数据访问。examples/hf_ptq/hf_ptq.py 是文本 LLM 与 VLM 量化的入口脚本，--dataset nemotron-post-training-v3与--calib_with_images均依赖 HF 认证。多节点 SLURM 脚本（examples/hf_ptq/slurm/multinode_fsdp2_ptq.slurm）则同时示范了"宿主机hf auth login"与"作业内export HF_TOKEN"两种传递方式。
2. 容器镜像拉取。slurm-setup.md 的容器注册表认证一节提供了完整的运行时检测与凭据核查流程：先which enroot/which docker判断运行时，再按镜像 URI 前缀（nvcr.io、vllm/vllm-openai、ghcr.io、docker.io）判断所需注册表，最后分别检查~/.config/enroot/.credentials与~/.docker/config.json。提交作业之前必须确认凭据存在——否则作业会在排队后于拉取阶段失败，浪费队列资源。
3. 门禁化的发布流水线。day0-release/SKILL.md 将凭据检查设为 Step 1 Setup 门禁的组成部分，失败即SYSTEMIC中止；ptq/SKILL.md 则要求 gated 数据集通过HF_TOKEN注入作业环境。这两处共同说明：凭据不是"锦上添花"的配置，而是决定流水线能否启动的前置条件。
远程集群的凭据检查
由于集群凭据只存在于集群上，正确的核查姿势是借助 remote-execution.md 描述的 SSH 持久会话执行远端检查：
source "$SKILL_DIR/remote_exec.sh" remote_load_cluster <cluster_name> remote_run 'grep -E "^\s*machine\s+" ~/.config/enroot/.credentials 2>/dev/null' remote_run 'cat ~/.docker/config.json 2>/dev/null | python3 -c "import json,sys; print(chr(10).join(json.load(sys.stdin).get(chr(97)+chr(117)+chr(116)+chr(104)+chr(115), {}).keys()))"'检查要点：enroot 凭据应出现machine nvcr.io（NGC）、machine auth.docker.io（Docker Hub）或machine ghcr.io（GHCR）行；Docker 凭据则应出现nvcr.io、https://index.docker.io/v1/、ghcr.io等 registry 键。
常见故障与定位
| 症状 | 涉及环节 | 根因 | 修复 |
|---|---|---|---|
curl: (22) ... error: 401 | enroot 拉取 | 注册表无凭据 | 向~/.config/enroot/.credentials追加对应machine条目 |
pyxis: failed to import docker image | enroot 拉取 | 认证失败或触发限流 | 核查凭据；Docker Hub 免费额度为每 IP 6 小时 100 次拉取 |
unauthorized: authentication required | docker 拉取 | 未执行docker login | 运行docker login [registry] |
GatedRepoError: 403 | HF 模型/数据集下载 | 未接受许可或缺少HF_TOKEN | 在 HF 上接受许可，并在deployment.env_vars与evaluation[].env_vars中同时设置HF_TOKEN |
| 部分节点能拉、部分节点失败 | 任意 | 镜像仅缓存在单个节点 | 预缓存镜像，或确保所有节点均有认证 |
最后一条经验同样来自仓库：注册表存在凭据，不代表具体镜像一定可拉取——镜像可能不存在，或凭据缺乏对该仓库的权限。提交作业前可用enroot import --output /dev/null docker://<registry>#<image>、docker manifest inspect <image>等方式验证镜像确实可拉取，避免"凭据齐全却镜像 404"的二次踩坑。
- 人工智能
- 大模型
- 模型优化
- 模型量化
- 模型压缩
【免费下载链接】Model-Optimizer
A unified library of SOTA model optimization techniques like quantization, distillation, pruning, neural architecture search, speculative decoding, etc. It compresses deep learning models for downstream deployment frameworks like TensorRT-LLM, TensorRT, vLLM, etc. to optimize inference speed.
相关推荐
SwiftPM `swift package-registry` 命令完全指南：注册表配置、凭据认证与包发布实战
SwiftPM swift package registry 命令完全指南：注册表配置、凭据认证与包发布实战 Swift Package Manager 从 S
开发工具构建工具mRemoteNG 凭据注册表设置指南：通过注册表锁定导出、保存与默认凭据行为
mRemoteNG 凭据注册表设置指南：通过注册表锁定导出、保存与默认凭据行为 mRemoteNG 作为一款开源的多协议远程连接管理器，允许用户通过 Windo
桌面应用网络OpenTofu 使用 OCI 注册表时的认证配置指南：环境凭据自动发现与显式配置
OpenTofu 使用 OCI 注册表时的认证配置指南：环境凭据自动发现与显式配置 本篇指南围绕 OpenTofu 通过 OCI 注册表（OCI Registr
云原生DevOps基础设施
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
