Docker Model Runner Cheatsheet: Perintah & Contoh

Referensi cepat untuk perintah Docker Model Runner

Docker Model Runner (DMR) adalah solusi resmi Docker untuk menjalankan model AI secara lokal, diperkenalkan pada April 2025. Cheat sheet ini memberikan referensi cepat untuk semua perintah penting, konfigurasi, dan praktik terbaik.

daftar model gemma yang tersedia di docker model runner

Instalasi

Docker Desktop

Aktifkan Docker Model Runner melalui GUI:

  1. Buka Docker Desktop
  2. Pergi ke Pengaturan → Tab AI
  3. Klik Aktifkan Docker Model Runner
  4. Restart Docker Desktop

/home/rg/prj/hugo-pers/content/post/2025/10/docker-model-runner-cheatsheet/docker-model-runner_w678.jpg docker model runner windows

Docker Engine (Linux)

Pasang paket plugin:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker-model-plugin

# Fedora/RHEL
sudo dnf install docker-model-plugin

# Arch Linux
sudo pacman -S docker-model-plugin

Verifikasi instalasi:

docker model --help

Dukungan NVIDIA RTX untuk Docker

Untuk mengaktifkan agar LLMs berjalan di GPU alih-alih CPU, instal nvidia-container-toolkit:

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

kemudian Anda dapat menjalankan kontainer dengan --gpus all

docker run --rm --gpus all <image> <command>

periksa bahwa kontainer dapat melihat GPU:

docker run --rm --gpus all nvidia/cuda:12.2.2-base-ubi8 nvidia-smi

Menambahkan Dukungan NVidia untuk Docker Model Runner

Docker Model Runner memerlukan konfigurasi GPU secara eksplisit. Berbeda dengan perintah docker run standar, docker model run tidak mendukung flag --gpus atau -e. Sebaliknya, Anda perlu:

  1. Konfigurasikan daemon Docker untuk menggunakan runtime NVIDIA secara default

Pertama, periksa di mana nvidia-container-runtime diinstal:

which nvidia-container-runtime

Ini biasanya menghasilkan /usr/bin/nvidia-container-runtime. Gunakan jalur ini dalam konfigurasi berikut.

Buat atau perbarui /etc/docker/daemon.json:

sudo tee /etc/docker/daemon.json > /dev/null << 'EOF'
{
  "default-runtime": "nvidia",
  "runtimes": {
    "nvidia": {
      "path": "/usr/bin/nvidia-container-runtime",
      "runtimeArgs": []
    }
  }
}
EOF

Catatan: Jika which nvidia-container-runtime mengembalikan jalur yang berbeda, perbarui nilai "path" dalam konfigurasi JSON sesuai.

Restart Docker:

sudo systemctl restart docker

Verifikasi konfigurasi:

docker info | grep -i runtime

Anda harus melihat Default Runtime: nvidia dalam output.

  1. Reinstall Docker Model Runner dengan dukungan GPU

Docker Model Runner harus diinstal/reinstal dengan dukungan GPU eksplisit:

# Berhenti runner saat ini
docker model stop-runner

# Reinstal dengan dukungan CUDA GPU
docker model reinstall-runner --gpu cuda

Ini akan menarik versi yang didukung CUDA (docker/model-runner:latest-cuda) alih-alih versi hanya CPU.

  1. Verifikasi akses GPU

Periksa bahwa kontainer Docker Model Runner dapat mengakses GPU:

docker exec docker-model-runner nvidia-smi
  1. Uji model dengan GPU

Jalankan model dan periksa log untuk memastikan penggunaan GPU:

docker model run ai/qwen3:14B-Q6_K "who are you?"

Periksa log untuk konfirmasi GPU:

docker model logs | grep -i cuda

Anda harus melihat pesan seperti:

  • using device CUDA0 (NVIDIA GeForce RTX 4080)
  • offloaded 41/41 layers to GPU
  • CUDA0 model buffer size = 10946.13 MiB

Catatan: Jika Anda sudah menginstal Docker Model Runner tanpa dukungan GPU, Anda harus menginstal ulang dengan flag --gpu cuda. Hanya mengkonfigurasi daemon Docker tidak cukup - kontainer runner itu sendiri perlu menjadi versi yang didukung CUDA.

Backend GPU yang tersedia:

  • cuda - NVIDIA CUDA (paling umum)
  • rocm - AMD ROCm
  • musa - Moore Threads MUSA
  • cann - Huawei CANN
  • auto - Deteksi otomatis (default)
  • none - Hanya CPU

Perintah Inti

Menarik Model

