Potato 2.1은 비주얼 AI 지원을 추가하여 이미지와 동영상 어노테이션 안에 AI 보조 기능을 바로 넣었습니다. 모든 바운딩 박스를 손으로 그리는 대신, YOLO가 객체를 탐지하게 하고 찾아낸 결과를 검토하거나, 이미지를 비전-언어 모델에 넘겨 이미지를 분류하고 그 이유를 설명하게 할 수 있습니다.

이 가이드는 각 비주얼 AI 엔드포인트를 설정하는 방법, 보조 모드, 그리고 비주얼 AI를 Potato의 텍스트 기반 AI와 함께 쓰는 방법을 안내합니다. 비주얼 AI 원본 문서에 전체 API 레퍼런스가 있습니다.

배우게 될 내용

빠른 로컬 객체 탐지를 위한 YOLO 설정
로컬 이미지 이해를 위한 Ollama Vision 모델 실행
OpenAI와 Anthropic 클라우드 비전 API 사용
탐지, 사전 어노테이션, 분류, 힌트 모드 구성
비주얼 AI와 텍스트 AI 엔드포인트를 하나의 프로젝트에서 결합
AI 제안을 검토하기 위한 수락/거부 워크플로

사전 준비

Potato 2.1.0 이상이 필요합니다:

bash

pip install --upgrade potato-annotation

그리고 선택하는 엔드포인트에 따라 다음 중 하나가 필요합니다:

YOLO: pip install ultralytics opencv-python
Ollama: ollama.ai에서 설치하고 비전 모델을 받습니다
OpenAI: GPT-4o에 접근할 수 있는 API 키
Anthropic: Claude 비전 모델에 접근할 수 있는 API 키

옵션 1: 객체 탐지를 위한 YOLO

빠르고 정밀한 바운딩 박스 탐지를 원하고 그 작업을 전부 자신의 머신에서 돌리고 싶을 때 YOLO를 선택하세요. 흔한 객체(사람, 자동차, 동물, 가구)에 능하며 이미지를 밀리초 단위로 처리합니다.

설정

bash

pip install ultralytics opencv-python

구성

yaml

annotation_task_name: "Object Detection with YOLO"
 
data_files:
  - data/images.json
 
item_properties:
  id_key: id
  text_key: image_url
 
instance_display:
  fields:
    - key: image_url
      type: image
      display_options:
        max_width: 800
        zoomable: true
 
annotation_schemes:
  - annotation_type: image_annotation
    name: objects
    description: "Detect and label objects"
    source_field: "image_url"
    tools:
      - bbox
    labels:
      - name: "person"
        color: "#FF6B6B"
      - name: "car"
        color: "#4ECDC4"
      - name: "dog"
        color: "#45B7D1"
      - name: "cat"
        color: "#96CEB4"
 
    ai_support:
      enabled: true
      features:
        detection: true
        pre_annotate: true
        hint: true
 
ai_support:
  enabled: true
  endpoint_type: "yolo"
  ai_config:
    model: "yolov8m.pt"
    confidence_threshold: 0.5
    iou_threshold: 0.45
 
output_annotation_dir: "annotation_output/"
user_config:
  allow_all_users: true

데이터 형식

data/images.json을 JSONL 형식(한 줄에 하나의 JSON 객체)으로 만듭니다:

json

{"id": "img_001", "image_url": "images/street_scene_1.jpg"}
{"id": "img_002", "image_url": "images/park_photo.jpg"}
{"id": "img_003", "image_url": "https://example.com/images/office.jpg"}

YOLO 모델 선택

모델	크기	속도	정확도	적합한 용도
`yolov8n.pt`	6 MB	가장 빠름	더 낮음	빠른 프로토타이핑
`yolov8s.pt`	22 MB	빠름	양호	균형 잡힌 작업
`yolov8m.pt`	50 MB	보통	더 나음	일반 용도
`yolov8l.pt`	84 MB	더 느림	높음	정확도가 중요할 때
`yolov8x.pt`	131 MB	가장 느림	가장 높음	최대 정밀도

YOLO의 내장 클래스에 없는 객체를 탐지하려면 개방형 어휘 탐지를 위해 YOLO-World를 사용하세요:

yaml

ai_config:
  model: "yolo-world"
  confidence_threshold: 0.3

탐지 조정

YOLO가 객체를 놓치고 있다면 신뢰도 임계값을 낮추세요:

yaml

ai_config:
  confidence_threshold: 0.3  # More detections, more false positives

거짓 양성이 너무 많이 나온다면 임계값을 높이세요:

yaml

ai_config:
  confidence_threshold: 0.7  # Fewer detections, higher precision

옵션 2: 로컬 VLLM을 위한 Ollama Vision

Ollama Vision은 비전-언어 모델을 로컬에서 실행합니다. YOLO와 달리 이 모델들은 이미지 맥락을 읽고, 장면을 분류하고, 설명을 작성하며, 데이터가 머신을 벗어나지 않습니다.

설정

bash

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh
 
# Pull a vision model
ollama pull llava
 
# Or for better performance:
ollama pull qwen2.5-vl:7b

구성

yaml

annotation_task_name: "Image Classification with Ollama Vision"
 
data_files:
  - data/images.json
 
item_properties:
  id_key: id
  text_key: image_url
 
instance_display:
  fields:
    - key: image_url
      type: image
      display_options:
        max_width: 600
        zoomable: true
 
annotation_schemes:
  - annotation_type: radio
    name: scene_type
    description: "What type of scene is shown?"
    labels:
      - indoor
      - outdoor_urban
      - outdoor_nature
      - aerial
      - underwater
 
    ai_support:
      enabled: true
      features:
        hint: true
        classification: true
 
ai_support:
  enabled: true
  endpoint_type: "ollama_vision"
  ai_config:
    model: "llava:latest"
    base_url: "http://localhost:11434"
    max_tokens: 500
    temperature: 0.1
 
output_annotation_dir: "annotation_output/"
user_config:
  allow_all_users: true

지원 모델

모델	파라미터	강점
`llava:7b`	7B	빠르고, 전반적인 이해가 좋음
`llava:13b`	13B	더 나은 정확도
`llava-llama3`	8B	강한 추론 능력
`bakllava`	7B	시각적 디테일에 강함
`llama3.2-vision:11b`	11B	최신 Llama 비전
`qwen2.5-vl:7b`	7B	다국어 + 비전에 강함
`moondream`	1.8B	매우 빠르고 가벼움

옵션 3: OpenAI Vision

OpenAI Vision은 GPT-4o를 통해 이미지 이해 기능을 제공합니다. 가장 강력한 비전 모델을 원하고 클라우드 API 호출 비용을 감수할 수 있을 때 사용하세요.

구성

yaml

ai_support:
  enabled: true
  endpoint_type: "openai_vision"
  ai_config:
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-4o"
    max_tokens: 1000
    detail: "auto"  # "low" for faster/cheaper, "high" for detail

API 키를 설정합니다:

bash

export OPENAI_API_KEY="sk-..."

detail 파라미터는 API로 전송되는 이미지 해상도를 제어합니다:

low, 더 빠르고 더 저렴하며, 분류에 적합
high, 전체 해상도, 작은 객체를 찾는 데 더 나음
auto, API가 결정하도록 맡김

옵션 4: Anthropic Vision

Claude의 비전 모델은 이미지 맥락을 읽고 상세한 설명을 작성하는 데 능합니다.

구성

yaml

ai_support:
  enabled: true
  endpoint_type: "anthropic_vision"
  ai_config:
    api_key: "${ANTHROPIC_API_KEY}"
    model: "claude-sonnet-4-20250514"
    max_tokens: 1024

bash

export ANTHROPIC_API_KEY="sk-ant-..."

AI 보조 모드

각 비주얼 AI 엔드포인트는 몇 가지 보조 모드를 지원합니다. 어노테이션 스킴별로 필요한 것만 켜세요.

탐지 모드

구성한 라벨과 일치하는 객체를 찾아 점선 바운딩 박스 오버레이로 표시합니다:

yaml

ai_support:
  enabled: true
  features:
    detection: true

어노테이터가 "Detect"를 클릭하면 AI의 제안이 이미지 위에 점선 오버레이로 나타납니다. 더블클릭으로 수락하고, 오른쪽 클릭으로 거부합니다.

