qwencloud-vision

代理设置：如果您的代理不会自动加载技能（例如 Claude Code），
请参阅 agent-compatibility.md（每个会话一次）。

Qwen Vision（图像与视频理解）

使用 Qwen VL 和 QVQ 模型分析图像和视频。
此技能是 qwencloud/qwencloud-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
references/agent-compatibility.md	代理自检：为不自动加载技能的代理在项目配置中注册技能

安全

切勿以明文输出任何 API 密钥或凭据。 始终使用变量引用（shell 中的 $DASHSCOPE_API_KEY，Python 中的 os.environ["DASHSCOPE_API_KEY"]）。任何凭据检查或检测必须非明文：仅报告状态（例如“已设置”/“未设置”、“有效”/“无效”），绝不报告值。切勿显示可能包含机密的 .env 或配置文件内容。

当 API 密钥未配置时，切勿要求用户直接提供。 相反，帮助创建包含占位符的 .env 文件（DASHSCOPE_API_KEY=sk-your-key-here），并指示用户从 QwenCloud 控制台 替换为实际密钥。仅当用户明确要求时才写入实际密钥值。

密钥兼容性

脚本需要标准 QwenCloud API 密钥（sk-...）。Coding Plan 密钥（sk-sp-...）不能用于直接 API 调用，也不支持专用视觉模型（qwen3-vl-plus、qvq-max 等）。脚本在启动时检测 sk-sp- 密钥并打印警告。如果安装了 qwencloud-ops-auth，请参阅其 references/codingplan.md 获取完整详情。

模型选择

模型	用例
qwen3.6-plus	首选 — 最新旗舰，统一多模态（文本+图像+视频）。默认开启思考。质量、速度、成本的最佳平衡。
qwen3.5-plus	统一多模态（文本+图像+视频）。默认开启思考。
qwen3.5-flash	快速多模态 — 更便宜、更快。默认开启思考。
qwen3-vl-plus	高精度 — 物体定位（2D/3D）、文档/网页解析。
qwen3-vl-flash	快速视觉 — 更低延迟，支持 33 种语言。
qvq-max	视觉推理 — 数学、图表的思维链。仅流式输出。
qwen-vl-ocr	OCR — 文本提取、表格解析、文档扫描。
qwen-vl-max	Qwen2.5-VL — 2.5 系列中性能最佳。
qwen-vl-plus	Qwen2.5-VL — 更快，性能和成本的良好平衡，支持 11 种语言。

1. 用户指定了模型 → 直接使用。
2. 当模型选择取决于需求、场景或定价时，咨询 qwencloud-model-selector 技能。
3. 无信号，任务明确 → qwen3.6-plus。对于精确定位或 3D 检测，使用 qwen3-vl-plus。

⚠️ 重要：上述模型列表是时间点快照，可能已过时。模型可用性
频繁变化。在做出模型决策之前，始终检查官方模型列表以获取权威、最新的目录。

模型详情：有关特定模型的更多信息，请引导用户访问其详情页：https://www.qwencloud.com/models/<model-name>（将 <model-name> 替换为确切的模型 ID，例如 qwen3.6-plus → https://www.qwencloud.com/models/qwen3.6-plus）。切勿修改或猜测 URL 中的模型名称。

动态模型查询：如果 qwencloud-model-selector 技能或 QwenCloud CLI（qwencloud models info <model>）可用，请使用它获取实时模型数据。CLI 需要身份验证 — 请参阅 qwencloud-usage 技能了解登录流程。

执行

先决条件

• API 密钥：使用非明文检查确认 DASHSCOPE_API_KEY（或 QWEN_API_KEY）已设置（例如在 shell 中：
  [ -n "$DASHSCOPE_API_KEY" ]；仅报告“已设置”或“未设置”，绝不报告密钥值）。如果未设置：运行 qwencloud-ops-auth 技能（如果可用）；否则引导用户从 QwenCloud 控制台 获取密钥，并通过 .env 文件（
  echo 'DASHSCOPE_API_KEY=sk-your-key-here' >> .env 在项目根目录或当前目录）或环境变量设置。脚本会在当前工作目录和项目根目录中搜索 .env。技能可能独立安装 — 不要假设 qwencloud-ops-auth 存在。
