返回技能市场
通用工具 安全 需要 API Key

千问AI-视觉理解

@qianwen-ai/qianwen-vision

使用千问视觉模型理解图像和视频。适用场景：用户希望分析或描述图像或视频，或从中提取信息、提取 OCR 文本、读取图表/表格、进行视觉推理、多图像比较、屏幕截图理解或视频理解，或者按名称明确调用此 skill（例如，使用 qianwen-vision）。不适用场景：用户希望生成/创建图像（使用 qianwen-image-generation）、生成视频（使用 qianwen-video-generation）、处理没有视觉输入的纯文本任务，或处理非千问视觉任务。

千问AI平台 热度 1,619v0.0.2

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

使用 Qwen VL 和 QVQ 模型分析图像和视频。 此 skill 是 QianWen-AI/qianwen-ai 中的组成部分。

Skill 目录

执行和学习时，使用此 skill 的内部文件。默认路径失效或需要详细信息时，按需加载参考文件。

| 位置 | 用途 | |----------|---------| | 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 | 按任务分类的查询 Prompt 模板、思考模式判断 | | 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 文件，并指导用户将其替换为从千问AI平台控制台获取的实际密钥。仅当用户明确要求时，才写入实际密钥值。

密钥兼容性

同时支持 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，请严格选用 qianwen-model-selector 中列出的模型，或查阅 qianwen-ops-auth/references/tokenplan.md。如果不可用，请使用：

  • 个人版: https://platform.qianwenai.com/docs/token-plan/personal/token-plan-personal-overview.md
  • 团队版: https://platform.qianwenai.com/docs/token-plan/team/token-plan-team-overview.md

Token Plan 用户：请使用具备视觉能力的模型——qwen3.8-max、qwen3.8-flash、 qwen3.7-plus、qwen3.6-flash（个人版和团队版），或 qwen3.6-plus、kimi-k2.7-code、 kimi-k2.6、kimi-k2.5（仅限团队版）。Token Plan 中的其他模型不支持图像/视频 理解。

Token Plan 仅支持特定模型——请严格选用上述参考资料中的模型；不得 猜测或探测模型可用性。对于 PAYG，请继续阅读下文。

Token Plan 用户：ocr 的默认模型 qwen3.5-ocr 和 reason 的默认模型 qvq-max 均不在 Token Plan 中。
- OCR：请指定 --model qwen3.8-flash（低成本通用 OCR）或 qwen3.8-max（质量最佳）。在 ID 卡、坐标和公式等专项提取方面，准确率可能略低于专用 OCR 模型。
- 视觉推理：请指定 --model qwen3.8-max（视觉推理 + 思考）或 qwen3.8-flash（轻量级）。

模型选择

| 模型 | 使用场景 | |-------|----------| | qwen3.8-max | 最强旗舰模型——参数量达 2.4T，采用 MoE。具备顶级多模态能力（文本+图像+视频）。默认开启思考模式。上下文长度为 1M。成本更高。 | | qwen3.8-flash | 快速旗舰级多模态模型——与 qwen3.8-max 同代，针对速度和成本效益进行了优化。支持多模态（文本+图像+视频）。默认开启思考模式。上下文长度为 1M。 | | qwen3.7-flash | 高性能多模态快速模型——各方面均超越 qwen3.6-flash。通用识别能力、搜索 Agent 和 CI Agent 均得到增强。针对氛围编程进行了优化。默认开启思考模式。上下文长度为 1M。视觉任务性价比最高。 | | qwen3.7-plus | 首选——新一代均衡模型，在多模态理解、Agent 执行与编码、GUI 感知方面超越 qwen3.6-plus。上下文长度为 1M。默认开启思考模式。 | | qwen3.6-plus | 上一代均衡模型——支持多模态（文本+图像+视频）。默认开启思考模式。编码与通用识别能力强。 | | qwen3.5-plus | 统一多模态（文本+图像+视频）。默认开启思考模式。 | | qwen3.5-flash | 快速多模态模型——成本更低、速度更快。默认开启思考模式。 | | qwen3-vl-plus | 高精度——物体定位（2D/3D）、文档/网页解析。 | | qwen3-vl-flash | 快速视觉——延迟更低，支持 33 种语言。 | | qvq-max | 视觉推理——用于数学和图表的思维链推理。仅支持流式输出。 | | qwen3.5-ocr | OCR——最新推荐的 OCR 模型。PDF 解析、多轮对话、增强型 ID/卡片识别。 | | qwen-vl-ocr | OCR——文本提取、表格解析、文档扫描。旧版模型；使用 --model qwen-vl-ocr 显式选择。 | | qwen-vl-max | Qwen2.5-VL——2.5 系列中性能最佳。 | | qwen-vl-plus | Qwen2.5-VL——速度更快，在性能和成本之间取得良好平衡，支持 11 种语言。 |

  1. 用户指定了模型 → 直接使用。
  2. 当模型选择取决于需求、场景或定价时，请咨询 qianwen-model-selector skill。
  3. 无明确选择依据、任务清晰 → qwen3.7-plus。需要兼顾性价比与高性能视觉能力时，使用 qwen3.7-flash。最复杂的推理任务使用 qwen3.8-max。精确定位或 3D 检测使用 qwen3-vl-plus。
