도커 모델 러너: 컨텍스트 크기 설정 가이드

Docker 모델 러너에서 컨텍스트 크기 구성 및 대안 마련

Page content

Docker 모델 러너에서 컨텍스트 크기 구성은 예상보다 더 복잡한 경우가 많습니다.

context_size 파라미터는 docker-compose 구성에 존재하지만, docker/model-runner:latest-cuda 이미지는 이 값을 무시하고 고정된 4096 토큰의 컨텍스트 크기를 사용합니다. 이 가이드에서는 이러한 제한 사항을 설명하고 실용적인 대안을 제공합니다. Docker 모델 러너와 Ollama, vLLM, LocalAI, 클라우드 제공업체 간의 비교를 포함한 더 넓은 비교를 원하시면 LLM 호스팅: 로컬, 자가 호스팅 및 클라우드 인프라 비교를 참조하시기 바랍니다.

configuring car 이 이미지는 Flux 1 dev에 의해 생성되었습니다.

문제 이해

Docker 모델 러너와 docker-compose를 함께 사용할 때 컨텍스트 크기를 다음과 같이 구성할 수 있습니다:

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

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

하지만 로그를 확인하면 실제로 사용되는 컨텍스트 크기를 알 수 있습니다:

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

출력은 다음과 같을 수 있습니다:

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

docker/model-runner:latest-cuda 이미지는 --ctx-size 4096을 고정하여 llama.cpp에 전달하고, 사용자가 지정한 context_size: 10240 구성은 완전히 무시됩니다.

왜 이런 일이 발생하는가

컨텍스트 크기(n_ctx)는 Docker 모델 러너가 사용하는 백엔드 추론 엔진인 llama.cpp에서 모델 초기화 시점에 설정됩니다. 이는 API 요청 처리 전 모델의 컨텍스트 구성 단계에서 발생합니다. Docker 모델 러너의 compose 통합에는 models 섹션의 context_size 파라미터를 llama.cpp 프로세스에 올바르게 전달하지 못하는 버그가 존재합니다. 따라서 context_size 값을 설정하더라도 --ctx-size 4096이 기본값으로 사용됩니다.

이러한 제한으로 인해 Docker Compose는 YAML 구성에서 context_size 파라미터를 인식하지만, docker/model-runner:latest-cuda 이미지는 llama.cpp 명령줄 인수 구성 시 이 값을 무시하고 --ctx-size 4096을 우선 적용합니다.

대안 및 해결 방법

어떤 방법을 사용해야 할까요? 방법 1~3은 모두 작동하지만 각각 제한이 있습니다.

방법 1. 임시적, 작동은 하지만 제한이 있음
방법 2. 모델 내부에 고정
방법 3. 컨테이너화 및 자체 앱을 구성, 프로덕션에 더 가까움

방법 1: docker model configure 사용 (제한 있음)

Docker 모델 CLI를 사용하여 컨텍스트 크기를 구성할 수 있습니다. 이는 Docker 모델 메타데이터에 구성 정보를 저장합니다:

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

이 명령어는 모델의 구성 정보를 업데이트하지만, 구현에는 상당한 제한이 있습니다. 구성 정보는 저장되지만 항상 올바르게 적용되지는 않습니다.

제한 사항:

  • docker model run을 직접 사용할 때는 작동하지 않으며, API 엔드포인트로 curl을 통해만 작동
  • 구성 후 docker model run을 사용할 수 없으며, 구성 정보를 무시
  • docker/model-runner:latest-cuda 이미지와 함께 docker-compose를 사용할 때 구성 정보가 무시
  • 모델이 업데이트되거나 다시 끌어올릴 때 구성 정보가 손실될 수 있음

이 방법은 직접 API 호출을 사용한 테스트에 가장 적합하지만, docker-compose를 사용하는 프로덕션 배포에는 적합하지 않습니다.

방법 2: 자체 모델 패키징

커스텀 컨텍스트 크기를 설정하는 가장 신뢰할 수 있는 방법은 docker model package를 사용하여 원하는 컨텍스트 크기를 가진 자체 모델을 패키징하는 것입니다. 이 방법은 패키징 시점에 컨텍스트 크기를 모델 메타데이터에 고정시킵니다:

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

이 명령어는 새로운 OCI 아티팩트(도커 이미지와 유사)를 생성하며, 컨텍스트 크기가 영구적으로 구성됩니다. 패키징된 모델은 Docker Hub 또는 OCI 호환 레지스트리에 푸시하고, 다른 Docker 모델 러너 모델과 마찬가지로 끌어올 수 있습니다.

이 방법을 사용하려면 다음이 필요합니다:

  • 원본 GGUF 모델 파일에 대한 접근 (llama.cpp이 사용하는 양자화 형식)
  • 컨텍스트 크기를 변경할 때마다 모델을 다시 패키징해야 하며, 이는 시간이 많이 걸릴 수 있음
  • 자체 모델 레지스트리 또는 Docker Hub 계정 관리
  • Docker 모델 러너 패키징 워크플로우에 대한 이해

