Tầm nhìn tác vụ (Agentic Vision) trong Gemini 3: Hướng dẫn thực hành

Bạn gửi một hình ảnh tới API thị giác để nhờ đọc một nhãn giá nhỏ. Kết quả trả về tự tin nhưng sai. Tình huống tương tự khi đếm vật thể trong một bức ảnh lộn xộn: mô hình liếc qua toàn bộ ảnh một lần và đoán ra một con số lệch hẳn.

Gemini 3 Flash xử lý theo cách khác. Khi bật thực thi mã, nó có thể viết và chạy Python ngay giữa phản hồi để cắt, phóng to và chú thích ảnh trước khi đưa ra câu trả lời. Google gọi đây là agentic vision và báo cáo mức cải thiện chất lượng 5–10% trên các thước đo thị giác.

Hướng dẫn này đi qua bốn ví dụ với độ khó tăng dần: đọc chữ nhỏ trên kệ hàng tạp hóa, lấy tên đồ uống từ thực đơn quán bar thiếu sáng, đếm đồng xu rải rác và trích xuất dữ liệu bảng để vẽ biểu đồ.

Agentic Vision là gì? Vòng lặp "Think, Act, Observe"

Ý tưởng khá đơn giản. Khi bật thực thi mã, Gemini 3 có thể dừng giữa phản hồi, viết và chạy Python trong sandbox, xem những gì mã tạo ra và quyết định bước tiếp theo. 

Với các tác vụ thị giác, điều này thường có nghĩa là mô hình đang cắt các vùng của ảnh, phóng to, vẽ khung giới hạn hoặc điều chỉnh độ tương phản để kéo ra các chi tiết không nhìn thấy ở độ phân giải gốc.

Quá trình này diễn ra như một vòng lặp ba giai đoạn.

Trong giai đoạn Think, mô hình xem xét những gì nó có (ảnh gốc, hoặc phiên bản đã cắt hay chú thích) và lập kế hoạch bước kế tiếp. Nó có thể quyết định nhãn giá quá nhỏ để đọc và cần được cắt ra rồi phóng to.

Act biến kế hoạch đó thành Python. Sandbox có sẵn 43 thư viện (PIL, OpenCV, matplotlib, và nhiều hơn nữa), nên mô hình có thể viết bất kỳ mã xử lý ảnh cần thiết nào.

Sau khi mã chạy, Observe khép vòng lặp. Đầu ra (ảnh mới, văn bản in ra, giá trị tính toán) quay lại làm ngữ cảnh. Từ đó, mô hình hoặc trả lời hoặc lặp lại vòng nữa.

Một lần gọi API có thể lặp vòng này nhiều lần. Ở các ví dụ phía trước, bạn sẽ thấy nó cắt bảy vùng trên kệ chỉ trong một yêu cầu. Ở ví dụ khác, nó trích xuất dữ liệu bảng vào pandas DataFrame và tạo biểu đồ cột, tất cả trong một lần gọi. 

Nếu khái niệm vòng lặp agentic còn mới với bạn, lộ trình AI Agent Fundamentals của DataCamp có phần trình bày chi tiết.

Hạn chế và giới hạn

• Thực thi mã và gọi hàm tùy chỉnh không thể dùng trong cùng một yêu cầu.
• Tài liệu của Google cảnh báo rằng thực thi mã có thể làm giảm hiệu năng trên các tác vụ phi thị giác. Chỉ bật khi tác vụ hưởng lợi từ thao tác ảnh.
• Phân đoạn ở mức điểm ảnh (mặt nạ, đường biên) không thuộc agentic vision và vẫn ở Gemini 2.5.
• Đôi khi mô hình bỏ qua thực thi mã nếu một lần nhìn là đủ. Theo thiết kế, không phải lỗi.

Thiết lập môi trường cho Agentic Vision

Lấy khóa API từ ai.google.dev và lưu dưới tên GOOGLE_API_KEY trong môi trường của bạn hoặc tệp .env. Sau đó cài SDK và các thư viện ảnh:

pip install google-genai python-dotenv Pillow matplotlib opencv-pythonĐược hỗ trợ bởi

Bắt đầu bằng cách tạo client:

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"Được hỗ trợ bởi

Tham số timeout=600_000 rất quan trọng. Các cuộc gọi agentic vision gồm nhiều vòng sinh mã và thực thi trong sandbox, và một yêu cầu có thể mất khoảng bốn phút. 

Thời gian chờ mặc định của httpx sẽ ngắt kết nối từ lâu trước đó, để lại một ReadTimeout im lặng và bạn không biết chuyện gì đã xảy ra.

Tiếp theo, thiết lập cấu hình 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,
)Được hỗ trợ bởi

