본문으로 건너뛰기

개요

Runtime Local LLM Documentation

Runtime Local LLM은 llama.cpp 를 사용하여 런타임 중 인터넷 연결 없이 온디바이스에서 대규모 언어 모델을 실행하는 플러그인입니다. GGUF 모델 파일을 지원하며, 모델을 로드하고 메시지를 보내며 토큰 단위로 응답을 받는 전체 Blueprint API 를 제공하여 게임 스레드 콜백과 함께 백그라운드 스레드에서 작동합니다.

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

주요 기능​

  • 완전 오프라인 추론: 런타임 시 클라우드 서비스나 API 키 불필요
  • GGUF 모델 지원: Llama, Mistral, Phi, Gemma, Qwen 등 모든 GGUF 형식 모델 로드 가능
  • 최신 llama.cpp: Fab에서 정기적으로 업데이트되어 llama.cpp 릴리스와 발맞추며 최신 GGUF 모델 포맷을 항상 지원
  • GPU 가속화: Windows 및 Linux에서는 Vulkan, Mac 및 iOS에서는 Metal, Android 및 Meta Quest에서는 CPU + 인트린식을 사용
  • 다중 모델 로드 방법:
    • 로컬 파일 경로에서 로드
    • 모델 이름으로 로드 (Blueprints 의 드롭다운 선택)
    • URL 에서 다운로드하여 자동으로 로드
    • 모델 사전 캐싱을 위한 다운로드 전용
  • 토큰 단위 스트리밍: 실시간 표시를 위해 생성되는 각 토큰을 즉시 수신
  • 비동기 블루프린트 노드: 로드, 메시지 전송 및 다운로드를 위한 출력 디리게이트가 있는 노드
  • 구성 가능한 추론 매개변수: 온도, 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 파일로 저장됩니다. 플러그인은 Additional Non-Asset Directories To Copy (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