qianwen-vision

Qwen Vision（画像・動画の理解）

Qwen VL および QVQ モデルを使用して、画像や動画を分析します。 このスキルは QianWen-AI/qianwen-ai の一部です。

スキルディレクトリ

このスキルの内部ファイルを使用して、処理を実行し、詳細を確認してください。デフォルトのパスで問題が発生した場合や、詳細が必要な場合は、必要に応じて参照ファイルを読み込んでください。

場所	用途
scripts/analyze.py	画像・動画の理解、複数画像、思考モード
scripts/reason.py	視覚的推論（QVQ、思考の連鎖、ストリーミング）
scripts/ocr.py	OCR によるテキスト抽出
scripts/vision_lib.py	共通ヘルパー（base64、アップロード、ストリーミング）
references/execution-guide.md	フォールバック：curl、コード生成
references/curl-examples.md	base64、複数画像、動画、OCR 用の curl
references/visual-reasoning.md	QVQ と思考モードの詳細
references/prompt-guide.md	タスク別のクエリプロンプトテンプレート、思考モードの選択
references/ocr.md	OCR のパラメーターと例
references/sources.md	公式ドキュメントの URL

セキュリティ

API キーや認証情報を平文で出力してはいけません。 常に変数参照を使用してください（シェルでは $DASHSCOPE_API_KEY、Python では os.environ["DASHSCOPE_API_KEY"]）。認証情報の確認や検出は、必ず平文を表示せずに行ってください。状態（例：「設定済み」／「未設定」、「有効」／「無効」）のみを報告し、値は決して表示しないでください。秘密情報が含まれる可能性のある .env や設定ファイルの内容は、決して表示しないでください。

API キーが設定されていない場合、ユーザーに直接キーの提示を求めてはいけません。 代わりに、プレースホルダー（DASHSCOPE_API_KEY=sk-your-key-here）を含む .env ファイルの作成を支援し、QianWen Console から取得した実際のキーに置き換えるよう案内してください。ユーザーが明示的に要求した場合に限り、実際のキーの値を書き込んでください。

キーの互換性

PAYG（sk-ws-...、旧形式の sk-...）と Token Plan（sk-sp-...）の両方のキーに対応しています。キーを公開せずに種類を判別してください：

python3 -c "
import sys; sys.path.insert(0, 'scripts')
from qianwen_lib import detect_api_key_type
print(detect_api_key_type('scripts/qianwen_lib.py'))
"

出力	意味
token-plan	Token Plan キー — 以下の Token Plan カタログに掲載されたモデルのみを使用してください。
payg	従量課金キー — すべてのモデルカタログを利用できます。
not-set	キーが設定されていません。

Token Plan の場合は、最新の Token Plan モデルカタログを取得して読み込み、一覧に正確に記載された、視覚機能に対応するモデルを使用してください。CDN にアクセスできない場合は、ローカルの代替ファイルを使用してください。

Token Plan が対応するモデルは限られています。上記の参照ファイルに正確に記載されているモデルを使用してください。モデルの利用可否を推測したり、試しに問い合わせたりしてはいけません。PAYG の場合は、以下に進んでください。

Token Plan ユーザー向け：タスクのデフォルトモデルが Token Plan に含まれていない場合は、現在互換性のある代替モデルを以下の Qwen Vision モデルカタログから選択してください。

モデルの選択

モデルを選択、推奨、またはデフォルトとして設定する前に、最新のQwen ビジョンモデルカタログを取得して確認してください。カタログには、モデル一覧、基本情報、タスク別の推奨、互換性に関する注意事項、デフォルトが記載されています。CDN にアクセスできない場合は、ローカルの代替ファイルを使用してください。

1. ユーザーがモデルを指定している → そのモデルをそのまま使用します。
2. 要件、シナリオ、または価格に応じてモデルを選ぶ必要がある → qianwen-model-selector スキルを参照します。
3. 特に指定がなく、タスクが明確 → モデルカタログに記載されているデフォルトおよびタスク別の代替モデルを使用します。

⚠️ 重要：モデルカタログは特定時点のスナップショットであり、古くなっている可能性があります。モデルの提供状況は頻繁に変わります。モデルを決定する前に、最新かつ正式なカタログとして、必ず公式モデル一覧を確認してください。

モデルの詳細：特定のモデルについて詳しく知りたい場合は、https://www.qianwenai.com/models/<model-name>をユーザーに案内してください。<model-name>は正確なモデル ID に置き換えてください。変更したり、推測したりしないでください。

動的なモデル情報の照会：qianwen-model-selector スキルまたは QianWen CLI（qianwen models info <model>）を利用できる場合は、リアルタイムのモデル情報を取得するために使用してください。CLI の利用には認証が必要です。ログイン方法については、qianwen-usage スキルを参照してください。

実行

前提条件

