라이브러리 (Libraries)

라이브러리(library)는 에디터에서 사용할 수 있는 노드들의 모음 번들입니다. 일부는 엔진과 함께 제공되며, 일부는 Git URL에서 설치하고, 일부는 직접 작성할 수도 있습니다. 이 페이지는 라이브러리를 직접 개발하는 개발자가 아닌, 라이브러리를 설치하고 사용하는 아티스트를 위한 문서입니다. (라이브러리 개발자라면 커스텀 노드 가이드 및 워커를 통한 노드 격리를 참조하세요.)

두 라이브러리가 충돌할까 걱정된다면 공존 보장 섹션으로 이동하세요. 요약하자면 두 라이브러리의 Python 의존성은 서로 영향을 주지 않지만, 동일한 노드 이름을 가진 두 라이브러리는 모호할 수 있으며 엔진이 이에 대해 알려줍니다.

시작 시 제공되는 라이브러리 (What you start with)

엔진은 전체 라이브러리를 작성하지 않고도 자체 커스텀 노드를 신속하게 개발할 수 있는 스크래치패드 라이브러리인 샌드박스 라이브러리(Sandbox Library)를 지원합니다. 이는 설정하기 전까지는 존재하지 않습니다. Settings → Library → Sandbox Settings에서 Sandbox Library Directory를 디스크에 존재하는 폴더로 지정하세요. 설정이 완료되면 엔진이 해당 디렉터리에서 .py 노드 파일을 가져오며, 에디터의 Sandbox 카테고리에 표시되는 내용은 해당 디렉터리에 실제로 존재하는 파일에 따라 달라집니다.

샌드박스 라이브러리는 저장한 워크플로우를 노드로 바꿀 수도 있습니다. 아래의 워크플로우를 노드로 만들기를 참조하세요.

gtn init을 실행하는 동안 Advanced Media Library(디퓨전, 이미지 생성, 비디오)를 추가할 것인지 묻는 메시지가 표시됩니다. 이때 등록하거나 나중에 gtn init을 다시 실행하여 추가할 수 있습니다. 해당 경로는 FAQ를 참조하세요.

기타 라이브러리(퍼스트 파티 또는 커뮤니티 라이브러리)는 에디터를 통해 직접 설치합니다.

라이브러리 설치하기 (에디터 내)

에디터의 Libraries 패널이 기본 설치 인터페이스입니다. 헤더의 Manage 메뉴 → Library Management에서 엽니다.

Add Library(우측 상단)를 클릭하여 Add Library 모달을 엽니다. Git URL(예: 커뮤니티 라이브러리를 호스팅하는 GitHub 리포지토리)을 붙여넣고 Install을 클릭합니다. 에디터가 리포지토리를 클론하고 라이브러리의 griptape_nodes_library.json 매니페스트를 읽고 의존성을 설치한 후 등록합니다. 모달의 Advanced Options를 사용하면 리포지토리 기본값 대신 특정 브랜치, 태그 또는 커밋을 선택할 수 있습니다.

무엇을 설치해야 할지 잘 모르겠다면 모달 하단의 Browse Community Libraries 버튼을 클릭하여 설치 가능한 엄선된 라이브러리 목록을 확인하세요.

성공적으로 설치되면 새 라이브러리가 패널의 라이브러리 목록에 표시됩니다. 각 항목에는 다음이 표시됩니다:

라이브러리 이름 및 버전.
제공하는 노드의 수.
파일 관리자에서 라이브러리 디렉터리를 여는 Open 동작.
라이브러리의 Git 원격(remote), 참조(ref, 브랜치 또는 태그), 현재 커밋을 보여주는 Advanced 펼침 메뉴. 버그를 보고해야 하는 경우 여기에 표시된 커밋이 인용할 정확한 버전입니다.

상단의 칩을 사용하여 목록을 All, Updates, Errors별로 필터링할 수 있습니다. Errors는 라이브러리 중 하나에 문제가 발생했을 때 가장 먼저 확인해야 하는 위치로, 설치 실패, 의존성 설치 실패, 로드 시간 실패를 함께 표시합니다.

라이브러리 업데이트

