小艺图像理解
传入图片(本地路径或公网 URL),返回图像的详细文本描述。最多 10 张。
桌面形态(默认):云端接口调用(图像理解 / OSMS 图片上传)经主进程 skill API 代理(
np://claw-skill命名管道)转发,业务鉴权由主进程自动注入, 本 skill 零配置、零凭证。仅要求环境变量CLAW_SKILL_TOKEN(主进程已自动注入)。
核心功能
- 图片描述:详细描述图片中的场景、人物、活动
- OCR 文字识别:识别图中文字,保持原始排版,支持手写、印刷、表格
- 物体识别:识别并列举图中物体,标注位置
- 图片问答:针对图片内容提问,获取精准回答
- 图表分析:提取图表数据点、趋势和关键信息
用法
# 本地单图
python scripts/image_understanding.py --image "photo.jpg" --prompt "详细描述图片中的场景"
# URL 图片
python scripts/image_understanding.py --image "https://example.com/image.jpg" --prompt "提取图中所有文字"
# 多图(最多 10 张)
python scripts/image_understanding.py --image img1.jpg img2.jpg img3.jpg --prompt "对比这些图片的差异"
执行命令时,将外层 shell/exec 超时设为至少 900 秒,确保脚本自己的超时和错误处理能够完成;不要使用外层默认短超时提前杀掉进程。
参数
| 参数 | 必填 | 说明 |
|---|---|---|
| --image / -i | ✅ | 本地路径或 http/https URL,最多 10 张 |
| --prompt / -p | ✅ | 提示词 |
输出格式
{"images": ["photo.jpg"], "caption": "图片描述文本..."}
多图时 images 为数组,caption 为整体描述。失败时脚本返回非零退出码,并在最后一行输出:
{"images": ["photo.jpg"], "error": {"code": "request_timeout", "message": "...", "retryable": true}}
超时与重试
- 图片上传读超时为 180 秒。
- 图像理解等待响应头最多 120 秒,流连续 180 秒无数据视为空闲超时,单次云侧理解总时长最多 360 秒。
- 收到 SSE
[DONE]或明确完成事件后,脚本会立即结束,不继续等待服务端关闭连接。 - 只有最后一行 JSON 中
error.retryable为true时才允许自动重试;等待 10 秒后,使用完全相同的图片和 prompt 最多重试一次。 - 第二次失败后立即停止并向用户说明错误。禁止继续循环调用。
- 如果命令被外层 shell/exec 超时直接终止,没有拿到结构化错误,不要自动重试,以免前一个云侧任务仍在执行而产生重复请求。
Prompt 要点
- 说清楚要什么:
提取图中所有文字>图中讲了什么 - 限定范围:
忽略背景,只识别表格中的数字、仅描述人物动作 - 多图对比:
对比图1和图2的差异
故障排除
| 问题 | 解决方案 |
|---|---|
| 鉴权失败(401) | 请确认已登录小艺Work——业务凭据由主进程统一管理,skill 侧无需也无法配置 |
| 配置缺失 | 桌面管道形态零配置;旧沙箱形态才需检查 ~/.openclaw/.xiaoyienv 是否包含 PERSONAL_API_KEY、PERSONAL_UID、SERVICE_URL |
| 文件不存在 | 确认图片路径正确 |
| 上传失败 | 检查连接,确认图片未损坏(phase2 为预签名 URL 直传) |
| 识别不准确 | 使用更具体的 prompt |
| 请求超时 | 图片理解最长等待 360 秒;仅在结构化错误标记可重试时自动重试一次 |
| 图片过大 | 超过 2048×2048 自动等比例缩放 |