이 방법은 컨테이너 배포 간 일관되고 재현 가능한 컨텍스트 크기가 필요한 프로덕션 환경에 가장 적합합니다.

방법 3: Docker Compose

현재 docker/model-runner:latest-cuda에 대해 작동하지 않음

하지만, 이미지 내에서 자체 앱을 사용하는 경우 작동할 수 있습니다 :)

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

이 방법은 작동하지 않음 - context_size 파라미터는 docker-compose에 의해 인식되지만 적용되지 않습니다. 모델은 여전히 4096 토큰을 사용합니다.

방법 4: 환경 변수 사용 (작동하지 않음)

MODEL_CONTEXT 환경 변수를 사용해 보세요:

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

이 방법도 작동하지 않음 - 환경 변수는 docker-compose를 사용할 때 무시됩니다.

컨텍스트 크기 확인

실제로 사용되는 컨텍스트 크기를 확인하려면 로그를 살펴보세요:

# llama.cpp 인수 확인
docker compose logs 2>&1 | grep "llamaCppArgs"

# 실제 컨텍스트 크기 확인
docker compose logs 2>&1 | grep -i "n_ctx" | tail -10

출력은 다음과 같을 수 있습니다:

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

4096 이외의 값을 설정했음에도 불구하고 n_ctx = 4096을 보는 경우, 구성이 무시되고 있습니다.

컨텍스트 크기 테스트

설정된 컨텍스트 크기 구성이 실제로 적용되었는지 확인하려면, 기본 4096 토큰 제한을 초과하는 프롬프트로 테스트해야 합니다. 아래는 Python을 사용하여 컨텍스트 크기 구성이 작동하는지 확인하는 실용적인 스크립트입니다:

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

# 대규모 프롬프트 테스트
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

# 토큰 사용량 확인
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("✅ 컨텍스트 창이 4096보다 크습니다!")
        else:
            print("⚠️ 컨텍스트 창이 4096으로 제한되어 있습니다.")
PYTHON

대안 솔루션

더 유연한 컨텍스트 크기 구성이 필요한 경우 다음 대안을 고려해 보세요:

  • Ollama - 컨텍스트 크기 및 구성에 대한 더 나은 제어가 가능한 대안 LLM 호스팅 솔루션. Ollama는 모델별로 컨텍스트 크기를 지정할 수 있고, docker-compose 제한이 없습니다.

  • Docker 모델 러너 vs Ollama 비교 - 두 솔루션의 상세한 비교, 컨텍스트 크기 구성 능력, 성능, 각 플랫폼을 선택해야 할 때 등이 포함되어 있습니다.

Docker 모델 러너가 다른 로컬 및 클라우드 옵션과 어떻게 어울리는지 확인하려면 LLM 호스팅: 로컬, 자가 호스팅 및 클라우드 인프라 비교 가이드를 참조하시기 바랍니다.

관련 자료

Docker 모델 러너

Docker 및 인프라

대안 LLM 솔루션

공식 문서

결론

Docker 모델 러너에서 docker-compose를 사용할 때 컨텍스트 크기를 구성하는 것은 현재 문제가 있습니다. Docker Compose 명세에 context_size 구성이 존재하지만, docker/model-runner:latest-cuda 이미지는 사용자의 구성과 관계없이 4096 토큰의 고정된 컨텍스트 크기를 사용합니다.

가장 신뢰할 수 있는 대안은 docker model package를 사용하여 원하는 컨텍스트 크기를 가진 자체 모델을 패키징하는 것입니다. 하지만 이 방법은 작업 흐름에 복잡성을 추가하고, 원본 GGUF 모델 파일에 대한 접근이 필요합니다. 대안으로 docker model configure을 사용하여 직접 API 접근이 가능하지만, docker-compose 배포에서는 작동하지 않습니다.

대부분의 사용 사례에서는 기본 4096 토큰의 컨텍스트 크기가 일반적인 대화형 AI 애플리케이션에 충분합니다. 더 큰 컨텍스트 창 또는 더 유연한 구성이 필요한 경우, Ollama를 대안으로 고려해 보세요. 이 솔루션은 docker-compose 제한 없이 컨텍스트 크기에 대한 더 나은 제어를 제공합니다.

VRAM 사용량 최적화는 모델 양자화(Q4, Q6, Q8) 및 GPU 레이어 구성(MODEL_GPU_LAYERS)을 통해 다른 방법으로도 가능하며, 컨텍스트 크기 조정보다 메모리 소비 감소에 더 효과적입니다.

GPU 최적화 및 VRAM 관리에 대한 더 많은 정보는 NVIDIA GPU 지원 구성 가이드를 참조하시기 바랍니다.