多模态大模型实战：用Gemini完成目标检测与图像修复的自动化闭环

老做 CV 项目的人应该都有同感：以前要做一个“能看懂图还能改图”的自动化流程，得把目标检测、语义分割、图像修复、质量控制好几套模型串在一起，光对齐输入输出格式就够写几百行胶水代码。这两年多模态大模型把视觉理解往前推了一大步，真正常被低估的反而是“空间智能”这四个字——模型不只告诉你图里有什么，还能告诉你目标在哪个位置、哪些区域互相遮挡、哪些地方补全之后才符合物理直觉。这篇文章就把我从 Gemini 空间能力吃到红利的一套实战流程拆开讲：输入一张图，自动完成视觉对象检测，再按自然语言指令做图像修复，最后输出可以在前期方案、内容再创作、老照片老素材翻新这些场景直接用的成品。整个过程尽量做到“一键闭环”，不是 PPT 里的伪需求，是真的能跑起来的代码流程。

如果你是第一次听说 Gemini 能用来做对象检测，或者之前只在聊天框里让 Gemini 读图、没正经调过 API，这篇你按顺序看就能跟下来。我已经把遇到的坑、响应结构、JSON Schema、修复质量提升技巧都踩平了，照着抄作业是最省时间的学法。如果你本来就有用 YOLO、SAM 这类模型做视觉任务的底子，那建议重点看第三、四节：我会讲讲怎么用自然语言把“检测 + 修复”串成一条可信的自动化链路，而不是简单贴一堆官方 Demo。

1. 项目整体设计与思路拆解

1.1 我为什么放下传统视觉模型，改让 Gemini 做视觉前端

之前做视觉对象检测，大家的第一反应都是 YOLO、DETR、Grounding DINO 这一挂。这些模型定位精度确实不错，但凡是遇到两个死结就很头疼：一是只能检测你“预先喂过的类”，新增一个类目就要重新准备数据、重新训练；二是模型只输出方框和类别，完全不懂“框里的东西在其他物体后面只露出一半”“这个物体被阴影遮住了，修掉它之后背景应该是什么样”这类背景物理关系。

Gemini 这类多模态模型走的是另一条路。它最常用的入口是图生文，但往回追一步你会发现，模型在给出描述性文字时内部其实已经建立了一张空间关系图。调用接口时只要把输出格式强制成结构化 JSON，这张“空间关系图”就能被拆成坐标、置信度、遮挡状态、修理建议这些字段。对我这种不想为每个新项目维护一套训练集的人来说，Gemini 相当于把“开放词汇目标检测”和“视觉常识推理”一起打包交付了。

可能有人会问：大模型输出的坐标稳定吗？说实话，早期版本你让它返回边界框，确实偶尔会出现坐标错位、框偏移的毛病。但现在的版本配合设计良好的提示词和 JSON Schema 约束后，用在“找主体、做裁剪、生成修复蒙版”这个粒度上已经非常稳。后面第三节会专门讲坐标偏移问题怎么规避。

1.2 从“检测”到“修复”其实是同一条理解链路

传统做法里，检测和修复是两套彼此独立的流水线。检测只负责出框，修复必须另外有一个蒙版生成模型，把框转成掩码，再做 inpainting。中间任何一步发生坐标映射错误，修复结果就会糊成一团。

Gemini 真正方便的地方在于：检测后的修复意图可以直接用自然语言表达，不需要我再单独建一个图像编辑模型流程。比如检测结果里有一个人形白色塑像，区域有杂乱线缆，想让画面干净一点，检测和修复模型会统一用图像上下文展开推理。也就是说，模型如果“看懂了”前景和背景的遮挡边界，那它修复时补出来的内容就大概率符合常理，不会只拿纯色或纹理去硬填。

