用Gemini实现空间智能与图像修复：从目标检测到半自动管线实战

前段时间我把家里一批老照片做数字化，扫描件发黄、带划痕，人脸糊得只剩轮廓。一开始想靠修图软件一张张慢慢磨，后来发现一套完全不同的思路：让 Gemini 这种多模态模型同时干两件事——先把画面里的目标对象精准定位出来，再根据缺陷生成修复指令完成重绘。整个过程能做成半自动化管道，输入一张图，输出检测结果加修复成图。

这篇文章就是把这套“空间智能 + 视觉对象检测 + 图像修复”的完整链路拆开讲透。我不只给能跑的代码，还会把接入 API 时报错、提示词写不好、坐标偏移、修复出来脸变形这些坑都摆出来，说说我自己是怎么定位和解决的。适合做图像批处理脚本、内容自动化管线，或者单纯想用 Gemini 玩视觉任务的朋友参考。

1. 空间智能到底是什么：先搞懂 Gemini 能“看”到什么程度

1.1 识别、定位和空间推理是三件不同的事

很多刚接触视觉大模型的人有个误解：模型能识别出图片里有一只猫，就意味着它知道猫在哪儿。实际上“认识猫”“框出猫”“理解猫和沙发的空间关系”是三个层次完全不同的任务。

传统目标检测模型解决的是“定位”：YOLO、Grounding DINO，它们输出的是框、类别和置信度。识别和定位确实强，但只停留在“有什么、在哪个位置”。Gemini 这类多模态大模型则是先理解整张图的语义，再在这个语义基础上做推理。它能判断“人物左后方的行李箱”，能描述“画面中央偏右位置有一辆红色轿车，车尾被电线杆遮挡了近四分之一”，这种描述背后是空间关系的整体建模，不是单纯的滑窗扫描。

这个区别决定了你该怎么用 Gemini。如果你的任务是从十万张监控截图里找特定车牌，好好用专用检测模型，别用大模型硬扛。但如果你面对的是开放场景、类别不固定、还希望模型同时输出语义描述和结构化坐标，Gemini 就是更顺手的选择。

1.2 Gemini 在空间推理上哪些地方是真正能打的

我实测下来，Gemini 的空间能力有几个比较能打的方向：

第一，开放词汇检测。你不需要提前定义好所有类别。对模型说“把画面里所有能移动的东西标出来”，它会把人物、车辆、动物、无人机甚至被风吹动的帆都找出来。传统模型这时已经懵了，因为“能移动的东西”不是一个固定类别集合。

第二，相对位置描述能力强。Gemini 对“左上角”“居中偏右”“紧挨着”这类自然语言空间表达，能直接映射到坐标。这意味着你可以用自然语言做坐标级交互，比如“框出右上角那个红色的消防栓”。

第三，图像上下文理解对后续生成有用。这一点是检测和修复能串成一条链路的关键：Gemini 检测出人脸位置之后，同一套模型还能继续分析“这个区域有划痕、噪点、曝光不均”。

1.3 知道边界在哪，才不会瞎踩坑

大模型的空间智能有一个致命弱点：没有严格的几何一致性。同一个物体，你换几个 prompt 让它输出坐标，框的位置可能有 3% 到 10% 的浮动。对精细标注来说这不可接受，但对筛选、批次管理、后续修复的粗定位完全够用。

另一个坑是“小目标漏检”。画面里巴掌大的人脸能稳定检出，但一个 30 像素宽的路标就经常被忽略。遇到这类场景，我的经验是把图像切成几块分别检测，再合回原图坐标。切块检测还能顺带提升小目标的召回率，代价是请求次数增加、耗时变长。要不要切、切成几块，看你对召回的敏感度来定。

还有一个必须接受的现实：模型会一本正经地“脑补”不存在的物体。尤其是画质差、遮挡严重的图片，VLM 很容易把噪声纹理误判成物体轮廓。这个只能靠后处理设置置信度阈值、做多轮验证来控制，别指望一次到位。

2. 接入环境就劝退一半人：API 配置和账户异常排查实录

2.1 一次跑通的最小环境配置

先说最基础的环境准备。你需要一个 Google AI Studio 或 Vertex AI 的项目密钥，然后在本地装 SDK。

bash复制pip install google-generativeai python-dotenv pillow

Python 环境建议直接用 3.10 以上版本，太老的版本对 SDK 的 type hint 兼容性不好。密钥用环境变量管理，别写死在代码里：

python复制import os
from dotenv import load_dotenv
import google.generativeai as genai

