Union-search-skill 图片搜索实战:24个平台一图多搜,搜索+自动下载一次搞定

原创2026-10-29 11:30:161,917 阅读

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 的图片搜索让"找图"这件事从手工操作变成了自动化流程。🚀

登录后查看全文
union-search-skill