Gemini 3 的 Agentic Vision：动手教程

您把一张图片发给视觉 API，请它读取一个很小的价格标签。返回的结果信心十足，却错得离谱。杂乱照片里数物体同样如此：模型只扫了一眼整张图片，就随口猜了个相差甚远的数字。

Gemini 3 Flash 的处理方式不同。开启代码执行后，它可以在生成回复的过程中编写并运行 Python，先对图像进行裁剪、放大和标注，再给出答案。Google 将此称为 agentic vision，并报告在视觉基准上带来 5-10% 的质量提升。

本教程通过四个难度逐步提升的示例展开：从货架读取小字、在昏暗的酒吧菜单上提取酒名、统计散落的硬币、以及将表格数据提取为图表。

什么是 Agentic Vision？“Think、Act、Observe” 循环

思路很直接。开启代码执行后， Gemini 3 可以在回复中途暂停，在沙盒里编写并运行 Python，查看代码产出，再决定下一步要做什么。

对视觉任务而言，这通常意味着模型会裁切图像区域、放大、绘制边界框，或调整对比度，从而提取原始分辨率下不可见的细节。

这会以一个三阶段循环展开。

在 Think 阶段，模型会查看已有内容（原图，或已裁剪/标注的版本），并规划下一步。它可能判断某个价格标签太小，需要裁剪并放大后才能读。

Act 会把计划变成 Python。沙盒预装了 43 个库（PIL、OpenCV、matplotlib 等），模型可以按需编写任意图像处理代码。

代码运行后，Observe 阶段闭环。输出（新图像、打印文本、计算值）会回灌到上下文。接着，模型要么直接回答，要么再循环一轮。

单次 API 调用可以多次循环。在下面的示例中，您会看到它在一次请求中裁剪了货架的七个区域。另一个示例中，它将表格数据提取到 pandas DataFrame 并生成柱状图，同样在一次调用内完成。

如果您对 agentic 循环的概念还不熟悉，DataCamp 的 AI Agent Fundamentals 路线有深入讲解。

限制与边界

• 代码执行与自定义函数调用不能在同一个请求中使用。
• Google 文档提示，代码执行可能会降低非视觉任务的表现。仅在任务确实受益于图像处理时再开启。
• 像素级分割（掩膜、轮廓）不属于 agentic vision，仍在 Gemini 2.5 上。
• 如果一次观察就足够，模型有时会跳过代码执行。这是设计使然，而非缺陷。

为 Agentic Vision 配置您的环境

在 ai.google.dev 获取 API 密钥，并将其存为环境变量 GOOGLE_API_KEY，或写入 .env 文件。然后安装 SDK 和图像库：

pip install google-genai python-dotenv Pillow matplotlib opencv-python技术支持

先创建客户端：

from google import genai
from google.genai import types
from dotenv import load_dotenv
 
load_dotenv()
 
client = genai.Client(
    http_options=types.HttpOptions(timeout=600_000)
)
MODEL = "gemini-3-flash-preview"技术支持

这个 timeout=600_000 很重要。Agentic vision 调用会在沙盒内多轮生成与执行代码，单次请求可能需要约四分钟。

httpx 的默认超时会在此之前就断开连接，留给您一个静默的 ReadTimeout，完全不知发生了什么。

接下来，设置 agentic 配置：

agentic_config = types.GenerateContentConfig(
    tools=[types.Tool(code_execution=types.ToolCodeExecution())],
	thinking_config=types.ThinkingConfig(
    	thinking_level="HIGH",
    	include_thoughts=True
	),
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_HIGH,
)技术支持

tools 是开启代码执行的开关。它为模型提供了一个带 43 个库（numpy、pandas、PIL、matplotlib、OpenCV 等）的 Python 沙盒。每个代码块有 30 秒运行时间，沙盒在出错时最多重试 5 次。

thinking_level="HIGH" 让模型在写代码前有更充足的规划空间。对多步骤视觉任务而言，这个差异很明显。设置 include_thoughts=True 会在响应部分暴露推理过程，便于调试。

media_resolution 用于设置循环开始前输入图像占用的 token 数。MEDIA_RESOLUTION_HIGH 是不错的默认值。超高密度图像可提升至 MEDIA_RESOLUTION_ULTRA_HIGH，若更重视速度可降到 MEDIA_RESOLUTION_LOW。

相同配置也适用于 Vertex AI，仅需少量调整。关于 Gemini 3 API 的更全面讲解（超出视觉范畴），请参阅配套教程。

Gemini 3 中的 Agentic Vision：用裁剪与放大读取细节

下图是德国一家杂货店的货架，摆着三排商品。每层货架边缘都有价格标签，底部附近有一张“Liebe Kunden”（亲爱的顾客）告示。若您自己放大，标签是可读的；但对于一次性查看整张图的模型来说，它必须决定哪些看得清、哪些看不清。

解析多部分响应

Agentic 的响应不是单一文本块。它会以部件列表的形式到达：思考、模型写的代码、执行结果、生成的图像，以及最终答案。下面这个辅助函数可逐一查看：

def print_response(response, show_thoughts=False):
	for part in response.candidates[0].content.parts:
    	if part.thought and show_thoughts:
        	print("[THINK]", part.text[:500])
    	elif part.executable_code:
        	print("[CODE]")
        	print(part.executable_code.code)
    	elif part.code_execution_result:
        	print(f"[RESULT] ({part.code_execution_result.outcome})")
            print(part.code_execution_result.output)
    	elif part.inline_data:
        	print(f"[IMAGE] {part.inline_data.mime_type}, "
                  f"{len(part.inline_data.data):,} bytes")
    	elif part.text:
        	print("[ANSWER]", part.text)技术支持