load_dotenv()
genai.configure(api_key=os.getenv("GEMINI_API_KEY"))

能跑通之后，你会面对真正麻烦的事情：各种让人摸不着头脑的报错。我把自己实际遇到过的高频报错都整理了出来，排查思路直接抄就行。

2.2 高频报错排查表

2.3 “no available accounts”这个报错一定要平心静气

我第一次遇到 status_code=503 时第一反应是代码写错了，后来发现完全不是那么回事。这个报错的关键词是“no available gemini accounts”，意思是后端没有空闲的账户可以处理你的请求。它不是说你密钥错了，也不是说你的代码崩了，就是服务端暂时忙不过来。

应对策略只有一个字：等。但等也要有章法。用指数退避加重试抖动，比硬等效果好得多。退避公式是：

code复制等待时间 = min(基础等待时间 * 2 ^ 尝试次数, 最大等待时间) + 随机抖动

基础等待设 1 到 2 秒，最大等 30 到 60 秒，抖动不要超过 500 毫秒。随手写了个函数，这个在批量跑几千张图时省心很多：

python复制import time
import random

def retry_with_backoff(func, max_retries=5):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if attempt == max_retries - 1:
                raise e
            wait_time = min(2 ** attempt, 30) + random.uniform(0, 0.5)
            time.sleep(wait_time)

2.4 VSCode 接 Gemini Code Assist 的特例

如果你是在 VSCode 里用 Gemini Code Assist，登录失败一般和前面说的“client no longer supported”是同源问题。Code Assist 插件有自己独立的认证通道，更新插件往往就能解决。有些版本还支持填 API key 的方式接入，路径在设置里搜 gemini.codeAssist.apiKey。不过这种方式能用但有限制，不建议在需要高频图像请求的场景依赖编辑器插件，它本质上还是为代码补全设计的，直接写脚本调 SDK 才是正确姿势。

3. 把对象检测跑通：提示词工程与结构化 JSON 输出

3.1 让模型稳定输出 JSON 的三个关键动作

VLM 输出坐标不难，难的是稳定。所谓稳定，是指十次请求里九次返回结构一致、数值合理的结果。我总结下来三个关键动作缺一不可。

第一个动作：把 response_mime_type 设为 application/json。这能让模型从解码层面就用 JSON 格式生成，比在提示词里反复强调“你要输出JSON”有效得多。

第二个动作：提供明确的响应 Schema。光说“输出JSON”不够，你要告诉模型 JSON 里有哪些字段、字段类型是什么、坐标取值区间是什么。

第三个动作：把温度调到 0.1 以下。温度越高，模型输出的随机性越强，坐标抖动越明显。做检测任务时我基本固定用 temperature=0.1 或更低。

来看一段完整的检测代码：

python复制from PIL import Image
import google.generativeai as genai

model = genai.GenerativeModel(
    "gemini-1.5-pro",
    system_instruction=(
        "你是一个专业的视觉对象检测引擎。"
        "你只输出 JSON，不要输出任何其他文字。"
    ),
    generation_config=genai.types.GenerationConfig(
        temperature=0.1,
        top_p=0.95,
        response_mime_type="application/json",
        response_schema={
            "type": "object",
            "properties": {
                "detections": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "label": {"type": "string"},
                            "bbox": {
                                "type": "array",
                                "items": {"type": "number"},
                                "minItems": 4,
                                "maxItems": 4
                            },
                            "confidence": {"type": "number"}
                        }
                    }
                }
            }
        }
    )
)

def detect(image_path: str, object_types: list[str]) -> dict:
    img = Image.open(image_path)
    prompt = f"""
    请识别图片中所有属于这些类别的对象：{', '.join(object_types)}。

    坐标系统要求：
    - 使用 0-1000 的相对坐标系，左上角为原点 (0, 0)
    - 右下角为 (1000, 1000)
    - bbox 格式为 [x1, y1, x2, y2]
    - x1, y1 是左上角坐标，x2, y2 是右下角坐标

    置信度要求：
    - confidence 为 0 到 1 之间的浮点数
    - 只有置信度大于 0.5 的检测结果才输出

    如果画面中没有检测到任何对象，返回 {{"detections": []}}，不要编造。
    """
    response = model.generate_content([prompt, img])
    return response.text

3.2 提示词里最容易忽略的细节

