LiteLLM에서 비전(Vision) 모델 사용하기

텍스트만 넣는 모델도 많지만, 이제는 이미지를 이해하는 비전 모델이 주류가 됐어요. 이미지 URL을 넣어 '이 사진에 뭐가 있니?' 같은 질문을 할 수 있죠. LiteLLM은 OpenAI 규격의 image_url 콘텐츠 형식을 그대로 써서, 공급자가 달라도 비슷한 방식으로 이미지를 모델에 전달할 수 있게 해줘요. 어떻게 이미지를 넘기고, 이미지 타입을 보정하는지 살펴볼게요.

출처: 공식문서

퀵 스타트 — 이미지를 모델에 전달하기

completion의 messages에서 content를 리스트로 바꾸고, 그 안에 type: "text"(질문)와 type: "image_url"(이미지 URL) 요소를 함께 넣으면 돼요.

import os
from litellm import completion

os.environ["OPENAI_API_KEY"] = "your-api-key"

# openai call
response = completion(
    model = "gpt-5.6-terra",
    messages=[
        {
            "role": "user",
            "content": [
                            {
                                "type": "text",
                                "text": "What's in this image?"
                            },
                            {
                                "type": "image_url",
                                "image_url": {
                                "url": "https://awsmp-logos.s3.amazonaws.com/seller-xw5kijmvmzasy/c233c9ade2ccb5491072ae232c814942.png"
                                }
                            }
                        ]
        }
    ],
)

image_url.url에는 공개 이미지 URL이나 base64로 인코딩된 문자열을 넣을 수 있어요. 프라이빗 이미지나 로컬 파일은 base64로 먼저 인코딩해서 넘기는 게 일반적이에요.

모델이 비전을 지원하는지 확인하기

litellm.supports_vision(model="")로 특정 모델이 이미지 입력을 지원하는지 확인할 수 있어요. True면 지원, False면 지원하지 않는 거예요. 모델 이름에서 "vision"이나 이미지 기능이 있는지 대략 짐작할 수 있지만, 코드로 확실히 확인하는 게 안전해요.

assert litellm.supports_vision(model="openai/gpt-5.6-terra") == True
assert litellm.supports_vision(model="vertex_ai/gemini-3.1-pro-preview") == True
assert litellm.supports_vision(model="openai/gpt-3.5-turbo") == False
assert litellm.supports_vision(model="xai/grok-2-vision-latest") == True
assert litellm.supports_vision(model="xai/grok-2-latest") == False

이미지 타입(MIME) 명시하기

이미지에 MIME 타입이 없거나, LiteLLM이 이미지의 타입을 잘못 추론할 때가 있어요(예: Vertex AI와 함께 gs:// URL을 호출하는 경우). 이럴 땐 image_url 안의 format 파라미터로 타입을 직접 지정할 수 있어요.

"image_url": {
  "url": "gs://my-gs-image",
  "format": "image/jpeg"
}

LiteLLM이 이 format을 사용하는 것은 MIME 타입 지정을 지원하는 API 엔드포인트(예: anthropic/bedrock/vertex ai)에 한해요. OpenAI처럼 지정이 의미 없는 엔드포인트에서는 무시돼요.

import os
from litellm import completion

os.environ["ANTHROPIC_API_KEY"] = "your-api-key"

# openai call
response = completion(
    model = "claude-sonnet-5",
    messages=[
        {
            "role": "user",
            "content": [
                            {
                                "type": "text",
                                "text": "What's in this image?"
                            },
                            {
                                "type": "image_url",
                                "image_url": {
                                  "url": "https://awsmp-logos.s3.amazonaws.com/seller-xw5kijmvmzasy/c233c9ade2ccb5491072ae232c814942.png",
                                  "format": "image/jpeg"
                                }
                            }
                        ]
        }
    ],
)

`image_url` 스펙 요약

image_url은 문자열 하나를 받거나, 객체로 세부 옵션을 받아요.

"image_url": str

OR

"image_url": {
  "url": "url OR base64 encoded str",
  "detail": "openai-only param",
  "format": "specify mime-type of image"
}

url: 이미지 URL 또는 base64 인코딩 문자열
detail: OpenAI 전용 파라미터(이미지를 얼마나 자세히 볼지)
format: 이미지의 MIME 타입을 명시(MIME 지정을 지원하는 엔드포인트에서만 사용)

더 알아보기

오디오 입력을 다루는 방법은 멀티모달 I/O의 오디오 모델 페이지를 참고해요.
이미지 생성(이미지 출력)이 필요하다면 LiteLLM의 이미지 생성 관련 문서를 함께 봐요.

LiteLLM에서 비전(Vision) 모델 사용하기