• Python 3.9+（仅标准库，无需 pip 安装）

环境检查

首次执行前，验证 Python 可用：

python3 --version  # 必须是 3.9+

如果找不到 python3，请尝试 python --version 或 py -3 --version。如果 Python 不可用或低于 3.9，请跳至 execution-guide.md 中的 路径 2（curl）。

默认：运行脚本

脚本路径：脚本位于此技能目录（包含此 SKILL.md 的目录）的 scripts/ 子目录中。您必须首先定位此技能的安装目录，然后始终使用完整的绝对路径来执行脚本。 不要假设脚本位于当前工作目录。执行前不要使用 cd 切换目录。共享基础设施位于 scripts/vision_lib.py。

执行说明：在前台运行所有脚本 — 等待 stdout；不要后台运行。

发现：首先运行 python3 <this-skill-dir>/scripts/analyze.py --help（或 reason.py、ocr.py）查看所有可用参数。

脚本	用途	默认模型
scripts/analyze.py	图像理解、多图像、视频、思考模式、高分辨率	qwen3.6-plus
scripts/reason.py	带思维链的视觉推理、视频推理（始终流式）	qvq-max
scripts/ocr.py	从文档、收据、表格中提取 OCR 文本	qwen-vl-ocr

输入类型字段（在 --request JSON 中仅使用一个）：

字段	用途	示例
"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"。

# 图像分析
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/qwencloud-vision/result.json --print-response

# 视频分析（本地文件 — 对于 >= 7 MB 的文件添加 --upload-files）
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	将响应打印到 stdout
--stream	启用流式（思考/QVQ 自动启用）
--upload-files	将本地文件上传到临时存储（用于 > 7 MB 的文件）
--schema path.json	用于结构化提取的 JSON Schema

验证结果

• 退出代码 0 + 输出包含带 choices 字段的有效 JSON → 成功
• 非零退出、HTTP 错误、空响应或包含 "code"/"message" 错误的 JSON → 失败
• 执行后检查：使用 --output 时，验证响应 JSON 文件存在且包含预期内容
• 强制 — stderr 信号检查：确认结果后，扫描命令的 stderr 输出中是否有 [ACTION_REQUIRED] 或 [UPDATE_AVAILABLE]。如果存在任一信号，您必须在回复用户之前遵循下方 更新检查 中的说明。

失败时

如果脚本失败，将错误输出与下方诊断表匹配以确定解决方案。如果没有匹配项，请阅读 execution-guide.md 中的替代路径：curl 命令（路径 2）、代码生成（路径 3）和自主解决（路径 5）。

如果 Python 完全不可用 → 直接跳至 execution-guide.md 中的路径 2（curl）。

错误模式	诊断	解决方案
command not found: python3	Python 不在 PATH 中	尝试 python 或 py -3；如果缺失则安装 Python 3.9+
Python 3.9+ required	脚本版本检查失败	升级 Python 到 3.9+
SyntaxError 靠近类型提示	Python < 3.9	升级 Python 到 3.9+
QWEN_API_KEY/DASHSCOPE_API_KEY not found	缺少 API 密钥	从 QwenCloud 控制台 获取密钥；添加到 .env：echo 'DASHSCOPE_API_KEY=sk-...' >> .env；或运行 qwencloud-ops-auth（如果可用）
HTTP 401	无效或不匹配的密钥	运行 qwencloud-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%，将超过 10 MB 的 API 限制。小文件（包括 < 7 MB 的短视频片段）可以使用默认的 base64 路径。