这就是我把项目设计成“检测到修复一条提示词链路”的核心原因。先让 Gemini 给出四个信息：目标框、标签、可见度判断、修复建议。再把其中的“修复建议”作为图像编辑阶段的指令传入。这种两段式设计最大的优点是可回溯、可干预。如果模型修复出来的效果不对，我可以随时回看检测阶段的判断，而不是对着一个黑盒流程干瞪眼。

1.3 用“质控循环”逼近好莱坞级修复效果

说句实在话，“好莱坞级”这个目标不是靠某个模型一键点出来的，而是靠一个质量闭环迭代出来的。所谓电影工业级的老片修复或者画面重绘，核心流程从来都是：先分析画面损伤、生成修复意图、局部合成、对比前后结果、不满意再重来。Gemini 能替代的是第一、二步里的语义理解，以及最后一步的“看一眼结果是否有破绽”。

所以我的架构里没有省掉质控模块。每次完成局部修复后，把修复区域抠出来送回给 Gemini，让它从光照一致性、边缘过渡、纹理连续性和物理合理性四个维度打分，低于预期的自动触发重跑。这样整套系统的成功率不是靠单次调参赌运气，而是靠循环次数堆上来的。对内容修复、电商场景去杂物、老照片补全这种“要求高但容错也够跑两三轮”的任务来说，这是性价比非常高的方案。

2. 环境准备与关键选型

2.1 账号分级、API Key 与可用性排查

实战之前先把环境准备好。目前 Gemini 能力分成 Web 端体验和 API 两条路线，两者不建议混淆。做自动化项目肯定走 API，你需要做的是：

1. 注册一个可用的 Google 账号，完成开发者后台的项目创建。
2. 在 AI Studio 或 Vertex AI 里创建 API Key。免费额度适合调试，一旦要跑批量任务建议绑定正式计费项目，因为额度限制、并发上限都宽裕很多，响应也更稳定。
3. 在本地环境安装官方 Python SDK，或者直接用 requests 调 HTTP 接口。
4. 设置环境变量 GEMINI_API_KEY，不要把密钥硬编码在代码里。

我见过很多人在 Chrome 扩展或 Web 端遇到“Gemini 暂不可用”的提示，就以为是 API 不能用了，其实这是渠道差异化的问题。Web 端的功能是分批放量的，浏览器版本、账号所属区域、功能灰度开关都会影响可见性。API 通道则相对独立，只要项目开通、Key 有效，一般不会跟着 Web 端一起抽风。

另外有个细节需要注意：有些网络教程喜欢让你只依赖免费账号去刷并发请求。实际跑下来你会发现，免费层的账号并发限制非常小，一旦短时间请求频率上去，服务端很容易返回类似“no available accounts”的错误。我建议，如果你要做的是自动化脚本而不是聊天式 Demo，直接跳到有正式项目资源的 API Key，或者走云厂商托管的 Vertex AI 入口，这样能规避很多“账号级限流”引发的诡异报错。关于报错的排查细节，我在第五节统一列了个表格。

2.2 Python 环境和必要依赖

这个项目用到的东西不复杂，核心是 OpenAI 风格的调用方式，再配合 Python 的 Pillow 做图像处理。下面是我本地环境的初始化命令，Python 版本建议 3.10 以上。

bash复制# 创建虚拟环境
python -m venv gemini-vision-env
source gemini-vision-env/bin/activate   # Windows 下用 .\gemini-vision-env\Scripts\activate

# 安装依赖
pip install google-genai pillow requests python-dotenv

# 如果你希望修复阶段接开源 Stable Diffusion 系模型，再装下面这个
pip install diffusers transformers accelerate opencv-python

google-genai 是官方统一的 SDK 包，现在最新版已经可以同时处理文本生成、图像理解和图像生成，不用再像以前那样引入好几个不同版本的包。Pillow 用来读取图片、换算坐标、画框和生成蒙版。python-dotenv 单纯是为了方便读取 .env 里的密钥。

很多教程到这里会额外装一大堆深度学习库，但如果你只想在目标检测和修复环节用 Gemini，没必要把本地环境搞得那么重。我的建议是轻装上阵，跑通之后再按需加。

