Docker Compose 애플리케이션에서 AI 모델 정의하기

Compose로 애플리케이션의 핵심 구성 요소로서 AI 모델을 정의할 수 있어요. 서비스와 함께 모델 의존성을 선언하고, Compose Specification을 지원하는 어떤 플랫폼에서든 애플리케이션을 실행할 수 있답니다.

출처: 문서

본문

사전 요구 사항 (Prerequisites)

Docker Compose v2.38 이상
Docker Model Runner (DMR)처럼 Compose 모델을 지원하는 플랫폼

Compose 모델이란 무엇인가?

Compose 모델은 애플리케이션에서 AI 모델 의존성을 정의하는 표준화된 방법이에요. Compose 파일의 models 최상위 요소를 사용하면 다음을 할 수 있어요:

애플리케이션이 필요한 AI 모델을 선언
모델 구성과 요구 사항을 지정
애플리케이션을 여러 플랫폼에서 이식 가능하게 만들기
플랫폼이 모델 프로비저닝과 수명 주기 관리를 처리하도록 맡기기

기본적인 모델 정의

Compose 애플리케이션에서 모델을 정의하려면 models 최상위 요소를 사용하면 돼요:

services:
  chat-app:
    image: my-chat-app
    models:
      - llm

models:
  llm:
    model: ai/smollm2

이 예제는 다음을 정의해요:

chat-app 이라는 이름의 서비스로, llm 이라는 모델을 사용
aim/smollm2 모델 이미지를 참조하는 llm 모델 정의

모델 구성 옵션

모델은 다양한 구성 옵션을 지원해요:

models:
  llm:
    model: ai/smollm2
    context_size: 1024
    runtime_flags:
      - "--a-flag"
      - "--another-flag=42"

일반적인 구성 옵션은 다음과 같아요:

model (필수): 모델의 OCI 아티팩트 식별자예요. Compose가 이를 풀(pull)해서 모델 러너를 통해 실행해요.
context_size: 모델의 최대 토큰 컨텍스트 크기를 정의해요.

Note 각 모델은 고유한 최대 컨텍스트 크기를 가져요. 컨텍스트 길이를 늘릴 때는 하드웨어 제약을 고려해야 해요. 일반적으로 컨텍스트 크기는 특정 필요에 맞춰 가능한 한 작게 유지하는 게 좋아요.

runtime_flags: 모델이 시작될 때 추론 엔진(inference engine)에 전달되는 원시 명령줄 플래그 목록이에요. 자주 쓰는 파라미터와 예제는 Configuration options 문서를 참고하세요.
x-* 같은 확장 속성을 통해 플랫폼별 옵션을 사용할 수도 있어요.

Tip 더 많은 예제는 Common runtime configurations 섹션을 참고하세요.

서비스 모델 바인딩

서비스는 짧은 구문(short syntax)과 긴 구문(long syntax) 두 가지 방식으로 모델을 참조할 수 있어요.

짧은 구문 (Short syntax)

짧은 구문은 모델을 서비스에 바인딩하는 가장 간단한 방법이에요:

services:
  app:
    image: my-app
    models:
      - llm
      - embedding-model

models:
  llm:
    model: ai/smollm2
  embedding-model:
    model: ai/all-minilm

짧은 구문을 사용하면 플랫폼이 모델 이름에 기반해 환경 변수를 자동으로 생성해줘요:

LLM_URL - LLM 모델에 접근하는 URL
LLM_MODEL - LLM 모델의 식별자
EMBEDDING_MODEL_URL - embedding-model 에 접근하는 URL
EMBEDDING_MODEL_MODEL - embedding-model 의 모델 식별자

긴 구문 (Long syntax)

긴 구문을 사용하면 환경 변수 이름을 직접 커스터마이즈할 수 있어요:

services:
  app:
    image: my-app
    models:
      llm:
        endpoint_var: AI_MODEL_URL
        model_var: AI_MODEL_NAME
      embedding-model:
        endpoint_var: EMBEDDING_URL
        model_var: EMBEDDING_NAME

models:
  llm:
    model: ai/smollm2
  embedding-model:
    model: ai/all-minilm

이 구성으로 서비스는 다음을 전달받아요:

LLM 모델용 AI_MODEL_URL 과 AI_MODEL_NAME
임베딩 모델용 EMBEDDING_URL 과 EMBEDDING_NAME

플랫폼 이식성

Compose 모델을 사용하는 주요 장점 중 하나는 Compose specification을 지원하는 여러 플랫폼에서의 이식성이에요.

Docker Model Runner

Docker Model Runner가 활성화된 경우:

services:
  chat-app:
    image: my-chat-app
    models:
      llm:
        endpoint_var: AI_MODEL_URL
        model_var: AI_MODEL_NAME

