RamaLama: OCI 컨테이너를 통한 간편한 AI 모델 사용 및 서빙 도구

RamaLama는 OCI 컨테이너를 사용하여 AI 작업을 단순하고 직관적이며 친숙하게 만드는 것을 목표로 합니다.

RamaLama는 친숙한 컨테이너 접근 방식을 통해 모든 소스로부터 AI 모델의 로컬 사용 및 추론 (Inference) 서빙을 단순화하는 오픈 소스 도구입니다. 이를 통해 엔지니어들은 컨테이너 중심의 개발 패턴과 이점을 AI 사용 사례로 확장할 수 있습니다.

RamaLama는 호스트 시스템을 구성할 필요를 없애는 대신, 호스트 시스템에서 발견된 GPU에 특화된 컨테이너 이미지 (Container Image)를 가져옴으로써 다양한 모델과 플랫폼을 사용할 수 있도록 합니다.

• 사용자가 AI를 위해 호스트 시스템을 구성해야 하는 복잡성을 제거합니다.
• 호스트 시스템의 GPU에 특화된 가속 컨테이너 이미지를 감지하고 가져오며, 종속성 (Dependencies) 및 하드웨어 최적화를 처리합니다.
• RamaLama는 OCI 컨테이너 레지스트리 (OCI Container Registries)를 포함한 여러 AI 모델 레지스트리를 지원합니다.
• 모델은 Podman 및 Docker가 컨테이너 이미지를 다루는 방식과 유사하게 취급됩니다.
• 일반적인 컨테이너 명령어를 사용하여 AI 모델을 다룰 수 있습니다.
• 루트리스 컨테이너 (Rootless Containers)에서 AI 모델을 안전하게 실행하여, 모델을 기반 호스트로부터 격리합니다.
• 기본적으로 네트워크 액세스를 차단하고 애플리케이션 종료 시 모든 임시 데이터를 제거하여 데이터를 안전하게 유지합니다.
• REST API 또는 챗봇 (Chatbot) 형태로 모델과 상호작용합니다.

Python 및 모든 종속성이 포함된 독립형 macOS 설치 프로그램을 다운로드하세요:

• Releases에서 최신 .pkg 설치 프로그램을 다운로드하세요 - 더블 클릭하여 설치하거나, 다음을 실행하세요:
  sudo installer -pkg RamaLama-*-macOS-Installer.pkg -target /

자세한 지침은 macOS 설치 가이드를 참조하십시오.

RamaLama는 Fedora 및 이후 버전에서 사용할 수 있습니다. 설치하려면 다음을 실행하세요:

sudo dnf install ramalama

Fedora Silverblue 및 기타 불변 (Immutable) 변형 버전에서는 시스템이 읽기 전용입니다. RamaLama를 다음 두 가지 방법 중 하나로 실행할 수 있습니다:

Toolbox: Toolbox 컨테이너를 생성하고 그 안에 RamaLama를 설치합니다 (pip install ramalama 또는 dnf install ramalama)

(사용 가능하다면). RamaLama가 모델 컨테이너를 시작할 수 있도록 호스트의 동일한 Podman (또는 Docker)을 사용하십시오. 컨테이너 엔진이 설치되어 있는지, 그리고 toolbox가 호스트의 컨테이너 엔진에 접근할 수 있는지(예: 소켓을 바인드 마운트하거나 toolbox가 호스트의 podman 명령어를 사용하도록 설정하여) 확인하십시오. 호스트 설치 또는 호스트 접근 권한이 있는 Toolbox: 사용 중인 이미지에서 패키지를 사용할 수 있다면 rpm-ostree install ramalama를 통해 호스트에 RamaLama를 설치하거나, Podman/Docker를 사용할 수 있고 모델 저장소(model store)가 쓰기 가능한 위치(예: 홈 디렉토리)에 있는지 확인한 후 toolbox에서 RamaLama를 실행하십시오.

모델 저장소(model store)의 기본값은 ~/.local/share/ramalama이며, 이는 Silverblue에서 쓰기가 가능합니다.

RamaLama는 PyPI를 통해 https://pypi.org/project/ramalama 에서 사용할 수 있습니다.

pip install ramalama

다음 명령어를 실행하여 RamaLama를 설치하십시오:

