alt — Auto-Caption
input_dir의 각 이미지에 대해 로컬 VLM을 실행하고 output_dir에 JSON 사이드카 파일을 작성합니다. 캡션 자동 생성, 배치 콘텐츠 이해, 또는 다른 도구에 설명을 제공하는 데 유용합니다.
스킬 디렉토리(SKILL.md가 있는 위치)는 아래에서 $SKILL_DIR로 참조됩니다.
사용 시기
사용자가 다음과 같은 작업을 원할 때 이 스킬을 사용하세요:
- 사진에서 인스타그램 캡션을 자동으로 생성
- 이미지 배치를 수동으로 검토하지 않고 내용 파악
- 이미지 설명을 콘텐츠 파이프라인 또는 스케줄링 도구에 전달
설정 (최초 실행 시)
cd "$SKILL_DIR" && uv sync
moondream2 가중치는 최초 사용 시 다운로드됩니다 (~4 GB, HuggingFace). Phi-4 가중치는 더 큽니다 (~8 GB) GPU가 필요합니다.
에이전트 워크플로우
1. 사용자에게 질문
이미지를 설명하기 전에 다음 정보가 필요합니다:
🧠 모델
- moondream2 — 2B 파라미터, 빠름, CPU에서 작동 (기본값)
- phi4 — 3.8B 멀티모달, 더 높은 품질, GPU 필요
💬 캡션 스타일 (선택 사항 — 적절한 기본값 사용)
예: "캐주얼하고 재미있게, 이모지 포함" 또는 "전문적이고 영감을 주는 스타일"
⚙️ 장치
- auto — GPU 사용 가능 시 GPU, 아니면 CPU (기본값)
- cpu — moondream2만 가능; 최신 데스크탑 CPU에서 이미지당 약 7초
📁 입력 / 출력 디렉토리 (기본값: ./input 및 ./output)
2. config.json 편집
사용자가 캡션 스타일을 지정하면 prompt_caption에 반영합니다.
예: "이 이미지에 대한 재미있고 이모지가 풍부한 인스타그램 캡션을 작성하세요. 해시태그 3-5개를 포함하세요."
사용자가 브랜드 비주얼을 요청하면 skills/brand-manager/brand-assets/asset-manifest.json에서 사용 가능한 폰트를 확인하고 생성된 캡션 지침이나 인계 노트에 선호하는 브랜드 폰트를 언급합니다. 이 스킬은 JSON 사이드카만 작성하므로 텍스트 자체를 렌더링하지 않습니다. visual-hook, video-captioner, end-cta와 같은 다운스트림 렌더러는 폰트가 지정되고 사용 가능할 때 실제 브랜드 폰트 파일을 사용해야 합니다.
3. 실행
cd "$SKILL_DIR" && uv run python scripts/describe.py --config config.json
최초 실행 시 모델 가중치가 다운로드됩니다 — 사용자에게 몇 분이 소요될 수 있음을 알립니다.
4. 결과 보고
각 이미지에 대한 설명과 캡션을 보여줍니다. JSON 파일이 작성된 위치를 사용자에게 알립니다.
설정 참조
| 키 | 값 | 기본값 | 설명 |
|---|---|---|---|
input_dir | 경로 | ./input | 소스 이미지 폴더 |
output_dir | 경로 | ./output | JSON 사이드카 대상 폴더 |
model | moondream2, phi4 | moondream2 | 비전-언어 모델 |
prompt_description | 문자열 | "이 이미지를 한 문장으로 설명하세요." | 설명 필드 프롬프트 |
prompt_caption | 문자열 | "매력적인 인스타그램 캡션을 작성하세요…" | 캡션 필드 프롬프트 |
device | auto, cpu, cuda | auto | 추론 장치 |
일반적인 실행 명령
# 기본 설정 (moondream2, auto 장치)
cd "$SKILL_DIR" && uv run python scripts/describe.py
# 더 높은 품질 (GPU 필요)
cd "$SKILL_DIR" && uv run python scripts/describe.py --model phi4
# CPU 강제
cd "$SKILL_DIR" && uv run python scripts/describe.py --device cpu
# 사용자 정의 캡션 프롬프트
cd "$SKILL_DIR" && uv run python scripts/describe.py \
--prompt-caption "이 이미지에 대한 전문적인 링크드인 캡션을 작성하세요."
출력
input_dir의 각 photo.jpg에 대해 output_dir에 photo.json을 작성합니다:
{
"description": "햇살 가득한 카페에서 커피잔을 들고 있는 여성.",
"caption": "아침의 의식 ☕✨ 좋은 하루 시작. #커피타임 #모닝무드 #카페",
"tags": ["인물", "커피", "실내", "따뜻한 빛"]
}
브랜드 폰트가 관련된 경우, 이 JSON에 폰트 파일을 포함하지 말고 다운스트림 지침에 폰트 이름/태그를 포함하세요. 렌더링 스킬은 매니페스트 경로를 확인하고 폰트를 적용하는 역할을 담당합니다.
오류 처리
phi4+cpu→ 구성 검증 시 명확한 메시지와 함께 거부- 모델 다운로드 실패 → HuggingFace 오류 세부 정보 표시
- 개별 이미지 오류 → 기록됨; 다른 이미지는 계속 처리
원격 추론
이 스킬은 선택적 원격 캡션을 지원하며 동일한 JSON 사이드카 출력을 유지합니다.
- 기본 동작은 여전히 로컬입니다.
- 원격 제공자는 옵트인 전용입니다.
- 지원 제공자:
huggingface,replicate
구성 키
| 키 | 기본값 | 참고 |
|---|---|---|
provider | null | null, local, 또는 none은 로컬 모드 유지 |
remote_model | null | 선택적 제공자별 VLM 모델 재정의 |
hf_token_env | HF_TOKEN | HuggingFace 인증 환경 변수 이름 |
replicate_api_key_env | REPLICATE_API_TOKEN | Replicate 인증 환경 변수 이름 |
remote_timeout_seconds | 300 | 원격 호출 제한 시간 |
예시
# HuggingFace 원격 이미지 캡션
export HF_TOKEN=hf_your_token
uv run python scripts/describe.py --config config.json --provider huggingface
# Replicate 원격 이미지 캡션
export REPLICATE_API_TOKEN=r8_your_token
uv run python scripts/describe.py --config config.json --provider replicate --remote-model <replicate-model-slug>
참고
- 원격 모드는 여전히 동일한
description/caption/tagsJSON 사이드카를 작성합니다. - 누락된 자격 증명은 빠르게 실패합니다. 로컬 모드로의 무음 대체는 없습니다.
- Replicate는 원격 캡션에 명시적인 모델 슬러그가 필요합니다.
캡션 품질 기준
캡션은 이미지만큼 중요합니다. 약한 캡션은 강력한 비주얼을 낭비합니다. 캡션을 생성하거나 프롬프트할 때 다음 원칙을 적용하세요.
하나의 규칙
모든 캡션은 하나의 명확한 중심 아이디어를 전달해야 합니다. 캡션이 여러 요점을 전달하려고 하면 산만해지고 영향력이 떨어집니다. 가장 강력한 캡션은 하나의 창 끝을 가집니다: 하나의 약속, 하나의 교훈, 하나의 관찰, 하나의 스토리 비트.
테스트: 이 캡션을 한 문장으로 말할 수 있습니까? 모든 줄이 같은 아이디어를 지원합니까? 그렇지 않다면 핵심이 명확해질 때까지 잘라내세요.
후크 우선
캡션의 첫 번째 줄은 후크입니다. 인스타그램에서는 처음 ~125자만 '더보기' 전에 표시됩니다. 첫 번째 줄은 탭을 받을 가치가 있어야 합니다. 링크드인에서는 첫 번째 줄이 헤드라인입니다.
효과적인 후크 패턴:
- 반론: "X를 그만두세요."
- 호기심 갭: "대부분의 사람들은 깨닫지 못합니다..."
- 정체성 호출: "당신이 [X]라면, 주목하세요."
- 권위/경험: "처음부터 다시 시작해야 한다면, 이렇게 할 것입니다."
- 고통점: "이것이 당신이 [X]에 갇혀 있는 이유입니다."
"나"로 시작하거나 아무 말도 하지 않는 워밍업 문장은 피하세요. 첫 번째 줄은 나머지 읽을 가치가 있어야 합니다.
플랫폼별 구조
인스타그램:
- 후크 우선 (≤125자)
- 본문: 이야기, 교훈, 또는 통찰력
- 끝에 3-5개의 관련 해시태그
- 진정성 있는 어조 — 다듬어진 마케팅 언어 피함
- 이모지는 의미를 강화해야 하며 장식용이 아니어야 함
링크드인:
- 최대 도달을 위해 600-800자; 높은 CTR이 필요할 때 100-150자
- 첫 번째 줄에 강력한 후크
- 게시물 본문에 외부 링크 없음 (링크드인은 아웃바운드 링크에 대한 도달을 억제함)
- 효과적인 프레임워크: 후크 → 통찰력 → 분석 → CTA; 또는 스토리 → 교훈 → 행동 → 참여 질문
- 창의성보다 명확성 — 독자는 빠르게 스캔함
- 피할 것: 이모지 과다, 과도한 공백, 동일한 형식 연속, 외부 폰트
안티-일반 테스트
생성된 캡션을 받아들이기 전에 질문하세요: 이 사진을 찍은 전문가처럼 들리나요, 아니면 일반적인 AI 글쓰기처럼 들리나요? 누구나 무엇에 대해 쓸 수 있는 것이라면 실패입니다. 캡션은 특정 관점, 관찰, 또는 경험한 순간을 반영해야 합니다.
피할 것
- 첫 단어로 "나"로 시작
- 구체적인 요점이 없는 모호한 영감을 주는 문장
- 의미를 강화하기보다 시각적 패딩으로 사용된 이모지
- 단일 캡션에 둘 이상의 클릭 유도 문안
- 링크드인에서 해시태그 스팸 (10개 이상의 해시태그)