alicloud-ai-multimodal-qwen-vl

类别：provider

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，或将 dashscope_api_key 添加到 ~/.alibabacloud/credentials。

关键模型名称

优先使用 Qwen3 VL 系列：

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

需要显式使用“latest”路由或可复现的快照时，请使用官方模型列表中支持的别名/快照，例如：

• 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 专用提取，优先使用 skills/ai/multimodal/alicloud-ai-multimodal-qwen-ocr/，而不是通用 VL 技能。

规范化接口（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	后端临时故障	使用退避策略重试，并采用幂等请求设计。

操作指南

• 为确保生产环境中的行为稳定，请固定快照模型 ID，而不要单纯使用 -latest。
• 上传前压缩超大图像，以降低延迟和成本。
• 在提示词中明确提取约束（字段、JSON 结构、语言）。
• 对于类似 OCR 的输出，请要求提供置信度说明和未能识别文本的标记。

工作流

1. 确认用户意图、区域、标识符，以及操作是只读还是会修改数据。
2. 先运行一条最精简的只读查询，以验证连接和权限。
3. 使用明确的参数和有限的范围执行目标操作。
4. 验证结果并保存输出/证据文件。

参考资料

• 来源列表：references/sources.md
• API 说明：references/api_reference.md