구성 옵션

구성 옵션

Docker Model Runner는 모델 동작, 메모리 사용량, 추론 성능을 조정할 수 있는 여러 구성 옵션을 제공해요. 이 가이드는 핵심 설정과 적용 방법을 다뤄요.

출처: 문서

본문

컨텍스트 크기(context length)

컨텍스트 크기는 입력 프롬프트와 생성 출력을 모두 포함해 단일 요청에서 모델이 처리할 수 있는 최대 토큰 수를 정해요. 이는 메모리 사용량과 모델 기능에 영향을 주는 가장 중요한 설정 중 하나예요.

기본 컨텍스트 크기

기본적으로 Docker Model Runner는 기능과 리소스 효율의 균형을 맞춘 컨텍스트 크기를 사용해요:

엔진	기본 동작
llama.cpp	4096 토큰
vLLM	모델의 최대 훈련 컨텍스트 크기 사용

참고: 실제 기본값은 모델마다 달라요. 대부분의 모델은 기본적으로 2,048~8,192 토큰을 지원해요. 일부 최신 모델은 32K, 128K 또는 더 큰 컨텍스트를 지원해요.

컨텍스트 크기 구성

docker model configure 명령으로 모델별 컨텍스트 크기를 조정할 수 있어요:

$ docker model configure --context-size 8192 ai/qwen2.5-coder

또는 Compose 파일에서:

models:
  llm:
    model: ai/qwen2.5-coder
    context_size: 8192

컨텍스트 크기 가이드라인

컨텍스트 크기	전형적인 사용 사례	메모리 영향
2,048	간단한 질의, 짧은 코드 스니펫	낮음
4,096	표준 대화, 중간 크기 코드 파일	보통
8,192	긴 대화, 더 큰 코드 파일	높음
16,384+	긴 문서, 다중 파일 컨텍스트	매우 높음

중요: 컨텍스트 크기가 클수록 더 많은 메모리(RAM/VRAM)가 필요해요. 메모리 부족 오류가 발생하면 컨텍스트 크기를 줄이세요. 대략적으로 토큰 1,000개마다 모델 크기에 따라 추가 메모리가 약 100-500MB 필요해요.

모델의 최대 컨텍스트 확인

컨텍스트 크기를 포함한 모델의 구성을 보려면:

$ docker model inspect ai/qwen2.5-coder

참고: docker model inspect 명령은 모델의 최대 지원 컨텍스트 길이(예: gemma3.context_length)를 보여주지, 구성된 컨텍스트 크기를 보여주지는 않아요. 구성된 컨텍스트 크기는 docker model configure --context-size로 설정한 값으로, 추론 중 실제 한도를 나타내며 모델의 최대 지원 컨텍스트 길이보다 작거나 같아야 해요.

런타임 플래그

런타임 플래그를 사용하면 파라미터를 기본 추론 엔진에 직접 전달할 수 있어요. 이는 모델 동작에 대한 세밀한 제어를 제공해요.

런타임 플래그 사용

런타임 플래그는 여러 메커니즘으로 제공할 수 있어요.

Docker Compose 사용:

models:
  llm:
    model: ai/qwen2.5-coder
    context_size: 4096
    runtime_flags:
      - "--temp"
      - "0.7"
      - "--top-p"
      - "0.9"

명령줄 사용:

$ docker model configure ai/qwen2.5-coder -- --temp 0.7 --top-p 0.9

일반적인 llama.cpp 파라미터

다음은 가장 흔히 쓰는 llama.cpp 파라미터예요. 일반적인 사용 사례에서는 llama.cpp 문서를 찾아볼 필요가 없어요.

샘플링 파라미터

플래그	설명	기본값	범위
--temp	샘플링 온도. 낮을수록 결정적, 높을수록 창의적	0.8	0.0-2.0
--top-k	상위 K 토큰으로 샘플링 제한. 낮을수록 집중	40	1-100
--top-p	핵 샘플링 임계값. 낮을수록 집중	0.9	0.0-1.0
--min-p	최소 확률 임계값	0.05	0.0-1.0
--repeat-penalty	반복 토큰 페널티	1.1	1.0-2.0

예시: 결정적 출력(코드 생성용)

runtime_flags:
  - "--temp"
  - "0"
  - "--top-k"
  - "1"

