［開発者向け］MiniCPM-V 4.6 完全実装ガイド——1.3Bパラメータでスマートフォン搭載可能なマルチモーダルAIをTransformersで動かす

# TransformersとGPUサポート、動画デコードライブラリをまとめてインストール
pip install "transformers[torch]>=5.7.0" torchvision torchcodec

# torchcodecの代わりにav（PyAV）を使用する（画像・動画どちらも対応）
pip install "transformers[torch]>=5.7.0" torchvision av

# CUDA 12.8に合わせてtorchのインストールURLを指定する
pip install "transformers>=5.7.0" torchvision torchcodec --index-url https://download.pytorch.org/whl/cu128

from transformers import AutoModelForImageTextToText, AutoProcessor

# モデルIDの指定（Hugging FaceのリポジトリID）
model_id = "openbmb/MiniCPM-V-4.6"

# プロセッサ（画像前処理・トークナイザを統合）のロード
processor = AutoProcessor.from_pretrained(model_id)

# モデルのロード（torch_dtype="auto"でGPUに適した型を自動選択）
model = AutoModelForImageTextToText.from_pretrained(
    model_id, torch_dtype="auto", device_map="auto"
)

# 注: マルチ画像・動画推論時はFlash Attention 2の使用を推奨（要flash-attnパッケージ）
# model = AutoModelForImageTextToText.from_pretrained(
#     model_id,
#     torch_dtype=torch.bfloat16,
#     attn_implementation="flash_attention_2",  # Flash Attention 2を有効化
#     device_map="auto",
# )

messages = [
    {
        "role": "user",
        "content": [
            # 画像URLまたはローカルパスを指定
            {"type": "image", "url": "https://huggingface.co/datasets/openbmb/DemoCase/resolve/main/refract.png"},
            # テキストの質問
            {"type": "text", "text": "What causes this phenomenon?"},
        ],
    }
]

# downsample_mode: "16x"は高効率、"4x"は高精細（細かい文字や図の読み取りに推奨）
downsample_mode = "16x"

# チャットテンプレートを適用してモデル入力形式に変換
inputs = processor.apply_chat_template(
    messages,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
    return_tensors="pt",
    downsample_mode=downsample_mode,  # ビジュアルトークンの圧縮率を指定
    max_slice_nums=36,                # 高解像度画像のスライス最大数（画像は36推奨）
).to(model.device)

# テキスト生成
generated_ids = model.generate(
    **inputs,
    downsample_mode=downsample_mode,  # apply_chat_templateと同じ値を必ず指定
    max_new_tokens=512,
)

# 入力トークンを除いて生成部分だけを取り出す
generated_ids_trimmed = [
    out_ids[len(in_ids):]
    for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
]

# デコードしてテキストに変換
output_text = processor.batch_decode(
    generated_ids_trimmed,
    skip_special_tokens=True,
    clean_up_tokenization_spaces=False,
)
print(output_text[0])

messages = [
    {
        "role": "user",
        "content": [
            # 動画URLまたはローカルパスを指定
            {"type": "video", "url": "https://huggingface.co/datasets/openbmb/DemoCase/resolve/main/football.mp4"},
            {"type": "text", "text": "Describe this video in detail. Follow the timeline and focus on on-screen text, interface changes, main actions, and scene changes."},
        ],
    }
]

downsample_mode = "16x"

inputs = processor.apply_chat_template(
    messages,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
    return_tensors="pt",
    downsample_mode=downsample_mode,
    max_num_frames=128,   # 動画からサンプルするフレームの最大数
    stack_frames=1,       # 1秒あたりのサンプリング数（長動画は3または5を推奨）
    max_slice_nums=1,     # 動画の場合は1を指定（画像と異なる点）
    use_image_id=False,   # 動画の場合はFalse（画像の場合はTrueがデフォルト）
).to(model.device)

generated_ids = model.generate(
    **inputs,
    downsample_mode=downsample_mode,
    max_new_tokens=2048,  # 動画解説は長くなるため多めに設定
)
generated_ids_trimmed = [
    out_ids[len(in_ids):]
    for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
]
output_text = processor.batch_decode(
    generated_ids_trimmed,
    skip_special_tokens=True,
    clean_up_tokenization_spaces=False,
)
print(output_text[0])

# serving用パッケージのインストール
pip install "transformers[serving]>=5.7.0"

# サーバーを起動（--continuous-batchingで連続バッチ処理を有効化）
transformers serve openbmb/MiniCPM-V-4.6 --port 8000 --host 0.0.0.0 --continuous-batching

# OpenAI互換エンドポイントへリクエスト送信
curl -s http://localhost:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openbmb/MiniCPM-V-4.6",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "image_url", "image_url": {"url": "https://huggingface.co/datasets/openbmb/DemoCase/resolve/main/refract.png"}},
        {"type": "text", "text": "What causes this phenomenon?"}
      ]
    }]
  }'

# vLLMサーバーを起動
# --enable-auto-tool-choiceと--tool-call-parserはツール呼び出し機能を有効にするオプション
# ツール呼び出しが不要な場合は --enable-auto-tool-choice と --tool-call-parser を省略可能
vllm serve openbmb/MiniCPM-V-4.6 \
  --port 8000 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_coder \
  --default-chat-template-kwargs '{"enable_thinking": false}'

# SGLangサーバーを起動（python -mで直接起動できる）
python -m sglang.launch_server --model openbmb/MiniCPM-V-4.6 --port 30000

# Q4_K_MはGGUF量子化形式の一種で、品質と速度のバランスが良いとされる
# GGUFモデルは https://huggingface.co/openbmb/MiniCPM-V-4.6-gguf からダウンロード
llama-server -m MiniCPM-V-4.6-Q4_K_M.gguf --port 8080

# Ollama（ローカルLLM実行ツール）を使って1コマンドで起動
# 事前にhttps://ollama.com からOllamaをインストールしておく必要があります
ollama run minicpm-v-4.6

# LLaMA-Factory（軽量LoRA/QLoRAファインチューニングツール）でのSFT実行
# yamlファイルにデータセットパスやハイパーパラメータを設定する
llamafactory-cli train examples/train_lora/minicpmv4_6_lora_sft.yaml

# ms-swift（SWIFT: 効率的なパラメータチューニングフレームワーク）でのSFT実行
swift sft --model_type minicpm-v-4_6 --dataset <your-dataset>