Mu Tian实测 Gemini 视觉接口：一个请求搞定物体检测与老照片级图像修复
过去一年，我一直在折腾各类视觉模型，本地跑过 YOLO，也搭过 Stable Diffusion 全家桶，说白了就是又爱又恨：检测效果好但定制流程复杂，图像修复效果好但训练集一塌糊涂。直到我把 Gemini 官方的视觉接口系统地接进现有工作流，才发现“空间智能”这四个字不是忽悠人的。
你只需要传入一张图：要么让它告诉你图上有什么、在哪里，要么让它把破损严重的老照片直接补全、放大、去噪，两个任务本质上发生在同一次 API 请求里。这篇文章我就把这段时间整理的思路、接口行为、参数调优经验，以及踩过的坑全部倒出来，基于我自己的真实场景展开，不含任何隐蔽工具和外链，适合正在做视觉应用、想快速验证 Gemini 能力的开发者参考。
先说清楚：这不是一篇“换皮教程”，不会带你走通任何代理工具。内容仅围绕代码级调用、模型行为设计与工程落地展开，逻辑上参考官方文档提供的 API 能力和社区公开实验结论，所有示例代码与配置均可在合规环境下自行复现。
1. 空间智能任务的本质：检测和修复为什么能共用一个接口
1.1 视觉感知的最底层逻辑：理解空间关系
先看物体检测。常见方案是 YOLO 系列，输出一组框、类别与置信度，本质上是回归问题。图像修复则完全不同：给定一张破损图，缺失区域要么靠周围纹理延拓，要么靠语义理解重建语义内容，比如人脸的左眼没了，模型要能“编”出一个合理的左眼，且不能破坏身份特征。
这两类任务过去分属两套独立流程，检测走 CNN 回归派，修复走扩散派。Gemini 这类多模态大模型把它们统一到了同一个空间里：把图像切分为视觉 token，与文本 token 一起参与注意力计算。这样模型不仅“看到”像素，还能“理解”像素之间的关系，理解是一张脸，理解左眼与右眼的空间对称性，从而完成从零重建。
1.2 任务性质差异决定了工程方案分两次走
虽然共用一个接口，我的建议是不要在同一个 Prompt 里同时干两件事，比如“找到这只猫并修复它的耳朵”，实测效果会互相干扰。先让模型用文本形式输出检测框坐标与类别，再让它基于检测框坐标，对局部区域执行修复，这样每次调用模型都能把注意力集中在一个目标上，后续也方便跟踪输出质量。
这种拆单任务的设计，还带来一个额外好处：可以针对不同子任务，单独调节模型能力参数，比如 warmup 步数、随机数种子、局部生成范围，在不同语言参数组合下互不污染，定位问题和回溯实验都会干净很多。
1.3 我对“空间智能”这个词的理解
官方语境里的“空间智能”，不只是把文字转成框，而是像素坐标、物体边界、物体间相对位置、语义关系都同时存在于多模态模型的高维表示中。换句话说，它是一套“内化的空间认知”。
举例来说，老照片中一间屋子的窗户破了个洞，人如果不看周边墙角线、窗台倾斜角，是不可能猜出窗户原本的形状的。Gemini 能做到的原因，是其基于海量图文对学到的世界常识：它知道窗户是矩形、窗框与墙面的分界大多平行。这些常识被训练阶段固化在权重中，推理时与输入图的视觉特征对齐，就能给出比“纹理延拓”更高级的“语义重建”。检测同理：它不只看局部特征，它能根据桌面、键盘、显示器之间的上下文自动纠正遮挡造成的误判。这就解释了为什么它如此擅长完成物体框选：即使目标只有 20% 面积可见，也能合理推断出完整边界。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 技术参数解读：采样步数、种子与上下文窗口的真实影响
2.1 采样步数与扩散修复的质量曲线
在需要生成局部内容时，官方模型的采样步数越高，图像细节与语义一致性越好，但调用耗时与成本也越高，且超过阈值后收益趋缓。我的实测数据显示在一次人物老照片去除折痕实验里：
采样步数 20 步，人物脸部肤色过渡有轻微阶梯状；提到 50 步后，面颊高光与皱纹走向自然了许多；50 到 80 步的画面差异已经非常小，肉眼几乎无法区分，所以正常情况下我会直接固定在 50 步左右。
2.2 随机种子的作用与滥用风险
很多开发者对种子有一个误解：认为固定种子就能保证每次输出一致。实际在多模态生成里，种子只在同样输入、同样参数、同样模型版本的条件下复现结果。一旦你换一张图片，或者调整 prompt 中的某个词，种的输出就会彻底变化。
我的用法是：用随机种子做大量候选，选出某个满意结果后，记下这个种子，用于参数对照实验，比如固定所有条件只调整采样器类型，看看哪一类采样器更适合细节保持。工程上不要依赖种子追求确定性。你需要的是可复现的评测集，而不是单图可复现。
2.3 上下文窗口不是越长越好
Gemini 支持超大上下文窗口，视觉任务中还有一个经常被忽略的操作：你可以把多张参考图和组织说明文字一并塞进同一个请求，模型会跨图理解，比如给一张破损图，再给一张完整同款古董花瓶图，修复效果大幅提升。
但是上下文窗口填得越满，推理耗时越长，而且模型注意力分散后，核心任务出现偏差的概率会上升。我的建议是，把参考图控制在 2-3 张之内，每张都要经过裁剪预处理，只保留与修复区域语义最相关的部分。尤其不要把整本手册附上去再让它干活，注意力会被无关文本带跑。
2.4 模型版本差异造成的隐蔽困扰
官方经常推出新版本，号称精度升级、幻觉降低，但我实测发现，不同版本在视觉任务表现上并不总是新版更好。旧版本在检测垂直场景中边界框更紧致，新版在自然语言描述上更流畅。做视觉任务，建议先定好自己交付所用的固定模型版本，离线批量跑实验再切换。千万不要线上直接切换新版本，否则某天输出格式不对，你会花半天时间排查，最后才发现是版本行为变了。
3. 实操流程设计：用文本坐标作为中间表示
3.1 输入层设计
所有调用统一走官方 API，你需要准备一张常规 JPEG 或 PNG 图像，将二进制数据 base64 编码。检测场景中输入建议不超过 2048 像素长边，否则模型对目标缩小后的响应会降低；修复场景输入尺寸可以稍大，但大图一次性通过往往需要保持纵横比，否则面部会被压扁。推荐先编写预处理脚本：将长边缩放到 2048 像素以内，中心裁剪到 1536x1536，并以高质量重采样保存，以避免局部伪影。
3.2 提示词工程式任务描述
检测任务的提示词，我是如此设计的：
“你现在是一个视觉检测系统。请找到图中的全部小轿车、货车、公交车。输出严格 JSON 格式，包含对象类别、边界框左上角x、左上角y、右下角x、右下角y，用归一化坐标，保留四位小数。如果没有检测到任何目标，返回空数组。”
这里有几个细节特别重要：
- 必须说明输出格式为 JSON，否则它可能输出自然语言段落，需要二次解析；
- 很明确“边界框”用归一化坐标，便于直接映射到任意尺寸的原始图像;
- 要显式对待无目标输出，否则模型会强行生成一个不存在的框。
修复任务的提示词则是：
“你是一个老照片修复专家。请修复图中的划痕、折痕、污渍。面部区域要求自然，肤色过渡平滑。不得改变人物原身份特征。输出仅包含修复后的图像。”
其实只写“不得改变身份特征”没用，它感知不到身份具体特征。我习惯把参考信息也放进去，比如如果知道画面中人物的性别和年龄段，就直接写进提示词，让修复结果有更多锚点。
3.3 中间表示的价值
为什么建议用文本坐标作为中间表示？因为坐标是可解析、可验证、可规则过滤的。模型偶尔会生成“一只猫框在右上角”这种含糊坐标，你需要做一轮数值校验：坐标必须在 0-1 之间、x2 大于 x1、y2 大于 y1，类别在预置类别表内，不满足一律丢弃并重新调用一次，最多重试 3 次。
这种做法，能让整体视觉流程的可观测性大幅提升。日志里能看到每个任务的宽度和高度、每个目标类别和置信度、修复用的区域来自哪个检测框，后期做统计分析也非常方便。
4. 工程架构与调度细节
4.1 任务队列与并发策略
真实场景下，一张照片里可能要做五六处局部修复，如果每处都单独等待同步结果，总耗时高到不可接受。我建议引入一个简易任务队列，把每处修复切割为子任务，等待并发调用。这里的核心是速率限制：API 有每分钟请求数限制，以及每分钟 token 数限制。图像任务尤其消耗 token，每传一张 1080P 的图片，就可能消耗掉一小千 token。所以你必须做好并发配额管理，我的经验是，系统设定信号量，初始并发数设为 4，根据响应头里的速率限制字段动态调整，发现接近限制后排队等待，避免一次性 20 个请求全部线程阻塞。
4.2 缓存与去重设计
修复任务价格不低，本地必须有缓存层。我们依赖图片的 MD5 值加几何参数作为键，命中缓存就直接返回上次结果。这样可以避免因为用户的重复点击或者定时任务重复扫描，造成无谓的成本浪费。同时保存原始 prompt 的 hash，如果 prompt 版本升级，缓存自动失效。
4.3 视觉结果的回归测试
我发现最有价值的事，是做一个只有 30 张图的回归测试集，大约 20 张检测、10 张修复，其中 3 张 80 年代严重磨损老照片，1 张人脸侧脸遮挡失焦。每次模型参数或 prompt 有变动，先跑这个测试集，分别记录检测 mAP 与人工对比修复效果。30 张图规模不大，但足以暴露绝大多数 prompt 迁移或版本升级造成的回归问题。有这套机制之后，我在调整参数时胆子大了很多，再也不用担心上线后被反馈图像乱码。
5. 常见问题与排查技巧实录
5.1 请求返回 503 无可用账户
在服务高峰时段，请求可能返回提示表示没有可用账户。这是服务端容量控制，并非你的代码错误。最简单的策略是退避重试：先等待 2 秒重试，再 4 秒，再 8 秒，最多 5 次。实测高峰期连续重试 5 次成功率能从 60% 提升到 95%。如果你在构建自动化流水线，不妨把任务分散到早晨或下午时段运行，避开全球使用高峰期。
5.2 传入图像有时返回空白修复结果
我遇到过一次，排查很久才发现是自己传入的 PNG 图片带 Alpha 通道，模型对透明区域处理不稳定，输出全透明像素，视觉看起来像空白。解决办法是强制把输入统一为 RGB 三通道 JPEG，丢弃透明信息。
5.3 检测框整体偏移半个身位
某个检测框在画面中显示位置总偏右下。后来发现是因为上游代码用了未经 EXIF 旋转校正的 JPEG 做预处理，检测前没做自动旋转。之后我统一在预处理流水线里添加方向信息处理，先旋转到正确朝上，再缩放。坐标偏移问题消失。
5.4 坐标解析时浮点数逗号造成的崩溃
模型可能把数组输出为“0.5，0.3”，中文逗号，你用英文逗号 split 直接解析异常。建议解析前先用正则替换掉所有全角标点，再做分割。这个坑出现了好几次，后面我直接封装成标准坐标解析函数，加了异常兜底。
5.5 防止无限重试导致费用翻倍
重试机制必须设置整体预算。如果连续 3 次都检测到异常或空输出，不应该盲目换 prompt 继续调，更可能是输入图质量的问题，例如光照极低、目标过小、遮挡严重。此时更合理的做法是记录失败任务，转人工观察，或者用传统图像算法做一块预处理再走模型，而不是无限烧钱重试。
6. 我对这套方案选型的总结和感受
把检测跟修复放在同样一个 Gemini 接口体系里，最大的好处不是省了两次请求，而是开发和迭代的心智负担大幅下降。视觉任务原本依赖“模型 A 做检测，模型 B 做分割，模型 C 做修复”的复杂工具链，现在每个环节都由多模态大模型自己承担，加上文本坐标作为中间表示，日志可追踪、结果可验证、流程可复用。
目前这套工程思路在我自己的项目里运行了大约三个月，处理过千余张图，缺陷率稳定，质量可接受。成本比传统方案略高，却节省了人工选框、人工精细修复的大量劳动时间，折算是值得的。后续做多图参考融合、少样本风格迁移，仍然可以在这个框架下继续演进。
如果你正打算把视觉检测与图像修复统一到同一个大模型体系里，我的直接建议是：先拿 30 张图做小规模回归集，把 prompt 和输出格式固化下来，再加队并发优化，最后再做缓存和成本治理。框架搭好了，后面会很顺手。还有，遇到任何不稳定情况，先看输入图像，再问模型参数，最后再怀疑代码，这是我在实战里踩过很多坑换回来的经验。