예시: 창의적 출력(스토리텔링용)

runtime_flags:
  - "--temp"
  - "1.2"
  - "--top-p"
  - "0.95"

성능 파라미터

플래그	설명	기본값	참고
--threads	생성용 CPU 스레드	Auto	성능 코어 수로 설정
--threads-batch	배치 처리를 위한 CPU 스레드	Auto	보통 --threads와 동일
--batch-size	프롬프트 처리용 배치 크기	512	높을수록 프롬프트 처리 빠름
--mlock	모델을 메모리에 잠금	Off	스와핑 방지, 충분한 RAM 필요
--no-mmap	메모리 매핑 비활성화	Off	일부 시스템에서 성능 향상 가능

예시: 멀티코어 CPU에 최적화

runtime_flags:
  - "--threads"
  - "8"
  - "--batch-size"
  - "1024"

GPU 파라미터

플래그	설명	기본값	참고
--n-gpu-layers	GPU로 오프로드할 레이어	All(GPU 가능 시)	VRAM 부족 시 줄이기
--main-gpu	계산에 사용할 GPU	0	멀티 GPU 시스템용
--split-mode	GPU 간 분할 방식	layer	옵션: none, layer, row

예시: 부분 GPU 오프로드(VRAM 제한)

runtime_flags:
  - "--n-gpu-layers"
  - "20"

고급 파라미터

플래그	설명	기본값
--rope-scaling	RoPE 스케일링 방법	Auto
--rope-freq-base	RoPE 기본 주파수	모델 기본값
--rope-freq-scale	RoPE 주파수 스케일	모델 기본값
--no-prefill-assistant	어시스턴트 사전 채우기 비활성화	Off
--reasoning-budget	추론 모델용 토큰 예산	0(비활성화)

vLLM 파라미터

vLLM 백엔드를 사용할 때는 다른 파라미터를 사용할 수 있어요. --hf_overrides로 HuggingFace 모델 구성 오버라이드를 JSON으로 전달해요:

$ docker model configure --hf_overrides '{"rope_scaling": {"type": "dynamic", "factor": 2.0}}' ai/model-vllm

구성 프리셋

다음은 일반적인 사용 사례에 대한 완전한 구성 예시예요.

코드 완성(빠르고 결정적)

models:
  coder:
    model: ai/qwen2.5-coder
    context_size: 4096
    runtime_flags:
      - "--temp"
      - "0.1"
      - "--top-k"
      - "1"
      - "--batch-size"
      - "1024"

채팅 어시스턴트(균형)

models:
  assistant:
    model: ai/llama3.2
    context_size: 8192
    runtime_flags:
      - "--temp"
      - "0.7"
      - "--top-p"
      - "0.9"
      - "--repeat-penalty"
      - "1.1"

창의적 글쓰기(높은 온도)

models:
  writer:
    model: ai/llama3.2
    context_size: 8192
    runtime_flags:
      - "--temp"
      - "1.2"
      - "--top-p"
      - "0.95"
      - "--repeat-penalty"
      - "1.0"

긴 문서 분석(큰 컨텍스트)

models:
  analyzer:
    model: ai/qwen2.5-coder:14B
    context_size: 32768
    runtime_flags:
      - "--mlock"
      - "--batch-size"
      - "2048"

저메모리 시스템

models:
  efficient:
    model: ai/smollm2:360M-Q4_K_M
    context_size: 2048
    runtime_flags:
      - "--threads"
      - "4"

환경 기반 구성

컨테이너의 환경 변수로 모델을 구성할 수도 있어요:

변수	설명
LLM_URL	자동 주입된 모델 엔드포인트 URL
LLM_MODEL	자동 주입된 모델 식별자

이 값들이 어떻게 채워지는지에 대한 자세한 내용은 Models and Compose 문서를 참고해 주세요.

구성 초기화

docker model configure로 설정한 구성은 모델이 제거될 때까지 유지돼요. 구성을 초기화하려면:

$ docker model configure --context-size -1 ai/qwen2.5-coder

-1을 사용하면 기본값으로 초기화돼요.

다음 단계

• 추론 엔진 — llama.cpp와 vLLM 알아보기
• API 레퍼런스 — 요청별 구성용 API 파라미터
• Models and Compose — Compose 애플리케이션에서 모델 구성

더 알아보기 (Learn more)