엔진 및 런타임 관리¶

엔진 메뉴는 추론 엔진과 런타임 의존성을 관리하는 중앙 허브입니다. 이곳에서 llama.cpp, MLX 등 다양한 추론 백엔드의 여러 버전을 다운로드하고, 업데이트하며, 하드웨어에 맞게 설정할 수 있습니다.

엔진 페이지 이해하기¶

엔진 페이지는 세 가지 주요 섹션으로 구성됩니다:

1. 설치된 엔진 - 현재 시스템에 설치된 엔진들
2. 설치된 런타임 - 엔진이 의존하는 런타임 라이브러리
3. 사용 가능한 엔진 - 공식 레지스트리에서 다운로드 가능한 새 엔진들

왜 엔진을 직접 관리해야 하나요?¶

하드웨어별 최적화¶

각 GPU마다 다른 엔진 빌드가 필요합니다:

arm64의 CUDA 13: GPU별 빌드 두 가지¶

Linux arm64에서 llama.cpp는 CUDA 13 빌드를 두 가지 배포합니다. 서로 다른 NVIDIA GPU 아키텍처용으로 컴파일되어 있어, 한 호스트에서는 둘 중 하나만 동작합니다:

잘못된 빌드를 설치해도 설치 자체는 성공하지만, 이후 모델을 읽어들일 때마다 CUDA에서 실패합니다:

CUDA error: no kernel image is available for execution on the device

Backend.AI GO는 호스트 GPU를 감지해 일치하는 빌드에만 권장 배지를 붙입니다. 나머지 빌드는 목록에 남지만 선택할 수 없고, 대신 설치해야 할 빌드를 알려주는 안내가 표시됩니다. 잘못된 선택은 첫 모델 로드가 아니라 다운로드 전에 차단됩니다. 명령줄에서 감지 결과를 확인하려면:

aigo engine available

VARIANT 열에 gb10 또는 gh200이, NOTE 열에 recommended 또는 unsupported가 표시됩니다.

GB200과 GB300은 두 빌드 어느 쪽의 대상도 아닙니다. 같은 Blackwell 세대지만 연산 능력이 10.0이고 이를 대상으로 하는 패키지가 없어, 두 빌드 모두 제공되며 어느 쪽도 차단되지 않습니다.

호스트 GPU를 식별하지 못한 경우에는 두 빌드 모두 설치 가능한 상태로 남고 두 빌드 모두 권장 배지를 유지합니다. 감지에 실패했다고 해서 CUDA 호스트가 아무것도 설치할 수 없게 되어서는 안 되기 때문입니다. 이때는 연산 능력을 직접 확인해 해당하는 항목을 고르세요:

nvidia-smi --query-gpu=name,compute_cap --format=csv,noheader

DGX Spark에서는 NVIDIA GB10, 12.1이 출력되며, 이는 GB10 빌드에 해당합니다.

지원되는 추론 엔진¶

Backend.AI GO는 다양한 추론 엔진을 지원합니다:

버전 관리¶

여러 엔진 버전을 동시에 설치하고 운영할 수 있습니다:

• 새 릴리스를 적용하기 전에 미리 테스트
• 문제 발생 시 이전 버전으로 롤백
• 버전 간 성능 비교

의존성 관리¶

일부 엔진은 런타임 라이브러리가 필요합니다. 엔진 페이지에서 이러한 의존성을 자동으로 감지하고 필요시 설치해 줍니다.

엔진 설치하기¶

레지스트리에서 설치¶

1. 사이드바 메뉴에서 엔진 페이지로 이동합니다.

2. 사용 가능한 엔진 섹션으로 스크롤합니다.

3. 원하는 엔진을 찾습니다 (예: llama.cpp).

4. 다운로드 버튼을 클릭합니다.

5. 여러 변형이 있는 경우 (예: CUDA 13, Metal, CPU) 대화 상자가 나타납니다:

   • 감지된 하드웨어에 따라 권장 변형이 표시됩니다
   • 각 변형의 다운로드 크기가 표시됩니다
   • GPU에 맞는 변형을 선택하세요