동일한 Libraries 패널에서 필터 칩 옆의 아이콘 버튼을 사용하여 다음을 수행할 수 있습니다:

Check for updates — 설치된 모든 라이브러리에서 새 버전을 검색합니다. 업데이트가 있는 모든 항목은 Updates 필터 아래에 나타납니다.
Refresh — 라이브러리 목록을 다시 읽습니다(방금 무언가를 설치하고 제대로 적용되었는지 확인하려는 경우 유용함).

상시 업데이트 확인을 위해 Configuration Editor → Libraries에서 엔진이 자체적으로 라이브러리 업데이트를 얼마나 적극적으로 확인할지 제어할 수 있습니다.

Update Notifications 옵션:

Enable sidebar notifications — 업데이트가 있을 때 Libraries 탭과 라이브러리별 버튼에 배지를 표시합니다.
Notification color / animation — 배지의 시각적 스타일.
Check on startup — 엔진이 로드될 때마다 업데이트를 검색합니다.
Check periodically — 반복 일정 (Never, Hourly 등).
Check Now — 즉시 검색을 트리거합니다.

이러한 항목을 반드시 구성할 필요는 없으며 대부분의 아티스트에게 기본값으로 충분합니다.

라이브러리 토글 및 제거

동일한 Configuration Editor → Libraries 뷰에는 Library Registration → Libraries To Register도 표시됩니다. 해당 목록의 각 항목은 엔진이 시작 시 로드하는 라이브러리입니다. 항목당 2개의 컨트롤이 있습니다:

토글 (왼쪽) — 디스크에 라이브러리를 유지하되 엔진 시작 시 로드를 중지하려면 끕니다.
휴지통 아이콘 (오른쪽) — 항목을 완전히 제거합니다. 디스크의 클론은 그대로 유지되므로 디스크 공간을 확보하려면 해당 디렉터리를 수동으로 삭제하세요.

라이브러리의 노드가 어디에서 실행되는지는 설정 항목이 아닙니다. 라이브러리는 실행 중에만 필요한 의존성을 선언하며, 엔진은 이를 기준으로 실행 위치를 정합니다. 아래의 프로세스 격리를 참조하세요.

아래의 Add Library 버튼을 사용하면 이미 디스크에 있는 griptape_nodes_library.json(수동으로 클론한 라이브러리 또는 로컬에서 개발 중인 라이브러리)을 엔진에 지정할 수 있습니다.

공존 보장 (Coexistence guarantees)

두 라이브러리를 나란히 설치하는 목적은 서로에게 영향을 주지 않도록 하는 것입니다. 이를 보장하기 위해 세 가지 레이어가 작동합니다:

Python 의존성 격리

등록된 모든 라이브러리는 고유한 가상 환경(virtual environment)을 갖습니다. 이는 엔진 자체 패키지나 다른 라이브러리와 상태를 공유하지 않는 격리된 Python 패키지 세트입니다. 라이브러리 A는 torch==2.4.1을 고정할 수 있고 라이브러리 B는 torch==2.0.0을 고정할 수 있습니다. 둘 다 별도의 .venv 디렉터리에 설치되며 각 라이브러리는 해당 노드가 실행될 때 자체 가상 환경을 사용합니다.

이는 라이브러리의 노드가 실행되는 위치와 관계없이 동일하게 유지됩니다(프로세스 격리 참조). 어느 방식이든 .venv는 디스크의 라이브러리 매니페스트 옆에 위치합니다. 유일한 차이점은 해당 패키지를 로드하는 프로세스입니다. 아티스트의 관점에서 의존성 격리는 동일합니다.

pip 버전 충돌 없이 호환되지 않는 버전이 고정된 라이브러리들을 함께 설치할 수 있습니다. 이것이 이 페이지에서 가장 중요한 보장 사항입니다.

편집 시점 의존성과 실행 의존성 (Edit-time vs. execution dependencies)

라이브러리는 매니페스트에서 의존성을 두 집합으로 나눌 수 있습니다:

pip_dependencies — 편집 시점(edit-time): 에디터에 라이브러리의 노드를 표시하고, 캔버스에 배치하고, 파라미터를 편집하는 데 필요한 의존성입니다. 이 집합은 가볍게 유지하세요.
pip_dependencies_exec — 실행(execution): 노드가 실행될 때만 필요한 무거운 패키지(torch, diffusers 등)입니다.

실행 의존성은 별도의 환경(라이브러리의 .venv 옆에 있는 .venv-exec)에 설치되며, 노드가 실제로 실행되는 프로세스에서만 로드됩니다. 메인 엔진 프로세스에서는 절대 로드되지 않습니다. 따라서 라이브러리는 수 기가바이트 규모의 ML 스택에 의존하면서도 에디터는 가볍게 유지할 수 있고, 무거운 패키지 고정 버전이 충돌하는 두 라이브러리도 나란히 편집할 수 있습니다.

실행 의존성을 선언하지 않는 것은 항상 안전합니다. 모든 의존성이 편집 시점 의존성으로 취급되며, 라이브러리는 단일 환경 라이브러리로 설치되고 실행됩니다.

실행 의존성을 선언하면 달라지는 점 (What declaring execution dependencies changes)

실행 의존성을 선언한 라이브러리는 다음 세 가지 측면에서 다르게 동작합니다:

노드가 라이브러리 자체 프로세스에서 실행됩니다. 메인 엔진은 노드를 표시, 편집, 저장할 수 있습니다(편집 시점 의존성을 가지고 있으므로). 그러나 노드의 실행은 무거운 패키지가 있는 프로세스에서 이루어집니다. 해당 프로세스가 아직 시작되지 않았다면, 노드를 실행할 때 이상한 오류 없이 그 사실을 알려줍니다.
노드 코드는 상태를 직접 읽는 대신 엔진에 요청합니다. process() 내부에서 관리자(설정, 시크릿, 파일)에 직접 접근하면, 대신 사용해야 할 요청을 알려주는 오류가 발생합니다. 라이브러리 프로세스는 자체 설정이나 시크릿을 가지고 있지 않으므로, 직접 읽으면 잘못된 곳에서 답을 받게 됩니다. 정적 파일 저장은 평소와 같이 작동합니다.
일반 데이터 형식이 없는 값은 이를 생성한 프로세스에 남습니다. 직렬화할 수 없는 출력(라이브 모델 핸들, 텐서 등)에 serializable=False를 표시하면, 엔진은 해당 객체를 라이브러리 프로세스에 그대로 두고 다음 노드에는 그 객체를 가리키는 참조를 보냅니다. 일반 데이터 형식이 없는데 표시되지 않은 출력은 해당 출력의 이름을 밝히는 오류와 함께 노드를 실패시킵니다.

프로세스 격리 (Process Isolation)

실행 의존성을 선언한 라이브러리는 자체 프로세스에서 노드를 실행하며, 다음과 같은 이점이 있습니다:

내결함성(Fault tolerance): 노드를 실행하는 중에 라이브러리가 충돌하더라도 해당 라이브러리만 중단되고 엔진의 나머지 부분은 계속 실행됩니다.
리소스 격리: 라이브러리가 메모리에 로드하는 모든 항목(모델 가중치, GPU 메모리, 백그라운드 스레드)은 라이브러리 자체 프로세스에 상주하며 다른 라이브러리의 성능을 저하시킬 수 없습니다.

무거운 ML 라이브러리(디퓨전, 트랜스포머, 커스텀 CUDA 스택)가 실행 의존성을 선언하며, 가벼운 라이브러리(단순 HTTP / 데이터 노드)는 선언할 실행 의존성이 없으므로 메인 엔진 프로세스에서 실행됩니다. 이는 라이브러리 작성자가 griptape_nodes_library.json에서 결정하며, 스키마는 워커를 통한 노드 격리를 참조하세요. 아티스트가 설정할 항목은 없습니다.

노드 이름 충돌: 해결되지 않음

두 라이브러리가 동일한 이름의 노드 클래스를 등록하는 경우(예: 둘 다 MyImageNode를 제공함), 엔진은 둘 다 수락합니다. 엔진은 설치 시 경고를 표시하지 않습니다. 해당 노드를 생성할 때:

워크플로우에서 라이브러리를 명시적으로 지정하면 정상 작동합니다.
그렇지 않은 경우 엔진은 모호성을 해결할 수 있도록 두 라이브러리를 나열하는 오류를 발생시킵니다.

이것은 엔진이 사용자를 대신해 해결해주지 않는 유일한 공존 관련 문제입니다. 충돌이 의심되는 경우 가장 안전한 해결책은 원하지 않는 라이브러리를 Libraries To Register 목록에서 제거하는 것입니다.

문제 해결 (When something goes wrong)

"라이브러리를 설치했지만 해당 노드가 보이지 않습니다"

Libraries 패널을 열고 필터를 Errors로 전환합니다. 이는 설치 실패, 의존성 설치 실패 또는 로드 실패가 발생한 모든 라이브러리의 통합 뷰입니다. 특정 오류 메시지를 보려면 해당 라이브러리를 클릭하세요.

일반적인 원인:

라이브러리가 사용자의 Python 버전 또는 플랫폼용으로 존재하지 않는 휠(wheel, 사전 빌드된 Python 패키지)을 고정함(예: 지원되지 않는 CUDA 버전용 torch 휠).
네트워크에서 설치를 차단함(회사 프록시 또는 설치 단계 중 인터넷 연결 없음).
디스크 공간 부족(엔진이 이를 명시적으로 보고함).

근본적인 문제를 해결한 다음 설치를 다시 트리거하세요(Add Library 모달에서 URL을 다시 붙여넣거나 아래 CLI 대안에서 --overwrite 사용).

"라이브러리가 설치 또는 업데이트 후 작동을 멈췄습니다" (A library stopped working after an install or update)

라이브러리의 Python 패키지가 손상될 수 있습니다. 설치가 중간에 중단되었거나, 업데이트가 실패했거나, Griptape Nodes 외부에서 패키지가 변경된 경우입니다. Libraries 패널에서 라이브러리 행의 Reset을 누르세요. Errors 필터에 있는 라이브러리에도 표시됩니다. Reset은 라이브러리의 가상 환경(.venv와 .venv-exec)을 삭제하고 패키지를 다시 설치합니다. 라이브러리 파일과 설정은 그대로 유지됩니다.

Reset은 라이브러리 패키지를 다시 다운로드하므로, 무거운 라이브러리는 시간이 조금 걸릴 수 있습니다. 엔진이 이미 라이브러리의 패키지를 로드했다면 실행 중에는 교체할 수 없습니다. 이 경우 Reset은 다음번 엔진 시작 시 완료되며, Griptape Nodes는 엔진을 다시 시작하라고 안내합니다. 스튜디오 환경이 제공하는 라이브러리는 여기에서 Reset할 수 없습니다. 해당 환경을 설정한 담당자에게 문의하세요.

"에디터에서 노드가 깨졌거나 빨간색으로 표시됩니다"

엔진이 해당 노드를 생성할 수 없었음을 의미하며, 대개 라이브러리 로드에 실패했기 때문입니다. 워크플로우 파일이 손상되지 않도록 에디터가 플레이스홀더로 교체합니다. Libraries 패널의 Errors 필터에서 근본적인 로드 오류를 확인하세요. 문제를 해결한 후 워크플로우를 다시 열면 실제 노드가 다시 사용됩니다.

원시 오류 텍스트 확인하기

엔진이 실행 중인 터미널 창(엔진을 실행한 창)에는 스택 추적을 포함한 자세한 오류 로그가 표시됩니다. 라이브러리 자체 프로세스에서 노드를 실행하는 동안 발생한 오류는 Worker-<id> 접두사와 함께 나타납니다.

CLI 대안

자동화, 헤드리스 엔진 또는 개인적 선호로 인해 명령줄을 사용하려는 경우 에디터의 라이브러리 동작에 해당하는 gtn 명령어가 있습니다:

에디터 동작	CLI 명령어
Add Library → Install	`gtn libraries download <git_url>`
Check for updates → install pending	`gtn libraries sync`
Sync over local edits	`gtn libraries sync --overwrite`
Advanced Media Library 재등록	`gtn init`, `y` 응답