tools là công tắc bật thực thi mã. Nó cung cấp cho mô hình một môi trường Python sandbox với 43 thư viện (numpy, pandas, PIL, matplotlib, OpenCV và nhiều hơn nữa). Mỗi khối mã có 30 giây để chạy và sandbox sẽ thử lại tối đa 5 lần khi gặp lỗi.

thinking_level="HIGH" cho mô hình thêm không gian để lập kế hoạch trước khi viết mã. Với công việc thị giác nhiều bước, điều này tạo khác biệt rõ rệt. Thiết lập include_thoughts=True sẽ hiển thị phần suy luận trong các phần phản hồi, hữu ích để gỡ lỗi.

media_resolution đặt số token ảnh đầu vào nhận được trước khi vòng lặp bắt đầu. MEDIA_RESOLUTION_HIGH là mặc định tốt. Bạn có thể đẩy lên MEDIA_RESOLUTION_ULTRA_HIGH cho ảnh rất dày đặc hoặc giảm xuống MEDIA_RESOLUTION_LOW khi tốc độ quan trọng hơn chi tiết.

Thiết lập tương tự hoạt động trên Vertex AI với thay đổi tối thiểu. Để có hướng dẫn tổng quan hơn về Gemini 3 API ngoài mảng thị giác, xem bài hướng dẫn đi kèm.

Agentic Vision trong Gemini 3: Đọc chi tiết nhỏ bằng cắt và phóng to

Ảnh dưới đây là kệ hàng tạp hóa ở Đức với ba hàng sản phẩm. Nhãn giá nằm dọc mép mỗi kệ, và một thông báo "Liebe Kunden" (Kính gửi quý khách) ở gần đáy. Nếu tự phóng to, bạn có thể đọc được, nhưng chúng đủ nhỏ để khi nhìn toàn ảnh, mô hình phải quyết định phần nào đọc được và phần nào không.

Phân tích phản hồi nhiều phần

Phản hồi agentic không phải là một khối văn bản đơn. Chúng đến dưới dạng danh sách các phần: suy nghĩ, mã mô hình viết, kết quả thực thi, ảnh sinh ra và câu trả lời cuối. Trình trợ giúp này đi qua chúng:

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)Được hỗ trợ bởi

Mọi ví dụ trong hướng dẫn này đều dùng cùng hàm, nên hãy định nghĩa một lần và tái sử dụng.

Giờ hãy nạp ảnh kệ hàng và viết prompt yêu cầu mô hình đọc biển báo và liệt kê mọi sản phẩm với giá của chúng.

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."
)Được hỗ trợ bởi

Chạy thử trước khi bật thực thi mã:

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)Được hỗ trợ bởi

Đây là phiên bản rút gọn của đầu ra:

[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
...Được hỗ trợ bởi

Bản dịch biển báo là chính xác, và mô hình đọc được các nhãn Uncle Ben's mà nó nhận ra. Nhưng khoảng một phần ba mục là "(Label obscured)" và các thương hiệu như Oryza, Reis-fit và Reiskugeln hoàn toàn không xuất hiện.

Giờ dùng cùng prompt nhưng với cấu hình agentic:

agentic_response = client.models.generate_content(
	model=MODEL,
	contents=[image_part, prompt],
	config=agentic_config,
)
print_response(agentic_response, show_thoughts=True)Được hỗ trợ bởi

Cấu trúc đầu ra khác hẳn. Thay vì một [ANSWER] duy nhất, nó đi qua toàn bộ vòng 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Được hỗ trợ bởi

Bảy vùng cắt mà mô hình tạo ra:

Sau khi quan sát các vùng cắt đó, mô hình đưa ra câu trả lời đầy đủ:

[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 €
...Được hỗ trợ bởi

Đầu ra đầy đủ chưa rút gọn cho cả hai lần gọi có trong gist này.

Phản hồi agentic đọc được hơn 30 sản phẩm trên cả ba kệ. Những mặt hàng Oryza, Reis-fit, Madras Curry, Reiskugeln và Steam Basmati mà thị giác tiêu chuẩn gắn nhãn "(obscured)" đều xuất hiện với tên và giá.

Sự khác biệt không nằm ở chuyện hoang tưởng so với chính xác; thị giác tiêu chuẩn trung thực về những gì nó không đọc được. Agentic vision đơn giản là không chấp nhận giới hạn đó và phóng to cho đến khi đọc được.

Prompt cũng đóng vai trò ở đây. Yêu cầu mô hình "liệt kê tất cả tên sản phẩm nhìn thấy và giá của chúng" đặt ra một ngưỡng đầy đủ, thúc đẩy nó tiến tới cắt ảnh.

Một prompt mơ hồ như "mô tả bức ảnh này" có khả năng sẽ tạo ra câu trả lời một lượt ngay cả khi đã bật thực thi mã, vì mô hình không thấy lý do để đi xa hơn.