2.3 图像修复数据集能帮上什么忙

做图像修复的朋友大概率会在搜索时碰到“图像修复数据集”这个词。如果你不是要自己从零训练一个 inpainting 模型，那数据集的主要作用是做效果评估和 prompt 压测。平时可以准备 10 到 30 张覆盖不同场景的测试图，比如室内杂乱背景、老照片划痕、街道上的行人、户外线缆和天空交接区域，用来统一评估每次检测和修复的效果。

公开数据集里比较常见的有用于语义修复评估的 Places2，以及 COCO 里带物体实例标注的子集。你可以从这些数据集里抽图片，人为叠加一些遮挡物或随机蒙版，建立一个自己的“验收集”。我自己的项目里专门有个 assets/eval_set 目录，每次换模型版本或改提示词，都会拿同一批测试图跑一遍，这样哪个改动有效、哪个改动是负优化，一眼就能比较出来。

3. 视觉对象检测结构化的完整实现

3.1 用 JSON Schema 把空间智能“掰开揉碎”

要让 Gemini 输出坐标而不是散文，最关键的一步是给它一个严格的结构约束。现在的 Gemini API 支持响应 JSON Schema 强制输出，比从前靠提示词里说“请以 JSON 返回”要可靠得多。下面是我实际在用的 Schema 简化版：

python复制detect_schema = {
    "type": "object",
    "properties": {
        "objects": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "label": {
                        "type": "string",
                        "description": "目标类别，英文或中文"
                    },
                    "bbox": {
                        "type": "object",
                        "properties": {
                            "x_min": {"type": "number"},
                            "y_min": {"type": "number"},
                            "x_max": {"type": "number"},
                            "y_max": {"type": "number"}
                        },
                        "required": ["x_min", "y_min", "x_max", "y_max"]
                    },
                    "visibility": {
                        "type": "string",
                        "enum": ["visible", "partially_occluded", "heavily_occluded"]
                    },
                    "repair_reason": {
                        "type": "string",
                        "description": "如果要从画面中移除该物体，说明修复背景时需要注意什么"
                    }
                },
                "required": ["label", "bbox", "visibility"]
            }
        },
        "scene_type": {
            "type": "string",
            "description": "整体场景类型：室内/室外/人像/风景"
        }
    },
    "required": ["objects", "scene_type"]
}

这里有一个设计心得：Schema 里除了坐标，我还会强制要求 visibility 字段。这个字段直接影响后面的修复策略。如果模型判断目标“partially_occluded”，修复时就要额外关注遮挡边界的重建；如果目标完全可见，那移除它之后多数情况只需要做背景填充。把这种判断前置到检测阶段，后面接一个模板化的修复流程就会省很多事。

3.2 请求封装和响应解析范例

接下来是发送请求的代码。这里用官方 google-genai SDK：

python复制import os
import json
from dotenv import load_dotenv
from google import genai
from google.genai import types
from PIL import Image

load_dotenv()
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

def detect_objects(image_path: str):
    with open(image_path, "rb") as f:
        image_bytes = f.read()

    response = client.models.generate_content(
        model="gemini-2.5-flash",   # 根据自己账号可用模型名调整
        contents=types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg"),
        config=types.GenerateContentConfig(
            response_mime_type="application/json",
            response_schema=detect_schema,
            system_instruction=(
                "You are a precise visual perception engine. "
                "Detect all foreground objects and return structured info. "
                "If an object should be removed during image restoration, "
                "explain the background reconstruction requirement."
            ),
            temperature=0.1
        )
    )

    result = json.loads(response.text)
    return result

这里有几个细节很容易踩坑：

