qwencloud-vision

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

安全

绝不以明文形式输出任何 API 密钥或凭据。 始终使用变量引用（Shell 中使用 $QWENCLOUD_API_KEY，Python 中使用 os.environ["QWENCLOUD_API_KEY"]）。脚本依次接受 QWENCLOUD_API_KEY、QWEN_API_KEY 和 DASHSCOPE_API_KEY。任何凭据检查或检测都必须不以明文形式进行：只报告状态（例如“已设置”/“未设置”、“有效”/“无效”），绝不显示其值。绝不显示可能包含机密的 .env 或配置文件内容。

未配置 API 密钥时，绝不要求用户直接提供。 请改为帮助用户创建 .env 文件并填入占位符（QWENCLOUD_API_KEY=sk-your-key-here），并指导用户从 QwenCloud Console 获取实际密钥后替换占位符。只有用户明确要求时，才能写入实际密钥值。

密钥兼容性

脚本同时支持标准 QwenCloud API 密钥（sk-...）和 Token Plan 密钥（sk-sp-...）。对于受支持的多模态模型，Token Plan 密钥会自动路由到 Token Plan 端点 — 请参阅 Token Plan 模型目录。如果 CDN 访问失败，请使用本地备用文件。

Token Plan：请勿使用 curl；始终使用随附的 Python 脚本。

Coding Plan 密钥（同样以 sk-sp- 为前缀，但通过 Coding Plan 订阅购买）不能用于直接 API 调用。脚本会在启动时检测密钥类型并据此路由。如果已安装 qwencloud-ops-auth，请参阅其 references/codingplan.md，了解当前模型覆盖范围、端点映射和错误详情。

检测 API 密钥类型时，不要暴露密钥：

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

输出	含义
token-plan	检测到 Token Plan 密钥（sk-sp- 前缀）
payg	检测到标准 PAYG 密钥
not-set	环境中未找到 API 密钥

模型选择

🚫 严重警告 — 切勿覆盖用户指定的参数。 如果用户在提示词或请求 JSON 中明确指定了模型，必须严格使用该模型。请勿：

• 将其替换为“更适合”或更新的模型（例如，因为新版文档“更推荐”qwen3.7-plus/qwen3.8-max，就把用户指定的 qwen3-vl-plus 换成它们）
• 添加用户未要求的参数（enable_thinking、thinking_budget、vl_high_resolution_images、detail）；但如果用户请求 json_mode/schema 且未设置该参数，随附脚本必须发送 enable_thinking: false
• “优化”用户明确指定的选择

以下选择指南仅适用于用户未指定模型的情况。

在选择、推荐或设置默认模型之前，请获取并阅读最新的 QwenCloud 视觉模型目录。其中包含模型列表、基本信息、任务推荐、兼容性说明和默认设置。如果 CDN 访问失败，请使用本地备用文件。

1. 用户指定了模型 → 必须严格使用该模型 — 不得替换或“优化”。除上述结构化输出兼容性行为外，不得添加用户未要求的参数；如果指定的是仅支持思考的模型，应拒绝使用，而不是悄悄替换。
2. 模型选择取决于需求、场景或价格 → 查阅 qwencloud-model-selector 技能。
3. 没有明确偏好，任务清晰 → 使用模型目录中的默认模型和针对具体任务的替代模型。专用脚本的默认设置不受密钥类型影响；如果 Token Plan 用户的套餐不支持某个默认模型，应从目录中选择兼容的模型。

⚠️ 重要提示：模型目录是特定时间点的快照，可能已过时。模型可用性 经常变化。在决定模型前，务必查看官方模型列表 ，以获取权威的最新目录。

模型详情：如需了解某个模型的更多信息，请引导用户访问其详情页：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 Key：仅使用非明文方式检查 QWENCLOUD_API_KEY、QWEN_API_KEY，然后检查 DASHSCOPE_API_KEY（例如，在 shell 中运行： [ -n "$QWENCLOUD_API_KEY" ]；只报告“已设置”或“未设置”，绝不显示密钥值）。如果未设置：若可用，请运行 * qwencloud-ops-auth* 技能；否则，引导用户从 QwenCloud 控制台获取密钥，并通过 .env 文件（ 在项目根目录或当前目录中运行 echo 'QWENCLOUD_API_KEY=sk-your-key-here' >> .env）或环境变量设置。脚本会在当前工作目录和项目根目录中查找 .env。技能可能是单独安装的 — 不要假定一定有 qwencloud-ops-auth。 注意：脚本会自动从当前目录和项目根目录加载 .env（以及任何已导出的环境变量）。Shell 检查显示 $QWENCLOUD_API_KEY“未设置”，并不意味着脚本会失败 — 它仍可能在 .env 中找到密钥。检查结果仅供参考；权威测试方法是直接运行脚本（如果找不到任何密钥，脚本会退出并显示明确错误）。
• Python 3.9+（仅使用标准库，无需 pip install）