你会发现我在提示词里写了“如果画面中没有检测到任何对象，返回空数组，不要编造”。这句话不是废话。模型面对低质量图片时，默认倾向是“努力找出点什么”，哪怕根本没有。你不拦它，它就会把噪声纹理、阴影都当成对象框给你。明确允许它输出空结果，能显著降低幻觉率。

坐标范围用 0-1000 而不是 0-1，也是摸出来的经验。告诉模型“0-1000 相对坐标”，它会输出类似 [215, 340, 580, 720] 这样比较“顺眼”的整数；用 0-1 时模型经常输出 [0.214, 0.339, 0.581, 0.721] 这种接近无理数的长小数，容易出现精度幻觉。本质区别不大，但 0-1000 的表达更贴合人类习惯，模型执行起来更稳。

类别清单也要写清楚。不要只给一个大概范围，把可能出现的变体写全。比如你要检测车辆，写成“car, truck, bus, motorcycle, bicycle”比只写“vehicle”效果好得多。这背后的逻辑是，模型对具体名词的视觉特征记忆更清晰，而对抽象集合名词需要先在内部做一层语义扩展，容易漏。

3.3 解析响应时要做好防御式编程

模型偶尔会返回解析不了的内容，比如 JSON 里混了注释，或者坐标值超出 0-1000 范围，或者 x2 小于 x1。我在解析层做了三层防御：

python复制import json

def parse_detection_response(raw_text: str) -> list[dict]:
    try:
        data = json.loads(raw_text)
        detections = data.get("detections", [])
    except json.JSONDecodeError:
        # 尝试提取 JSON 片段
        start = raw_text.find("{")
        end = raw_text.rfind("}") + 1
        if start == -1 or end == 0:
            return []
        try:
            data = json.loads(raw_text[start:end])
            detections = data.get("detections", [])
        except json.JSONDecodeError:
            return []
    return detections

第一层直接解析，失败后第二层提取首尾的大括号再解析，如果还失败就直接返回空列表而不是让整个脚本崩溃。防御式编程看上去有点丑，但在脚本需要连续跑几千张图的时候，它比一次性闪退然后人工介入实在得多。

4. 后处理决定成败：坐标映射、去重和批量任务管线的设计

4.1 相对坐标到像素坐标的映射

Gemini 输出的坐标是 0-1000 相对坐标系，实际使用时要映射到图片真实像素。这一步看起来简单，但好多人在批量处理时因为忘了做就画错框。

python复制def bbox_to_pixels(bbox, img_width, img_height):
    x1, y1, x2, y2 = bbox
    px1 = x1 / 1000 * img_width
    py1 = y1 / 1000 * img_height
    px2 = x2 / 1000 * img_width
    py2 = y2 / 1000 * img_height
    return px1, py1, px2, py2

映射完之后顺手做一次坐标合法性校验，如果 px2 <= px1 或 py2 <= py1，这条检测结果基本就是模型抽风了，直接丢弃。

4.2 用 IoU 去重，别让重复框浪费算力

视觉大模型在一张图里对同一个对象会出现重复框。比如一幅画里有个人物侧面，模型可能同时给出两个高度重叠的框，一个标注“人物”，另一个标注“face”。如果你只是画个框预览问题不大，但如果每个框都要丢给修复模型处理，重复框就是双倍成本。

解决思路和传统检测算法里的 NMS 一样：计算两个框的交并比，超过阈值就只看置信度高的那个。

python复制def iou(box_a, box_b):
    ax1, ay1, ax2, ay2 = box_a
    bx1, by1, bx2, by2 = box_b
    ix1, iy1 = max(ax1, bx1), max(ay1, by1)
    ix2, iy2 = min(ax2, bx2), min(ay2, by2)
    inter_w = max(0, ix2 - ix1)
    inter_h = max(0, iy2 - iy1)
    inter_area = inter_w * inter_h
    area_a = (ax2 - ax1) * (ay2 - ay1)
    area_b = (bx2 - bx1) * (by2 - by1)
    union_area = area_a + area_b - inter_area
    return inter_area / union_area if union_area > 0 else 0

IoU 阈值我一般设 0.6，不同类别之间也做去重。重复检测出现的位置通常在对象边缘，阈值设太高容易漏掉重叠严重的重复框，设太低会误杀相邻的不同对象。0.6 是我在几十组测试里平衡下来的值，你可以按自己的场景微调。

4.3 批量任务的正确并发姿势

批量检测几百张图时，最容易犯的错误是不管服务器限流，一口气把线程池拉满。Gemini API 是有限流的，并发过高直接触发 429，然后退避逻辑又被触发，整体速度反而更慢。