1. mime_type 要和传入的图片格式保持一致。JPEG 和 PNG 都还好，如果是 WebP 或者 HEIC，最好用 Pillow 先转一下通用格式，否则某些后端可能在预处理阶段报错。
2. temperature 建议调低。目标检测是感知任务，不是创意写作，过高的随机性会导致同一张图两次检测结果不一致，这对自动化流程是致命的。
3. 有些版本 SDK 的 generate_content 返回对象里 text 可能为空，但 response.text 已经是字符串。解析前最好对 response.text 做一次 strips，再用 json.loads。如果返回内容开头被模型加了一点解释性文本，json.loads 会立刻崩，这时你需要一个从文本中提取 JSON 子串的容错函数，后面第五节我会给出通用解法。

3.3 坐标归一化换算与可视化画框

Gemini API 返回的 bbox 坐标默认是像素值还是归一化值，取决于输入图像和调用方式。实践下来，当你直接传入原始图片字节时，绝大多数情况模型会按像素坐标输出，但偶尔也会抽风给出 0 到 1000 之间的千分制坐标。所以收到结果后我一般不做假设，而是先获取图片真实宽高，然后检查坐标范围做一次标准化换算。

python复制def normalize_bbox(bbox, image_width, image_height):
    x_min_raw = float(bbox["x_min"])
    y_min_raw = float(bbox["y_min"])
    x_max_raw = float(bbox["x_max"])
    y_max_raw = float(bbox["y_max"])

    # 如果最大值小于等于1，或范围近似在0~1000之间，当作归一化坐标处理
    if x_max_raw <= 1.0 or x_max_raw <= 1000.0:
        x_min = x_min_raw / 1000.0 * image_width if x_max_raw <= 1000.0 and x_min_raw > 1.0 else x_min_raw * image_width
        y_min = y_min_raw / 1000.0 * image_height if y_max_raw <= 1000.0 and y_min_raw > 1.0 else y_min_raw * image_height
        x_max = x_max_raw / 1000.0 * image_width if x_max_raw <= 1000.0 and x_min_raw > 1.0 else x_max_raw * image_width
        y_max = y_max_raw / 1000.0 * image_height if y_max_raw <= 1000.0 and y_min_raw > 1.0 else y_max_raw * image_height
    else:
        x_min, y_min, x_max, y_max = x_min_raw, y_min_raw, x_max_raw, y_max_raw

    return int(round(x_min)), int(round(y_min)), int(round(x_max)), int(round(y_max))

这段代码写得稍微“防御性”强了一点，因为自动化管道里最怕的就是脏数据。实际跑的时候，你可以先打印一次结果，确认坐标范围到底落在哪边，再把分支补得更准。可视化画框可以简单用 Pillow 的 ImageDraw：

python复制from PIL import ImageDraw

def draw_boxes(image_path, objects, output_path="annotated.jpg"):
    img = Image.open(image_path).convert("RGB")
    draw = ImageDraw.Draw(img)
    width, height = img.size

    for obj in objects:
        x_min, y_min, x_max, y_max = normalize_bbox(obj["bbox"], width, height)
        label = obj.get("label", "object")
        color = "#FF3B30"
        draw.rectangle([x_min, y_min, x_max, y_max], outline=color, width=4)
        draw.text((x_min, max(0, y_min - 20)), label, fill=color)

    img.save(output_path, quality=92)
    print(f"Annontated image saved to {output_path}")

把检测结果可视化出来非常重要，尤其是刚开始调试验证阶段。脚本跑完我一般会直接打开标注图检查：框有没有偏移，目标有没有漏检，类别对不对。别急着进入修复环节，先把检测这层的准确率看到 90% 以上，后面修复质量才有保证。

3.4 为什么需要做“空间常识校验”

Gemini 的检测输出虽然已经比纯文本模型稳了很多，但偶尔会有“反常识”的框，比如人物框跑到天空上，或者缩成一个比蚂蚁还小的小方块。这类错误在传统视觉模型里也很常见，通常靠 NMS 和后处理过滤，我这里则加了一个空间常识校验函数。

规则很简单：

1. 框的宽度或高度小于图片长边的 1% 时，忽略。
2. 两个框如果高度重合且中心点距离相近，只保留置信度高的那一个。
3. 如果某个 label 明显不属于模型默认识别的语义范围，比如在室内场景里识别出“大象”，就标记为待人工复核。