curl -fsSL https://ramalama.ai/install.sh | bash

RamaLama는 Docker Desktop 또는 Podman Desktop을 사용하는 Windows를 지원합니다:

pip install ramalama

요구 사항:

• Python 3.9 이상
• WSL2 백엔드를 사용하는 Docker Desktop 또는 Podman Desktop
• GPU 지원을 보려면, WSL2용 NVIDIA GPU 설정을 참조하십시오.

참고: Windows 지원은 Docker/Podman을 통해 컨테이너를 실행해야 합니다. 모델 저장소(model store)는 하드링크 (hardlinks, 관리자 권한 불필요)를 사용하며, 하드링크를 사용할 수 없는 경우 파일 복사 방식으로 대체됩니다.

pip를 사용하여 RamaLama를 설치했다면, 다음 명령어로 삭제할 수 있습니다:

pip uninstall ramalama

DNF를 사용하여 RamaLama를 설치했다면:

sudo dnf remove ramalama

.pkg 설치 프로그램을 통해 설치된 RamaLama를 제거하려면:

# 실행 파일 제거
sudo rm /usr/local/bin/ramalama
# 설정 및 데이터 파일 제거
...

자세한 내용은 macOS 설치 가이드를 참조하십시오.

위의 어떤 방법으로든 RamaLama를 삭제한 후, 다운로드된 모델과 설정 파일을 제거하고 싶을 수 있습니다:

# 다운로드된 모델 및 데이터 제거 (용량이 클 수 있음)
rm -rf -- "${XDG_DATA_HOME:-~/.local/share}/ramalama"
# 설정 파일 제거
...

참고: 모델 데이터 디렉터리(기본값 ~/.local/share/ramalama)는 다운로드한 모델의 수에 따라 용량이 상당히 커질 수 있습니다. 위의 명령어를 실행하기 전에 이 파일들을 삭제해도 괜찮은지 반드시 확인하십시오.

가속기 (Accelerator)	이미지 (Image)
GGML_VK_VISIBLE_DEVICES (또는 CPU)	quay.io/ramalama/ramalama
...

처음 실행할 때, RamaLama는 시스템을 검사하여 GPU 지원 여부를 확인하며, GPU가 없는 경우 CPU로 대체(fallback)합니다. RamaLama는 Podman 또는 Docker와 같은 컨테이너 엔진 (container engines)을 사용하여 사용자의 시스템 설정에 맞춰 AI 모델 (AI Model)을 실행하는 데 필요한 모든 소프트웨어가 포함된 적절한 OCI 이미지를 가져옵니다(pull).

RamaLama는 어떻게 적절한 이미지를 선택하나요?

초기화 후, RamaLama는 OCI 이미지에 기반한 컨테이너 내에서 AI 모델을 실행합니다. RamaLama는 시스템에서 발견된 GPU에 특화된 컨테이너 이미지들을 가져옵니다. 이 이미지들은 RamaLama의 마이너 버전 (minor version)과 연결되어 있습니다.

• 예를 들어, NVIDIA 시스템에서 RamaLama 버전 1.2.3은 quay.io/ramalama/cuda:1.2를 가져옵니다. 기본 이미지를 재정의(override)하려면 --image 옵션을 사용하십시오.

그 후 RamaLama는 모델 레지스트리 (model registries)에서 AI 모델을 가져오며, 간단한 단일 명령어로 챗봇 (chatbot) 또는 REST API 서비스를 시작합니다. 모델은 Podman 및 Docker가 컨테이너 이미지를 다루는 방식과 유사하게 취급됩니다.

하드웨어 (Hardware)	활성화 여부 (Enabled)
CPU	✓
...

NVIDIA GPU가 장착된 시스템의 경우, 올바른 호스트 시스템 설정을 위해 ramalama-cuda 문서를 참조하십시오.

다음 Intel GPU들은 RamaLama에 의해 자동으로 감지됩니다:

GPU ID	설명 (Description)
0xe20b	Intel® Arc™ B580 Graphics
0xe20c	Intel® Arc™ B570 Graphics
0x7d51	Intel® Graphics - Arrow Lake-H
0x7dd5	Intel® Graphics - Meteor Lake
0x7d55	Intel® Arc™ Graphics - Meteor Lake