我的做法：用 ThreadPoolExecutor 控制并发数在 4 到 6，同时在每个请求之间留出固定间隔。实测下来，4 到 6 并发比 20 并发总耗时更短，因为前者不会频繁触发限流，请求成功率更高。

python复制from concurrent.futures import ThreadPoolExecutor, as_completed

def process_batch(image_paths: list[str], max_workers=4):
    results = {}
    with ThreadPoolExecutor(max_workers=max_workers) as executor:
        future_map = {
            executor.submit(detect, path, ["人物", "车辆"]): path
            for path in image_paths
        }
        for future in as_completed(future_map):
            path = future_map[future]
            try:
                results[path] = future.result()
            except Exception as e:
                results[path] = {"error": str(e)}
    return results

还有一个非常实用的优化：用文件内容的哈希做缓存。同一张图不要重复请求，尤其当你的管道是“检测完还要修复”，一次失败重跑时，直接读已有缓存，能为调试省下大量时间和配额。

5. 好莱坞级修复的完整链路：分析缺陷、生成提示、图像生成一跳到位

5.1 “修复”这两个字最容易让人走弯路

很多人一提图像修复，第一反应是找专门的修复模型，先超分、再去划痕、再上色，每个环节一个独立模型。但 Gemini 这种多模态模型给了另一条路径：它既能看图，又能产出高质量的自然语言指令，而新一代图像生成能力又可以直接根据指令产出修复结果，三件事一个模型链路内完成。

这里有一个关键认知：你在修复之前，先要让模型“看懂”损坏的地方。模型不会读心。你直接给它一句“修复这张图”，它只能按通用理解去美化，结果就是人脸被过度磨皮、皮肤失去纹理、细节变得塑料感十足。所谓好莱坞级修复，第一步不是修，是分析。

5.2 让 Gemini 先输出修复指令再执行生成

我把整个修复流程拆成两步：分析阶段和生成阶段。分析阶段只输出文字，不碰图像生成；生成阶段把分析结果作为指令传给图像生成接口。

分析阶段的 prompt 长这样：

python复制analysis_prompt = """
请仔细观察这张图片，按以下结构输出分析结果：
1. 画面主题：用一句话描述图片内容、主体和光照方向
2. 损坏情况：逐一列出画面中的划痕、噪点、褪色、折痕、污渍、模糊区域
3. 修复目标：针对每一处损坏，说明修复后应该呈现的效果
4. 修复指令：生成一段 100 字以内的修复指令，要求：
   - 保留主体人物或物体的身份特征
   - 明确说明需要保持的自然质感，禁止过度平滑
   - 指出需要恢复的细节，如眼睛高光、衣服纹理、背景层次
5. 评价标准：列出 3 条衡量修复效果的质量指标，供后续人工或程序化评估使用
"""

这段请求的妙处在于：它逼着模型先“看”清画面，再“想”清方案，最后才动手。实际效果比直接说“修复它”好非常多，因为模型在生成阶段有机会参考到自己刚才分析出来的损坏清单，不会凭想象乱补。

5.3 图像生成接口的调用与结果保存

调用图像生成接口时，我把分析阶段产出的修复指令和分析用的原始图像一起传进去。这样模型既知道自己要修什么，也看得到原图，修复过程不是凭空生成，而是在原图基础上做受控编辑。

python复制import io
from google import genai

client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))

def restore_image(image_path: str, instruction: str) -> str:
    img = Image.open(image_path)
    response = client.models.generate_content(
        model="gemini-2.0-flash-preview-image-generation",
        contents=[
            "请严格按照修复指令处理这张图片，输出修复后的图像。",
            instruction,
            img,
        ],
        config=types.GenerateContentConfig(
            response_modalities=["image", "text"]
        )
    )

    for candidate in response.candidates:
        for part in candidate.content.parts:
            if part.inline_data is not None:
                image_bytes = part.inline_data.data
                output_path = image_path.replace(".jpg", "_restored.png")
                with open(output_path, "wb") as f:
                    f.write(image_bytes)
                return output_path
    raise RuntimeError("未在响应中找到图像数据")

这里我踩过的坑是：response_modalities 里既要 image 又要 text，否则模型可能只回文字不回图，或者反过来。保存格式用 PNG，修复图如果存 JPEG 会在边缘被压缩出新的伪影，等于二次损伤。

5.4 人脸修复时必须死守住的几条底线

人脸是图像修复里最难处理的部分。我总结了几条代价换来的底线：