这套规则不能替代精细的算法，但对自动化流程的稳定性提升非常明显。你宁可少检出一个边角目标，也不要因为一个错框把整张图的修复区域带偏。

4. 修复闭环：从目标掩码到好莱坞级画面合成

4.1 选择合适的图像修复后端

修复阶段这里要说明一点：Gemini 作为多模态模型，可以直接编辑图片，但我测试下来，文本生成模型接口并不是所有场景下都适合做像素级局部修复。要实现真正的“好莱坞级修复”，现实的做法是让 Gemini 继续当“空间大脑”，负责生成掩码区域和修复指令，把真正逐像素的修复工作交给专门的图像生成或修复后端。你可以根据自己对整套技术栈的熟悉程度选一条路线：

我目前的项目采用“混合 ARM”策略：默认先走开源 Stable Diffusion Inpainting 路线，因为这个方案可控性最好，蒙版精准、成本低；遇到语义特别复杂的场景，比如要补全大面积被遮挡的人脸或极其复杂的透视背景，再切换到 Gemini 原生编辑接口。

这里尤其不推荐直接用传统 OpenCV 修复算法处理大目标移除，效果一定是灾难性的。它根本不知道被移除物体背后的语义内容是什么，只会从周边纹理硬拗，结果就是一大片模糊色块。相信我，别省这个步骤。

4.2 检测到修复的自动化管线和蒙版生成

假设我们要实现的需求是：检测到画面里所有行人或干扰物，并自动从背景中抹掉它们。下一步就是把目标框展开成修复蒙版。

理想情况当然是用 SAM 一类的分割模型把前景目标抠出来，按分割蒙版做修复，边缘最自然。但这是一个“一键”项目，塞进 SAM 会增加部署成本。聪明的折中方案是：把检测框做向内收缩和膨胀后再作为修复蒙版。向内收缩能保护目标边缘不被误伤，膨胀则是为了让修复算法有更充裕的背景上下文来推测被遮挡的部分。

python复制import cv2
import numpy as np
from PIL import Image

def bboxes_to_mask(image, boxes, padding=30, shrink=5):
    h, w = image.shape[:2]
    mask = np.zeros((h, w), dtype=np.uint8)

    for (x_min, y_min, x_max, y_max) in boxes:
        # 向内收缩几个像素，减少边缘伪影
        x_min_s = max(0, x_min + shrink)
        y_min_s = max(0, y_min + shrink)
        x_max_s = min(w, x_max - shrink)
        y_max_s = min(h, y_max - shrink)

        # 再向外扩一部分，让修复模型有足够的上下文
        x_min_e = max(0, x_min_s - padding)
        y_min_e = max(0, y_min_s - padding)
        x_max_e = min(w, x_max_s + padding)
        y_max_e = min(h, y_max_s + padding)

        mask[y_min_e:y_max_e, x_min_e:x_max_e] = 255

    # 高斯模糊蒙版边缘，避免修复边界过于生硬
    mask = cv2.GaussianBlur(mask, (15, 15), 0)
    return mask

为什么蒙版边缘要加高斯模糊？因为扩散模型在处理硬边缘蒙版时，经常会出现一圈明显的接缝。模糊后的蒙版让模型在过渡区域有渐变权重，最终合成的结果会自然很多。这种细节就是“好莱坞级”和“玩具级”的分水岭。

4.3 用提示词工程控制修复目标和质量

拿到蒙版后，OpenCV 或 SD Inpainting 还需要一个文本提示词来描述修复目标。这里 Gemini 已经在检测阶段生成了 repair_reason，我们不需要从零写 Prompt，直接把它拼进去就行。以下是一个调用 Stable Diffusion Inpainting 管线的最小示例：

python复制import torch
from diffusers import StableDiffusionInpaintPipeline

