다중모달 AI 모델 사용하기 — Docker Model Runner 중심 가이드

다중모달(multimodal) AI의 개념부터 Docker Model Runner(DMR)로 텍스트·이미지·오디오 입력을 처리하는 실전 방법, 내부 운영/보안 가이드, 점검 포인트까지 한 번에 볼 수 있습니다.

개요 & 배경

• 다중모달 AI는 하나의 모델이 텍스트·이미지·오디오 등 서로 다른 입력을 동시에 이해하고 결합해 답을 생성하는 기술입니다. 예를 들어 “이 사진에 뭐가 보여?”(이미지+텍스트), “이 오디오를 한 단어로 받아써”(오디오+텍스트) 같은 작업을 한 모델에서 수행합니다.
• Docker는 Model Runner로 로컬에서 이런 모델을 간단한 CLI와 OpenAI 호환 API로 실행/제공할 수 있게 했습니다. Gemma3, Moondream2, SmolVLM 등 이미지+텍스트 입력을 받는 모델 예시가 안내되어 있고, 오디오는 HF(허깅페이스) 모델 예시를 통해 다룹니다.
• 글(게시: 2025-11-03)에서는 CLI 한 줄로 이미지 설명을 시키는 예시, API로 텍스트+이미지(Base64)를 함께 보내는 예시, HF의 오디오 전사 모델을 호출하는 예시를 보여줍니다.

핵심 개념 정리

1. 모델 선택
   모든 모델이 멀티모달을 지원하는 것은 아닙니다. Docker Hub의 모델 카드에서 입력 유형(텍스트/이미지/오디오) 지원 여부를 확인하세요.
2. OpenAI 호환 API
   Model Runner는 chat/completions 포맷 등 OpenAI 호환 REST 인터페이스를 제공합니다. 익숙한 클라이언트로 그대로 붙여 쓸 수 있습니다.
3. 멀티모달 프로젝터(mmproj)
   이미지·오디오 같은 비텍스트 입력을 토큰 임베딩으로 변환해 LLM이 이해하도록 돕는 얇은 신경망 레이어입니다. Docker의 모델 OCI 아티팩트 안에 vnd.docker.ai.mmproj 미디어 타입 레이어로 포함됩니다.
4. 네트워크 노출 포트 & 접근 경로
   기본적으로 Docker 소켓을 통해 접근하지만, 호스트 TCP(기본 12434) 로도 노출할 수 있습니다(옵션). 내부망·프록시 구성 시 고려 포인트입니다.

실전 예시 — 바로 따라하기

1. 가장 빠른 맛보기 (CLI 한 줄)

# 로컬에 멀티모달 지원 모델(Gemma3 등)을 실행하고
# 이미지에 무엇이 있는지 묻는 간단한 예시
docker model run gemma3 "What's in this image? /path/to/image.jpg"

— 모델이 이미지 내용을 분석해 설명을 반환합니다.

2. OpenAI 호환 API로 텍스트+이미지 함께 보내기

curl --location 'http://localhost:12434/engines/llama.cpp/v1/chat/completions' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "ai/gemma3",
    "messages": [{
      "role": "user",
      "content": [
        { "type": "text", "text": "describe the image" },
        {
          "type": "image_url",
          "image_url": { "url": "data:image/png;base64,<BASE64_DATA>" }
        }
      ]
    }]
  }'

— 텍스트와 이미지(Base64) 를 하나의 메시지에 담아 전송합니다.

3. Hugging Face 모델로 오디오 전사(예시)

curl --location 'http://localhost:12434/engines/llama.cpp/v1/chat/completions' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "hf.co/ggml-org/ultravox-v0_5-llama-3_1-8b-gguf",
    "temperature": 0,
    "messages": [{
      "role": "user",
      "content": [
        { "type": "text", "text": "transcribe the audio, one word" },
        {
          "type": "input_audio",
          "input_audio": { "data": "<BASE64_MP3>", "format": "mp3" }
        }
      ]
    }]
  }'

— 허깅페이스 모델을 직접 경로(model: hf.co/...) 로 지정해 오디오 입력을 처리합니다.

4. API 테스트 팁

• 동일 엔드포인트로 일반 텍스트 질의도 간단히 수행할 수 있습니다.
• Docker 소켓 경유 또는 TCP 12434 로 호출할 수 있습니다. 운영에서는 TCP 노출 시 인증 프록시를 반드시 고려하세요.

300x250

운영 관점: 모델·런타임 관리 명령어

# 설치/확인
docker model install-runner        # (Docker Engine 환경) Model Runner 설치
docker model list                  # 풀(Pull)된 모델 목록
docker model inspect ai/gemma3     # 모델 메타데이터(아티팩트 정보) 확인
docker model logs                  # Model Runner 로그 확인

# 패키징
docker model package \
  --model-file path/to/model.gguf \
  --model ai/my-model:1.0          # GGUF → OCI 아티팩트 패키징

— 위 명령은 공식 레퍼런스의 CLI/REST 사용 범위에 기초한 운영 흐름입니다. 특히 inspect/package는 내부 레지스트리에 표준 형식으로 모델을 관리하는 데 유용합니다.

프로젝터(mmproj) 확인
docker model inspect ai/gemma3 결과의 아티팩트/레이어 정보를 점검하면 멀티모달 프로젝터가 포함되어 있음을 확인할 수 있습니다(문서·블로그 기준).

활용 시나리오 & 유사 내용