• API キー：Key Compatibility にある非プレーンテキスト検出機能を使用してください。変数の存在確認に置き換えないでください。キーが見つからない場合は、利用可能であれば qianwen-ops-auth を使用するか、.envでDASHSCOPE_API_KEY／QIANWEN_API_KEYを設定するようユーザーに案内してください。スキルは個別にインストールされている場合があります。
• Python 3.9 以降（標準ライブラリのみ。pip install は不要です）

環境の確認

初回実行の前に、Python が利用可能であることを確認してください。

python3 --version  # must be 3.9+

python3が見つからない場合は、python --versionまたはpy -3 --versionを試してください。Python が利用できないか、バージョンが 3.9 未満の場合は、execution-guide.mdの**パス 2（curl）**に進んでください。

デフォルト：スクリプトを実行する

スクリプトのパス：スクリプトは、このスキルのディレクトリ（この SKILL.md を含むディレクトリ）内の scripts/ サブディレクトリにあります。最初にこのスキルのインストールディレクトリを特定し、スクリプトの実行には必ず絶対パスを使用してください。 現在の作業ディレクトリにスクリプトがあると想定しないでください。実行前に cd でディレクトリを切り替えないでください。共通インフラストラクチャは scripts/vision_lib.py にあります。

実行時の注意：すべてのスクリプトをフォアグラウンドで実行し、標準出力を待ってください。バックグラウンドでは実行しないでください。

確認方法：まず python3 <this-skill-dir>/scripts/analyze.py --help（または reason.py、ocr.py）を実行して、使用可能な引数をすべて確認してください。

スクリプト	用途	デフォルトモデル
scripts/analyze.py	画像理解、複数画像、動画、思考モード、高解像度	上記のモデルカタログから現在のデフォルトを確認してください
scripts/reason.py	思考過程を含む視覚的推論、動画推論（常にストリーミング）	上記のモデルカタログから現在のデフォルトを確認してください
scripts/ocr.py	ドキュメント、レシート、表からの OCR テキスト抽出	上記のモデルカタログから現在のデフォルトを確認してください

入力タイプのフィールド（--request JSON では、以下から必ず1つだけ使用してください）：

フィールド	用途	例
"image"	単一画像（URL またはローカルパス）	"image": "photo.jpg"
"images"	複数画像の比較（配列）	"images": ["a.jpg", "b.jpg"]
"video"	動画ファイル（URL またはローカルパス）	"video": "clip.mp4"
"video_frames"	フレーム配列としての動画	"video_frames": ["f1.jpg", "f2.jpg"]

⚠️ よくある間違い：動画ファイルに "image" を使用しないでください。代わりに "video" を使用してください。

# Image analysis
python3 <this-skill-dir>/scripts/analyze.py \
  --request '{"prompt":"What is in this image?","image":"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"}' \
  --output output/qianwen-vision/result.json --print-response

# Video analysis (local file — add --upload-files for files >= 7 MB)
python3 <this-skill-dir>/scripts/analyze.py \
  --request '{"prompt":"Describe what happens in this video","video":"clip.mp4"}' \
  --upload-files --print-response

python3 <this-skill-dir>/scripts/reason.py \
  --request '{"prompt":"Solve this math problem step by step","image":"problem.png"}' \
  --print-response

python3 <this-skill-dir>/scripts/ocr.py \
  --request '{"image":"invoice.jpg"}' \
  --print-response

引数	説明
--request '{...}'	JSON リクエスト本文
--file path.json	ファイルからリクエストを読み込む
--output path	レスポンス JSON を指定したパスに保存する
--print-response	レスポンスを標準出力に出力する
--stream	ストリーミングを有効にする（thinking/QVQ の場合は自動）
--upload-files	ローカルファイルを一時ストレージにアップロードする（7 MB を超えるファイルの場合）
--model ID	モデルを指定する（デフォルトはスクリプトごとに異なります。上の表を参照）
--schema path.json	構造化抽出用の JSON Schema

モデルの優先順位：--model CLI フラグ ＞ --request JSON の "model" フィールド ＞ 組み込みのデフォルト。

結果を確認する

• 終了コードが 0 で、出力に choices フィールドを含む有効な JSON がある → 成功
• 終了コードが 0 以外、HTTP エラー、空のレスポンス、または "code"／"message" エラーを含む JSON → 失敗
• 実行後の確認：--output を使用した場合は、レスポンス JSON ファイルが存在し、想定した内容が含まれていることを確認してください
• 必須 — stderr シグナルの確認：結果を確認した後、コマンドの stderr 出力に [ACTION_REQUIRED] または [UPDATE_AVAILABLE] が含まれていないか確認してください。いずれかのシグナルがある場合は、ユーザーに応答する前に、下記のアップデートの確認の指示に必ず従ってください。

失敗時