model_id = "runwayml/stable-diffusion-inpainting"   # 使用合规的开源权重
inpaint_pipe = StableDiffusionInpaintPipeline.from_pretrained(
    model_id,
    torch_dtype=torch.float16,
)
inpaint_pipe = inpaint_pipe.to("cuda")

def run_inpaint(init_image, mask_image, repair_reason):
    # 提示词里既要有移除指令，也要有背景描述
    prompt = (
        f"Remove the marked object completely, reconstruct the natural background. "
        f"Notes: {repair_reason}. "
        "High resolution, realistic texture, consistent lighting, no watermark."
    )
    negative_prompt = (
        "blurry, distorted, duplicated object, uneven lighting, "
        "oversaturated, watermark, text, bad edge"
    )

    result = inpaint_pipe(
        prompt=prompt,
        negative_prompt=negative_prompt,
        image=init_image,
        mask_image=mask_image,
        height=init_image.height,
        width=init_image.width,
        num_inference_steps=40,
        strength=0.9,
    ).images[0]

    return result

有几个参数可以直接影响修复质量，不是随便跑通就完事：

1. num_inference_steps 步数太低会显得粗糙，太高又浪费时间。40 步是我试下来质量稳定性和耗时的甜点，如果你对画面质量不满意可以往上加到 50 步。
2. strength 控制在 0.85 到 0.95 之间。这个值的意思是“对原图的改造强度”，修复场景太低的话旧物体残影消除不掉，太高则会让没有蒙版的区域也被重绘。
3. negative_prompt 必须写“watermark, text, blurry”这类负面约束。不做这一步，画面边缘很容易出现莫名其妙的水印感和文字伪影，尤其是跑全图编辑时。

4.4 Gemini 二次质检：从“修完”到“修好”

前面这套流程能保证“修完”，但离“修好”还差一个质检员。修复最怕的是骗过了人眼没骗过细节，比如地面阴影方向错了、物体接缝处有一缕诡异颜色、背景结构扭曲了。人工逐张检查当然可靠，但不是“一键”该有的样子。

因此我在最后加了一个 Gemini 视觉质检环节，把修复后的图与原图一起发过去，要求它从局部到整体逐项打分：

python复制def quality_check(original_path, repaired_path, repair_desc):
    with open(original_path, "rb") as f1:
        original_bytes = f1.read()
    with open(repaired_path, "rb") as f2:
        repaired_bytes = f2.read()

    prompt = (
        "You are an expert image quality inspector. "
        f"Task: {repair_desc}. "
        "Compare the original and repaired images. Score each item 1-10: "
        "edge_transition, lighting_consistency, texture_continuity, physical_plausibility. "
        "If any score below 6, suggest concrete rework instructions. Return JSON."
    )

    resp = client.models.generate_content(
        model="gemini-2.5-flash",
        contents=[
            types.Part.from_bytes(data=original_bytes, mime_type="image/png"),
            types.Part.from_bytes(data=repaired_bytes, mime_type="image/png"),
            prompt,
        ],
        config=types.GenerateContentConfig(
            response_mime_type="application/json",
            temperature=0.2,
        )
    )

    return json.loads(resp.text)

质检结果里有 suggestion 的话，我会把建议重新拼成修复提示词，再用新的蒙版跑一轮。这个自动重试循环我最多跑三次，第三次如果还是低分，就把它放进人工复核队列。这是我自己总结出来的经验：不要无限循环，大部分问题第三次重跑也修不好，反而陷入了浪费算力的死循环。

4.5 细节把控：采样次数、局部裁剪和光照匹配

再往深了说，“好莱坞级”往往不是一次 inpaint 就能完成的，要把修复效果拉高，我有三个进阶技巧：