더 자세한 정보는 Intel 하드웨어 표를 참조하십시오.

Moore Threads GPU가 장착된 시스템의 경우, 올바른 호스트 시스템 설정을 위해 ramalama-musa 문서를 참조하십시오.

MLX 런타임 (runtime)은 Apple Silicon Mac을 위한 최적화된 추론 (inference)을 제공합니다. MLX에는 다음이 필요합니다:

• macOS 운영체제 (operating system)
• Apple Silicon 하드웨어 (M1, M2, M3 또는 그 이후 모델)
• --nocontainer 옵션을 사용하여 사용 시 (컨테이너는 지원되지 않음) - 호스트 시스템에 uv 도구로서 mlx-lm uv 패키지가 설치되어 있어야 함

MLX에서 Phi-4를 설치하고 실행하려면 uv를 사용하세요. 만약 uv가 설치되어 있지 않다면, curl -LsSf https://astral.sh/uv/install.sh | sh를 통해 설치할 수 있습니다:

uv tool install mlx-lm
# 또는 최신 버전으로 업그레이드:
uv tool upgrade mlx-lm
...

Podman과 Docker가 모두 설치되어 있는 경우, RamaLama는 기본적으로 Podman을 사용합니다. RAMALAMA_CONTAINER_ENGINE=docker 환경 변수를 사용하여 이 동작을 재정의할 수 있습니다. 둘 다 설치되어 있지 않은 경우, RamaLama는 로컬 시스템의 소프트웨어를 사용하여 모델 실행을 시도합니다.

RamaLama는 Podman 또는 Docker를 사용하여 루트리스 컨테이너 (rootless containers) 내부에서 AI 모델을 실행하는 것을 기본값으로 하기 때문에, 이러한 컨테이너는 기반이 되는 호스트의 정보로부터 AI 모델을 격리합니다. RamaLama 컨테이너를 사용하면 AI 모델이 읽기 전용 (read-only) 모드로 컨테이너 내부에 볼륨 (volume)으로 마운트됩니다.

그 결과 모델을 실행하는 프로세스 (llama.cpp 또는 vLLM)가 호스트로부터 격리됩니다. 또한, ramalama run은 --network=none 옵션을 사용하므로, 컨테이너는 네트워크에 접속할 수 없으며 시스템 외부로 어떠한 정보도 유출할 수 없습니다. 마지막으로, 컨테이너는 --rm 옵션과 함께 실행되므로 애플리케이션이 종료될 때 컨테이너 실행 중에 작성된 모든 콘텐츠가 삭제됩니다.

컨테이너 격리 (Container Isolation) – AI 모델이 격리된 컨테이너 내에서 실행되어 호스트 시스템에 대한 직접적인 접근을 방지합니다.
읽기 전용 볼륨 마운트 (Read-Only Volume Mounts) – AI 모델이 읽기 전용 모드로 마운트되므로, 컨테이너 내부의 프로세스가 호스트 파일을 수정할 수 없습니다.
네트워크 접속 불가 (No Network Access) – ramalama run은 --network=none으로 실행되므로, 모델이 외부로 연결될 수 없어 정보가 유출될 가능성이 없습니다.
자동 정리 (Auto-Cleanup) – 컨테이너는 --rm 옵션과 함께 실행됩니다.

, 세션이 종료되면 모든 임시 데이터를 삭제합니다.모든 Linux Capabilities 제거 (Drop All Linux Capabilities) – 호스트 시스템을 공격하기 위한 Linux Capabilities에 접근할 수 없습니다.새로운 권한 부여 금지 (No New Privileges) – 컨테이너 프로세스가 추가 권한을 얻는 것을 방지하는 Linux 커널 기능입니다.

RamaLama는 '트랜스포트 (transports)'라고 불리는 여러 종류의 AI 모델 레지스트리 유형을 지원합니다.

트랜스포트 (Transports)	웹사이트
HuggingFace	huggingface.co
...	예시: quay.io, Docker Hub, Pulp, Artifactory

