跳转至

常见问题答疑 (Frequently Asked Questions)

遇到具体报错或异常？

如果你正在排查某个具体的错误弹窗或异常，请参阅 故障排错指南 (Troubleshooting)，了解高频报错的根因与恢复方案。

我的工作区在哪里（文件保存在哪里）？

所有保存的工作流文件、项目以及中间资产均保存在工作区目录 (Workspace Directory) 中。

你可以随时在 Griptape Nodes 编辑器中查看当前的工作区路径：

  1. 打开 Griptape Nodes 编辑器；
  2. 打开任意工作流或新建空白工作流；
  3. 点击顶部的 Settings（设置）；
  4. 选择 Configuration Editor（配置编辑器）；
  5. 点击最左侧一列中的 Griptape Nodes Settings（若尚未选中）；
  6. 在右侧面板中即可查看 Workspace Directory 对应的物理磁盘路径。

如果你当前未启动编辑器，也可以在命令行终端中运行以下命令直接查询工作区路径：

gtn config show | grep workspace

执行引擎与编辑器可以运行在不同的机器上吗？

完全可以。 后端引擎与前端编辑器完全解耦，支持跨机器分布式运行。需要注意的是：你保存的任何工作流文件以及注册的算子库，均物理存储在运行后端引擎的机器上。因此，如果你在画布上发现找不到先前保存的文件，请首先确认你的浏览器当前连接的是哪一台物理机器上运行的引擎实例。

Griptape Nodes 的程序安装目录在哪里？

如果你需要定位 Griptape Nodes 在本机的确切安装路径，可以运行以下命令进行精准探测：

=== "macOS / Linux"

```bash
dirname $(dirname $(readlink -f $(which griptape-nodes)))
```

=== "Windows (PowerShell)"

```powershell
Split-Path (Split-Path (Get-Command griptape-nodes).Source)
```

我可以查看或编辑底层的配置文件吗？

在编辑器中，点击顶部菜单栏的 Settings，然后选择 Copy Path to Settings（复制设置文件路径）。系统会将配置文件的绝对路径自动复制到你的系统剪贴板中。

如果你习惯使用命令行终端，直接运行以下命令即可打印全量配置：

gtn config show

初始引导跳过后，后续如何补充安装 Advanced Media 算子库？

关于算子库的全局安装与生命周期治理（包括非 Advanced Media 的第三方库），请参阅 算子库管理手册。

如果你在初次安装配置时跳过了 Advanced Media 库，后续可以随时通过在终端运行以下命令重新唤起引导：

gtn init

此命令将重新进入初始化交互流程。直接按回车（Enter）保持你现有的工作区与 Griptape Cloud API Key 配置不变。当控制台弹出以下确认提示时：

Register Advanced Media Library? [y/n] (n):

键入 y 回车即可自动安装该库；键入 n 则跳过。

模型权重额外准备

Advanced Media 算子库中的部分专业节点依赖特定的深度学习模型权重。这些权重需要根据需要单独下载配置。请参阅各算子节点的官方技术文档获取具体的模型规格要求与下载链接。

Advanced Media 算子库中被弃用的旧节点去哪儿了？

在版本 0.64.0 中，官方彻底清理并移除了 Advanced Media 库中先前已被标记为弃用 (Deprecated) 的旧算子节点，并全面替换为更轻量、模块化程度更高的全新架构。

如果你的历史工作流中仍包含这些旧节点，请参阅官方开源仓库中的 MIGRATION.md 迁移指南。该指南提供了：

  • 详尽的被废弃节点与全新替代节点的 1:1 对照矩阵；
  • 图文分步迁移指导教程；
  • 替代节点的工作流连线拓扑示例；
  • 全新 Diffusion Pipeline Builder（扩散模型流水线构建器）架构详解。

该迁移指南完整覆盖了图像处理、扩散流水线装配、高画质超分辨率放大 (Upscaling) 以及 LoRA 注入等所有被重构的节点体系。

如何彻底卸载清理 Griptape Nodes？

请参阅 卸载 Griptape Nodes 指南。

如何将 Griptape Nodes 升级至最新版本？

在命令行模式下，Griptape Nodes 在每次启动运行时均会自动检查是否有可用更新。若检测到新版本，控制台会弹出 (y/n) 升级确认提示。输入 y 即可自动执行平滑升级。

如果你希望主动手动升级，随时可以在终端中运行以下命令：

griptape-nodes self update
griptape-nodes libraries sync

或使用简写别名命令：

gtn self update
gtn libraries sync

如何提交反馈或与官方社区交流？

你可以通过以下渠道随时联系团队与全球社区开发者：

这些链接也常驻在每一篇官方文档右下角的底部导航图标中。

如何尝鲜体验尚未发布的预览版特性？

如果你希望提前测试未发布的最新前沿特性，可以切换安装 Griptape Nodes 的预发布预览版 (Pre-release)。

预览版稳定性风险提示

预发布构建版未经过全面的生产级回归测试，可能包含未知的缺陷 (Bugs) 或处于半成品的未完工特性。请自担风险并在非生产环境中进行测试评估。

如果你使用的是 Griptape Nodes Desktop 桌面客户端，只需在应用设置 (App Settings) 中将 Release Channel 切换为 Nightly 即可。Nightly 每夜版本每日自动打包构建，将前沿引擎与前沿编辑器一并封装分发。你可以随时在设置中一键切回 Stable 稳定版，无需重新下载安装。

如果你是通过命令行独立安装引擎，预发布引擎版本每天会两次自动打包发布至 GitHub 的 latest Release Tag 标签下。

运行以下命令即可切换至预发布构建版：

uv tool uninstall griptape-nodes
uv tool install git+https://github.com/griptape-ai/griptape-nodes.git@latest --reinstall --force --python 3.12

该命令将卸载当前的 Griptape Nodes 引擎，并从 GitHub 仓库拉取最新提交进行强行构建安装。

工作区与工程不受影响

执行 uv tool uninstall griptape-nodes 仅仅卸载执行引擎的 Python 虚拟环境，绝不会删除或破坏你现有的任何项目工程、工作流文件或设置数据。

安装完成后，运行 gtn self version 进行验证。此时输出的版本号会明确附带 Git Commit 哈希标识：

gtn self version
v0.31.0 (git - e172e80)

后续若需切回官方正式稳定版，重新运行标准安装命令即可：

uv tool uninstall griptape-nodes
uv tool install griptape-nodes