docker-compose.yml에서 context_size가 docker/model-runner 이미지와 함께 작동하지 않는 이유는 무엇인가요?

docker/model-runner:latest-cuda 이미지는 llama.cpp를 호출할 때 –ctx-size 4096을 하드코딩하여 모델 섹션의 context_size 매개변수를 무시합니다. 이는 현재 구현의 알려진 한계입니다.

API 요청당 컨텍스트 크기를 변경할 수 있나요?

아니요, 컨텍스트 크기는 요청별로 설정되는 것이 아니라 모델 초기화 시에 설정됩니다. API 요청에서 max_tokens 매개변수만으로 출력 길이를 제어할 수 있습니다.

도커 모델 구성 –context-size가 작동하나요?

예, 하지만 docker model run을 직접 사용할 때만 해당됩니다. docker/model-runner 이미지와 docker-compose를 사용하는 경우 구성은 무시됩니다.

실제로 사용되는 컨텍스트 크기를 어떻게 확인할 수 있나요?

docker compose logs 2>&1 | grep -i "n_ctx" 명령어로 docker compose 로그를 확인하여 llama.cpp가 실제로 사용하는 컨텍스트 크기(n_ctx)를 확인하세요.

사용자 정의 컨텍스트 크기를 사용하는 가장 좋은 방법은 무엇인가요?

자신만의 모델을 docker 모델 패키지 –context-size와 함께 패키징하거나, docker 모델 configure를 사용하여 직접 docker 모델 실행 명령을 사용할 수 있습니다. docker-compose의 경우, context_size를 제대로 지원하는 향후 업데이트가 필요할 수 있습니다.

문맥 크기가 VRAM 사용에 왜 중요한가요?

더 큰 컨텍스트 크기는 더 많은 VRAM을 요구합니다. 그러나 docker/model-runner를 사용할 경우 컨텍스트 크기는 4096으로 고정되어 있으므로, VRAM 사용량은 주로 모델 크기, 양자화 수준 및 GPU 레이어 수(MODEL_GPU_LAYERS)에 의해 결정됩니다.

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

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

Page content

도커 모델 러너에서 컨텍스트 크기 구성은 예상보다 더 복잡합니다.

context_size 파라미터는 도커-컴포즈 구성에 존재하지만, docker/model-runner:latest-cuda 이미지는 이 값을 무시하고 4096 토큰의 컨텍스트 크기를 고정적으로 사용합니다. 이 가이드는 이러한 제한 사항을 설명하고 실용적인 대안을 제시합니다.

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

문제 이해

도커-컴포즈와 함께 도커 모델 러너를 사용할 때, 다음과 같이 컨텍스트 크기를 구성할 수 있습니다:

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을 고정적으로 사용하여, context_size: 10240 설정을 완전히 무시합니다.

이러한 문제가 발생하는 이유

컨텍스트 크기(n_ctx)는 도커 모델 러너가 사용하는 llama.cpp 엔진에서 모델 초기화 시 설정됩니다. 이는 API 요청이 처리되기 전에 모델의 컨텍스트 생성 단계에서 발생합니다. 도커 모델 러너의 도커-컴포즈 통합에는 models 섹션에서 context_size 파라미터를 llama.cpp 프로세스로 올바르게 전달하지 못하는 버그가 존재합니다. 따라서 context_size 설정과 관계없이 --ctx-size 4096 플래그가 기본값으로 사용됩니다.

이러한 제한으로 인해 도커-컴포즈는 YAML 구성에서 context_size 파라미터를 인식하지만, docker/model-runner:latest-cuda 이미지는 이를 llama.cpp 명령줄 인수에 반영하지 않습니다. --ctx-size 4096 플래그가 설정값보다 우선 적용됩니다.

대안 및 해결 방법

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

방법 1. 임시적, 작동은 하지만 제한이 있습니다.
방법 2. 모델 내부에 고정적으로 설정.
방법 3. 컨테이너화된 앱을 구성하여 사용. 이 방법은 생산 환경에 더 적합합니다.

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

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

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

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

제한 사항:

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

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

방법 2: 자체 모델 패키징

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

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

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

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

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

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

방법 3: 도커-컴포즈

현재 docker/model-runner:latest-cuda에 대해서는 작동하지 않습니다.

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

도커-컴포즈.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 파라미터는 도커-컴포즈에 의해 인식되지만 적용되지 않습니다. 모델은 여전히 4096 토큰을 사용합니다.

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

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

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

이 방법도 작동하지 않습니다 - 환경 변수는 도커-컴포즈를 사용할 때 무시됩니다.

컨텍스트 크기 확인

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

# 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 토큰 제한을 초과하는 프롬프트를 사용하여 테스트해야 합니다. 아래는 파이썬을 사용하여 컨텍스트 크기 설정이 작동하는지 확인하는 실용적인 스크립트입니다:

#!/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는 모델별로 컨텍스트 크기를 지정할 수 있으며, 도커-컴포즈의 제한을 피할 수 있습니다.
도커 모델 러너 vs Ollama 비교 - 두 솔루션의 비교, 컨텍스트 크기 구성 능력, 성능, 각 플랫폼을 선택할 때의 조건을 포함한 상세한 비교.

결론

도커-컴포즈를 사용할 때 도커 모델 러너에서 컨텍스트 크기를 구성하는 것은 현재 문제가 있습니다. 도커-컴포즈 명세에 context_size 구성 구문이 존재하지만, docker/model-runner:latest-cuda 이미지는 이 값을 무시하고 4096 토큰의 컨텍스트 크기를 고정적으로 사용합니다.

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

대부분의 사용 사례에서는 기본 4096 토큰의 컨텍스트 크기가 일반적인 대화형 AI 애플리케이션에 충분합니다. 더 큰 컨텍스트 윈도우나 더 유연한 구성이 필요한 경우, Ollama를 대안으로 고려하는 것이 좋습니다. 이는 도커-컴포즈의 제한 없이 컨텍스트 크기에 대한 더 나은 제어를 제공합니다.

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

GPU 최적화 및 VRAM 관리에 대한 자세한 내용은 NVIDIA GPU 지원 구성 가이드를 참조하세요.