astrbot_plugin_serpapi_imgsearch

通过 SerpApi 为 AstrBot 的大语言模型注册函数工具（Function Tool / Tool Use），让 LLM 在对话中自动完成两件事：

• 文字搜图并发图 (pic_search)：根据关键词用 Google 图片（google_images）抓取大量候选图，再用视觉语言模型（VLM）多轮淘汰赛挑出最符合描述的一张，直接发送给用户。
• 以图搜图 (reverse_image_search)：对用户发送/引用的图片做反向检索。默认使用 Google Lens（SerpApi google_lens，通用网页出处）；可选启用 SauceNAO 附加引擎（二次元/插画溯源，可精确到 pixiv、danbooru、番剧出处），启用后两引擎并发检索。检索后先按引擎自带可信度定级（SauceNAO 相似度阈值、Lens 精确匹配标记），再把灰色地带候选缩略图与原图拼成对比图交视觉模型补充核验，归纳为 confirmed（同图，确认来源）/ suspected（相似，输出疑似名称/来源）/ no_match（LLM 降级为纯视觉辨识）三级结论后交 LLM 呈现。

仅通过 LLM 函数工具 触发，不注册任何聊天指令。文字搜图与 Google Lens 以图搜图共用同一组 SerpApi Key；SauceNAO 附加引擎走独立的 SauceNAO 额度。

工作原理

能力	函数工具	说明
文字搜图	pic_search(query)	google_images 抓候选图 → 下载拼网格图 → VLM 多轮筛选 → 下载冠军图并直接发送。需要一个支持图片输入的模型。
以图搜图	reverse_image_search(image_url?)	取当前消息/被引用消息中的图片 → 必要时上传图床转公网 URL → Google Lens（+可选 SauceNAO 并发）反向检索 → 引擎可信度定级（SauceNAO 相似度阈值、Lens exact_matches）→ 灰色地带候选与原图拼「原图 | 编号网格」对比图交 VLM 补充判定 → 归纳 verdict 交由 LLM 呈现。

安装与配置

1. 将本插件放入 AstrBot 的 data/plugins/ 目录（或通过插件市场安装），重载插件。
2. 在 管理面板 → 插件管理 → 本插件 → 配置 中填写：

配置项	说明	默认值
api_keys.serpapi_keys	SerpApi Key 列表，文字搜图与 Google Lens 以图搜图共用，支持多个 Key 负载均衡。获取	[]
api_keys.saucenao_api_key	SauceNAO API Key（启用附加引擎时用）。获取；留空以游客额度调用（限制更严）。	空
saucenao.enabled	启用 SauceNAO 附加引擎：以图搜图同时用 Google Lens 与 SauceNAO 并发检索、结果合并。	false
saucenao.hide	SauceNAO 成人内容过滤：0=全部显示、1=隐藏确认 R18、2=再隐藏疑似 R18、3=只显示确认安全。	0
saucenao.dbs	SauceNAO 限定检索的索引编号列表（如 5=pixiv、9=danbooru）。留空检索全部索引。	[]
saucenao.exact_similarity	SauceNAO 相似度达此值（%）直接判定同图（exact），不交视觉模型、不会被推翻。	85
saucenao.similar_similarity	SauceNAO 相似度达此值（%）至少判定相似（similar），视觉模型只能升级不能降级。	65
vlm_provider_id	文字搜图筛选候选图、以图搜图原图 vs 候选图比对所用的视觉 Provider ID。留空则用当前会话默认模型（需支持图片输入）。	空
batch_size	每轮淘汰赛单批处理的图片数量。	16
default_scrape_count	文字搜图默认抓取的候选图数量（建议 16 的倍数）。	16
region.gl	搜索国家/地区代码（Google gl，Lens 映射为 country），如 us、cn、jp。	us
region.hl	界面语言代码（Google hl），如 en、zh-cn、ja。	zh-cn
network.proxy_url	HTTP/HTTPS 代理，如 http://127.0.0.1:7890。留空不使用。	空
network.allow_image_upload	以图搜图时允许把本地/临时图片上传到图床取公网 URL（关闭则仅支持公网直链图）。	true
network.image_host	上传图床：litterbox(临时1h,推荐)、uguu(临时)、catbox(永久)。临时图床更适合以图搜图，且对代理/机房 IP 更友好。	litterbox
max_results	以图搜图每个引擎的最大结果数（也是参与视觉比对的候选数上限）。	5
lens_safe_search	Google Lens 安全搜索。默认关闭（safe=off）：开启后 Google 会对疑似成人内容的缩略图打码，SFW 插画也常被误伤，打码缩略图无法用于视觉比对。	false
reverse_verify.enabled	以图搜图视觉核验：把引擎未定为同图的候选缩略图与原图拼对比图交 VLM 补充判定。关闭则只按引擎自带可信度判定。	true
reverse_verify.send_comparison	把「原图 | 编号候选网格」对比图一并发到会话，便于用户自行核对。	false
reverse_verify.skip_vlm_when_confirmed	引擎可信度已判出同图（结论 confirmed）时跳过视觉比对，省去一次数十秒的多图 VLM 调用。	true

3. 文字搜图与以图搜图的视觉核验都依赖视觉/多模态模型：请配置 vlm_provider_id，或确保当前会话的默认对话模型支持图片输入。

以图搜图的结论分级

核验分两层：引擎可信度优先（SauceNAO 相似度达阈值 / Google Lens exact_matches 标记直接定级，不会被推翻），再把灰色地带候选与原图拼对比图交 VLM 补充判定（只能升级不能降级）。工具返回的 JSON 带 verdict 字段，LLM 按其分流：

verdict	含义	LLM 应当
confirmed	至少一条候选被判定为同一张图（match=exact）	直接确认来源（作品 / 作者 / 链接），不再视觉猜测
suspected	无同图，但有同角色 / 同人物 / 同作品 / 同画师的相近图（match=similar）	输出「疑似」名称 / 来源，并说明是相似匹配
no_match	候选全部无关或无法核验，或各引擎均无结果 / 失败	转述插件附带的 visual_analysis（VLM 对原图的辨识），坦诚告知反查未命中，不再调用任何工具

关于以图搜图的“图片转公网链接”

SerpApi / SauceNAO 服务器需要能从公网访问到待检索的图片：

• 若图片本身已是公网 http(s) URL（多数平台的图片消息）→ 直接使用。
• 否则在 allow_image_upload=true 时，把图片上传到所选图床（image_host：Litterbox/uguu/Catbox）换取公网 URL。
• 若转链失败，工具同样返回 verdict: no_match 并附带插件自行完成的视觉辨识，模型据此作答，不会中断对话。

使用示例

• 「帮我找一张赛博朋克霓虹城市夜景的图」→ LLM 调 pic_search(query="赛博朋克 霓虹城市夜景") → 抓图/拼图/VLM 选择 → 直接发图。
• （发送或引用一张图片）「以图搜图」→ LLM 调 reverse_image_search() → Google Lens（+可选 SauceNAO）检索 → 候选图与原图对比核验 → 按 verdict 给出确认来源 / 疑似来源 / 视觉推测。

依赖

无需额外安装

致谢

本插件的两大功能在实现思路上受到以下两个优秀项目的启发，特此感谢：

• 文字搜图（候选图 → 拼网格 → VLM 多轮淘汰赛）灵感来自 RC-CHN/astrbot_plugin_pic_search。
• 以图搜图（图片转公网链接 → 反向检索）灵感来自 FlanChanXwO/astrbot_plugin_imgexploration。

同时感谢：

• AstrBot 提供的插件框架。
• SerpApi 与 SauceNAO 提供的检索能力。