alicloud-ai-multimodal-qwen-vl

カテゴリ：プロバイダー

Model Studio Qwen VL（画像理解）

検証

mkdir -p output/alicloud-ai-multimodal-qwen-vl
python -m py_compile skills/ai/multimodal/alicloud-ai-multimodal-qwen-vl/scripts/analyze_image.py && echo "py_compile_ok" > output/alicloud-ai-multimodal-qwen-vl/validate.txt

合格基準：コマンドが 0 で終了し、output/alicloud-ai-multimodal-qwen-vl/validate.txt が生成されます。

出力とエビデンス

• モデルの生の応答と正規化された抽出結果を output/alicloud-ai-multimodal-qwen-vl/ に保存します。
• トレーサビリティを確保するため、入力画像の参照情報とプロンプトを含めます。

DashScope 互換モード API を通じて、画像入力とテキスト出力による理解タスクに Qwen VL モデルを使用します。

前提条件

• 依存関係をインストールします（venv の使用を推奨します）。

python3 -m venv .venv
. .venv/bin/activate
python -m pip install requests

• 環境に DASHSCOPE_API_KEY を設定するか、~/.alibabacloud/credentials に dashscope_api_key を追加します。

重要なモデル名

Qwen3 VL ファミリーを優先してください。

• qwen3-vl-plus
• qwen3-vl-flash

「最新」のルーティングを明示する場合や、再現可能なスナップショットが必要な場合は、次のような公式モデル一覧でサポートされているエイリアス／スナップショットを使用してください。

• qwen3-vl-plus-latest
• qwen3-vl-plus-2025-12-19
• qwen3-vl-flash-2026-01-22
• qwen3-vl-flash-latest

一部のワークロードで今も使われているレガシー名：

• qwen-vl-max-latest
• qwen-vl-plus-latest

OCR に特化した抽出には、汎用の VL スキルではなく skills/ai/multimodal/alicloud-ai-multimodal-qwen-ocr/ を優先してください。

正規化インターフェース（multimodal.chat）

リクエスト

• prompt（文字列、必須）：画像に関するユーザーの質問／指示です。
• image（文字列、必須）：HTTPS URL、ローカルパス、または data: URL です。
• model（文字列、任意）：デフォルトは qwen3-vl-plus です。
• max_tokens（整数、任意）：デフォルトは 512 です。
• temperature（浮動小数点数、任意）：デフォルトは 0.2 です。
• detail（文字列、任意）：auto／low／high、デフォルトは auto です。
• json_mode（ブール値、任意）：可能な場合、JSON のみの応答を返します。
• schema（オブジェクト、任意）：構造化抽出用の JSON Schema です。
• max_retries（整数、任意）：429/5xx の再試行回数です。デフォルトは 2 です。
• retry_backoff_s（浮動小数点数、任意）：指数バックオフの基準秒数です。デフォルトは 1.5 です。

応答

• text（文字列）：モデルの主な回答です。
• model（文字列）：実際に使用されたモデルです。
• usage（オブジェクト）：バックエンドから返された場合のトークン使用量です。

クイックスタート

python skills/ai/multimodal/alicloud-ai-multimodal-qwen-vl/scripts/analyze_image.py \
  --request '{"prompt":"Summarize the main content in this image","image":"https://example.com/demo.jpg"}' \
  --print-response

ローカル画像を使用する場合：

python skills/ai/multimodal/alicloud-ai-multimodal-qwen-vl/scripts/analyze_image.py \
  --request '{"prompt":"Extract key information from the image","image":"./samples/invoice.png","model":"qwen3-vl-plus"}' \
  --print-response

構造化抽出（JSON モード）：

python skills/ai/multimodal/alicloud-ai-multimodal-qwen-vl/scripts/analyze_image.py \
  --request '{"prompt":"Extract fields: title, amount, date","image":"./samples/invoice.png"}' \
  --json-mode \
  --print-response

構造化抽出（JSON Schema）：

python skills/ai/multimodal/alicloud-ai-multimodal-qwen-vl/scripts/analyze_image.py \
  --request '{"prompt":"Extract invoice fields","image":"./samples/invoice.png"}' \
  --schema skills/ai/multimodal/alicloud-ai-multimodal-qwen-vl/references/examples/invoice.schema.json \
  --print-response

cURL（互換モード）

curl -sS https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"qwen3-vl-plus",
    "messages":[
      {
        "role":"user",
        "content":[
          {"type":"image_url","image_url":{"url":"https://example.com/demo.jpg"}},
          {"type":"text","text":"Describe this image and list executable actions"}
        ]
      }
    ],
    "max_tokens":512,
    "temperature":0.2
  }'

出力先

• --output が設定されている場合、JSON 応答はそのファイルに保存されます。
• デフォルトの出力ディレクトリ規約：output/alicloud-ai-multimodal-qwen-vl/。

スモークテスト

python tests/ai/multimodal/alicloud-ai-multimodal-qwen-vl-test/scripts/smoke_test_qwen_vl.py \
  --image ./tmp/vl_test_cat.png

エラー処理

エラー	考えられる原因	対処方法
401/403	キーがない、または無効	DASHSCOPE_API_KEY とアカウントの権限を確認します。
400	リクエストスキーマが無効、または画像ソースが未対応	messages の内容と画像 URL／パスの形式を検証します。
429	レート制限	指数バックオフで再試行し、同時実行数を減らします。
5xx	一時的なバックエンドの問題	バックオフを使って再試行し、冪等なリクエスト設計にします。

運用ガイダンス

• 本番環境で安定した動作を得るには、-latest のみを指定するのではなく、スナップショットのモデル ID を固定してください。
• レイテンシとコストを削減するため、非常に大きな画像はアップロード前に圧縮してください。
• プロンプトに抽出条件（フィールド、JSON の形式、言語）を明示してください。
• OCR のような出力では、信頼度に関する注記と、未解決テキストを示すマーカーを求めてください。

ワークフロー

1. ユーザーの意図、リージョン、識別子、および操作が読み取り専用か変更を伴うかを確認します。
2. 接続と権限を確認するため、まず最小限の読み取り専用クエリを 1 つ実行します。
3. 明示的なパラメーターと限定された範囲で、対象の操作を実行します。
4. 結果を検証し、出力／エビデンスファイルを保存します。

参考資料

• ソース一覧：references/sources.md
• API の注記：references/api_reference.md