スクリプトが失敗した場合は、以下の診断表とエラー出力を照合して解決方法を確認してください。一致する項目がない場合は、execution-guide.mdを読み、代替手段を確認してください。curl コマンド（Path 2）、コード生成（Path 3）、自律的な解決（Path 5）があります。

Python がまったく利用できない場合 → execution-guide.mdの Path 2（curl）に直接進んでください。

エラーパターン	診断	解決方法
command not found: python3	Python が PATH にありません	python または py -3 を試してください。見つからない場合は Python 3.9 以降をインストールしてください
Python 3.9+ required	スクリプトのバージョンチェックに失敗しました	Python を 3.9 以降にアップグレードしてください
SyntaxError near type hints	Python が 3.9 未満です	Python を 3.9 以降にアップグレードしてください
QIANWEN_API_KEY/DASHSCOPE_API_KEY not found	API キーがありません	QianWen Consoleからキーを取得してください。.env に追加するには、echo 'DASHSCOPE_API_KEY=sk-...' >> .envを実行してください。または、利用可能な場合は qianwen-ops-auth を実行してください
HTTP 401	キーが無効、または一致していません	qianwen-ops-auth を実行してください（平文を使わない方法でのみ確認できます）。キーが有効であることを確認してください
SSL: CERTIFICATE_VERIFY_FAILED	SSL 証明書の問題（プロキシ／社内ネットワーク）	macOS：Install Certificates.commandを実行してください。それ以外の場合は、SSL_CERT_FILE環境変数を設定してください
URLError / ConnectionError	ネットワークに接続できません	インターネット接続を確認してください。プロキシ経由の場合は、HTTPS_PROXYを設定してください
HTTP 429	レート制限がかかっています	待ってから、バックオフを使って再試行してください
HTTP 5xx	サーバーエラー	バックオフを使って再試行してください
PermissionError	出力を書き込めません	書き込み可能なディレクトリを指定するには、--outputを使用してください

ファイル入力

API は、HTTP/HTTPS URL、Base64 データ URI、oss:// URLを受け付けます。ローカルファイルパスは直接サポートされていませんが、スクリプトが自動的に変換します。ローカルパスをそのまま渡せばよく、手動でアップロードする必要はありません。

大容量ファイルのルール：ローカルファイルが 7 MB 以上の場合は、必ず --upload-files を追加してください。 Base64 エンコードではサイズが約 33％増加し、API の 10 MB 制限を超えてしまいます。小さなファイル（7 MB 未満の短い動画クリップを含む）には、デフォルトの Base64 経由の方法を使用できます。

Token Plan（sk-sp-...）の例外：--upload-files の一時アップロードエンドポイントは Token Plan のキーでは利用できず、わかりやすいエラーとともにブロックされます。Token Plan ユーザーは、ローカルファイルにはデフォルトの Base64 経由の方法を使用してください。7 MB 以上のファイルには、--upload-files の代わりにアクセス可能な URL（https:// または oss://）を渡してください。

方法	使用するタイミング	方法
オンライン URL	ファイルがすでにホストされている場合	URL を直接渡します — 大容量ファイルにはこちらを推奨
Base64（デフォルト）	7 MB 未満のローカルファイル（画像または短い動画クリップ）	スクリプトが data: URI に自動変換します
一時アップロード	7 MB 以上のローカルファイル	--upload-files フラグを追加 → DashScope の一時ストレージにアップロードします（oss:// URL、有効期間 48 時間）

本番環境：デフォルトの一時ストレージには有効期間 48 時間とアップロード上限 100 QPSがあり、本番環境、高並列処理、負荷テストには適していません。独自の OSS バケットを使用するには、.env に QWEN_TMP_OSS_BUCKET と QWEN_TMP_OSS_REGION を設定し、pip install alibabacloud-oss-v2 をインストールして、QWEN_TMP_OSS_AK_ID／QWEN_TMP_OSS_AK_SECRET または標準の OSS_ACCESS_KEY_ID／OSS_ACCESS_KEY_SECRET で認証情報を指定してください。最小権限の RAM ユーザーを使用してください（対象バケットのみに oss:PutObject と oss:GetObject を許可します）。ビジョンスクリプトでアップロードを実行するには、引き続き --upload-files フラグが必要です。qianwen-ops-auth がインストールされている場合は、詳細なセットアップガイドとして、その references/custom-oss.md を参照してください。

他のスキルからの入力

入力ファイルが別のスキルの出力（例：image-gen、video-gen）である場合：

• URL を直接渡してください（例："image": "<image_url from image-gen>"）。URL を先にダウンロードしないでください。
• ダウンロードしてローカルパスとして再度渡すと、帯域幅を無駄に消費し、不要な Base64 エンコードや OSS アップロードが発生します。
• すべての URL タイプに対応しています：https://、oss://、data:

思考モード