사전 어노테이션(자동) 모드

한 번의 작업으로 모든 객체를 탐지하고 제안을 생성합니다. 대규모 데이터셋을 초기 구축할 때 가장 좋습니다:

yaml

ai_support:
  enabled: true
  features:
    pre_annotate: true

분류 모드

선택한 영역이나 이미지 전체를 분류하고, 신뢰도 점수와 함께 제안 라벨을 반환합니다:

yaml

ai_support:
  enabled: true
  features:
    classification: true

힌트 모드

정답을 알려주지 않으면서 안내 텍스트를 제공합니다. 새 어노테이터를 교육할 때 좋습니다:

yaml

ai_support:
  enabled: true
  features:
    hint: true

수락/거부 워크플로

어노테이터가 AI 보조 버튼을 클릭하면 제안이 점선 오버레이로 나타납니다:

제안 수락: 점선 오버레이를 더블클릭하여 실제 어노테이션으로 변환합니다
제안 거부: 오버레이를 오른쪽 클릭하여 해제합니다
모두 수락: 툴바에서 "Accept All"을 클릭하여 모든 제안을 한 번에 수락합니다
모두 지우기: "Clear"를 클릭하여 모든 제안을 해제합니다

어노테이터가 계속 통제권을 쥐면서도 손으로 그리는 박스는 훨씬 줄어듭니다.

비주얼 AI를 활용한 동영상 어노테이션

비주얼 AI는 동영상 작업에서도 작동합니다. 장면 탐지, 키프레임 탐지, 객체 추적을 켤 수 있습니다:

yaml

annotation_schemes:
  - annotation_type: video_annotation
    name: scenes
    description: "Segment this video into scenes"
    mode: segment
    labels:
      - name: "intro"
        color: "#4ECDC4"
      - name: "main_content"
        color: "#FF6B6B"
      - name: "outro"
        color: "#45B7D1"
 
    ai_support:
      enabled: true
      features:
        scene_detection: true
        pre_annotate: true
        hint: true
 
ai_support:
  enabled: true
  endpoint_type: "ollama_vision"
  ai_config:
    model: "llava:latest"
    max_frames: 10  # Number of frames to sample

max_frames 파라미터는 AI가 동영상에서 샘플링하는 프레임 수를 설정합니다. 프레임이 많을수록 정확도는 높아지고 처리는 느려집니다.

비주얼 AI와 텍스트 AI 엔드포인트 결합

프로젝트에서 텍스트와 이미지 어노테이션을 섞어 쓴다면, 각각에 별도의 엔드포인트를 설정할 수 있습니다. 힌트와 키워드용 텍스트 모델, 탐지용 비전 모델입니다.

yaml

ai_support:
  enabled: true
 
  # Text AI for radio buttons, text schemes, etc.
  endpoint_type: "ollama"
  ai_config:
    model: "llama3.2"
    include:
      all: true
 
  # Visual AI for image/video schemes
  visual_endpoint_type: "yolo"
  visual_ai_config:
    model: "yolov8m.pt"
    confidence_threshold: 0.5

또는 로컬 텍스트 모델과 함께 클라우드 비전 모델을 사용합니다:

yaml

ai_support:
  enabled: true
  endpoint_type: "ollama"
  visual_endpoint_type: "openai_vision"
  ai_config:
    model: "llama3.2"
  visual_ai_config:
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-4o"

전체 예시: 제품 사진 어노테이션

다음은 YOLO 탐지와 텍스트 기반 AI 힌트를 사용해 제품 사진을 어노테이션하기 위해 바로 출시할 수 있는 구성입니다:

yaml

annotation_task_name: "Product Photo Annotation"
 
data_files:
  - data/product_photos.json
 
item_properties:
  id_key: sku
  text_key: photo_url
 
instance_display:
  layout:
    direction: horizontal
    gap: 24px
  fields:
    - key: photo_url
      type: image
      label: "Product Photo"
      display_options:
        max_width: 600
        zoomable: true
    - key: product_description
      type: text
      label: "Product Details"
 