6. 다운로드가 즉시 시작됩니다. 플로팅 다운로드 대기열 패널에서 진행 상황을 확인할 수 있습니다.

다운로드 진행 단계¶

설치 과정은 여러 단계를 거칩니다:

오프라인 설치¶

에어갭(air-gapped) 환경이나 수동 다운로드를 선호하는 경우:

1. Backend.AI GO Releases에서 .baiengine 패키지 파일을 다운로드합니다.

2. incoming 디렉토리에 파일을 배치합니다:

   macOS / LinuxWindows

   ~/Library/Application Support/ai.backend.go/engines/incoming/ (macOS) 또는 ~/.local/share/ai.backend.go/engines/incoming/ (Linux)
   

   %APPDATA%\ai.backend.go\engines\incoming\
   

3. 엔진 페이지를 열면 대기 중인 패키지 배너가 나타납니다.

4. 가져오기 버튼을 클릭하여 감지된 패키지를 설치합니다.

또는 .baiengine 파일을 엔진 페이지로 드래그 앤 드롭할 수도 있습니다.

설치된 엔진 관리하기¶

엔진 카드¶

설치된 각 엔진은 다음 정보를 보여주는 카드로 표시됩니다:

• 엔진 이름 및 버전 (예: llama.cpp 1.0.0)
• 가속기 배지: Metal, CUDA 13, CPU 등
• 상태 배지:
  • 🟢 활성 - 현재 모델 실행 중
  • 🟠 업데이트 가능 - 레지스트리에 새 버전 존재
• 지원 형식: GGUF, MLX 등
• 설치 크기

수행 가능한 작업¶

기본 엔진 설정하기¶

같은 모델 포맷을 지원하는 엔진이 여러 개 설치된 경우 (예: llama.cpp-metal과 llama.cpp-cpu 모두 GGUF 지원), 포맷별로 기본 엔진을 지정할 수 있습니다:

1. 원하는 엔진 카드에서 GGUF 기본으로 설정 (또는 해당 포맷 이름) 버튼을 클릭합니다.
2. 버튼이 기본 — GGUF 배지로 바뀌고, 해당 포맷에서 이전에 지정된 기본 엔진은 해제됩니다.
3. 이후 해당 포맷의 모델을 로드할 때 Backend.AI GO가 이 엔진을 사용합니다.

엔진 상세 정보 드로어¶

엔진 카드를 클릭하면 세 개의 탭이 있는 상세 정보 드로어가 열립니다:

개요 탭¶

• 기본 정보: ID, 버전, 가속기, 설치 날짜
• 매니페스트 상세: 포맷 버전, 업스트림 버전, 플랫폼 호환성
• 가속기 정보: 특정 백엔드 세부 정보 및 최적화 내용

파일 탭¶

설치된 파일 탐색:

• 디렉토리 구조
• 파일 크기
• 문제 해결이나 설치 확인에 유용

의존성 탭¶

런타임 의존성 확인:

• 필수 vs 선택 의존성
• 각 의존성의 설치 상태
• 버전 요구 사항

런타임 라이브러리¶

런타임이란?¶

런타임 라이브러리는 엔진 작동에 필요한 공유 의존성입니다. 가장 일반적인 것들은 다음과 같습니다:

자동 설치¶

런타임이 필요한 엔진을 설치할 때:

1. Backend.AI GO가 누락된 의존성을 감지합니다.
2. 런타임이 자동으로 다운로드됩니다.
3. 다운로드 대기열에 두 개의 진행률 표시기가 나타납니다.
4. 런타임이 엔진 설치 완료 전에 설치됩니다.

설치된 런타임 보기¶

설치된 런타임 섹션에는 다음이 표시됩니다:

• 런타임 이름 및 버전
• 설치 날짜
• 이 런타임에 의존하는 엔진들

