이미지 캡셔닝 (Image Captioning)은 접근성 도구, 에셋 관리 파이프라인, 시각적 검색 인덱스의 동력을 제공합니다. 이 튜토리얼에서는 Oxlo.ai에 호스팅된 시각 기능이 있는 LLM을 사용하여 로컬 이미지를 읽고 구조화된 캡션을 반환하는 작은 Python 유틸리티를 구축할 것입니다. 최종 스크립트는 제가 수동 태깅 없이 스크린샷과 제품 사진을 카탈로그화할 때 사용하는 것입니다.

필요한 사항

• Python 3.10 이상
• https://portal.oxlo.ai에서 발급받은 Oxlo.ai API 키
• OpenAI SDK: pip install openai
• 작업 디렉토리에 있는 sample.jpg라는 이름의 샘플 이미지 파일

1단계: Oxlo.ai 클라이언트 설정

OpenAI SDK가 Oxlo.ai를 가리키도록 설정합니다. 실제 운영 환경에서는 환경 변수에서 키를 읽어오지만, 명확성을 위해 아래 스니펫에서는 직접 할당하는 방식을 보여줍니다.

from openai import OpenAI

client = OpenAI(
...

2단계: 이미지 로드 및 인코딩

Oxlo.ai 비전 모델은 채팅 메시지 페이로드(payload) 내의 base64로 인코딩된 이미지를 수락합니다. 이 헬퍼 함수는 로컬 파일을 읽고 데이터 URI 문자열을 반환합니다.

import base64

def encode_image(image_path):
...

3단계: 캡셔닝 프롬프트 작성

강력한 시스템 프롬프트 (System Prompt)는 설명을 일관되게 유지하고 환각 (Hallucination)된 세부 정보를 방지합니다. 저는 이를 스크립트의 나머지 부분을 건드리지 않고 조정할 수 있는 상수로 취급합니다.

SYSTEM_PROMPT = """당신은 이미지 캡셔닝 어시스턴트입니다. 이미지를 하나의 간결한 단락으로 설명하세요. 주요 피사체, 배경, 색상 및 눈에 보이는 모든 텍스트를 언급하세요. 보이지 않는 정보를 추측하지 마세요. 어조는 중립적이고 사실적이어야 합니다."""

4단계: 첫 번째 캡션 생성

Oxlo.ai에서 비전과 추론을 잘 처리하는 kimi-k2.6을 호출합니다. 사용자 메시지에는 지침과 base64 이미지 블록이 모두 포함됩니다.

response = client.chat.completions.create(
    model="kimi-k2.6",
    messages=[
...

5단계: 구조화된 JSON 출력 강제 적용

Raw text(원문 텍스트)는 유용하지만, 다운스트림 파이프라인(downstream pipelines)에는 기계가 읽을 수 있는 필드가 필요합니다. Oxlo.ai는 JSON 모드를 지원하므로, subject, setting, keywords와 같은 키를 가진 객체를 요청할 수 있습니다.

import json

response = client.chat.completions.create(
...

6단계: 폴더 일괄 처리 (Batch process)

진정한 가치는 이를 수많은 파일에 대해 실행할 때 나타납니다. 이 루프는 ./images/ 내의 모든 .jpg 파일을 처리하고 단일 카탈로그 파일을 작성합니다.

import glob

catalog = []
...

실행하기

스크립트를 caption.py로 저장하고, ./images/ 폴더에 이미지를 몇 장 넣은 뒤, API 키를 설정하고 실행하세요:

export OXLO_API_KEY="sk-..."
python caption.py

해질녘 도시 거리 사진의 경우, 출력 결과는 다음과 유사하게 나타납니다:

{
  "subject": "A row of brick storefronts with outdoor seating",
  "setting": "Urban street corner during blue hour",
...

마무리

이제 Oxlo.ai에서 완전히 작동하는 이미지 캡셔닝(image captioning) 파이프라인을 갖게 되었습니다. 이 플랫폼은 요청당 고정 가격(flat per-request pricing)을 사용하므로, 수백 개의 긴 컨텍스트 비전(long-context vision) 요청을 배치(batching) 처리하더라도 프롬프트 길이에 관계없이 호출당 비용은 동일합니다. 자세한 내용은 https://oxlo.ai/pricing에서 확인하세요. 명확한 다음 단계로는 두 가지가 있습니다. 하나는 이를 CMS 업로드 웹훅(webhook)에 연결하여 에셋(assets)이 도착하자마자 태그가 지정되도록 하는 것이고, 다른 하나는 단순한 카탈로그 이미지에 대해 더 빠른 처리량(throughput)이 필요한 경우 gemma-3-27b로 전환하는 것입니다.