annotation_schemes:
  - annotation_type: image_annotation
    name: product_regions
    description: "Draw boxes around products and defects"
    source_field: "photo_url"
    tools:
      - bbox
    labels:
      - name: "product"
        color: "#4ECDC4"
      - name: "defect"
        color: "#FF6B6B"
      - name: "label"
        color: "#45B7D1"
      - name: "packaging"
        color: "#96CEB4"
 
    ai_support:
      enabled: true
      features:
        detection: true
        pre_annotate: true
 
  - annotation_type: radio
    name: photo_quality
    description: "Is this photo suitable for the product listing?"
    labels:
      - Approved
      - Needs editing
      - Reshoot required
 
  - annotation_type: multiselect
    name: quality_issues
    description: "Select any issues present"
    labels:
      - Blurry
      - Poor lighting
      - Wrong angle
      - Background clutter
      - Color inaccurate
 
ai_support:
  enabled: true
  endpoint_type: "ollama"
  visual_endpoint_type: "yolo"
 
  ai_config:
    model: "llama3.2"
    include:
      all: true
 
  visual_ai_config:
    model: "yolov8m.pt"
    confidence_threshold: 0.5
 
output_annotation_dir: "annotation_output/"
export_annotation_format: "json"
user_config:
  allow_all_users: true

샘플 데이터 (data/product_photos.json):

json

{"sku": "SKU-001", "photo_url": "images/products/laptop_front.jpg", "product_description": "15-inch laptop, silver finish"}
{"sku": "SKU-002", "photo_url": "images/products/headphones_side.jpg", "product_description": "Over-ear wireless headphones, black"}
{"sku": "SKU-003", "photo_url": "images/products/backpack_full.jpg", "product_description": "40L hiking backpack, navy blue"}

비주얼 AI 어노테이션 팁

대규모 데이터셋은 사전 어노테이션으로 시작하세요: Auto 버튼을 눌러 전체에 대한 제안을 생성한 뒤, 어노테이터가 처음부터 그리는 대신 검토하고 수정하게 하세요
엔드포인트를 작업에 맞추세요: 정밀 탐지에는 YOLO, 분류와 이해에는 VLLM
신뢰도 임계값을 조정하세요: 0.5에서 시작하여 거짓 양성/음성의 절충 양상을 보고 조정하세요
어노테이터 교육에 힌트를 사용하세요: 힌트 모드는 특정 답으로 유도하지 않으면서 어노테이터를 안내합니다
엔드포인트를 결합하세요: 탐지용 YOLO 엔드포인트와 힌트용 Ollama 텍스트 엔드포인트면 양쪽을 모두 커버합니다
AI 결과를 캐시하세요: 디스크 캐시를 켜서 같은 이미지에 대해 탐지를 다시 실행하지 않도록 하세요

문제 해결

"No visual AI endpoint configured"

ai_support.enabled가 true인지, 그리고 비전을 지원하는 endpoint_type(yolo, ollama_vision, openai_vision, anthropic_vision)을 설정했는지 확인하세요.

YOLO가 객체를 탐지하지 못함

YOLO의 내장 클래스는 흔한 객체 80개를 다룹니다. 라벨이 YOLO의 클래스 이름과 일치하지 않으면 개방형 어휘 탐지를 위해 YOLO-World를 시도하거나 confidence_threshold를 낮추세요.

Ollama가 오류를 반환함

Ollama가 실행 중이고 비전 모델을 받았는지 확인하세요:

bash

curl http://localhost:11434/api/tags  # Check Ollama is running
ollama list                           # Check installed models

클라우드 API의 느린 응답

같은 이미지가 두 번 분석되지 않도록 캐싱을 켜세요:

yaml

ai_support:
  cache_config:
    disk_cache:
      enabled: true
      path: "ai_cache/visual_cache.json"

다음 단계

API 레퍼런스 세부 사항은 비주얼 AI 지원 전체 문서를 읽어 보세요
이미지를 다른 콘텐츠 유형과 나란히 표시하려면 instance display를 설정하세요
힌트와 키워드 강조를 위해 텍스트 기반 AI 지원을 살펴보세요

전체 문서는 /docs/features/visual-ai-support에 있습니다.