⚠️ 重要提示：上述模型列表是特定时间点的快照，可能已经过时。模型可用性
变化频繁。**在选择模型前，请务必查看官方模型列表
，以获取权威的最新模型目录。**
模型详情：要了解特定模型的更多信息，请引导用户访问其详情页面：https://www.qianwenai.com/models/<model-name>（将 <model-name> 替换为确切的模型 ID，例如 qwen3.6-plus → <https://www.qianwenai.com/models/qwen3.6-plus>）。禁止修改或猜测 URL 中的模型名称。
动态模型查询：如果 qianwen-model-selector skill 或 千问AI平台 CLI（qianwen models info <model>）可用，请用其获取实时模型数据。CLI 需要身份验证——登录流程请参阅 qianwen-usage skill。

执行

前提条件

  • API 密钥：使用密钥兼容性中的非明文检测器；不得将其替换为

    • 变量存在性检查。如果未找到密钥，请在 qianwen-ops-auth 可用时使用该工具，或指导用户 在 .env 中配置 DASHSCOPE_API_KEY/QIANWEN_API_KEY。Skills 可独立安装。

  • Python 3.9+（仅使用标准库，无需执行 pip install）

环境检查

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

python3 --version  # must be 3.9+

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

默认方式：运行脚本

脚本路径：脚本位于此 skill 的目录（包含此 SKILL.md 的目录）下的 scripts/ 子目录中。必须先找到此 skill 的安装目录，然后始终使用完整绝对路径执行脚本。 不得假定脚本位于当前工作目录中。执行前不得使用 cd 切换目录。共享基础组件位于 scripts/vision_lib.py 中。

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

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

| 脚本 | 用途 | 默认模型 | |--------|---------|---------------| | scripts/analyze.py | 图像理解、多图像处理、视频处理、思考模式、高分辨率 | qwen3.7-plus | | scripts/reason.py | 带思维链的视觉推理、视频推理（始终使用流式输出） | qvq-max | | scripts/ocr.py | 从文档、收据和表格中提取 OCR 文本 | qwen3.5-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 | 将响应打印到 stdout | | --stream | 启用流式输出（思考模式或 QVQ 会自动启用） | | --upload-files | 将本地文件上传到临时存储（适用于大于 7 MB 的文件） | | --model ID | 覆盖模型设置（各脚本的默认值见上表） | | --schema path.json | 用于结构化提取的 JSON 模式 |

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

验证结果

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

失败处理

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

