跳转至

Hugging Face Token 设置

VoiceStudio 每次模型下载、许可证门禁检查以及显式的 立即测试 操作都使用同一个 HF Token。本页介绍 VoiceStudio 查找 Token 的三个位置，以及 v0.3+ 的推荐方式。

三个来源（级联）

VoiceStudio 按优先级顺序遍历三个来源来解析当前使用的 HF Token——第一个拥有 Token 且通过实时 whoami 调用的来源胜出：

  1. 应用 —— 加密存储在 VoiceStudio 的 SQLite 设置存储中。 通过应用内 设置 → 凭据 面板设置。
  2. 环境 —— 对 VoiceStudio 进程可见的 HF_TOKEN（或旧版 HUGGING_FACE_HUB_TOKEN）环境变量。
  3. HF CLI —— 由 huggingface-cli login 写入的本地 HF_TOKEN_PATH 文件（通常是 ~/.cache/huggingface/token）。

引导流程和设置中的来源标签遵循所选 UI 语言；产品名称（如 HuggingFace CLI）保持不变。

打开 设置 → 凭据 时，每一行都会显示本地已设置/未设置状态和掩码预览（hf_…3jw）。在您选择 立即测试 之前，Token 会一直显示为 未测试。该显式检查会显示 whoami 用户名，并为有效来源显示绿色对勾，同时在优先级最高的有效来源上显示 活动 徽章。

  1. 打开 设置 → 凭据。
  2. 粘贴您的 HF Token（可从 huggingface.co/settings/tokens 获取——“read”范围就足够了）。
  3. 点击 保存。Token 在静态存储时会被加密（Fernet 对称 AEAD，密钥按安装实例从机器标识符派生），同时也会写入标准的 huggingface_hub Token 位置，以便子进程引擎自动获取。
  4. 选择 立即测试 以使用 Hugging Face 验证 Token。测试成功后，指示器会变绿，并将 活动 徽章移到“应用”。

已知限制（如实说明）： 加密密钥按安装实例从机器标识符派生。 如果你将 omnivoice_data/ 复制到其他机器，settings 中的 Token 行将无法在新机器上解密 ——解析器会记录警告并回退到环境变量 / CLI 来源。 请在新机器上重新保存 Token，以使用新安装的密钥重新加密。

通过环境变量设置（高级用户）

如果你从终端或 CI 启动 VoiceStudio，并更倾向于用环境变量管理，请在 shell 启动文件中导出 HF_TOKEN：

# macOS (zsh — default since 10.15)
echo 'export HF_TOKEN=hf_yourtokenhere' >> ~/.zshrc && source ~/.zshrc

# Linux (bash)
echo 'export HF_TOKEN=hf_yourtokenhere' >> ~/.bashrc && source ~/.bashrc

Windows PowerShell —— 写入用户级环境变量：

[Environment]::SetEnvironmentVariable("HF_TOKEN","hf_yourtokenhere","User")

该设置对新开的 shell 持久生效。关闭并重新打开 PowerShell 或终端即可看到。

不要使用 setx。 setx HF_TOKEN "hf_..." 会写入变量，但 不会传播到当前 shell ——“我设置了，但它却是空的”这类 bug 报告通常源于此。请使用应用内 设置 → 凭据 路径，或上面那行 [Environment]::SetEnvironmentVariable 命令。

通过 huggingface-cli 设置

如果你已经在使用 HuggingFace CLI：

pip install --upgrade huggingface_hub
huggingface-cli login
# paste token at the prompt

这通常会写入 ~/.cache/huggingface/token。VoiceStudio 会直接读取选定的本地 Token 文件——你会看到 设置 → 凭据 中的 HF CLI 行变为“已设置”。

接受模型许可证

有些模型需要同时具备 Token 并且点击接受许可证，下载才能正常工作。请使用同一个 HF 账号登录后访问以下各页面：

  • pyannote/speaker-diarization-3.1 —— 进行说话人分离（diarization）所必需。参见 docs/features/diarization.md。
  • pyannote/segmentation-3.0 —— 上述模型间接依赖所必需。
  • IndexTeam/IndexTTS-2.5 —— 如果你使用 IndexTTS 2.5 进行语音克隆，则必需接受。
  • Supertone/supertonic-3 —— 如果你启用 Supertonic-3 引擎，则必需接受。
  • kyutai/pocket-tts —— 如果你启用 PocketTTS，则必需接受；请先在 Hugging Face 上接受其访问条件，然后使用同一账号的 Token。

在每页点击 “同意并访问仓库” 后，请重启任何正在进行的 VoiceStudio 任务（门禁检查会在进程生命周期内缓存）。

故障排除

  • 即使已设置 Token 也出现 HF 401 —— 请访问模型的 HuggingFace 页面并接受许可证（见上文）。Token 本身没问题；许可证门禁是独立的。
  • 点击“立即测试”后 Token 行仍为红色 —— whoami 调用失败。请检查 Token 在 huggingface.co/settings/tokens 是否有效，并且至少具有“read”范围。
  • Token 重启后消失 —— 打开 设置 → 凭据 并检查“应用”行。如果为空，可能是 SQLite 存储被清空——请重新保存。如果已设置，但活动来源是“环境”或“HF CLI”，这是级联机制按预期工作的表现（“应用”优先级最高）。

打开引导流程或设置只会读取本地 Token 的存在状态和掩码预览，不会联系 Hugging Face。未经测试的 Token 会显示为 未测试；引导流程会报告 Token 在何处被发现，但不会声称其有效。立即测试 会显式联系 Hugging Face。替换已保存的 Token 不会撤销 Hugging Face 上之前的 Token。

Windows 会自动缩短模型缓存路径，同时保留正常的 CLI Token 位置。如果只存在之前 VoiceStudio 的短缓存 Token，应用会继续使用该文件。已存在的正常 CLI Token 优先；显式的 Token 或缓存覆盖设置仍然具有最高权威。凭据绝不会在这些位置之间复制。

CLI 行只读取选定的本地文件，不进行 OAuth 刷新，也不回退到环境 Token。同时清除已保存的 HuggingFace CLI Token 文件 会删除已识别自动位置中的活动 Token 文件和已存储 Token 文件，因此旧版应用的 Token 不会在重启后重新出现。显式覆盖会将清除范围限制在其所选位置。仅清除应用 Token 会保留 CLI 文件；这两种操作都不会撤销 Hugging Face 上的 Token，也不会更改 Git 凭据。如果发生文件权限失败，会报告错误，而不是声称文件已被清除。

如果引导流程无法读取令牌状态，它会显示错误和重试，并在发现成功之前保持令牌输入项隐藏。替换令牌通过与设置相同的端点写入加密的应用令牌，因此即使已有旧凭据存在，它也会替换最高优先级的应用凭据。成功消息仅确认保存；验证仍然是单独的显式操作。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 om/VoiceStudio