전체 레퍼런스는 명령줄 인터페이스를 참조하세요.

워크플로우를 노드로 만들기 (Turning a workflow into a node)

샌드박스 폴더(Settings → Library → Sandbox Settings의 Sandbox Library Directory)에 넣은 저장된 워크플로우는 모두 노드 선택기에 노드로 나타납니다. Sandbox Library의 Sandbox 제목 아래, 해당 폴더에서 개발 중인 커스텀 노드 옆에 표시됩니다. 개발 중인 다른 노드와 마찬가지로 취급하세요. 안정화되면 별도의 라이브러리로 옮길 수 있습니다.

워크플로우가 노드가 되려면 Start Flow 노드와 End Flow 노드가 있어야 합니다. Start Flow 노드의 파라미터는 노드의 입력이 되고, End Flow 노드의 파라미터는 노드의 출력이 됩니다. 따라서 노드에 연결한 값이 워크플로우에 전달되고, 워크플로우가 마지막에 내놓은 값이 노드의 출력으로 전달됩니다.

노드 이름은 워크플로우 이름에서 가져옵니다. 예를 들어 shout_workflow는 ShoutWorkflow가 됩니다. 노드 선택기에 표시되는 표시 이름과 설명은 워크플로우 자체의 이름과 설명에서 가져옵니다.

참고할 사항은 다음과 같습니다:

변경 사항은 라이브러리를 로드할 때 나타납니다. 샌드박스 폴더는 엔진이 시작될 때와 Refresh Libraries를 선택할 때마다 읽습니다. 그 사이에 워크플로우를 추가, 수정, 삭제해도 다음 읽기 전까지는 반영되지 않습니다.
워크플로우 이름을 바꾸면 다른 노드가 됩니다. 노드 이름이 워크플로우 이름에서 오므로, 이름을 바꾸면 새 노드가 생깁니다. 이전 노드를 사용하던 워크플로우는 더 이상 그 노드를 찾을 수 없습니다.
게시해도 워크플로우가 함께 전달되지는 않습니다. 이 노드를 사용하는 워크플로우는, 노드 뒤에 있는 워크플로우가 함께 있지 않으면 다른 설치 환경에서 실행되지 않습니다.
문제는 Libraries 패널에 표시됩니다. 워크플로우를 노드로 만들 수 없는 경우(Start Flow 또는 End Flow 노드가 없거나 저장된 세부 정보를 읽을 수 없는 경우), Libraries 패널의 Sandbox Library 항목에 그 이유가 표시됩니다. 문제를 해결하고 저장한 다음 Refresh Libraries를 선택하세요.
워크플로우와 커스텀 노드는 같은 이름을 쓸 수 없습니다. 워크플로우의 노드 이름이 샌드박스의 커스텀 노드와 같으면, 워크플로우의 노드가 그 이름을 가지고 커스텀 노드는 목록에서 빠집니다. Sandbox Library 항목에 이름 중복 문제가 표시됩니다. 둘 중 하나의 이름을 바꾸고 Refresh Libraries를 선택하세요.

디스크의 라이브러리 저장 위치

구성(Config): ~/.config/griptape_nodes/griptape_nodes_config.json(또는 플랫폼에 해당하는 파일 — 엔진 설정 참조). 내부의 app_events.on_app_initialization_complete.libraries_to_register 목록이 에디터의 Libraries To Register 목록이 편집하는 대상입니다.
클론 / 가상 환경(venvs): 에디터가 라이브러리를 클론한 디렉터리 내부. 라이브러리의 .venv는 griptape_nodes_library.json 옆에 있습니다.
샌드박스 라이브러리: 샌드박스 디렉터리는 설정에서 별도로 구성됩니다. 기본값은 플랫폼에 따라 다릅니다.

프로젝트를 특정 라이브러리 버전에 고정하려면(활성화 시 일치하도록 라이브러리를 프로비저닝하고 필요한 경우 덮어씀) 엔진 및 라이브러리 버전 고정을 참조하세요.

라이브러리 작성자를 위한 안내: 커스텀 노드 및 워커를 통한 노드 격리를 참조하세요.