qianwen-vision

Qwen 视觉（图像与视频理解）

使用 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 密钥或凭据。 始终使用变量引用（Shell 中使用 $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-...）密钥均受支持。检测 API 密钥类型时，不要泄露密钥：

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 视觉模型目录查找当前兼容的替代模型。

模型选择

在选择、推荐或默认使用某个模型之前，请获取并阅读当前的 Qwen 视觉模型目录。其中包含模型列表、基本信息、任务推荐、兼容性说明和默认选项。如果 CDN 无法访问，请使用本地备用文件。

1. 用户指定了模型 → 直接使用。
2. 模型选择取决于需求、场景或价格 → 查阅 qianwen-model-selector 技能。
3. 没有明确信息，任务清晰 → 使用模型目录中的默认模型和针对具体任务的备选模型。

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

模型详情：如需了解特定模型的更多信息，请引导用户访问 https://www.qianwenai.com/models/<model-name>。将 <model-name> 替换为准确的模型 ID；切勿修改或猜测该 ID。

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

执行

前置条件

• API Key：使用 Key Compatibility 中的非明文检测器；不要将其替换为变量存在性检查。如果未找到 Key，请在 qianwen-ops-auth 可用时使用它，或引导用户在 .env 中配置 DASHSCOPE_API_KEY/QIANWEN_API_KEY。技能可以单独安装。
• Python 3.9+（仅使用标准库，无需安装 pip 包）

环境检查

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

python3 --version  # must be 3.9+

如果找不到 python3，请尝试 python --version 或 py -3 --version。如果 Python 不可用或版本低于 3.9，请跳至执行指南中的路径 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 中恰好使用一个）：

字段	用途	示例
"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	启用流式传输（思考模式/QVQ 会自动启用）
--upload-files	将本地文件上传到临时存储（适用于大于 7 MB 的文件）
--model ID	覆盖模型（各脚本的默认值见上表）
--schema path.json	用于结构化提取的 JSON Schema

模型优先级：--model CLI 标志 > --request JSON 中的 "model" 字段 > 内置默认值。

验证结果

• 退出代码为 0，且输出包含带有 choices 字段的有效 JSON → 成功
• 退出代码非零、HTTP 错误、响应为空，或 JSON 中包含 "code"/"message" 错误 → 失败
• 执行后检查：使用 --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 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-...）例外：Token Plan 密钥无法使用 --upload-files 临时上传端点，该端点会被拦截并返回友好提示。Token Plan 用户应对本地文件使用默认的 Base64 路径；对于 >= 7 MB 的文件，请传入可访问的 URL（https:// 或 oss://），而不要使用 --upload-files。

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

生产环境：默认临时存储的 TTL 为 48h，且上传限制为 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

请使用上方链接的 Qwen 视觉模型目录，了解当前 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 密钥无效或缺失	如果可用，请运行 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