VS Code中用vLLM加载google/gemma-2b遇401未授权错误

问题概述 #

使用vLLM加载google/gemma-2b模型时，常规终端手动运行脚本可正常加载，但在VS Code集成终端执行时触发401 Unauthorized错误。已做以下尝试：

• 常规终端运行脚本：正常加载模型
• VS Code集成终端运行脚本：报错401
• VS Code终端执行huggingface-cli login完成登录：问题依旧
• 脚本中手动传入Hugging Face Token：仍然报错

推测核心原因是VS Code的环境隔离机制，导致集成终端未继承正确的Hugging Face认证信息。

解决方案 #

1. 检查并同步环境变量 #

在常规终端和VS Code集成终端分别执行：

echo $HUGGING_FACE_HUB_TOKEN

若VS Code终端无输出，说明环境变量未继承：

• 打开VS Code设置，启用Terminal > Integrated > Inherit Env选项，确保集成终端继承系统环境变量
• 或手动在VS Code终端导出Token：

  export HUGGING_FACE_HUB_TOKEN=你的Hugging Face Token
  

2. 确认Hugging Face配置文件权限与路径 #

Hugging Face认证信息默认存储在~/.huggingface/token文件中：

• 检查VS Code是否以当前用户身份启动（避免用sudo打开VS Code，否则会读取root用户的配置）
• 若路径权限有问题，可在脚本中手动指定配置路径：

  import os
  os.environ["HUGGINGFACE_HUB_CACHE"] = "/home/你的用户名/.huggingface"
  

3. 脚本中正确传入Token #

确保vLLM初始化时正确传递Token参数，推荐通过环境变量读取（避免硬编码）：

import os
from vllm import LLM, SamplingParams

hf_token = os.getenv("HUGGING_FACE_HUB_TOKEN")
llm = LLM(model="google/gemma-2b", token=hf_token)
sampling_params = SamplingParams(max_tokens=100)
outputs = llm.generate("Hello, world!", sampling_params)

4. 重置VS Code终端环境 #

• 关闭所有VS Code终端，重启VS Code
• 重新打开终端执行huggingface-cli login，确认登录成功后再运行脚本

日志示例 #

• 错误日志：

  HTTPError: 401 Client Error: Unauthorized for url: https://huggingface.co/google/gemma-2b/resolve/main/config.json
  ValueError: Failed to download model 'google/gemma-2b'. Please check the model name or your authentication credentials.

• 成功运行输出：

  INFO 10-05 14:32:00 llm_engine.py:73] Initializing an LLM engine with config: model='google/gemma-2b', tokenizer='google/gemma-2b', ...
  INFO 10-05 14:32:05 llm_engine.py:204] Loaded model in 4.87 seconds.

内容的提问来源于stack exchange，提问作者Charlie Parker