런타임 카드를 클릭하면 의존하는 엔진의 전체 목록을 볼 수 있습니다.

런타임 지속성¶

런타임은 엔진 버전 간에 공유됩니다:

• 엔진 업데이트 시: 런타임은 그대로 유지됨
• 런타임을 사용하는 모든 엔진 제거 시: 런타임은 유지됨 (향후 사용 대비)
• 런타임 수동 삭제 시: 의존하는 엔진이 작동하지 않을 수 있음

하드웨어 감지¶

Backend.AI GO는 최적의 엔진 변형을 추천하기 위해 시스템 하드웨어를 자동으로 감지합니다.

감지 항목¶

• GPU 제조사: NVIDIA, AMD, Intel, Apple
• GPU 모델: 특정 카드 이름 (예: RTX 4090, RX 7900 XTX)
• 드라이버 버전: CUDA 버전, ROCm 버전 등
• VRAM: 사용 가능한 비디오 메모리
• 디스크 공간: 엔진 설치에 사용 가능한 저장 공간

시스템 기능 확인¶

시스템 기능은 엔진 변형 선택 시 표시됩니다:

• 하드웨어에 맞는 최적의 변형에 권장 배지 표시
• 설치 대화 상자에 사용 가능한 가속기 목록 표시
• 저장 공간 부족 시 경고 표시

엔진 업데이트하기¶

업데이트 확인¶

Backend.AI GO는 주기적으로 레지스트리에서 새 엔진 버전을 확인합니다. 엔진 페이지의 새로고침 버튼을 포함해 확인할 때마다 레지스트리를 다시 읽으므로, 앱이 실행 중일 때 배포된 버전도 재시작 없이 나타납니다. 업데이트가 있으면:

• 엔진 카드에 주황색 업데이트 가능 배지가 나타납니다
• 업데이트 버전 번호가 표시됩니다

업데이트 적용¶

1. 엔진 카드에서 새로고침 아이콘을 클릭합니다.
2. 새 버전을 다운로드하고 체크섬을 검증합니다. 이 동안 설치된 버전은 그대로 있습니다.
3. 새 버전이 기존 버전을 대체합니다. 다운로드나 설치가 실패하거나 앱이 도중에 종료되면 기존 버전이 유지됩니다(종료된 경우 다음 시작 때 복구됩니다).
4. 설정 및 기본 환경 설정은 유지됩니다.

문제 해결¶

엔진이 설치되지 않음¶

시스템 라이브러리 누락¶

엔진 패키지는 자체 라이브러리를 lib/에 담아 배포하며, AI:GO는 서버를 시작하기 전에 그 디렉토리와 런타임 의존성을 라이브러리 검색 경로에 넣습니다. 패키지가 링크한 라이브러리 중 두 곳 어디에도 없는 것은 운영체제가 제공해야 합니다.

이제 설치 단계에서 동적 로더에게 패키지의 실행 파일이 이 컴퓨터에서 실제로 시작될 수 있는지 물어보고, 그렇지 않으면 설치를 거부합니다. 메시지에는 실행 파일과 라이브러리가 모두 나옵니다.

ENGINE_MISSING_SHARED_LIBRARY: bin/llama-server cannot start on this host. The dynamic loader
cannot find libnccl.so.2, which is shipped in neither the engine package nor its runtime
dependencies. Install the missing library with your system package manager, then install the
engine again.

배포판의 패키지 관리자로 해당 라이브러리를 설치한 뒤 엔진을 다시 설치하세요. 패키지 자체에는 고칠 것이 없습니다.

엔진이 시작되지 않음¶

멈춘 다운로드 해결¶

다운로드가 멈춘 것 같으면:

1. 다운로드 대기열에서 취소 버튼을 클릭합니다.
2. 정리가 완료될 때까지 기다립니다.
3. 설치를 다시 시도합니다.

모범 사례¶

올바른 변형 선택¶

