litgpt 如何用 --access_token 下载 Llama、Gemma 等需要授权的 Hugging Face 模型

litgpt 如何用 --access_token 下载 Llama、Gemma 等需要授权的 Hugging Face 模型

【免费下载链接】litgpt20+ high-performance LLMs with recipes to pretrain, finetune and deploy at scale.项目地址: https://gitcode.com/GitHub_Trending/li/litgpt

LitGPT 的litgpt download命令可以从 Hugging Face Hub 拉取模型权重并自动转换为 LitGPT 格式，但 Llama、Gemma 等模型在 Hub 上属于需要授权的仓库（gated repo）：Llama 2 要求你先接受 Meta AI 的条款，Gemma 系列要求你在模型页完成访问申请。没有授权时，直接用litgpt download <repo_id>下载会被 Hub 拒绝。本文说明如何申请访问、创建访问令牌，并在下载命令中通过--access_token把令牌传给 litgpt，最后验证权重是否下载并完成转换。

前提：安装 litgpt 并确认要下载的模型

先按 tutorials/0_to_litgpt.md 的方式安装 LitGPT：

pip install 'litgpt[all]'

运行litgpt download list可以列出 LitGPT 支持的全部模型及其repo_id。与本文相关的门控模型在列表中的写法包括google/gemma-2b、meta-llama/Llama-2-7b-hf、meta-llama/Meta-Llama-3.1-8B等。如果你不确定名称拼写，可以先用grep过滤，例如litgpt download list | grep gemma。

申请模型访问权限并创建访问令牌

文档给出的两条申请路径：

• Gemma：按google/gemma-2b模型页面上的步骤申请访问（参见 tutorials/download_model_weights.md 的 “Specific models and access tokens” 一节）。
• Llama 2：需要先在对应模型页接受 Meta AI 的服务条款（参见 tutorials/0_to_litgpt.md）。

访问被批准后，到 Hugging Face 账号的令牌页面创建/查看你的 Hub 令牌。文档中两个位置的描述是同一个入口：settings/tokens页面，或 Model Hub 个人资料下的Profile > Access Tokens菜单。

用 --access_token 下载模型

拿到令牌后，把它通过--access_token传给下载命令。文档中的原始示例（your_hf_token是占位符，替换为你自己的令牌）：

litgpt download google/gemma-2b \ --access_token your_hf_token

文档给出了几个真实命令的写法可供对照：

• Llama 2 只下载 tokenizer（来自 tutorials/pretrain_tinyllama.md）：

litgpt download meta-llama/Llama-2-7b-hf \ --access_token your_hf_token \ --tokenizer_only true

这里同时使用--tokenizer_only true，适合不需要权重、只需 tokenizer 的场景（例如从零预训练时准备 tokenizer）。

• Llama 3.1 8B 完整下载（来自 tutorials/examples/ptl-trainer/README.md）：

litgpt download meta-llama/Meta-Llama-3.1-8B --access_token hf_...

其中hf_...是该文档中的占位写法，使用时替换为你的令牌。

可选替代路径：litgpt/scripts/download.py 中download_from_hub的access_token参数默认读取环境变量HF_TOKEN（os.getenv("HF_TOKEN")），并且脚本报错信息也明确提示可以“set theHF_TOKEN=your_tokenenvironment variable or pass--access_token=your_token”。因此也可以改用环境变量方式：

export HF_TOKEN=your_hf_token litgpt download google/gemma-2b

两种方式二选一即可，令牌本身的获取方式不变。

验证下载结果

litgpt download <repo_id>会把文件存到checkpoints/目录下的<repo_id>子目录，并在下载完成后自动把 checkpoint 转换为 LitGPT 格式。以文档中的 phi-2 为例（文档示例输出，模型与令牌无关，仅展示流程）：

Converting checkpoint files to LitGPT format. Processing checkpoints/microsoft/phi-2/model-00001-of-00002.bin ... Saving converted checkpoint to checkpoints/microsoft/phi-2

出现Saving converted checkpoint to checkpoints/<repo_id>说明转换完成。你可以按文档的做法查看目录内容确认文件齐全：

ls -lh checkpoints/microsoft/phi-2/

文档示例输出如下（phi-2，含转换后的lit_model.pth与model_config.yaml）：

total 11G -rw-r--r-- 1 sebastian sebastian 863 Mar 19 21:14 config.json -rw-r--r-- 1 sebastian sebastian 124 Mar 19 21:14 generation_config.json -rw-r--r-- 1 sebastian sebastian 5.2G Mar 19 21:15 lit_model.pth ... -rw-r--r-- 1 sebastian sebastian 528 Mar 19 21:15 model_config.yaml

最后用chat命令实际运行模型，确认权重可用（<repo_id>换成你下载的模型，如google/gemma-2b）：

litgpt chat <repo_id>

能进入对话界面即说明下载与转换的产物可以正常加载。

下载仍失败时：根据报错信息定位

litgpt/scripts/download.py 的gated_repo_catcher针对门控仓库定义了三种报错，可以按报错文本对号入座：

也就是说，如果传了令牌仍报 gated repo 错误，问题通常出在“访问申请未批准”或“令牌没有覆盖该仓库的权限”，而不是命令写法——此时先回到模型页确认授权状态，再重新执行下载。

可选：在 Python API 中传 access_token

如果走 Python API 而不是命令行，LLM.load也接受access_token参数。litgpt/api.py 的文档说明其为 “Optional API token to access models with restrictions when usinginit="pretrained"”，即模型不在本地、需要从 Hub 自动下载时使用。tutorials/evaluation.md 中的用法示例：

from litgpt import LLM llm = LLM.load("meta-llama/Meta-Llama-3-8B-Instruct", access_token="你的令牌")

同样地，access_token缺省时也会回退读取HF_TOKEN环境变量（见 litgpt/utils.py 中auto_download_checkpoint的实现）。

下载完成后，如果模型在 GPU 显存上吃紧，文档还提供了与令牌无关的--dtype bf16-true选项用于转换时降低精度（见 tutorials/download_model_weights.md 的 “Tips for GPU Memory Limitations”）；这是下载流程之外的显存问题，按需使用。

【免费下载链接】litgpt20+ high-performance LLMs with recipes to pretrain, finetune and deploy at scale.项目地址: https://gitcode.com/GitHub_Trending/li/litgpt