models:
  llm:
    model: ai/smollm2
    context_size: 4096
    runtime_flags:
      - "--no-prefill-assistant"

Docker Model Runner는 다음을 수행해요:

지정된 모델을 로컬에서 풀하고 실행
모델에 접근하기 위한 엔드포인트 URL 제공
서비스에 환경 변수 주입

클라우드 제공자 (Cloud providers)

Compose 모델 specification은 이식 가능해요. Compose specification을 구현하는 플랫폼이라면 models 최상위 요소를 지원해서, 같은 Compose 파일을 다른 인프라에서도 실행할 수 있어요. 클라우드별 동작은 확장 속성(x-*)으로 설정할 수 있어요:

services:
  chat-app:
    image: my-chat-app
    models:
      - llm

models:
  llm:
    model: ai/smollm2
# Cloud-specific configurations
x-cloud-options:
  - "cloud.instance-type=gpu-small"
  - "cloud.region=us-west-2"

플랫폼이 모델 정의를 처리하는 방식은 구현에 따라 달라져요. 플랫폼은 다음을 할 수 있어요:

로컬에서 모델을 실행하는 대신 관리형 AI 서비스를 사용
플랫폼 특화 최적화와 스케일링 적용
추가적인 모니터링과 로깅 기능 제공
모델 버전 관리와 업데이트를 자동으로 처리

일반적인 런타임 구성

아래는 다양한 사용 사례에 대한 예제 구성들이에요.

개발 (Development)

services:
  app:
    image: app
    models:
      dev_model:
        endpoint_var: DEV_URL
        model_var: DEV_MODEL

models:
  dev_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--verbose" # Set verbosity level to infinity
      - "--verbose-prompt" # Print a verbose prompt before generation
      - "--log-prefix" # Enable prefix in log messages
      - "--log-timestamps" # Enable timestamps in log messages
      - "--log-colors" # Enable colored logging

추론을 비활성화한 보수적 설정 (Conservative with disabled reasoning)

services:
  app:
    image: app
    models:
      conservative_model:
        endpoint_var: CONSERVATIVE_URL
        model_var: CONSERVATIVE_MODEL

models:
  conservative_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--temp" # Temperature
      - "0.1"
      - "--top-k" # Top-k sampling
      - "1"
      - "--reasoning-budget" # Disable reasoning
      - "0"

높은 무작위성의 창의적 설정 (Creative with high randomness)

services:
  app:
    image: app
    models:
      creative_model:
        endpoint_var: CREATIVE_URL
        model_var: CREATIVE_MODEL

models:
  creative_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--temp" # Temperature
      - "1"
      - "--top-p" # Top-p sampling
      - "0.9"

고도로 결정적인 설정 (Highly deterministic)

services:
  app:
    image: app
    models:
      deterministic_model:
        endpoint_var: DET_URL
        model_var: DET_MODEL

models:
  deterministic_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--temp" # Temperature
      - "0"
      - "--top-k" # Top-k sampling
      - "1"

동시 처리 (Concurrent processing)

services:
  app:
    image: app
    models:
      concurrent_model:
        endpoint_var: CONCURRENT_URL
        model_var: CONCURRENT_MODEL

models:
  concurrent_model:
    model: ai/model
    context_size: 2048
    runtime_flags:
      - "--threads" # Number of threads to use during generation
      - "8"
      - "--mlock" # Lock memory to prevent swapping

풍부한 어휘 모델 (Rich vocabulary model)

services:
  app:
    image: app
    models:
      rich_vocab_model:
        endpoint_var: RICH_VOCAB_URL
        model_var: RICH_VOCAB_MODEL

models:
  rich_vocab_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--temp" # Temperature
      - "0.1"
      - "--top-p" # Top-p sampling
      - "0.9"

임베딩 (Embeddings)

/v1/embeddings 엔드포인트와 함께 임베딩 모델을 사용할 때는 모델이 올바르게 구성되도록 --embeddings 런타임 플래그를 반드시 포함해야 해요:

services:
  app:
    image: app
    models:
      embedding_model:
        endpoint_var: EMBEDDING_URL
        model_var: EMBEDDING_MODEL

models:
  embedding_model:
    model: ai/all-minilm
    context_size: 2048
    runtime_flags:
      - "--embeddings" # Required for embedding models

참고 자료 (Reference)

models 최상위 요소
models 속성
Docker Model Runner 문서
Configuration options - 컨텍스트 크기와 런타임 파라미터
Inference engines - llama.cpp와 vLLM 상세
API reference - OpenAI 및 Ollama 호환 API

Docker Compose 애플리케이션에서 AI 모델 정의하기