Hugging Face <org>/<model> 형식으로 지정된 모델은 Hugging Face에서 자동으로 가져옵니다. 조직(organization) 없이 지정된 모델(예: granite-code)의 경우, RamaLama는 현재 기본적으로 Ollama 트랜스포트를 사용합니다. 참고: Ollama 모델은 더 이상 llama.cpp와 호환되지 않으며, Ollama 트랜스포트에 대한 지원은 향후 릴리스에서 제거될 예정입니다. 사용자는 Hugging Face 모델로 마이그레이션해야 합니다.

트랜스포트 변경 방법

RAMALAMA_TRANSPORT 환경 변수를 사용하여 기본값을 수정할 수 있습니다. export RAMALAMA_TRANSPORT=huggingface 명령을 사용하면 RamaLama가 huggingface 트랜스포트를 사용하도록 변경됩니다.

huggingface://, oci://, modelscope://, ollama://, 또는 rlcr:// 접두사(prefix)를 통해 모델을 지정할 때 개별 모델 트랜스포트를 수정할 수 있습니다.

예시:

ramalama pull huggingface://afrideva/Tiny-Vicuna-1B-GGUF/tiny-vicuna-1b.q2_k.gguf

사용자의 편의를 위해 RamaLama는 '숏네임 (shortnames)' 파일을 사용합니다. 이 파일에는 전체 경로가 지정된 AI 모델에 대한 별칭(alias) 이름이 포함되어 있어, 사용자가 더 짧은 이름으로 모델을 참조할 수 있습니다.

숏네임에 대한 추가 정보

RamaLama는 shortnames.conf 파일이 존재할 경우 이를 읽어들입니다. 이 파일에는 모델을 지정하는 이름-값(name-value) 쌍의 목록이 포함되어 있습니다. 다음 표는 RamaLama가 파일을 읽는 순서를 나타냅니다. 중복된 이름이 존재할 경우 이전에 정의된 숏네임을 덮어씁니다.

벤치마크 지정 AI 모델

$ ramalama bench granite3-moe

---

실행 중인 AI 모델 컨테이너 목록 보기

$ ramalama containers

예시 반환:

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 85ad75ecf866 quay.io/ramalama/ramalama:latest /usr/bin/ramalama... 5 hours ago Up 5 hours 0.0.0.0:8080->8080/tcp ramalama_s3Oh6oDfOP 85ad75ecf866 quay.io/ramalama/ramalama:latest /usr/bin/ramalama... 4 minutes ago Exited (0) 4 minutes ago granite-server

---

특정 형식으로 모든 컨테이너 목록 보기

$ ramalama ps --noheading --format "{{ .Names }}"

예시 반환:

ramalama_s3Oh6oDfOP granite-server

---

Ollama 모델을 OCI 모델로 변환하기.

$ ramalama convert ollama://tinyllama:latest oci://quay.io/rhatdan/tiny:latest

예시 반환:

Building quay.io/rhatdan/tiny:latest... STEP 1/2: FROM scratch STEP 2/2: COPY sha256:2af3b81862c6be03c769683af18efdadb2c33f60ff32ab6f83e42c043d6c7816 /model --> Using cache 69db4a10191c976d2c3c24da972a2a909adec45135a69dbb9daeaaf2a3a36344 COMMIT quay.io/rhatdan/tiny:latest --> 69db4a10191c Successfully tagged quay.io/rhatdan/tiny:latest 69db4a10191c976d2c3c24da972a2a909adec45135a69dbb9daeaaf2a3a36344

---

Safetensors에서 양자화된 GGUF로 변환하여 OCI 모델 생성 및 실행하기.

OCI 모델 생성

$ ramalama --image quay.io/ramalama/ramalama-rag convert --gguf Q4_K_M hf://ibm-granite/granite-3.2-2b-instruct oci://quay.io/kugupta/granite-3.2-q4-k-m:latest

예시 반환:

Converting /Users/kugupta/.local/share/ramalama/models/huggingface/ibm-granite/granite-3.2-2b-instruct to quay.io/kugupta/granite-3.2-q4-k-m:latest... Building quay.io/kugupta/granite-3.2-q4-k-m:latest...

생성된 모델 실행

$ ramalama run oci://quay.io/kugupta/granite-3.2-q4-k-m:latest

컨테이너 엔진 없는 정보 확인 (Info with no container engine).

$ ramalama info

예시 출력: