Docker Model Runner: Panduan Konfigurasi Ukuran Konteks

Konfigurasikan ukuran konteks di Docker Model Runner dengan solusi kerumitan

Konten Halaman

Menyetel ukuran konteks di Docker Model Runner lebih kompleks dari yang seharusnya.

Meskipun parameter context_size ada dalam konfigurasi docker-compose, sering kali diabaikan oleh gambar docker/model-runner:latest-cuda, yang mengkodekan ulang ukuran konteks 4096 token. Panduan ini menjelaskan keterbatasan dan memberikan solusi praktis.

menyetel mobil Gambar ini dihasilkan oleh Flux 1 dev.

Memahami Masalahnya

Ketika menggunakan Docker Model Runner dengan docker-compose, Anda mungkin mengatur ukuran konteks seperti ini:

services:
  llm:
    image: docker/model-runner:latest-cuda
    models:
      - llm_model

models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240

Namun, memeriksa log menunjukkan ukuran konteks yang sebenarnya digunakan:

docker compose logs 2>&1 | grep -i "n_ctx"

Anda akan melihat output seperti:

llamaCppArgs: [... --ctx-size 4096 ...]
llama_context: n_ctx = 4096

Gambar docker/model-runner:latest-cuda mengkodekan ulang --ctx-size 4096 saat memanggil llama.cpp, sepenuhnya mengabaikan konfigurasi context_size: 10240 Anda.

Mengapa Ini Terjadi

Ukuran konteks (n_ctx) ditetapkan saat inisialisasi model dalam llama.cpp, mesin inferensi dasar yang digunakan oleh Docker Model Runner. Ini terjadi selama fase konstruksi konteks model, sebelum permintaan API apa pun diproses. Integrasi compose Docker Model Runner tampaknya memiliki bug di mana parameter context_size dari bagian models tidak dikirimkan dengan benar ke proses llama.cpp yang mendasarinya. Sebaliknya, ia secara default menggunakan 4096 token, terlepas dari konfigurasi Anda.

Keterbatasan ini berarti meskipun Docker Compose mengenali parameter context_size dalam konfigurasi YAML Anda, gambar docker/model-runner:latest-cuda tidak menghormatinya saat membangun argumen baris perintah llama.cpp. Flag yang dikodekan ulang --ctx-size 4096 mengambil alih dari konfigurasi apa pun yang Anda tentukan.

Solusi dan Alternatif

Apa yang harus dilakukan? Metode 1-2-3 akan bekerja, tetapi memiliki keterbatasan.

Metode 1. ad-hoc, akan bekerja. Metode 2. dikodekan ulang dalam model. Metode 3. diperlukan kontainerisasi dan memasukkan aplikasi Anda sendiri ke dalam komposisi. Ini lebih dekat ke produksi.

Metode 1: Gunakan docker model configure (Terbatas)

Anda dapat mengatur ukuran konteks menggunakan CLI Docker Model, yang menyimpan konfigurasi dalam metadata Docker:

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

Perintah ini memperbarui konfigurasi model, tetapi implementasinya memiliki keterbatasan signifikan. Konfigurasi disimpan tetapi tidak selalu diterapkan dengan benar.

Keterbatasan:

  • Ini tidak bekerja ketika menggunakan docker model run secara langsung, hanya melalui curl ke akhir titik API
  • Anda tidak dapat menggunakan docker model run setelah mengonfigurasi - akan mengabaikan konfigurasi
  • Konfigurasi diabaikan ketika menggunakan docker-compose dengan gambar docker/model-runner:latest-cuda
  • Konfigurasi mungkin hilang ketika model diperbarui atau diunduh kembali

Metode ini bekerja terbaik untuk pengujian dengan panggilan API langsung, tetapi tidak cocok untuk penempatan produksi menggunakan docker-compose.

Metode 2: Kemas Model Anda Sendiri

Cara paling andal untuk menetapkan ukuran konteks khusus adalah dengan mengemas model Anda sendiri dengan ukuran konteks yang diinginkan menggunakan docker model package. Ini memasak ukuran konteks ke dalam metadata model saat pengemasan:

docker model package \
  --gguf /path/to/model.gguf \
  --context-size 10240 \
  --name my-model:custom-context

Ini menciptakan artefak OCI baru (mirip dengan gambar Docker) dengan ukuran konteks yang dikonfigurasi secara permanen. Model yang dikemas kemudian dapat dipasang ke Docker Hub atau registry yang sesuai dengan OCI dan diunduh seperti model Docker Model Runner lainnya.

Namun, pendekatan ini memerlukan:

  • Akses ke file model GGUF asli (format kuantisasi yang digunakan oleh llama.cpp)
  • Pengemasan ulang setiap kali Anda ingin mengubah ukuran konteks, yang bisa memakan waktu
  • Manajemen registri model Anda sendiri atau akun Docker Hub
  • Pemahaman tentang alur kerja pengemasan Docker Model Runner

Metode ini paling cocok untuk lingkungan produksi di mana Anda membutuhkan ukuran konteks yang konsisten dan dapat diulang di seluruh penempatan.

Metode 3: Docker Compose

Ini saat ini rusak untuk docker/model-runner:latest-cuda

Tetapi untuk aplikasi Anda sendiri dalam gambar mungkin bekerja :)

Meskipun sintaks ada dalam docker-compose.yml:

services:
  llm:
    image: docker/model-runner:latest-cuda
    models:
      - llm_model

models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240

Ini tidak bekerja - parameter context_size dikenali oleh docker-compose tetapi tidak diterapkan. Model masih menggunakan 4096 token.

Metode 4: Variabel Lingkungan (Juga Rusak)

Mencoba menggunakan variabel lingkungan MODEL_CONTEXT:

services:
  llm:
    image: docker/model-runner:latest-cuda
    environment:
      - MODEL_CONTEXT=10240

Ini juga tidak bekerja - variabel lingkungan tidak dihormati ketika menggunakan docker-compose.

Memverifikasi Ukuran Konteks

Untuk memeriksa ukuran konteks yang sebenarnya digunakan, periksa lognya:

# Periksa argumen llama.cpp
docker compose logs 2>&1 | grep "llamaCppArgs"

# Periksa ukuran konteks sebenarnya
docker compose logs 2>&1 | grep -i "n_ctx" | tail -10

Anda akan melihat output seperti:

llamaCppArgs: [-ngl 999 --metrics --model /models/... --ctx-size 4096 ...]
llama_context: n_ctx = 4096
llama_context: n_ctx_per_seq = 4096

Jika Anda melihat n_ctx = 4096 meskipun mengonfigurasi nilai yang berbeda, konfigurasi Anda diabaikan.

Menguji Ukuran Konteks

Untuk memverifikasi apakah konfigurasi ukuran konteks Anda sebenarnya diterapkan, Anda perlu menguji dengan prompt yang melebihi batas default 4096 token. Berikut adalah skrip praktis menggunakan Python untuk menguji apakah konfigurasi ukuran konteks Anda bekerja:

#!/bin/bash
MODEL="ai/gemma3-qat:4B"
PORT=8085

# Uji dengan prompt besar
python3 -c "print('test ' * 5000)" > large_prompt.txt

python3 << 'PYTHON' > request.json
import json
import os

with open('large_prompt.txt', 'r') as f:
    large_prompt = f.read().strip()

request = {
    "model": os.environ.get("MODEL", "ai/gemma3-qat:4B"),
    "messages": [{
        "role": "user",
        "content": large_prompt
    }]
}
print(json.dumps(request))
PYTHON

curl -s http://localhost:${PORT}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d @request.json > response.json

# Periksa penggunaan token
python3 << 'PYTHON'
import json
with open('response.json') as f:
    r = json.load(f)
    if 'usage' in r:
        print(f"Prompt tokens: {r['usage']['prompt_tokens']}")
        if r['usage']['prompt_tokens'] > 4096:
            print("✅ Ukuran konteks lebih besar dari 4096!")
        else:
            print("⚠️ Ukuran konteks tampaknya dibatasi hingga 4096")
PYTHON

Solusi Alternatif

Jika Anda membutuhkan konfigurasi ukuran konteks yang lebih fleksibel, pertimbangkan alternatif berikut:

  • Ollama - Solusi alternatif hosting LLM yang memberikan kontrol yang lebih baik terhadap ukuran konteks dan konfigurasi yang lebih sederhana. Ollama memungkinkan Anda menentukan ukuran konteks per model dan tidak memiliki keterbatasan docker-compose yang sama.

  • Perbandingan Docker Model Runner vs Ollama - Perbandingan terperinci antara kedua solusi, termasuk kemampuan konfigurasi ukuran konteks, kinerja, dan kapan harus memilih platform mana.

Sumber Daya Terkait

Docker Model Runner

Docker dan Infrastruktur

Solusi LLM Alternatif

Dokumentasi Resmi

Kesimpulan

Menyetel ukuran konteks di Docker Model Runner saat ini bermasalah ketika menggunakan docker-compose. Meskipun sintaks konfigurasi ada dalam spesifikasi Docker Compose, tidak diimplementasikan dengan benar dalam gambar docker/model-runner:latest-cuda, yang mengkodekan ulang ukuran konteks 4096 token terlepas dari konfigurasi Anda.

Solusi paling andal adalah mengemas model Anda sendiri dengan ukuran konteks yang diinginkan menggunakan docker model package, meskipun ini menambah kompleksitas pada alur kerja Anda dan memerlukan akses ke file model GGUF asli. Alternatifnya, Anda dapat menggunakan docker model configure untuk akses langsung ke API, tetapi ini tidak bekerja dengan penempatan docker-compose.

Untuk kebanyakan kasus penggunaan, ukuran konteks default 4096 token sudah cukup untuk aplikasi AI percakapan biasa. Jika Anda membutuhkan jendela konteks yang lebih besar atau konfigurasi yang lebih fleksibel, pertimbangkan menggunakan Ollama sebagai alternatif, yang memberikan kontrol yang lebih baik terhadap ukuran konteks tanpa keterbatasan docker-compose.

Anda masih dapat mengoptimalkan penggunaan VRAM melalui cara lain seperti kuantisasi model (Q4, Q6, Q8) dan konfigurasi lapisan GPU (MODEL_GPU_LAYERS), yang lebih efektif dalam mengurangi konsumsi memori dibandingkan penyesuaian ukuran konteks.

Untuk informasi lebih lanjut tentang optimasi GPU dan manajemen VRAM, lihat panduan kami tentang menyetel dukungan GPU NVIDIA.