1. 分块局部处理。如果目标区域很大，不要一次性丢给低分辨率模型去跑。先用检测框裁剪出局部区域，把这块局部放大后再跑 inpainting，最后再把修复好的局部贴回原图。这比直接全图 inpainting 多保留很多纹理细节，成本增加不多，效果立竿见影。
2. 多次采样后自动选优。Stable Diffusion 在固定 seed 下的效果不稳定，我会跑 3 到 4 个不同随机种子，然后让 Gemini 从结果里挑一张结构最自然、边缘过渡最好的。这个做法看起来费时，实际成功率提升明显。
3. 后处理叠加原图纹理。如果只是在图上移除一个小物体，没有大背景透视变化，我会把修复区域单独抠出来，用透明度和羽化蒙版叠加回原图。这样既确保边界无缝，又保住了原图大量未被修改区域的原始纹理。原理就类似于修图软件里的“局部修复图层”，只是把过程自动化了。

5. 常见问题与排查技巧实录

5.1 典型报错速查表

自动化项目跑得多了必然会和各种状态码打交道。我把实验和落地中最常遇到的几类问题整理成了下面这张速查表，尤其是你标题里带着的那几个高频错误，基本都能在这里找到对应处理办法。

这里专门强调一句：遇到 503 和账号相关错误时，第一反应不要是“服务挂了”，而要先想清楚自己用的是免费 Web 还是正式 API。两套通道的基础设施和配额策略差别很大，混为一谈会误导排查方向。

5.2 JSON 容错解析的通用函数

响应解析是这类项目里最容易被忽略、但最实用的一个点。我把自己常用的容错解析函数贴出来，你直接拿去用就行：

python复制import re
import json

def robust_json_parse(text: str):
    text = text.strip()

    # 直接解析尝试
    try:
        return json.loads(text)
    except json.JSONDecodeError:
        pass

    # 去掉可能存在的 markdown 代码块标记
    text = re.sub(r"^```(?:json)?|```$", "", text.strip(), flags=re.MULTILINE).strip()

    # 提取最外层 JSON 对象
    start_idx = text.find("{")
    end_idx = text.rfind("}")
    if start_idx == -1 or end_idx == -1 or end_idx < start_idx:
        raise ValueError(f"Cannot extract JSON from response: {text[:200]}")

    try:
        return json.loads(text[start_idx:end_idx + 1])
    except json.JSONDecodeError as e:
        raise ValueError(f"JSON decode failed: {e}") from e

这个函数看起来很基础，但在生产环境里救过我很多次。模型即使在被要求“只返回 JSON”的时候，偶尔也会在首尾多输出空格、反引号甚至一两句总结。没有这层容错，流水线会在半夜跑到一半直接崩掉。

5.3 输入图像过大和内存溢出的处理

目标检测和图像修复的另一个高发问题就是图片尺寸。很多人第一版直接拿 4000×3000 的超清原图去交给 Gemini 和 Diffusion 模型，结果不是 API 报请求体过大，就是本地显存直接爆掉。实际上你并不需要一开始就让模型看全分辨率原图：目标检测阶段把长边压缩到 2048 像素就足够让模型判断物体位置；修复阶段如果不是精细到毛孔级别，1024 到 1536 的工作分辨率也够用。

需要修正的是，输出时你要把修复结果重新映射到原图分辨率，而不是用修复模型直接生成的缩略图当交付物。那就需要在全分辨率原图上重新应用变换或拼接。换句话说，输入“低分辨率打草稿”，输出“高分辨率拼精稿”。这是我做影像修复项目最重要的心得之一。

5.4 关于账号体系与学生认证的提醒

不少初学者会搜“gemini 学生认证”，以为用教育邮箱就能解锁所有能力。实际看下来，教育或学生认证跟普通账号的核心差别主要在于部分云项目的免费额度和功能试用资格，并不是说你拿学生账号就能绕过区域的可用性或者拿到完全不一样的模型权限。如果你所在学校有官方教育合作计划，那么通过正规渠道申请是没问题的；但如果只是听说可以“白嫖”高级能力而去随意填假资料，我劝你别这么做，因为自动化项目跑到一半被封号，代价比买几次 API 调用高得多。

5.5 记忆、缓存与 API 成本管理