Tarik model yang dikemas sebelumnya dari Docker Hub:

# Tarik dasar
docker model pull ai/llama2

# Tarik versi spesifik
docker model pull ai/llama2:7b-q4

# Tarik dari registry kustom
docker model pull myregistry.com/models/mistral:latest

# Daftar model yang tersedia dalam namespace
docker search ai/

Menjalankan Model

Mulai model dengan pelayanan API otomatis:

# Jalankan dasar (interaktif)
docker model run ai/llama2 "Apa itu Docker?"

# Jalankan sebagai layanan (dalam latar belakang)
docker model run -d

secara keseluruhan kita tidak memiliki banyak opsi dengan menjalankan model melalui CLI:

docker model run --help
Usage:  docker model run MODEL [PROMPT]

Jalankan model dan berinteraksi dengannya menggunakan prompt yang diserahkan atau mode chat

Opsi:
      --color string                  Gunakan output berwarna (auto|yes|no) (default "auto")
      --debug                         Aktifkan logging debug
  -d, --detach                        Muat model di latar belakang tanpa interaksi
      --ignore-runtime-memory-check   Jangan blokir tarik jika memori runtime yang diperkirakan untuk model melebihi sumber daya sistem.

Mendaftar Model

Lihat model yang diunduh dan berjalan:

# Daftar semua model yang diunduh
docker model ls

# Daftar model yang berjalan
docker model ps

# Daftar dengan informasi terperinci
docker model ls --json

# Daftar dengan informasi terperinci
docker model ls --openai

# Akan mengembalikan hash kode
docker model ls -q

Menghapus Model

Hapus model dari penyimpanan lokal:

# Hapus model spesifik
docker model rm ai/llama2

# Hapus dengan paksa (bahkan jika berjalan)
docker model rm -f ai/llama2

# Hapus model yang tidak digunakan
docker model prune

# Hapus semua model
docker model rm $(docker model ls -q)

Mengonfigurasi Ukuran Konteks Model

Kita tidak dapat menggunakan CLI untuk menentukan ukuran konteks untuk permintaan tertentu.

Secara dasar, kita hanya dapat mengontrol ukuran konteks model dalam tiga cara:

  1. Paket model sendiri, menentukan ukuran konteks yang diperlukan dengan hardcoded (Lihat bagian berikutnya untuk informasi lebih lanjut.)

  2. Saat menggunakan docker model runner, konfigurasikan perintah dengan parameter –context-size seperti:

docker model configure --context-size=10000 ai/gemma3-qat:4B

Kemudian Anda dapat memanggil curl kepadanya, tetapi tidak dapat melakukan docker model run... - yang satu ini akan mengabaikan konfigurasi.

  1. Dalam file docker-compose.yaml, tetapi kita tidak dapat menggunakan gambar docker-model-runner ini cara ini, karena itu mengirimkan ukuran konteks hardcoded sebesar 4096 ke model
...
models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240
...

Untuk informasi lebih lanjut, silakan lihat posting khusus tentang hal ini: Menentukan ukuran konteks dalam DMR

Mengemas Model Kustom

Membuat OCI Artifact dari GGUF

Paket model GGUF Anda sendiri:

# Pengemasan dasar
docker model package --gguf /path/to/model.gguf myorg/mymodel:latest

# Pengemasan dengan metadata
docker model package \
  --gguf /path/to/model.gguf \
  --label "description=Model Llama kustom" \
  --label "version=1.0" \
  myorg/mymodel:v1.0

# Pengemasan dan push dalam satu perintah
docker model package --gguf /path/to/model.gguf --push myorg/mymodel:latest

# Pengemasan dengan ukuran konteks kustom
docker model package \
  --gguf /path/to/model.gguf \
  --context 8192 \
  myorg/mymodel:latest

Menerbitkan Model

Kirim model ke registri:

# Masuk ke Docker Hub
docker login

# Kirim ke Docker Hub
docker model push myorg/mymodel:latest

# Kirim ke registri pribadi
docker login myregistry.com
docker model push myregistry.com/models/mymodel:latest

# Tag dan kirim
docker model tag mymodel:latest myorg/mymodel:v1.0
docker model push myorg/mymodel:v1.0

Penggunaan API

Titik Akhir yang Kompatibel dengan OpenAI

Docker Model Runner secara otomatis mengekspos titik akhir API yang kompatibel dengan OpenAI:

# Mulai model dengan API
docker model run -d -p 8080:8080 --name llm ai/llama2

# Kompleksi chat
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Halo!"}]
  }'

# Generasi teks
curl http://localhost:8080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "prompt": "Pada suatu waktu",
    "max_tokens": 100
  }'

# Respons streaming
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Ceritakan sebuah cerita"}],
    "stream": true
  }'

# Daftar model yang tersedia melalui API
curl http://localhost:8080/v1/models

# Informasi model
curl http://localhost:8080/v1/models/llama2

Konfigurasi Docker Compose

File Compose Dasar

version: '3.8'

services:
  llm:
    image: docker-model-runner
    model: ai/llama2:7b-q4
    ports:
      - "8080:8080"
    environment:
      - MODEL_TEMPERATURE=0.7
    volumes:
      - docker-model-runner-models:/models
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  docker-model-runner-models:
    external: true

Pengaturan Multi-Model

version: '3.8'

services:
  llama:
    image: docker-model-runner
    model: ai/llama2
    ports:
      - "8080:8080"
    
  mistral:
    image: docker-model-runner
    model: ai/mistral
    ports:
      - "8081:8080"
    
  embedding:
    image: docker-model-runner
    model: ai/nomic-embed-text
    ports:
      - "8082:8080"

Untuk konfigurasi Docker Compose yang lebih lanjut dan perintah, lihat Docker Compose Cheatsheet yang mencakup jaringan, volume, dan pola orkestrasi.

Variabel Lingkungan

Konfigurasikan perilaku model dengan variabel lingkungan:

# Suhu (0.0-1.0)
MODEL_TEMPERATURE=0.7

# Sampling top-p
MODEL_TOP_P=0.9

# Sampling top-k
MODEL_TOP_K=40

# Maksimum token
MODEL_MAX_TOKENS=2048

# Jumlah lapisan GPU
MODEL_GPU_LAYERS=35

# Ukuran batch
MODEL_BATCH_SIZE=512

# Jumlah thread (CPU)
MODEL_THREADS=8

# Aktifkan logging rinci
MODEL_VERBOSE=true

# Kunci API untuk otentikasi
MODEL_API_KEY=your-secret-key

Jalankan dengan variabel lingkungan:

docker model run \
  -e MODEL_TEMPERATURE=0.8 \
  -e MODEL_API_KEY=secret123 \
  ai/llama2

Konfigurasi GPU

Deteksi GPU Otomatis

DMR secara otomatis mendeteksi dan menggunakan GPU yang tersedia:

# Gunakan semua GPU
docker model run --gpus all ai/llama2

# Gunakan GPU spesifik
docker model run --gpus 0 ai/llama2

# Gunakan beberapa GPU spesifik
docker model run --gpus 0,1,2 ai/llama2

# GPU dengan batas memori
docker model run --gpus all --memory 16g ai/llama2

Mode Hanya CPU

Paksa inferensi CPU ketika GPU tersedia:

docker model run --no-gpu ai/llama2

Paralelisme Tensor Multi-GPU

Distribusikan model besar ke beberapa GPU:

docker model run \
  --gpus all \
  --tensor-parallel 2 \
  ai/llama2-70b

Inspeksi dan Debugging

Lihat Detail Model

# Inspeksi konfigurasi model
docker model inspect ai/llama2

# Lihat lapisan model
docker model history ai/llama2

# Periksa ukuran model dan metadata
docker model inspect --format='{{.Size}}' ai/llama2

Log dan Monitoring

# Lihat log model
docker model logs llm

# Ikuti log secara real-time
docker model logs -f llm

# Lihat 100 baris terakhir
docker model logs --tail 100 llm

# Lihat log dengan timestamp
docker model logs -t llm

Statistik Kinerja

# Penggunaan sumber daya
docker model stats

# Statistik model spesifik
docker model stats llm

# Statistik dalam format JSON
docker model stats --format json

Jaringan

Menyediakan API

# Port default (8080)
docker model run -p 8080:8080 ai/llama2

# Port kustom
docker model run -p 3000:8080 ai/llama2

# Bind ke antarmuka spesifik
docker model run -p 127.0.0.1:8080:8080 ai/llama2

# Banyak port
docker model run -p 8080:8080 -p 9090:9090 ai/llama2

Konfigurasi Jaringan

# Buat jaringan kustom
docker network create llm-network

# Jalankan model pada jaringan kustom
docker model run --network llm-network --name llm ai/llama2

# Hubungkan ke jaringan yang ada
docker model run --network host ai/llama2

Keamanan

Kontrol Akses

# Jalankan dengan otentikasi API key
docker model run \
  -e MODEL_API_KEY=my-secret-key \
  ai/llama2

# Gunakan dengan otentikasi
curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer my-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama2", "messages": [...]}'