第一条，别让人脸被过度平滑。提示词里一定要出现“保持皮肤纹理、保留高光细节、不要美颜”这类反向约束。生成模型默认倾向产出“完美脸”，但你看多了会发现完美脸就是塑料脸。

第二条，多轮修复不如一轮到位。有些人觉得修复效果不好就再跑一次。实际上你每多跑一次生成，就是多一次信息损耗。正确做法是第一次就把分析指令写足，把想保留的细节列清楚，一次生成。真不行就局部修复，裁出脸部区域单独处理再贴回原图。

第三条，用上一步检测到的脸部坐标做局部修复时，坐标范围要稍微外扩。把脸框扩到包含部分头发和衣领，修复出来的脸部过渡才自然。只裁一个对得死死的脸框，生成模型没有周边参考，容易把脸型画歪。

6. 旧照片修复实战复盘：从检测到出图我走过的完整流程

6.1 素材准备与链路设计

拿一张典型的旧照片举例：整体发黄、有横向划痕、人物面部有噪点、背景细节丢失。这个案例我故意挑了一个比较恶劣的素材，这样能看出链路里每一环的作用。

流程设计是：

code复制原始图片 → Gemini 检测（定位人物区域）→ Gemini 分析（输出损坏清单和修复指令）
→ 图像生成（执行修复）→ 修复结果 → Gemini 再次评估（对比修复前后差异）→ 最终成图

检测阶段在这里的主要用途是确认“人物到底在哪”。旧照片里背景噪声多，没有检测直接分析，模型容易被背景纹理带偏。检测出来的坐标我用来做两个事：一是把脸部区域单独裁出来修复重点保障，二是给分析阶段提供“只看人物区域”的裁剪图，减少无关干扰。

6.2 第一次修复结果为什么翻车

第一次跑完整流程，修复出来的脸几乎没法看。右边脸颊完全重绘了，脸型比原来瘦了一圈，嘴角还微微上扬，整个人的表情都变了。

问题出在分析阶段的指令里只写了“修复划痕和噪点”，没有写“保持主体人物身份特征”。生成模型拿到了自由度，自作主张把脸画成了它认为“更好看”的样子。

修正方式是在修复指令里加几条硬性约束：

code复制1. 不得改变脸型、五官比例和表情
2. 只修复划痕和噪点区域，其他区域保持原样
3. 如果某个区域信息缺失严重，优先恢复纹理而不是重建结构
4. 肤色以原图为基准，不做偏色校正

改成这个指令之后，第二次修复就正常多了。眼部高光、嘴角弧度、面部轮廓都保住了，划痕也被清掉大半。这说明指令里“不做什么”和“做什么”同样重要。

6.3 引入修复后的自评环节

我还加了一个不大起眼但实际很好用的环节：让 Gemini 评价自己的修复结果。具体做法是把原图和修复图成对传给模型，让它按分析阶段产出的评价标准打分，并列出仍然存在问题的区域。

这一步相当于给管道加了一个自动质检员。脚本只会把评价分数超过阈值的图标记为“通过”，没通过的进入第二轮局部修复。整体下来，一批 100 张图的合格率从不到六成提到了八成以上，剩下的少数疑难图件再人工处理，工作量一下子小了很多。

6.4 这个流程还能扩展到哪里

这套“检测 → 分析 → 生成 → 评估”的闭环不只是旧照片能用。我后来把同一套流水线改了几个 prompt，直接用于电商商品图质检：先检测商品主体、再分析瑕疵、随后生成替换背景或修正瑕疵。逻辑一点都不变，变的只是检测类别和修复指令。

还有一个很值得做的扩展：把目标检测坐标和修复结果联动起来。检测到人脸就去修复人脸，检测到文字区域就去修复文字，检测到天空就去修复天空。每个区域用不同的修复策略，比整张图一刀切精细得多。这就是空间智能在图像修复里最大的价值——它让模型知道了“该重点看哪里”，而不是无差别地处理每个像素。

就我目前的实践感受，Gemini 这套多模态链路还远没到天花板。每次迭代，模型对坐标的稳定性和生成图像的质量都在往上走。把手头的检测、分析、生成、自评四个环节做成可复用的模板，不管以后模型怎么换代，这套骨架能一直用下去。最后再分享一个技巧：所有步骤的中间结果，包括检测 JSON、分析文本、修复指令，都留一份存档。看起来多占一点存储，但在调 prompt 对比效果时，没有这些中间产物你根本说不清是哪一步出了偏差。有记录才有优化，这是整个流程里我最想让你记住的一件事。