本教程的每个示例都使用相同的函数，因此定义一次反复复用即可。

现在载入货架图片，并写一个提示词，请模型读取告示并列出每件商品与其价格。

from pathlib import Path
 
image_path = Path("images/grocery_shelf.jpg")
image_part = types.Part.from_bytes(
	data=image_path.read_bytes(), mime_type="image/jpeg"
)
 
prompt = (
	"Read the 'Liebe Kunden' sign at the bottom of the shelf. "
	"What does it say? Also list all visible product names "
	"and their prices from the shelf labels."
)技术支持

先在未开启代码执行的情况下运行：

standard_config = types.GenerateContentConfig(
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_HIGH,
)
 
standard_response = client.models.generate_content(
	model=MODEL,
	contents=[image_part, prompt],
	config=standard_config,
)
print_response(standard_response)技术支持

以下是精简后的输出：

[ANSWER] Based on the image provided, here is the information requested:
 
### The 'Liebe Kunden' Sign
> "Dear Customers, unfortunately, we must inform you that due to
> increased demand, we cannot currently offer all products..."
 
### Product Names and Prices (from shelf labels)
 
**Top Row Labels:**
*   Uncle Ben's Express Reis Mexi-Scharf 250g: 1,69
*   Uncle Ben's Express Reis Griechisch 250g: 1,69
*   Uncle Ben's Express Reis Curry 250g: 1,69
*   Channa Masala 300g (partially obscured): 2,49
*   (Label obscured): 2,49
*   (Label obscured): 1,29
*   (Label obscured): 0,99
...
 
**Second Row Labels:**
*   Uncle Ben's Express Reis Chili con Carne 250g: 2,49
*   Uncle Ben's Spitzen-Langkorn Reis 10 Min 500g: 1,79
*   (Label obscured): 2,99
*   (Label obscured): 2,79
...技术支持

告示的翻译是正确的，模型也读出了能识别的 Uncle Ben's 标签。但约有三成条目是“（标签被遮挡）”，Oryza、Reis-fit 和 Reiskugeln 等品牌完全没有出现。

现在用相同提示词，切换到 agentic 配置：

agentic_response = client.models.generate_content(
	model=MODEL,
	contents=[image_part, prompt],
	config=agentic_config,
)
print_response(agentic_response, show_thoughts=True)技术支持

输出结构不同了。不再是单个 [ANSWER]，而是完整走了一遍 Think/Act/Observe 循环：

[THINK] Okay, so the primary goal here is twofold: First, I need to
decipher that "Liebe Kunden" sign down there. Then, I need to build a
comprehensive list of what's on this shelf...
 
[CODE]
import PIL.Image
 
img = PIL.Image.open('input_file_0.jpeg')
width, height = img.size
 
crops = [
	{'box_2d': [630, 447, 887, 559], 'label': 'liebe_kunden_sign'},
	{'box_2d': [80, 40, 240, 560], 'label': 'shelf1_left'},
	{'box_2d': [190, 550, 310, 980], 'label': 'shelf1_right'},
	{'box_2d': [400, 0, 480, 450], 'label': 'shelf2_left'},
	{'box_2d': [410, 450, 480, 1000], 'label': 'shelf2_right'},
	{'box_2d': [630, 130, 760, 460], 'label': 'shelf3_left'},
	{'box_2d': [550, 600, 660, 990], 'label': 'shelf3_right'},
]
# ... crops and saves each region
 
[IMAGE] image/png, 135,953 bytes
[IMAGE] image/png, 90,395 bytes
[IMAGE] image/png, 125,816 bytes
[IMAGE] image/png, 102,288 bytes
[IMAGE] image/png, 173,606 bytes
[IMAGE] image/png, 283,263 bytes
[IMAGE] image/png, 100,522 bytes技术支持

模型生成的七个裁剪区域：

观察这些裁剪图后，模型给出了完整答案：

[ANSWER]
**Top Shelf (Left to Right):**
*   Uncle Ben's Express Reis Mexi. Scharf 250g: 1,69 €
*   Channa Masala 285g: 2,49 €
*   Madras Curry 285g: 2,49 €
*   Steam Basmati Reis Kochbeutel 250g: 1,99 €
*   Reiskugeln Pur 4x2 St: 1,99 €
...
 
**Middle Shelf (Left to Right):**
*   Uncle Ben's Express Reis Chili con Carne 250g: 2,49 €
*   Oryza Langkorn & Wildreis 500g Kochbeutel: 2,99 €
*   Oryza Basmati & Wildreis 500g Kochbeutel: 2,79 €
*   Oryza Jasmin Reis 500g Kochbeutel: 2,79 €
...
 
**Bottom Shelf (Left to Right):**
*   Uncle Ben's Natur Reis 10-Min. Kochbeutel 1kg: 3,69 €
*   Reis-fit 10 Minuten Natur-Reis 500g: 1,89 €
*   Reis-fit Langkorn & Wildreis 500g: 1,89 €
...技术支持

两次调用的完整未截断输出见 此 gist。

Agentic 的响应读出了三层货架上 30 多款商品。标准视觉标为“（遮挡）”的 Oryza、Reis-fit、Madras Curry、Reiskugeln 和 Steam Basmati 等项目，都以名称和价格出现。

差异并非“幻觉 vs. 准确性”；标准视觉如实承认看不清。Agentic vision 则是不接受这个限制，直到放大到能看清为止。

提示词也有影响。要求模型“列出所有可见商品名及价格”为完整性设定了门槛，推动它走向裁剪放大。

如果提示词更含糊，比如“描述这张图片”，即便开启代码执行，也很可能只给出一次性答案，因为模型看不到进一步处理的必要。