본문으로 건너뛰기

개요

Runtime Local LLM Documentation

Runtime Local LLM은 llama.cpp를 사용하여 대규모 언어 모델을 전적으로 기기에서 실행하는 플러그인으로, 런타임 시 인터넷 연결이 필요하지 않습니다. GGUF 모델 파일을 지원하며, 모델 로드, 메시지 전송, 토큰 단위 응답 수신을 위한 완전한 블루프린트 API를 제공합니다. 모든 작업은 백그라운드 스레드에서 이루어지며 게임 스레드 콜백을 통해 처리됩니다.

이 플러그인은 Windows, Mac, Linux, Android(Meta Quest 및 기타 Android 기반 플랫폼 포함), iOS를 지원합니다.

주요 기능​

  • 완전한 오프라인 추론: 런타임 시 클라우드 서비스나 API 키가 필요하지 않음
  • GGUF 모델 지원: 모든 GGUF 형식 모델(Llama, Mistral, Phi, Gemma, Qwen 등) 로드 가능
  • 최신 llama.cpp: Fab에서 정기적으로 업데이트되어 llama.cpp 릴리스와 보조를 맞추므로 최신 GGUF 모델 형식을 항상 지원
  • GPU 가속: Windows와 Linux에서는 Vulkan, Mac과 iOS에서는 Metal, Android와 Meta Quest에서는 CPU + 내장 함수 사용
  • 다중 모델 로딩 방식:
    • 로컬 파일 경로에서 로드
    • 모델 이름으로 로드 (블루프린트의 드롭다운 선택)
    • URL에서 다운로드 후 자동 로드
    • 모델 사전 캐싱을 위한 다운로드 전용
  • 토큰 단위 스트리밍: 생성되는 각 토큰을 실시간으로 표시
  • 비동기 블루프린트 노드: 로딩, 메시지 전송, 다운로드를 위한 출력 델리게이트가 있는 노드
  • 구성 가능한 추론 파라미터: Temperature, Top-P, Top-K, 반복 페널티, GPU 레이어 오프로딩, 컨텍스트 크기, 시드, 스레드 수, 시스템 프롬프트
  • 대화 관리: 컨텍스트 리셋, 디스크 저장/로드, 인메모리 스냅샷, 장기 대화 자동 요약을 지원하는 다중 턴 대화
  • 에디터 모델 관리자: 프로젝트 설정에서 모델을 직접 탐색, 다운로드, 가져오기, 삭제, 테스트
  • 크로스 플랫폼 패키징: NonUFS 스테이징을 통해 모델을 프로젝트와 함께 배포

작동 방식​

  1. 에디터에서 모델 관리: 플러그인 설정 패널을 사용하여 사전 정의된 모델 카탈로그를 탐색하고, 다운로드하거나, 자신의 GGUF 파일을 가져옵니다
  2. 런타임에 모델 로드: 추론 매개변수와 함께 로드 함수 중 하나(파일별, 이름별, URL별 또는 메타데이터별)를 호출합니다
  3. 메시지 전송: LLM 인스턴스에 사용자 메시지를 전달합니다. 모델이 응답을 생성할 때 토큰이 델리게이트를 통해 스트리밍됩니다
  4. 응답 사용: 채팅 UI에 토큰을 표시하고, NPC 대화를 구동하며, 동적 콘텐츠를 생성하거나, 다른 시스템에 전달합니다

모든 추론은 전용 백그라운드 스레드에서 실행됩니다. 콜백(토큰 생성, 완료, 오류)은 게임 스레드에서 실행되므로, 이를 통해 UI와 게임 상태를 안전하게 업데이트할 수 있습니다.

일반적인 사용 사례​

  • 게임 내 챗봇 및 어시스턴트: Q&A, 도움말 시스템, 동적 튜토리얼
  • NPC 대화: 대화 스냅샷을 사용하여 지속적인 캐릭터별 메모리를 가진 대화형 NPC
  • 장시간 롤플레이 및 내러티브 시스템: 자동 요약을 통해 핵심 정보를 잃지 않으면서도 여러 시간 분량의 대화를 컨텍스트 제한 내에서 유지
  • 절차적 콘텐츠: 퀘스트 설명, 아이템 배경 이야기, 대화 트리를 즉석에서 생성
  • 오프라인 우선 애플리케이션: 네트워크 연결 없이 LLM 기능이 필요한 모든 것

모델 저장 및 패키징​

모델은 프로젝트의 Content/RuntimeLocalLLM/Models 디렉토리에 .gguf 파일로 저장됩니다. 플러그인은 추가 비에셋 디렉토리 복사 대상(DirectoriesToAlwaysStageAsNonUFS)을 자동으로 구성하여 모델 파일이 패키징된 프로젝트와 함께 제공되며 런타임에 표준 파일 I/O를 통해 접근 가능하도록 합니다.

각 모델에는 메타데이터(표시 이름, 계열, 변형, 설명, 매개변수 수)를 저장하는 .json 사이드카 파일도 있습니다.

지원되는 모델​

이 플러그인은 GGUF 형식의 모든 모델과 호환됩니다. 편집기에서 인기 있는 사전 정의 모델 카탈로그를 제공하여 원클릭 다운로드가 가능하며, 사용자 정의 GGUF 파일을 가져올 수도 있습니다. 일반적인 모델군은 다음과 같습니다:

  • Llama (Meta) — 1B, 3B, 8B 및 그 이상
  • Mistral / Mixtral — 7B 및 그 이상
  • Phi (Microsoft) — 2B, 3B, 4B
  • Gemma (Google) — 2B, 7B
  • Qwen (Alibaba) — 1.5B, 7B 및 그 이상
  • TinyLlama — 1.1B
  • 그 외 다양한 커뮤니티 모델

양자화​

모델은 품질과 크기 및 속도를 절충하는 다양한 양자화 수준으로 제공됩니다.

양자화품질Size속도
Q2_K낮추다가장 작은가장 빠른
Q4_K_MGood중간Fast
Q5_K_M더 나은더 큰중간
Q8_0High대형느리게
F16 / F32최고가장 큰가장 느린

모바일 및 VR 기기의 경우, 소형 모델(1B~3B 파라미터)과 함께 더 작은 양자화(Q2_K ~ Q4_K_M)를 권장합니다. 데스크톱의 경우 사용 가능한 RAM 및 CPU/GPU 리소스에 따라 더 큰 모델과 더 높은 양자화 수준을 사용할 수 있습니다.

추가 자료​

Join our Discord
online · support