环境检查

首次执行前，请确认 Python 可用：

python3 --version  # must be 3.9+

如果 python3 不可用或版本低于 3.9，按量付费（PAYG）可使用路径 2（curl）；Token Plan 则必须安装 Python 3.9+。

默认方式：运行脚本

脚本路径：脚本位于此技能目录（包含此 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 中准确使用其中一个）：

字段	用途	示例
"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/qwencloud-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	启用流式传输（思考模式/QVQ 下自动启用）
--upload-files	将本地文件上传到临时存储（适用于大于 7 MB 的文件）
--schema path.json	用于结构化提取的 JSON Schema

验证结果

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

失败时

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

如果完全无法使用 Python → PAYG 可使用路径 2（curl）；Token Plan 必须安装 Python 3.9+。

错误模式	诊断	解决方法
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+
QWENCLOUD_API_KEY/QWEN_API_KEY/DASHSCOPE_API_KEY not found	缺少 API 密钥	从 QwenCloud Console 获取密钥；添加到 .env：echo 'QWENCLOUD_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%，并超过 API 的 10 MB 限制。小文件（包括时长较短且小于 7 MB 的视频片段）可使用默认的 Base64 方式。

方式	适用情况	操作
在线 URL	文件已托管	直接传入 URL——大文件优先使用此方式
Base64（默认）	小于 7 MB 的本地文件（图像或短视频片段）	脚本会自动转换为 data: URI
临时上传	大于等于 7 MB 的本地文件	添加 --upload-files 标志 → 上传到 DashScope 临时存储（oss:// URL，TTL 为 48 小时）

生产环境：默认临时存储的 TTL 为 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 标志来触发上传。如果已安装 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:

思考模式

请使用上方链接的视觉模型目录，了解当前默认思考模式设置和模型兼容性。除非用户明确要求更改，否则不要设置 enable_thinking——无论是“因为任务看起来很复杂”而启用，还是“因为任务看起来很简单”而禁用。唯一的兼容性例外是结构化输出：json_mode 和 schema 要求使用非思考模式，因此捆绑脚本会在未指定该设置时自动发送 enable_thinking: false，并拒绝显式设置为 true。仅支持思考模式的模型不能用于结构化输出。

详情请参阅 visual-reasoning.md。

OCR

请使用上方链接的视觉模型目录，了解当前 OCR 默认设置、替代方案和模型功能。参数和示例请参阅 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 密钥无效或缺失	如果有，请运行 qwencloud-ops-auth；否则提示用户设置密钥（仅检查是否为明文）
400	请求错误（格式无效）	检查 messages 格式以及图片 URL/格式
429	请求频率受限	使用指数退避重试
5xx	服务器错误	使用指数退避重试

用量与账单：使用 qwencloud-usage 技能直接查看用量、免费层级额度和账单。用户也可以访问 QwenCloud 控制台： 用量分析 | 按需付费账单 | Coding Plan 账单

**绝不要编造、猜测或构造用量/账单/控制台 URL。**只能提供此技能中列出的准确链接。如果此处未列出某个 URL，请勿编造。

输出位置

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

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

Token Plan 支持

Token Plan 密钥（sk-sp-...）支持具备视觉能力的多模态模型。

支持的视觉模型

获取并读取当前的 Token Plan 模型目录，然后使用目录中准确列出的、具备视觉能力的模型。如果 CDN 访问失败，请使用本地备用文件。

这些模型使用兼容 OpenAI 的聊天 API 和多模态消息格式（image_url 内容类型）。

默认值

未提供模型时，每个脚本都会使用其配置的默认模型，不受密钥类型影响。请检查视觉模型和 Token Plan 目录以确认当前兼容性。明确指定的请求模型始终优先。

Token Plan 不支持的模型

Token Plan 模型目录中未列为具备视觉能力的模型需要使用 PAYG 密钥。只有在用户明确同意后，才能从视觉模型目录中推荐兼容的替代选项。绝不要因密钥类型限制而擅自替换用户指定的模型；请列出选项并让用户选择。

必需的请求头

User-Agent: qwencloud-skills 会自动添加。

更新检查（执行后必须进行）

脚本执行后，请检查 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]，则无需采取任何操作 — 该 skill 已安装且为最新版本（或缓存时间在 24 小时内）。

用户明确请求

当用户明确要求检查更新时（例如“检查更新”“检查版本”）：

1. 在同级 skill 目录中查找 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