• 최대 성능을 위해: GPU에 맞는 엔진 변형 선택
• 호환성을 위해: CPU 변형은 어디서나 작동하지만 속도가 느림
• 메모리 제한 시스템의 경우: 일부 변형이 더 메모리 효율적임

엔진 최신 상태 유지¶

새 버전에는 보통 다음이 포함됩니다:

• 성능 향상
• 버그 수정
• 새로운 모델 아키텍처 지원
• 보안 패치

디스크 공간 관리¶

엔진 패키지는 상당히 클 수 있습니다 (100MB - 1GB 이상). 주기적으로:

• 사용하지 않는 엔진 변형 제거
• 파일 탭에서 설치 크기 확인
• 실제로 사용하는 변형만 유지

모델 로딩과의 연동¶

엔진 페이지는 모델 로딩 시스템과 긴밀하게 연동됩니다:

1. 모델 형식 감지: 모델을 로드하면 Backend.AI GO가 형식(GGUF, Safetensors 등)을 확인합니다.

2. 엔진 선택: 해당 형식을 지원하는 설치된 엔진을 찾습니다.

3. 포맷별 기본값: 설정에서 해당 형식의 기본 엔진을 확인합니다.

4. 우선순위 기반 선택: 기본값이 설정되지 않은 경우 우선순위에 따라 엔진이 선택됩니다:

   • MLX 형식: MLXcel > MLX LM
   • GGUF 형식: llama.cpp (GPU 가속 우선)

5. 하드웨어 최적화: 동일 우선순위에서 GPU 가속 변형이 CPU 전용보다 우선됩니다. CUDA와 SYCL처럼 여러 GPU 계열이 함께 설치된 경우, 자동 선택기는 감지된 하드웨어와 가속기 계열이 일치하는 엔진을 고릅니다. 예를 들어 NVIDIA 호스트에 CUDA 빌드와 SYCL 빌드가 모두 설치되어 있으면 CUDA 빌드가 자동으로 선택됩니다. CUDA 버전이 여럿 설치된 경우에는 드라이버가 지원하는 가장 높은 버전이 선택됩니다.

모델 로딩에 대한 자세한 내용은 다음을 참조하세요:

• 모델 실행하기
• llama.cpp 가속
• MLX 가속

기술 세부 사항¶

엔진 패키지 형식¶

엔진 패키지는 .baiengine 형식을 사용합니다:

• 바이너리와 메타데이터를 포함하는 ZIP 아카이브
• manifest.json에 엔진 및 요구 사항 기술
• 체크섬으로 파일 무결성 보장
• 각 OS/아키텍처용 플랫폼별 빌드

디렉토리 구조¶

앱 데이터 루트는 macOS에서 ~/Library/Application Support/ai.backend.go/, Windows에서 %APPDATA%\ai.backend.go\, Linux에서 ~/.local/share/ai.backend.go/입니다. 기존 ~/.backend-ai-go/ 루트는 레거시 전용입니다.

<app-data>/
├── engines/
│   ├── incoming/              # 오프라인 패키지 스테이징
│   ├── installed.json         # 설치된 엔진 레지스트리
│   ├── llama-cpp-metal/       # 엔진: Metal 기반 llama.cpp
│   ├── llama-cpp-cuda13/      # 엔진: CUDA 13 기반 llama.cpp
│   └── mlxcel/                # 엔진: MLXcel
├── runtimes/
│   ├── installed.json         # 설치된 런타임 레지스트리
│   ├── cuda13-runtime/        # 런타임: CUDA 13
│   └── hip-runtime/           # 런타임: AMD HIP
├── logs/                      # 애플리케이션 로그
└── config/                    # 설정 파일

지원되는 가속기¶

엔진 시스템은 사용자의 하드웨어에 최적화된 추론 백엔드를 항상 사용할 수 있도록 보장하여, 로컬 AI를 접근 가능하고 성능 좋게 만들어 줍니다.