跳转至

面向 Hugging Face 算子节点的依赖配置指南

账户准备与访问令牌签发 (Account and Token Creation)

本指南将带你一步步注册 Hugging Face 账号、生成个人访问令牌 (User Access Token)，并拉取安装 Griptape Nodes 所需的本地 AI 权重模型。

已有账号提示

若你已经注册过 Hugging Face 账号，可直接跳过注册，前往 第 2 步：签发访问令牌。

1. 注册 Hugging Face 账户

  1. 访问官网 https://huggingface.co/；
  2. 点击右上角的 Sign Up 注册按钮；
  3. 按照页面引导完成人机安全验证与邮箱确认。

Hugging Face 官网主页

Hugging Face 注册页面

2. 签发访问令牌 (Create an Access Token)

  1. 登录成功后，点击右上角的个人头像图标；

  2. 在下拉菜单中选择 Settings（或直接访问 个人设置中心）；

    Settings 菜单

强制要求邮箱已验证

若在创建 Token 时提示无权限或操作失败，请首先检查注册邮箱是否已完成官方确认邮件验证。必须完成验证后方可签发令牌。

  1. 在左侧设置导航中定位并点击 Access Tokens；

Access Tokens 导航

  1. 点击右上角的 Create new token 按钮；
  2. 令牌权限类型选择 Read（只读权限即可满足下载拉取模型的需求）；

选择 Read 权限

  1. 为令牌赋予一个易于识别的名称（如：GriptapeNodes）；
  2. 点击 Create Token。此时屏幕会弹出包含完整令牌字符串的浮窗——请务必当场复制并妥善保存，因为这是系统唯一一次向你完整展示明文的机会；

复制并保存 Token

  1. 复制并安全妥善保存该 Token；
  2. 点击 Done 关闭弹窗。

安全合规警示

强烈建议将该 Token 存放在专业的密码管理器（如 1Password、Bitwarden）或加密笔记中。该访问令牌代表你个人在 Hugging Face 社区的模型拉取权限，切勿将令牌明文硬编码提交至公共 GitHub 仓库、截图录屏或通过即时通讯软件发送给他人。请像保管银行卡密码一样严肃对待它。

安装依赖环境与拉取权重模型 (Install Required Files)

拥有访问令牌后，你便可安装官方的 Hugging Face CLI 命令行工具，通过终端极速拉取模型。

1. 安装 Hugging Face CLI 命令行客户端

打开系统终端（PowerShell 或 Bash）并执行：

pip install -U "huggingface_hub[cli]"

更多高级用法请参阅 Hugging Face CLI 官方开发文档。

2. 通过 Token 登录终端授权

在终端中执行鉴权指令：

huggingface-cli login

在交互式提示中粘贴你刚刚创建的 Access Token 并回车确认（当询问是否将 Token 附加至 Git 凭据时可选择 Y）。

3. 按需拉取对应的 AI 模型

各个 Hugging Face 相关算子节点分别绑定了特定的底模。部分算子专为单一模型打造，部分则兼容多种架构：

算子节点名称 兼容的官方底模
SPAN Upscale 4x-ClearRealityV1.pth
Flux FLUX.1-dev, FLUX.1-schnell
Flux Post Upscale FLUX.1-dev, FLUX.1-schnell

模型下载策略权衡考量 (Model Installation Considerations)

模型安装主要有两种策略，具体取决于你的创作需求、磁盘剩余空间与带宽网速：

  1. 按需精准安装 (Selective Installation)：仅下载当前工作流实际需要的单一模型。
    • 优点：节省初次拉取等待时间与固态硬盘空间；
    • 缺点：若后续工作流引用新算子，需要再次暂停下载。
  2. 全量一次性安装 (Complete Installation)：将所有常用模型全部预先下载至本地。
    • 优点：开箱即用，所有画布算子均可瞬间秒级加载运行；
    • 缺点：初次准备阶段耗时较长，对磁盘容量门槛较高。

下载耗时提醒

这些主流扩散与高清模型文件体积普遍较大（单体权重通常在 5GB~25GB 不等）。根据你的网络物理带宽，下载全量模型可能需要耗费 30 分钟到数小时不等。在后台拉取模型的同时，你可以继续完成下方的 Griptape Nodes 设置步骤。

缓存落盘路径查询

模型会被统一下载至 Hugging Face Hub 的全局系统缓存区。若需确认具体物理路径，可在终端执行：

huggingface-cli env

在输出的诊断信息中找到以 - HF_HUB_CACHE: 开头的行，例如：

- HF_HUB_CACHE: C:\Users\Username\.cache\huggingface\hub

拉取 SPAN Upscale 4x 高清放大模型

huggingface-cli download skbhadra/ClearRealityV1 4x-ClearRealityV1.pth

拉取 FLUX.1-schnell 极速扩散模型

huggingface-cli download black-forest-labs/FLUX.1-schnell

拉取 FLUX.1-dev 电影级画质扩散模型

huggingface-cli download black-forest-labs/FLUX.1-dev

受限模型 (Gated Repo) 权限申请

在尝试拉取某些开源模型（如 FLUX.1 系列）时，终端可能会弹出如下权限拒绝报错：

Cannot access gated repo for url https://huggingface.co...

报错信息的末尾会贴心地附带一个官方权限申请网页链接。请遵循指引：

访问对应的主页（例如 https://huggingface.co/black-forest-labs/FLUX.1-schnell），在页面中阅读使用协议并点击申请同意。一旦通过授权，网页会显示已获得授权，此时重新在终端执行下载命令即可畅通拉取。

Gated 受限模型许可确认

将 Hugging Face Token 登记至 Griptape Nodes 全局配置中

概览

完成账号准备与模型拉取后，需将访问 Token 登记进 Griptape Nodes，以便引擎具备合法的鉴权通道。

1. 打开 Griptape Nodes 设置菜单

  1. 启动并进入 Griptape Nodes 编辑器；
  2. 在顶部主菜单栏中点击 Settings 打开配置窗口。

Settings 菜单

2. 在 API Keys & Secrets 中登记 Token

  1. 在左侧配置树状分类中，找到并展开 API Keys and Secrets；
  2. 向下滚动定位至 HUGGINGFACE_HUB_ACCESS_TOKEN 字段；
  3. 将前面生成的 Access Token 字符串粘贴至该输入框；
  4. 直接关闭配置编辑器窗口——配置将全自动持久化落盘并即刻生效。

在配置编辑器中登记 Hugging Face Token

配置全部就绪

完成上述配置后，画布中所有基于 Hugging Face 生态的扩散生成与超分辨率放大算子即可完全无阻碍正常运行！