方法	何时使用	如何
在线 URL	文件已托管	直接传递 URL — 大文件首选
Base64（默认）	本地文件 < 7 MB（图像或短视频片段）	脚本自动转换为 data: URI
临时上传	本地文件 >= 7 MB	添加 --upload-files 标志 → 上传到 DashScope 临时存储（oss:// URL，48 小时 TTL）

生产环境：默认临时存储具有 48 小时 TTL 和 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 标志来触发上传。如果安装了 qwencloud-ops-auth，请参阅其 references/custom-oss.md 获取完整设置指南。

来自其他技能的输入

当输入文件来自其他技能的输出（例如 image-gen、video-gen）时：

• 直接传递 URL（例如 "image": "<image_url from image-gen>"）— 不要先下载 URL
• 下载并作为本地路径重新传递会浪费带宽，并触发不必要的 base64 编码或 OSS 上传
• 支持所有 URL 类型：https://、oss://、data:

思考模式

模型	思考默认	备注
qwen3.6-plus	开启	最新旗舰。对于简单任务，使用 enable_thinking: false 禁用。
qwen3.5-plus / qwen3.5-flash	开启	对于简单任务，使用 enable_thinking: false 禁用。
qwen3-vl-plus / qwen3-vl-flash	关闭	使用 enable_thinking: true 启用。
qvq-max	始终开启	需要流式输出。

有关详细信息，请参阅 visual-reasoning.md。

OCR（qwen-vl-ocr）

针对文本提取进行了优化。支持多语言、倾斜图像、表格、公式。有关参数和示例，请参阅 ocr.md。

输入限制

图像：BMP/JPEG/PNG/TIFF/WEBP/HEIC。最小边长 10px，宽高比 <= 200:1。最大 20 MB（URL，Qwen3.5）/ 10 MB（其他）。

视频：MP4/AVI/MKV/MOV/FLV/WMV。时长 2 秒–2 小时（Qwen3.5）/ 2 秒–10 分钟（其他）。最大 2 GB（URL）/ 10 MB（base64）。fps 范围 [0.1, 10]，默认 2.0。

错误处理

HTTP	含义	操作
401	无效或缺少 API 密钥	运行 qwencloud-ops-auth（如果可用）；否则提示用户设置密钥（仅非明文检查）
400	错误请求（格式无效）	验证消息格式和图像 URL/格式
429	速率受限	使用指数退避重试
5xx	服务器错误	使用指数退避重试

使用与计费：使用 qwencloud-usage 技能直接检查使用量、免费额度配额和计费。或者，用户可以访问 QwenCloud 控制台：
使用分析 |
按量付费计费 |
Coding Plan 计费

切勿编造、猜测或构造使用/计费/控制台 URL。 仅提供此技能中列出的确切链接。如果此处未列出 URL，请勿发明。

输出位置

优先使用当前工作目录。默认子目录：./output/qwencloud-vision/。

写入禁止：切勿将输出文件写入此技能的安装目录或任何 skills/ 层级。所有生成的内容必须放在当前工作目录下的 output/ 或用户指定的路径中。

更新检查（强制执行后）

脚本执行后，检查 stderr 中的操作信号。脚本会自动检测更新状态并发出结构化信号。您必须对它们采取行动。当用户明确要求检查更新时，本节也适用。

信号：[ACTION_REQUIRED] qwencloud-update-check skill is not installed

当 stderr 包含此信号时，您必须向用户呈现以下选项，并等待他们的响应后再继续。不要静默跳过。

更新检查技能未安装。它可以让您了解 qwencloud/qwencloud-ai 的新功能和错误修复。

1. 立即安装 — 我将为您运行安装命令
2. 暂时跳过 — 这次不执行任何操作
3. 不再提醒 — 永久抑制此提示

用户响应后：

• 用户选择 1 → 运行：npx skills add QwenCloud/qwencloud-ai --skill qwencloud-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. 在兄弟技能目录中查找 qwencloud-update-check/SKILL.md。
2. 如果找到 — 运行：python3 <qwencloud-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