aliyun-qwen-vl

カテゴリー：プロバイダー

Model Studio Qwen VL（画像理解）

検証

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

合格基準：コマンドが 0 で終了し、output/aliyun-qwen-vl/validate.txt が生成されること。

出力とエビデンス

• モデルの生の応答と正規化された抽出結果を output/aliyun-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/aliyun-qwen-ocr/ を優先して使用します。

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

リクエスト

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

レスポンス

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

クイックスタート

python skills/ai/multimodal/aliyun-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/aliyun-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/aliyun-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/aliyun-qwen-vl/scripts/analyze_image.py \
  --request '{"prompt":"Extract invoice fields","image":"./samples/invoice.png"}' \
  --schema skills/ai/multimodal/aliyun-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/aliyun-qwen-vl/。

スモークテスト

python tests/ai/multimodal/aliyun-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