8.4. 플러그인 관리¶
Backend.AI GO는 서드파티 또는 사용자 정의 플러그인으로 애플리케이션 기능을 확장할 수 있는 플러그인 시스템을 지원합니다. 이 가이드에서는 플러그인 페이지를 통해 플러그인을 관리하는 방법을 설명합니다.
미리보기 기능
플러그인 시스템은 현재 미리보기 단계입니다. 플러그인 로드, 라이프사이클 관리, 오류 격리, 플러그인 SDK가 구현되어 있습니다. 공개 레지스트리를 통한 플러그인 배포는 향후 릴리스에서 제공될 예정입니다.
개요¶
플러그인은 Backend.AI GO에 다음과 같은 추가 기능을 제공합니다:
- 향상된 채팅 포맷팅 및 구문 강조
- 모델 분석 및 성능 모니터링
- 커스텀 테마 및 UI 수정
- 데이터 내보내기 기능
- 서드파티 서비스 연동
플러그인 페이지 접근¶
사이드바의 플랫폼 섹션에서 플러그인 페이지로 이동할 수 있습니다. 여기서 다음 작업을 수행할 수 있습니다:
- 설치된 모든 플러그인 보기
- 플러그인 활성화 또는 비활성화
- 플러그인 설정 구성
- 새 플러그인 설치
- 더 이상 필요하지 않은 플러그인 제거
기본 제공 플러그인¶
Backend.AI GO는 애플리케이션 시작 시 자동으로 설치 및 업데이트되는 기본 제공 플러그인을 포함하고 있습니다. 이러한 플러그인은 플러그인 카드에 기본 제공 배지로 표시됩니다.
기본 제공 플러그인의 특징:
- 최초 실행 시 자동으로 설치됩니다
- 새 애플리케이션 버전에 최신 플러그인 버전이 포함되면 자동으로 업데이트됩니다
- 다른 플러그인과 마찬가지로 활성화 또는 비활성화할 수 있습니다
- 제거할 수 없습니다 (제거 버튼이 숨겨져 있습니다)
- 업데이트 시 활성화/비활성화 설정이 보존됩니다
Companion Chat 플러그인이 기본 제공 플러그인으로 포함되어 있으며, 페르소나 커스터마이징 및 메모리 통합 기능을 갖춘 AI 어시스턴트 인터페이스를 제공합니다.
플러그인 카테고리¶
플러그인은 다음 카테고리로 분류됩니다:
| 카테고리 | 설명 |
|---|---|
| UI | 사용자 인터페이스 개선, 테마 및 시각적 수정 |
| 모델 | 모델 관련 도구, 분석 및 성능 모니터링 |
| 데이터 | 데이터 관리, 내보내기 및 변환 도구 |
| 연동 | 서드파티 서비스 연동 |
| 유틸리티 | 범용 유틸리티 및 도구 |
플러그인 관리¶
플러그인 활성화 및 비활성화¶
각 플러그인 카드에는 플러그인을 활성화하거나 비활성화하는 토글 스위치가 표시됩니다:
- 관리할 플러그인을 찾습니다
- 토글 스위치를 클릭하여 상태를 변경합니다
- 활성화된 플러그인은 "활성화됨" 섹션에 표시됩니다
- 비활성화된 플러그인은 "비활성화됨" 섹션에 표시됩니다
플러그인 설정¶
많은 플러그인이 구성 가능한 설정을 제공합니다. 플러그인 설정에 접근하려면:
- 플러그인 카드의 설정 버튼(톱니바퀴 아이콘)을 클릭합니다
- 설정 모달에서 사용 가능한 설정을 수정합니다
- 저장을 클릭하여 변경 사항을 적용하거나, 취소를 클릭하여 변경 사항을 버립니다
설정에는 다음이 포함될 수 있습니다:
- 기능 토글 (불리언 옵션)
- 선택 드롭다운 (미리 정의된 옵션 중 선택)
- 텍스트 또는 숫자 입력
모든 설정을 플러그인 매니페스트의 원래 값으로 복원하려면, 설정 모달에서 기본값으로 복원 버튼을 클릭하세요. 이렇게 하면 현재 값이 플러그인 개발자가 정의한 기본값으로 교체됩니다.
플러그인 설치¶
새 플러그인을 설치하려면:
- 페이지 헤더의 플러그인 설치 버튼을 클릭합니다
- 설치 방법을 선택합니다:
- Zip에서 설치: 패키징된 플러그인이 포함된
.zip파일 선택 - 디렉토리에서 설치: 압축 해제된 플러그인이 포함된 로컬 디렉토리 선택
- 파일 브라우저 대화 상자에서 선택을 확인합니다
- 플러그인이 자동으로 유효성 검사되고 설치됩니다
- 설치가 완료되면 플러그인이 목록에 나타납니다
플러그인 패키지 요구 사항 (zip 형식):
- 최대 아카이브 크기: 50 MB
- 루트 또는 단일 최상위 하위 디렉토리 내에
plugin.json매니페스트가 포함되어야 합니다 - 매니페스트에 선언된 진입점 파일이 아카이브에 존재해야 합니다
- 심볼릭 링크 또는 경로 탐색 항목이 포함된 아카이브는 보안상의 이유로 거부됩니다
플러그인 제거¶
플러그인을 제거하려면:
- 플러그인 카드의 제거 버튼(휴지통 아이콘)을 클릭합니다
- 확인 대화 상자에서 제거를 확인합니다
- 플러그인이 현재 활성화되어 있으면 제거 전에 자동으로 비활성화됩니다
- 플러그인 디렉토리와 모든 데이터가 시스템에서 제거됩니다
Warning
플러그인을 제거하면 모든 데이터와 설정이 삭제됩니다. 이 작업은 취소할 수 없습니다.
Note
기본 제공 플러그인은 제거할 수 없습니다. 기본 제공 플러그인의 제거 버튼은 숨겨져 있습니다. 대신 기본 제공 플러그인을 비활성화할 수 있습니다.
플러그인 권한¶
플러그인은 올바르게 작동하기 위해 다양한 권한을 요청할 수 있습니다. 플러그인 세부 정보를 볼 때 필요한 권한을 확인할 수 있습니다:
- 필수 권한: 이러한 권한 없이는 플러그인이 작동할 수 없습니다
- 선택적 권한: 부여할 수 있는 추가 기능
일반적인 권한에는 다음이 포함됩니다:
| 권한 | 설명 |
|---|---|
| 채팅 메시지 읽기 | 처리를 위한 채팅 콘텐츠 접근 |
| UI 요소 수정 | 커스텀 컴포넌트 렌더링 기능 |
| 모델 정보 읽기 | 모델 메타데이터 접근 |
| 메트릭 수집 | 성능 데이터 모니터링 |
| 파일 시스템 쓰기 | 디스크에 파일 저장 |
플러그인 SDK¶
플러그인 SDK는 플러그인 개발자에게 호스트 애플리케이션과 상호작용할 수 있는 구조적이고 권한 제어된 API를 제공합니다. 모든 플러그인은 활성화될 때 선언된 권한에 맞게 범위가 지정된 PluginAPI 인스턴스를 받습니다.
API 도메인¶
| 도메인 | 주요 메서드 | 필요 권한 |
|---|---|---|
| 채팅 | sendMessage, streamMessage, cancelStream, getActiveModel, listModels | chat.inference, chat.models |
| 스토리지 | get, set, delete (키-값); 대화 CRUD | storage.scoped, storage.conversations |
| 메모리 | 네임스페이스 CRUD, 항목 CRUD, 추출, 통합 | memory.read, memory.write, memory.extract |
| 설정 | getAll, get, onChange | 없음 |
| UI | showNotification, getTheme, onThemeChange | ui.notifications (알림용) |
사용 가능한 권한¶
다음 권한을 plugin.json에 선언할 수 있습니다:
| 권한 | 설명 |
|---|---|
chat.inference | 추론 서버에 메시지를 보내고 응답을 받습니다 |
chat.models | 사용 가능한 모델 목록 조회 및 정보 읽기 |
storage.scoped | 플러그인 자체 데이터 디렉토리에서 파일 읽기 및 쓰기 |
storage.conversations | 플러그인 범위 대화 생성, 읽기, 업데이트, 삭제 |
memory.read | 플러그인 자체 메모리 뱅크 네임스페이스에서 항목 읽기 |
memory.write | 플러그인 자체 메모리 뱅크 네임스페이스에서 항목 생성, 업데이트, 삭제 |
memory.extract | 플러그인 네임스페이스에 LLM 기반 메모리 추출 실행 |
ui.overlay | 오버레이 레이어에 UI 컴포넌트 렌더링 |
ui.sidebar | 사이드바에 UI 컴포넌트 렌더링 |
ui.statusbar | 상태 표시줄에 UI 컴포넌트 렌더링 |
ui.toolbar | 툴바에 UI 컴포넌트 렌더링 |
ui.notifications | 사용자에게 알림 표시 |
메모리 네임스페이스 격리¶
플러그인은 자신이 소유한 메모리 뱅크 네임스페이스에만 접근할 수 있습니다. SDK를 통해 생성된 모든 네임스페이스는 자동으로 plugin:<pluginId>: 접두사가 붙습니다. 예를 들어 ID가 companion-chat인 플러그인이 memory.createNamespace("notes")를 호출하면 plugin:companion-chat:notes라는 이름의 네임스페이스가 생성됩니다. 다른 플러그인이나 호스트 애플리케이션이 소유한 네임스페이스에 접근하려 하면 PluginPermissionError가 발생합니다.
플러그인 모듈 계약¶
플러그인의 JavaScript 번들은 다음을 내보내야 합니다:
default(필수):{ api, pluginId, manifest }를 props로 받는 React 컴포넌트.onActivate(선택): 모듈이 성공적으로 로드된 후 호출되는 함수로,PluginAPI인스턴스를 받습니다.onDeactivate(선택): 모듈이 언로드되기 전에 정리 작업을 위해 호출되는 함수.
플러그인 검색¶
플러그인 페이지 상단의 검색 바를 사용하여 다음 기준으로 플러그인을 필터링할 수 있습니다:
- 플러그인 이름
- 설명
- 작성자
- 카테고리
모범 사례¶
- 신뢰할 수 있는 플러그인만 설치: 플러그인을 설치하기 전에 출처를 확인하세요
- 권한 검토: 플러그인을 활성화하기 전에 요청하는 권한을 이해하세요
- 플러그인 업데이트 유지: 최신 기능과 보안 수정 사항을 받으려면 업데이트를 확인하세요
- 사용하지 않는 플러그인 비활성화: 비활성화된 플러그인은 리소스를 소비하지 않습니다
오류 격리¶
Backend.AI GO는 각 플러그인 컴포넌트를 오류 경계(error boundary)로 감쌉니다. 플러그인이 렌더링 중에 충돌하더라도 오류가 격리되어 나머지 애플리케이션은 정상적으로 계속 작동합니다.
플러그인에서 렌더링 오류가 발생하면, 해당 플러그인 영역에 다음 내용이 포함된 대체 패널이 표시됩니다:
- 충돌한 플러그인의 이름
- 오류에 대한 간략한 설명
- 플러그인 컴포넌트 재로드를 시도하는 다시 시도 버튼
다시 시도를 클릭하면 오류 경계가 초기화되고 플러그인 컴포넌트가 다시 렌더링됩니다. 플러그인이 즉시 다시 충돌하는 경우, 플러그인 페이지에서 비활성화했다가 다시 활성화해 보세요.
Note
오류 경계는 React 렌더링 중에 발생하는 오류를 처리합니다. 라이프사이클 훅(onActivate, onDeactivate)에서 발생하는 오류는 로드 또는 언로드 단계에서 처리되며, 대체 패널이 아닌 플러그인 상태를 "오류"로 설정합니다.
문제 해결¶
플러그인이 로드되지 않음¶
플러그인이 로드되지 않는 경우:
- 플러그인이 Backend.AI GO 버전과 호환되는지 확인하세요
- 플러그인을 비활성화했다가 다시 활성화해 보세요
- 애플리케이션 로그에서 오류 메시지를 확인하세요
- 플러그인을 제거하고 다시 설치하는 것을 고려하세요
플러그인에 오류 패널이 표시됨¶
렌더링 후 플러그인에 오류 대체 패널이 표시되는 경우:
- 오류 패널의 다시 시도를 클릭하여 복구를 시도하세요
- 오류가 지속되면 플러그인 페이지에서 플러그인을 비활성화했다가 다시 활성화하세요
- 충돌에 대한 자세한 내용은 애플리케이션 로그를 확인하세요
- 오류가 재현 가능한 경우 플러그인 작성자에게 문의하세요
설정이 저장되지 않음¶
플러그인 설정이 저장되지 않는 경우:
- 애플리케이션 데이터 디렉토리에 쓰기 권한이 있는지 확인하세요
- 애플리케이션을 다시 시작해 보세요
- 플러그인을 기본 설정으로 재설정하고 다시 구성하세요