这个项目跑久了你会突然发现，最大开销不是推理时间，而是重复调用同一张图。我见过有人调试一段 prompt，同一个固定图反复上传了十几遍，既费 token 又费时间。建议在脚本入口加一层文件级别的缓存：把图片路径、提示词、模型版本号拼接成哈希，如果哈希相同且缓存文件存在，就直接读取之前的结果，跳过 API 调用。

python复制import hashlib
import os
import json

def cached_request(image_path, prompt, cache_dir=".cache"):
    signature = hashlib.md5(
        f"{image_path}:{prompt}:{model_name}".encode()
    ).hexdigest()

    os.makedirs(cache_dir, exist_ok=True)
    cache_file = os.path.join(cache_dir, f"{signature}.json")

    if os.path.exists(cache_file):
        with open(cache_file, "r", encoding="utf-8") as f:
            return json.load(f)

    response_data = perform_actual_request(image_path, prompt)

    with open(cache_file, "w", encoding="utf-8") as f:
        json.dump(response_data, f, ensure_ascii=False, indent=2)

    return response_data

这个缓存机制对反复调参特别友好。只有当你修改了检测提示词或修复 prompt 时，哈希变化才会重新调 API。日常微调代码逻辑、调整可视化参数时，基本不会多花一分钱。

6. 实战心得与后续扩展

6.1 实测下来最有用的三句话

第一句：不要把 Gemini 当成一个“检测模型”，把它当成一个“懂空间的编辑助理”。你在 Prompt 里给的信息越结构化，它的表现越稳定。给它一份严格的 JSON Schema、给它几行明确的空间判断规则，比让它“自由发挥”得到的 bbox 可靠得多。

第二句：检测和修复不能各做各的。空间智能真正的价值在“看懂前后关系”之后的连贯执行。我在这套项目里受益最大的改动，就是把检测阶段的 vision/visibility 判断和修复阶段的提示词打通了。以前两个模型各做各的，经常出现修复后的背景跟前景光照方向冲突；现在让检测模型在输出框的同时说明“这里应该补出什么背景”，修复的准确率呈指数级上升。

第三句：好莱坞级效果是“修完再检，检完再修”修出来的。重复的 loop 不是浪费，而是质量兜底。说白了，人和专业修图师的区别不在于一笔画得多准，而在于他会退远几步看整体协调性。Gemini 质检就是那个退远几步看得人。

6.2 可以继续扩展的方向

这套流程在我这边已经不只是玩票，实际被用在电商场景的杂物移除、老照片修复和图文素材二次创作上。再往后做，有三个方向我觉得特别有意思：

1. 接入视频帧序列检测与修复，利用时间维度的空间一致性处理视频里的闪烁物体移除。Gemini 的空间理解结合追踪算法，有机会做出一条比一帧一帧硬修稳定得多的视频管道。
2. 把目标检测结果直接转成可编辑的图层操作指令，输出到 Photoshop 或开源图像编辑器的 Script，让人工精修前先有一版自动整理好的分层文件。
3. 针对业务数据的专项评测集自动生成，把每次检测到修复的质量分数沉淀成结构化数据，帮助团队更科学地选模型、调参数。

6.3 最后再分享一个小技巧

如果你的修复结果偶尔会出现边缘发灰或色调偏冷，别急着调 Prompt，先检查一下图像在 RGB 和 BGR 通道之间是否被搞混了。用 OpenCV 读图再交给 Pillow 处理时，通道顺序不一样是彩色修复里最常见也最隐蔽的 bug。很多“模型效果不行”的结论，最后查下来只是颜色通道没对齐。

这个项目的初衷就是别让技术细节毁掉创意表达。Gemini 空间智能把“看见”和“理解”之间的距离拉近了一大截，我们要做的就是把手头的图像工程基础设施接好，让模型在正确的轨道上自由发挥。希望这篇实战记录能帮你少走几步弯路，快速落地属于自己的视觉检测与图像修复闭环。