Otentikasi Registry

# Masuk ke registry pribadi
docker login myregistry.com -u username -p password

# Tarik dari registry pribadi
docker model pull myregistry.com/private/model:latest

# Gunakan helper kredensial
docker login --password-stdin < token.txt

Praktik Terbaik

Pemilihan Model

# Gunakan model yang dikuantisasi untuk inferensi yang lebih cepat
docker model pull ai/llama2:7b-q4     # Kuantisasi 4-bit
docker model pull ai/llama2:7b-q5     # Kuantisasi 5-bit
docker model pull ai/llama2:7b-q8     # Kuantisasi 8-bit

# Periksa variasi model
docker search ai/llama2

Manajemen Sumber Daya

# Tetapkan batas memori
docker model run --memory 8g --memory-swap 16g ai/llama2

# Tetapkan batas CPU
docker model run --cpus 4 ai/llama2

# Batasi memori GPU
docker model run --gpus all --gpu-memory 8g ai/llama2

Pemeriksaan Kesehatan

# Jalankan dengan pemeriksaan kesehatan
docker model run \
  --health-cmd "curl -f http://localhost:8080/health || exit 1" \
  --health-interval 30s \
  --health-timeout 10s \
  --health-retries 3 \
  ai/llama2

Orkestrasi Produksi

Untuk penggunaan produksi dengan Kubernetes, kontainer Docker Model Runner dapat diorkestrasi menggunakan manifest Kubernetes standar. Definisikan deployment dengan batas sumber daya, autoscaling, dan load balancing. Untuk referensi lengkap perintah Kubernetes dan pola deployment, lihat Kubernetes Cheatsheet.

# Contoh: Deploy ke cluster Kubernetes
kubectl apply -f llm-deployment.yaml

# Skala deployment
kubectl scale deployment llm --replicas=3

# Ekspose sebagai layanan
kubectl expose deployment llm --type=LoadBalancer --port=8080

Penyelesaian Masalah

Masalah Umum

Model tidak dapat dimulai:

# Periksa ruang disk yang tersedia
df -h

# Lihat log kesalahan terperinci
docker model logs --tail 50 llm

# Verifikasi ketersediaan GPU
nvidia-smi  # Untuk GPU NVIDIA

Kesalahan kehabisan memori:

# Gunakan model yang dikuantisasi lebih kecil
docker model pull ai/llama2:7b-q4

# Kurangi ukuran konteks
docker model run -e MODEL_CONTEXT=2048 ai/llama2

# Batasi ukuran batch
docker model run -e MODEL_BATCH_SIZE=256 ai/llama2

Inferensi lambat:

# Periksa penggunaan GPU
docker model stats llm

# Pastikan GPU digunakan
docker model logs llm | grep -i gpu

# Tingkatkan jumlah lapisan GPU
docker model run -e MODEL_GPU_LAYERS=40 ai/llama2

Perintah Diagnostik

# Informasi sistem
docker model system info

# Penggunaan disk
docker model system df

# Bersihkan sumber daya yang tidak digunakan
docker model system prune

# Bersihkan penuh (hapus semua model)
docker model system prune -a

Contoh Integrasi

Integrasi Python

import openai

# Konfigurasi klien untuk Docker Model Runner
client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"  # DMR tidak memerlukan kunci secara default
)

# Kompleksi chat
response = client.chat.completions.create(
    model="llama2",
    messages=[
        {"role": "user", "content": "Halo!"}
    ]
)

print(response.choices[0].message.content)

# Streaming
stream = client.chat.completions.create(
    model="llama2",
    messages=[{"role": "user", "content": "Ceritakan sebuah cerita"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Skrip Bash

#!/bin/bash

# Mulai model jika belum berjalan
if ! docker model ps | grep -q "llm"; then
    docker model run -d --name llm -p 8080:8080 ai/llama2
    echo "Menunggu model untuk dimulai..."
    sleep 10
fi

# Buat panggilan API
curl -s http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "'"$1"'"}]
  }' | jq -r '.choices[0].message.content'

Integrasi Node.js

import OpenAI from 'openai';

const client = new OpenAI({
    baseURL: 'http://localhost:8080/v1',
    apiKey: 'not-needed'
});

async function chat(message) {
    const completion = await client.chat.completions.create({
        model: 'llama2',
        messages: [{ role: 'user', content: message }]
    });
    
    return completion.choices[0].message.content;
}

// Penggunaan
const response = await chat('Apa itu Docker Model Runner?');
console.log(response);

Tautan Berguna

Dokumentasi Resmi

Cheat Sheet Terkait

Artikel Perbandingan