Union-search-skill 图片搜索实战:24个平台一图多搜,搜索+自动下载一次搞定
Union-search-skill 图片搜索实战:24个平台一图多搜,搜索+自动下载一次搞定
union-search-skill(Union Search) 是一个面向命令行与 AI Agent 的多平台搜索工具,同一个查询可以一次分发到 51 个搜索渠道。它的 图片搜索(image) 子命令更进一步:一条命令即可在 24 个图片平台 上"一图多搜",搜到的图片会 自动下载到本地,并逐张完成文件校验与元数据记录——从找图到存图,一次搞定。📥
为什么选 Union Search 做图片搜索
平时找图,我们往往要在百度、Bing、Google 之间反复切换,找到满意的还要一张张手动保存。Union Search 的图片搜索把这些步骤压缩成一条命令:
| 能力 | 说明 |
|---|---|
| 🔍 一图多搜 | 同一关键词同时搜 24 个图片平台(默认 baidu bing wikicommons) |
| 📥 搜索 + 自动下载 | 默认搜索后直接下载原图到本地目录,无需手动保存 |
| 🗂 统一元数据 | 标题、图片地址、来源页面、尺寸、作者、许可等信息统一成 JSON 字段 |
| ✅ 文件级校验 | 下载后校验图片实际内容,记录 sha256 与文件大小,坏图不会被当成"下载成功" |
快速安装:两步上手图片搜索
图片搜索能力随主仓库提供,先获取代码并安装依赖:
git clone https://gitcode.com/gh_mirrors/un/union-search-skill
cd union-search-skill
python -m pip install -r requirements.txt
依赖清单见 requirements.txt:原生图片平台使用 Pillow>=12(图片校验)与 chompjs>=1.2(页面解析),SDK 平台依赖 pyimagedl。全部命令都在仓库根目录执行。
一条命令:24个平台一图多搜
安装完成后,第一次图片搜索只需要一行:
python union_search_cli.py image "sunset" --limit 5 --pretty
这条命令默认在 baidu、bing、wikicommons 三个平台上搜索 "sunset",每个平台取 5 张,搜索完成后自动下载。--limit 5 是每个平台的结果上限,写 --limit 0 表示保留本次取得的全部结果。
想用更多平台?用 --platforms 显式指定即可:
python union_search_cli.py image "mountain landscape" --platforms baidu bing pixabay --limit 10 --pretty
想知道当前环境里实际可选哪些平台,运行:
python union_search_cli.py list --type images --pretty
24个图片平台一览
图片平台分为两类,注册表定义见 scripts/cli/registry.py:
| 类型 | 数量 | 平台 |
|---|---|---|
| 原生平台(项目独立实现) | 12 | baidu、bing、sogou、quark、pixabay、flickr、pinterest、500px、wikicommons、naver、artstation、findthatmeme |
| SDK 平台(基于 pyimagedl) | 12 | google、i360、yandex、yahoo、unsplash、gelbooru、safebooru、danbooru、pexels、huaban、foodiesfeed、volcengine |
两个实用细节:
- 原生平台解析图片地址、来源页面与元数据,下载时逐张校验,是默认推荐;
volcengine(火山引擎)走 API,需要在.env中配置VOLCENGINE_API_KEY,且每次最多请求 5 张,获取方式见 凭据指南。
下载的图片在哪里:输出目录与汇总报告
下载结果按"平台 + 时间戳"分目录保存,不会互相覆盖:
image_downloads/
└── baidu_20261029_013000_123456/ # 平台名_时间戳
├── <图片文件>
└── metadata.json # 该批图片的元数据
自定义目录用 --output-dir,例如:
python union_search_cli.py image "flowers" --platforms bing --output-dir ./my_images --limit 5
每次运行还会自动生成一份汇总报告,保存在 scripts/union_image_search/responses/ 下,文件名形如 YYYYMMDD_HHMMSS_image_search_results.json,包含各平台成功/失败状态、找到数量与下载数量,方便事后核对。
只要链接不要文件:--search-only 只搜索不下载
如果你只想要图片地址和元数据(比如交给 Agent 做后续筛选),加上 --search-only 即可,不会生成任何图片文件:
python union_search_cli.py image "mountain landscape" --search-only --limit 5 --pretty
注意两点:--search-only 仅支持 12 个原生平台,显式指定 SDK 平台时会明确报错;原生搜索每次只取单页有限结果,不会自动遍历全部分页。
图片元数据有哪些字段
每张图片的元数据都统一保留一套字段,来源没有提供的输出为 null,方便程序化读取:
| 字段 | 含义 |
|---|---|
title / image_url / source_url |
图片标题、下载用的原图地址、来源页面 |
thumbnail / width / height |
缩略图地址与图片尺寸 |
author / license |
作者与许可信息(为空不代表可免费使用) |
image_variant |
实际取到的是来源原图还是最大可用版本 |
file_path / download_status |
本地文件位置与单张下载状态 |
字段统一逻辑集中在 native_images.py,完整字段说明见 图片模块文档。
下载的图片是"真图":自动文件校验
这是图片搜索容易忽略的一步:URL 能访问不代表文件是完整图片。Union Search 下载后会用 Pillow 的 Image.verify() 检查实际图片内容,并记录文件 sha256 与字节数——只有校验通过的文件才会被标记为下载成功。
同样重要的是"部分失败不拖垮全局":某一张图下载失败时,只会在该图片上保留错误记录,其余平台的成功结果照常返回;此时统一 CLI 顶层 ok 为 false、错误码为 PARTIAL_FAILURE,但 data 中仍保留全部成功数据。脚本逻辑见 multi_platform_image_search.py。
常见问题排查
| 现象 | 先做什么 |
|---|---|
| 图片命令不可用 | 检查当前 Python 环境是否装好 Pillow、chompjs 及 SDK 平台需要的 pyimagedl,即 python -m pip install -r requirements.txt |
| 某平台搜索没结果 | 换一个更明确的关键词;匿名请求仍可能遇到验证码或限流 |
一个平台失败导致整体 ok: false |
读取保留的成功数据,再单独检查失败平台,可运行 python union_search_cli.py doctor --pretty |
| 火山引擎报错 | 在 .env 中配置 VOLCENGINE_API_KEY |
平台失败不会自动切换到其他来源,需要调用方自行更换渠道,这一点在设计上是刻意为之——结果来源始终可预期。更多说明见 故障排查文档。
相关模块路径
| 文件 | 说明 |
|---|---|
| union_search_cli.py | 统一命令入口,image 子命令定义处 |
| scripts/union_image_search/README.md | 图片搜索完整文档(参数、输出位置、错误规则) |
| scripts/union_image_search/multi_platform_image_search.py | 多平台图片搜索与下载主脚本 |
| scripts/union_image_search/native_images.py | 统一字段、下载与图片验证 |
| scripts/cli/registry.py | 24 个图片平台注册表 |
| references/api_credentials.md | 各平台 API Key 获取指南 |
一条命令,24 个平台,搜完即下载、下载必校验——Union Search 的图片搜索让"找图"这件事从手工操作变成了自动化流程。🚀