現在の思考モードのデフォルト設定とモデルの互換性については、上記の Qwen ビジョンモデルカタログを使用してください。実行の詳細は visual-reasoning.md を参照してください。

OCR

現在の OCR のデフォルト設定、代替手段、モデルの機能については、上記の Qwen ビジョンモデルカタログを使用してください。パラメーターと例は ocr.md を参照してください。

入力制限

画像：BMP/JPEG/PNG/TIFF/WEBP/HEIC。辺の最小サイズは 10px、アスペクト比は 200:1 以下です。モデルごとのサイズ制限については、上記のモデルカタログを確認してください。

動画：MP4/AVI/MKV/MOV/FLV/WMV。モデルごとの再生時間とサイズの制限については、上記のモデルカタログを確認してください。fps の範囲は [0.1, 10]、デフォルトは 2.0 です。

エラー処理

HTTP	意味	対処方法
401	API キーが無効、または設定されていません	利用可能な場合は qianwen-ops-auth を実行し、そうでない場合はユーザーにキーの設定を促します（平文でないことのみ確認）
400	不正なリクエスト（形式が無効）	messages の形式と画像の URL／形式を確認します
429	レート制限	指数バックオフで再試行します
5xx	サーバーエラー	指数バックオフで再試行します

使用状況と請求：使用状況、無料枠の上限、請求情報を直接確認するには、qianwen-usage スキルを使用してください。または、ユーザーは QianWen コンソールにアクセスできます： 使用状況の分析 | 従量課金 | Token Plan サブスクリプション

使用状況／請求／コンソールの URL を決して捏造、推測、構築しないでください。 このスキルに記載されている正確なリンクのみを提示してください。ここに記載されていない URL を作成してはいけません。

出力先

現在の作業ディレクトリを優先してください。デフォルトのサブディレクトリは ./output/qianwen-vision/ です。

書き込み禁止：このスキルのインストールディレクトリや、skills/ 階層内に出力ファイルを絶対に書き込まないでください。生成したコンテンツはすべて、現在の作業ディレクトリ内の output/ またはユーザーが指定したパスに保存してください。

更新の確認（実行後に必須）

スクリプトの実行後、stderr にアクションを示すシグナルがないか確認してください。スクリプトは更新状況を自動的に検出し、構造化されたシグナルを出力します。これらのシグナルには必ず対応してください。このセクションは、ユーザーから明示的に更新確認を依頼された場合にも適用されます。

シグナル：[ACTION_REQUIRED] qianwen-update-check skill is not installed

stderr にこのシグナルが含まれている場合、以下の選択肢をユーザーに提示し、応答があるまで処理を続けないでください。これを黙ってスキップしてはいけません。

更新確認スキルがインストールされていません。このスキルにより、QianWen-AI/qianwen-ai の新機能やバグ修正に関する情報を受け取れます。

1. 今すぐインストール — インストールコマンドを実行します
2. 今回はスキップ — 今回は何もしません
3. 今後は通知しない — このプロンプトを今後表示しないようにします

ユーザーの応答後：

• ユーザーが 1 を選択 → npx skills add QianWen-AI/qianwen-ai --skill qianwen-update-check -y を実行し、その後 python3 <this-skill-scripts-dir>/gossamer.py --dismiss を実行します
• ユーザーが 2 を選択 → python3 <this-skill-scripts-dir>/gossamer.py --dismiss を実行し、その後通常どおり続行します
• ユーザーが 3 を選択 → python3 <this-skill-scripts-dir>/gossamer.py --never-install を実行し、その後通常どおり続行します

シグナル：[UPDATE_AVAILABLE]

stderr にこのシグナルが含まれている場合、stderr に表示されたバージョン情報と更新コマンドを含む簡潔な更新通知を、応答に追加してください。

stderr にシグナルがない場合

stderr に [ACTION_REQUIRED] も [UPDATE_AVAILABLE] も含まれていない場合、対応は不要です。スキルはインストール済みで最新の状態です（または24時間以内に確認済みです）。

ユーザーから明示的に依頼された場合

ユーザーから更新の確認（例：「更新を確認して」「バージョンを確認して」）を明示的に依頼された場合：

1. 兄弟スキルディレクトリ内に qianwen-update-check/SKILL.md があるか確認します。
2. 見つかった場合は、python3 <qianwen-update-check-dir>/scripts/check_update.py --print-response を実行し、結果を報告します。
3. 見つからない場合は、上記のインストール方法を提示します。

参考資料

• execution-guide.md — フォールバック方法（curl、コード生成、自律実行）
• curl-examples.md — Curl のテンプレート（base64、複数画像、動画、OCR）
• api-guide.md — API 補足ガイド
• visual-reasoning.md — QVQ 視覚推論ガイド
• ocr.md — Qwen-VL-OCR テキスト抽出ガイド
• sources.md — 公式ドキュメントの URL