alt — Auto-Caption
在本地 VLM 上對 input_dir 中的每張圖片進行推論,並將 JSON 側車檔案寫入 output_dir。適用於自動產生標題、理解批次內容,或將描述饋入其他工具。
技能目錄(即此 SKILL.md 所在目錄)在下方簡稱為 $SKILL_DIR。
使用時機
當使用者想要下列功能時,請使用此技能:
- 從照片自動產生 Instagram 標題
- 無需逐一檢視即可了解批次圖片內容
- 將圖片描述饋入內容管線或排程工具
設定(僅首次執行)
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。
範例:"為這張圖片撰寫一個有趣、充滿表情符號的 Instagram 標題。包含 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 | 字串 | "寫一個吸引人的 Instagram 標題…" | 標題欄位的提示詞 |
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 "為這張圖片寫一個專業的 LinkedIn 標題。"
輸出
對於 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 需要明確的模型 slug 才能進行遠端標題產生
標題品質標準
標題與圖片同等重要。一個薄弱的標題會浪費一個強而有力的視覺。在產生或提示標題時,請套用這些原則。
單一原則
每個標題應承載一個清晰的核心想法。如果標題試圖傳達多個重點,就會變得模糊而失去影響力。最強的標題只有一個矛頭:一個承諾、一個教訓、一個觀察、一個故事節奏。
測試:你能用一句話說出這個標題嗎?所有句子是否都支持同一個想法?如果不是,請刪減直到核心明確為止。
開頭要吸引
標題的第一行是鉤子。在 Instagram 上,只有前約 125 個字元會在「更多」之前顯示 — 那第一行必須贏得點擊。在 LinkedIn 上,第一行就是標題。
有效的鉤子模式:
- 反向操作:「停止做 X。」
- 好奇心缺口:「大多數人沒有意識到…」
- 身份呼籲:「如果你是 [X],請注意。」
- 權威/經驗:「如果我必須從頭開始,我會這麼做。」
- 痛點:「這就是你卡在 [X] 的原因。」
避免以「我」開頭,或以空洞的暖場句子開頭。第一行應該為後續內容贏得閱讀機會。
平台特定結構
Instagram:
- 開頭吸引(≤125 字元)
- 正文:故事、教訓或見解
- 結尾 3–5 個相關主題標籤
- 真實語氣 — 避免修飾過的行銷語言
- 可接受表情符號,但應強化意義,而非裝飾
LinkedIn:
- 600–800 字元以達到最佳觸及;需要高點擊率時 100–150 字元
- 第一行強力的鉤子
- 正文中無外部連結(LinkedIn 會壓低外部連結的觸及)
- 有效的框架:鉤子 → 見解 → 分解 → 行動呼籲;或 故事 → 教訓 → 行動 → 互動問題
- 清晰重於創意 — 讀者快速掃描
- 避免:過多表情符號、過多空白、連續相同格式、外部字型
反通用測試
在接受產生的標題前,請問:這聽起來像是拍攝這張照片的專家寫的,還是聽起來像是一般性的 AI 寫作?如果它可以是任何人寫的任何東西,那麼它失敗了。標題必須反映特定的觀點、觀察或親身經歷的時刻。
避免
- 以「我」作為第一個字開頭
- 缺乏具體重點的模糊激勵性陳述
- 用表情符號作為視覺填充,而非強化意義
- 單一標題中包含多個行動呼籲
- LinkedIn 上過多的主題標籤(10 個以上)