如果 Python 完全不可用 → 直接跳至 [execution-guide.md](references/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+ | | QIANWEN_API_KEY/DASHSCOPE_API_KEY not found | 缺少 API 密钥 | 从千问AI平台控制台获取密钥；将其添加到 .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 的文件，应传入可访问的 URL（https:// 或 oss://），而不是使用 --upload-files。

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

生产环境：默认临时存储的 TTL 为 48h，且 上传上限为 100 QPS — 不适用于生产环境、高并发场景或负载测试。要使用自己的 OSS 存储空间，请在 .env 中设置 QWEN_TMP_OSS_BUCKET 和 QWEN_TMP_OSS_REGION，安装 pip install oss2，并通过 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 获取完整配置指南。

来自其他 Skills 的输入

当输入文件来自另一个 skill 的输出时（例如，图像生成、视频生成）：

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

思考模式

| 模型 | 思考模式默认状态 | 说明 | |-------|-----------------|-------| | qwen3.8-max | 开启 | 最强旗舰模型。对于简单任务，可使用 enable_thinking: false 关闭。 | | qwen3.7-plus | 开启 | 首选默认模型。 对于简单任务，可使用 enable_thinking: false 关闭。 | | qwen3.7-flash | 开启 | 高性能快速模型。对于简单任务，可使用 enable_thinking: false 关闭。 | | 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](references/visual-reasoning.md)。

OCR (qwen3.5-ocr)

默认 OCR 模型为 qwen3.5-ocr——这是最新推荐的 OCR 模型，具备 PDF 解析、多轮对话和增强的 ID/卡片识别能力。旧版 qwen-vl-ocr 仍可通过 --model qwen-vl-ocr 使用。支持多种语言、倾斜图像、表格和公式。有关参数和示例，请参见 [ocr.md](references/ocr.md)。

输入限制

图像：BMP/JPEG/PNG/TIFF/WEBP/HEIC。边长最小为 10px，宽高比 <= 200:1。最大文件大小为 20 MB（URL；Qwen3.8/3.7/3.6/3.5 和 Qwen3-VL 系列）/ 10 MB（其他模型）。

视频：MP4/AVI/MKV/MOV/FLV/WMV。时长为 2s–2h（Qwen3.8/3.7/3.6/3.5 系列）/ 2s–1h（Qwen3-VL 系列）/ 2s–10min（其他模型）。最大文件大小为 2 GB（URL）/ 10 MB（Base64 编码）。帧率范围为 [0.1, 10]，默认值为 2.0。

错误处理

| HTTP | 含义 | 处理措施 | |------|---------|--------| | 401 | API 密钥无效或缺失 | 如可用，运行 qianwen-ops-auth；否则，提示用户配置密钥（仅进行非明文检查） | | 400 | 错误请求（格式无效） | 检查消息格式和图像 URL/格式 | | 429 | 请求受到限流 | 采用指数退避策略重试 | | 5xx | 服务器错误 | 采用指数退避策略重试 |

使用量与计费：使用 qianwen-usage skill 直接查看使用量、免费额度和计费信息。或者，用户可以访问千问AI平台控制台：
用量分析 |
按量付费账单 |
Token Plan 订阅
严禁伪造、猜测或构造使用量/计费/控制台 URL。 只能提供此 skill 中列出的确切链接。如果此处未列出某个 URL，不得自行编造。

输出位置

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

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

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

脚本执行后，检查 stderr 中的操作信号。脚本会自动检测更新状态并发出结构化信号。你必须根据这些信号采取行动。当用户明确要求检查更新时，本节同样适用。

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

当 stderr 包含此信号时，你必须向用户提供以下选项，并等待用户回复后再继续。不得在不告知用户的情况下跳过此步骤。

更新检查 skill 尚未安装。它可以让你及时了解 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]，则无需执行任何操作 — 该 skill 已安装且为最新版本（或已在 24h 内缓存）。

用户明确请求

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

  1. 在同级 skill 目录中查找 qianwen-update-check/SKILL.md。
  2. 如果找到 — 运行：python3 <qianwen-update-check-dir>/scripts/check_update.py --print-response，并报告结果。
  3. 如果未找到 — 向用户提供上述安装选项。

参考资料

  • [execution-guide.md](references/execution-guide.md) — 回退路径（curl、代码生成、自主处理）
  • [curl-examples.md](references/curl-examples.md) — Curl 模板（base64、多图像、视频、OCR）
  • [api-guide.md](references/api-guide.md) — API 补充指南
  • [visual-reasoning.md](references/visual-reasoning.md) — QVQ 视觉推理指南
  • [ocr.md](references/ocr.md) — Qwen-VL-OCR 文本提取指南
  • [sources.md](references/sources.md) — 官方文档 URL
qianwen skills install @qianwen-ai/qianwen-vision