1. 비전 Q&A: 고객이 업로드한 상품 이미지에서 주요 속성 추출(색상·로고·형태), 품질 검사 코멘트 생성.
2. 문서+시각 컨텍스트 결합: 업무 문서 요약 중 이미지(차트/도면) 내용을 함께 참조해 더 정확한 요약/설명 생성.
3. 오디오 워크플로: 콜센터 음성 요약, 보안 교육 음성의 키워드 추출 → 티켓/대시보드 자동 기록.
4. Edge/온프레미스 운영: 데이터 반출 제한 환경에서 내부 GPU/CPU 자원으로 저비용 로컬 추론 파이프라인 구축.
   — 모두 OpenAI 호환 API 덕분에 기존 클라이언트/SDK를 바꾸지 않고 빠르게 PoC→운영 이전이 가능합니다.

보안 관점 가이드 & 점검 포인트

아래는 서비스 프로바이더/내부 플랫폼 운영자 시각에서, 실제로 내부 사용자에게 제시하기 좋은 체크리스트입니다.

1. 네트워크·접근 제어

1. 노출 경로 통제
   • 운영 기본은 Docker 소켓 경유. 호스트 TCP(12434) 노출 시엔 내부망 한정·방화벽·mTLS/리버스 프록시(인증)로 보호.
2. 인증/인가 계층
   • NGINX/Envoy 앞단에 Basic/OIDC 등 인증 적용, IP/네트워크 ACL로 호출 주체 제한.
3. 레이트 리밋/쿼타
   • 멀티모달 요청(특히 이미지/오디오 Base64)은 페이로드가 큽니다. 요청 크기 제한과 레이트 리밋을 프록시/게이트웨이에서 강제.

2. 데이터 보호·프라이버시

1. 민감 이미지/오디오 차단 정책
   • 업로드 콘텐츠에 DLP/민감정보 검출(얼굴, 신분증 등) 전처리를 적용하고, 저장/로그에 원본을 남기지 않도록 설계.
2. 로그 최소화
   • 요청/응답 본문은 기본 비저장, 필요 시 요약/해시만 보존.
3. 내부 모델 카드 합의
   • 모델별 허용/비허용 입력(예: 고객 PII 포함 스크린샷 금지)과 출력 사용범위/판단 주의 문구를 정책화.

3. 모델·아티팩트 신뢰성

1. OCI 아티팩트 서플라이체인
   • 모델은 OCI 아티팩트로 유통됩니다. 내부 레지스트리에서 서명/서명 검증(예: cosign), 취약점 스캔(Docker Scout 등) 적용을 권장. 프로젝터(mmproj) 레이어 존재를 주기적으로 검증(모델 카드와 일치 여부).
2. 라이선스/배포 제한 준수
   • 모델 카드의 사용 조건(연구·상업 사용, 재배포 가능 여부)을 내부 정책에 반영해 자동 점검.

4. 런타임 격리·자원 관리

1. GPU/메모리 가드레일
   • 모델별 메모리·쓰레드·컨텍스트 길이 한도를 문서화하고, 과도한 요청을 사전 차단.
2. 워크로드 격리
   • 테넌트/팀 단위로 별도 Model Runner 인스턴스 또는 네임스페이스 분리.
3. 가용성·모니터링
   • docker model logs 수집, API 5xx/지연 알람, 입력 크기/오류 유형 메트릭화.

5. 프롬프트 보안(멀티모달 특화)

1. 이미지/오디오 기반 프롬프트 인젝션
   • 이미지 내 텍스트(스티커/워터마크)에 주입된 은닉 지시문 차단(전처리 OCR 검사/필터).
2. 컨텍스트 경계
   • RAG/도구호출 연계 시 모드별 권한(읽기 전용 vs 변경) 을 분리, 고위험 도구 호출은 휴먼 인더루프.

공유하기 좋은 “운영 체크리스트”

1. 모델 카드/입력 유형 확인(텍스트/이미지/오디오)
2. 프로젝터(mmproj) 포함 여부 확인(모델 일관성·품질 점검)
3. 호출 경로 선택(소켓 우선, TCP 노출 시 인증/ACL/레이트 리밋)
4. 요청 본문 크기 제한·로그 정책 수립
5. OCI 서명 검증·스캔·라이선스 준수
6. 리소스 한도·테넌트 격리·알람/모니터링
7. 이미지/오디오 인젝션 대비 전처리·필터

자주 쓰는 스니펫 모음

1. 이미지+텍스트 멀티메시지(JSON)

{
  "model": "ai/gemma3",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "이 이미지를 요약해줘" },
      {
        "type": "image_url",
        "image_url": { "url": "data:image/jpeg;base64,<BASE64_JPEG>" }
      }
    ]
  }]
}

— OpenAI 호환 chat/completions 에 바로 사용.

2. 오디오 입력(단어 단위 전사)

{
  "model": "hf.co/ggml-org/ultravox-v0_5-llama-3_1-8b-gguf",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "transcribe the audio, one word" },
      { "type": "input_audio", "input_audio": { "data": "<BASE64_MP3>", "format": "mp3" } }
    ]
  }]
}

— HF 모델 경로를 그대로 사용 가능.

3. 운영 점검용 CLI

docker model list
docker model inspect ai/gemma3
docker model logs

— 모델/러너 상태·메타데이터 확인에 유용.

 

Docker Model Runner는 오픈소스로 공개되어 있어, 문서 개선·버그 수정·기능 제안 등 다양한 형태의 기여가 가능합니다.

참고 출처

• Docker Blog: How to Use Multimodal AI Models With Docker Model Runner — 개념/예시/프로젝터(mmproj) 설명. 
• Docker Docs: Model Runner 개요·API·CLI 레퍼런스 — 엔드포인트·소켓/TCP 호출·명령어.
• Collabnix 가이드: 호스트 TCP(기본 12434) 노출 설명.