Hướng dẫn API Gemini 3.8 Flash: Thinking Levels, trích xuất PDF và Function Calling trong Python

Gemini 3.8 Flash là gì?

Gemini 3.8 Flash là mẫu chủ lực của Google, khả dụng rộng rãi từ ngày 2/9/2026 với ID model gemini-3.8-flash. Nó ra mắt sau 3 tuần kể từ 3.7 Flash, và Google định vị cho lập trình đường dài, quy trình agent, và suy luận nhiều bước trong các lĩnh vực chuyên sâu như tài chính và pháp lý.

Thông số quan trọng cho các cuộc gọi API không đổi so với 3.7: 

• cửa sổ ngữ cảnh 1M token
• 64k token đầu ra tối đa
• đa phương thức đầu vào (văn bản, hình ảnh, video, âm thanh, PDF) với đầu ra văn bản
• Cùng mức giá khởi điểm $0,75 cho 1M token đầu vào và $3,75 cho 1M token đầu ra đến hết 31/12/2026 (tăng lên $1,50 và $7,50 từ 1/1/2027)

Điều thay đổi là hành vi, không phải bề mặt: Google nói 3.8 làm việc chăm hơn với tác vụ phức tạp, thực hiện thêm các bước suy luận và gọi công cụ lặp, điều này có thể tăng lượng token ở mức nỗ lực cao. 3.7 Flash vẫn được hỗ trợ đầy đủ cho khối lượng công việc coi trọng hiệu suất hơn độ sâu.

Để xem benchmark và chi tiết giá, hãy đọc hướng dẫn Gemini 3.8 Flash của chúng tôi, hoặc đọc Google Gemini là gì? để có tổng quan về nền tảng.

Gemini 3.8 Flash so với 3.8 Flash Cyber

Bản phát hành gồm 2 biến thể, và chỉ 1 biến thể có ID model bạn có thể gõ. 

• Gemini 3.8 Flash là mẫu chung, hiện có trong Google AI Studio và Gemini API. 
• Gemini 3.8 Flash Cyber là biến thể an ninh mạng tinh chỉnh cho phát hiện lỗ hổng và vá tự động.

Biến thể Cyber không có trên API công khai: truy cập thông qua Chương trình Fairwind của Google, giới hạn cho cơ quan nhà nước đã duyệt, đơn vị vận hành hạ tầng trọng yếu, và bên bảo trì phần mềm.

Nếu bạn theo hướng dẫn này, ID model của bạn là gemini-3.8-flash. Nội dung bên dưới không cần và không dùng biến thể Cyber.

Interactions API so với generateContent

Để gọi Gemini 3.8 Flash, hãy dùng client.interactions.create() trong SDK google-genai. Google đã đưa Interactions API lên GA tháng 6/2026 và khuyến nghị cho mọi công việc mới. Dù generateContent vẫn hoạt động, nó nay là kế thừa. Tính năng mới như lịch sử phía máy chủ, thực thi nền, và quan sát bước thực thi xuất hiện trước trên Interactions.

Khác biệt lớn nhất trong thực tế là quản lý trạng thái. Cuộc gọi nhiều lượt nay dùng previous_interaction_id phía máy chủ: bạn truyền ID lượt trước, và máy chủ khôi phục trạng thái. Bạn không còn cần tự nối hoặc gửi lại toàn bộ lịch sử chat từ client. Tránh điền trước lượt của model; đó là mẫu generateContent kế thừa và sẽ hỏng trên Gemini 3.x.

Có một điều hầu như ai cũng vấp, và nó quay lại ở phần PDF: previous_interaction_id chỉ khôi phục lịch sử hội thoại, không gì khác. tools, system_instruction, generation_config, và response_format có phạm vi theo interaction, nên mọi lượt cần chúng đều phải truyền lại.

thinking_level thay thế các núm sampling

Trên các mẫu Gemini cũ, nhà phát triển dùng temperature, top_p, và top_k để kiểm soát độ ngẫu nhiên đầu ra. Gemini 3.x loại bỏ các núm sampling này và thay bằng thinking_level, nay là núm duy nhất.

Nó nhận 3 giá trị:

• low: ít token suy luận nhất, nhanh và rẻ nhất. Phù hợp trích xuất, phân loại, và mọi thứ bạn sẽ tự kiểm tra.

• medium: mặc định, và Google khuyến nghị cho mã và công việc agent.

• high: ngân sách suy luận lớn nhất, cho logic nhiều bước khó và tác vụ dùng nhiều công cụ.

Không gửi minimal. Nó không hợp lệ từ Gemini Flash 3.7 và trả về lỗi xác thực 400. 

Một quy tắc khác giữ nguyên từ 3.7: frequency_penalty, presence_penalty, và candidate_count nay ném lỗi API chủ động, nên cũng loại bỏ chúng khỏi cấu hình kế thừa.

Thiết lập API Gemini 3.8 Flash như thế nào?

Thiết lập môi trường mất khoảng 2 phút. Bạn cần một khóa API từ Google AI Studio và thư viện Python google-genai được cập nhật.

Lấy khóa API từ Google AI Studio

Truy cập Google AI Studio trên trình duyệt và đăng nhập bằng tài khoản Google. Bấm Create API Key, chọn hoặc tạo dự án Google Cloud, và sao chép chuỗi khóa bí mật của bạn. 

Mở terminal và lưu khóa thành biến môi trường với export GEMINI_API_KEY=<your-key>.

Không bao giờ truyền khóa dưới dạng tham số truy vấn ?key= trong URL; chuỗi truy vấn sẽ vào log máy chủ, lịch sử trình duyệt, và bộ nhớ đệm proxy. Nếu bạn muốn khám phá model trong playground trước khi viết code, Hướng dẫn Google AI Studio bao gồm chế độ Chat, Build, và Stream; bài này chỉ dùng API.

Đối với hệ thống sản xuất, câu chuyện xác thực thay đổi: Vertex AI (nay là một phần của Gemini Enterprise Agent Platform) cung cấp OAuth, vai trò IAM và endpoint theo vùng thay vì khóa API thô. Mọi thứ trong hướng dẫn này dùng khóa AI Studio vì đó là con đường nhanh nhất để học, nhưng hãy lên kế hoạch di trú sang Vertex trước khi có dữ liệu người dùng thật.

Cài google-genai và tạo client

Nhiều hướng dẫn vẫn bảo cài google-generativeai. Đó là SDK cũ và không có Interactions API. Hãy cài google-genai (phiên bản 2.3.0 trở lên):

pip install -U google-genai

Sau khi cài, hãy kiểm tra Python tải thư viện và khởi tạo client mà không lỗi:

from google import genai # reads GEMINI_API_KEY from the environment
client = genai.Client() 
print("Client initialized successfully.")

Thực hiện cuộc gọi Interactions API đầu tiên

Mỗi yêu cầu tới Interactions API tạo một tài nguyên Interaction, ghi lại toàn bộ lượt: đầu vào của bạn, suy nghĩ của model, mọi lần gọi công cụ, và đầu ra cuối. SDK cung cấp văn bản cuối qua thuộc tính tiện dụng output_text, nên bạn hiếm khi cần duyệt thủ công các bước.

from google import genai
client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=(
        "Write a pandas one-liner that adds a 7-day rolling average "
        "revenue column per store_id to a DataFrame with columns "
        "date, store_id, revenue. Reply with only the code, no explanation."
    ),
    generation_config={"thinking_level": "medium"},
)
print(interaction.output_text)
usage = interaction.usage
print(
    f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
    f"thinking={usage.total_thought_tokens} | total={usage.total_tokens}"
)

Trên máy tôi, model trả lời bằng một one-liner pandas có xâu chuỗi, và dòng usage như sau:

Những con số đó ẩn khác biệt thực sự đầu tiên với 3.7. Tôi chạy lại cùng tác vụ với prompt dài hơn và không hạn chế đầu ra, và 3.8 dùng 1.436 token suy nghĩ so với 870 token đầu ra. Với ràng buộc, nó dùng 1.515 so với 42. Ngân sách suy luận hầu như không đổi, trái ngược 3.7, nơi cùng 2 prompt khiến suy nghĩ từ 838 lên 1.530.

Nói cách khác, 3.8 quyết định mức độ suy nghĩ dựa trên tác vụ, không dựa vào cách bạn diễn đạt tác vụ, phù hợp với tuyên bố của Google rằng model suy luận và kiểm chứng nhiều hơn có chủ đích. Token suy nghĩ được tính ở mức giá đầu ra, nên trong cuộc gọi bị ràng buộc, khoảng 97% token tính phí là suy luận bạn không thấy. Đó là lý do phần tiếp theo tồn tại. 

Stream phản hồi

Với giao diện chat hay bất cứ thứ gì người dùng xem trực tiếp, chờ vài giây cho toàn bộ phản hồi sẽ thấy chậm. Truyền stream=True vào client.interactions.create() và in các mảnh khi chúng đến:

	from google import genai

	client = genai.Client()

	stream = client.interactions.create(
	   model="gemini-3.8-flash",
	   input="Explain the difference between a JOIN and a correlated subquery in SQL.",
	   generation_config={"thinking_level": "low"},
	   stream=True,
	)

	for event in stream:
	   if event.event_type == "step.delta" and event.delta.type == "text":
	       print(event.delta.text, end="", flush=True)
	print() 

Khi tôi chạy, model trả về câu trả lời dài, có tổ chức tốt ở thinking_level: "low": so sánh khái niệm, bảng tóm tắt, và 2 ví dụ SQL để tìm đơn hàng gần nhất của mỗi khách hàng, 1 với join bảng dẫn xuất và 1 với truy vấn con tương quan trong danh sách SELECT. Những từ đầu tiên xuất hiện gần như ngay lập tức, đó chính là mục đích.

Lệnh print() cuối cùng có lý do. Thiếu nó, mảnh cuối sẽ dừng giữa dòng và zsh hiển thị dấu % lạc chỗ trước prompt của bạn, vì stream kết thúc đúng nơi văn bản của model dừng. Ngoài ra, delta chỉ mang văn bản; nếu bạn ghi log số token mỗi yêu cầu, hãy đọc từ sự kiện hoàn tất cuối thay vì cộng dồn các mảnh.

thinking_level ảnh hưởng chi phí và chất lượng thế nào?

thinking_level đặt lượng suy luận mà Gemini 3.8 Flash thực hiện trước khi viết câu trả lời. Token suy luận được tính ở mức đầu ra $3,75 mỗi 1M, nên mức bạn chọn tác động trực tiếp chi phí và độ trễ, và Google nói 3.8 cố ý tận dụng điều này: nó thực hiện thêm bước suy luận ở tác vụ phức tạp và có thể tiêu tốn nhiều token hơn ở mức nỗ lực cao so với 3.7.

Chạy một prompt ở low, medium và high

Bài kiểm tra là điều kiện tranh chấp (race condition) trong một hàm thử lại thanh toán, được gửi cùng prompt ở cả 3 mức. Lỗi đồng thời trừng phạt việc đọc lướt, nên nếu các mức khác nhau, đây là nơi nó thể hiện. Nếu bạn chỉ chạy 1 khối mã trong bài này, hãy chạy khối này, vì các con số thuyết phục hơn mọi lời văn.

import time

from google import genai

client = genai.Client()

BUGGY_CODE = '''
import threading

payment_attempts = {}

def retry_payment(order_id, charge_fn, max_retries=3):
    """Retry a failed payment up to max_retries times."""
    if order_id not in payment_attempts:
        payment_attempts[order_id] = 0

    while payment_attempts[order_id] < max_retries:
        success = charge_fn(order_id)
        if success:
            del payment_attempts[order_id]
            return True
        payment_attempts[order_id] += 1
    return False
'''

PROMPT = (
    "Two worker threads can call retry_payment() with the same order_id "
    "at the same time. Identify the concurrency bug that can double-charge "
    "a customer, and rewrite the function to fix it.\n\n" + BUGGY_CODE
)

for level in ["low", "medium", "high"]:
    start = time.perf_counter()
    interaction = client.interactions.create(
        model="gemini-3.8-flash",
        input=PROMPT,
        generation_config={"thinking_level": level},
    )
    elapsed = time.perf_counter() - start
    usage = interaction.usage
    print(f"\n=== thinking_level: {level} | {elapsed:.1f}s ===")
    print(interaction.output_text)
    print(
        f"input={usage.total_input_tokens} | output={usage.total_output_tokens} | "
        f"thinking={usage.total_thought_tokens}"
    )

Để tham chiếu, lỗ hổng là kiểm-tra-rồi-hành-động không nguyên tử trên payment_attempts[order_id]. Dưới điều kiện đồng thời, 2 luồng có thể cùng thỏa điều kiện while và cùng gọi charge_fn() trước khi bất kỳ cái nào tăng bộ đếm. Sửa nghĩa là bao bọc luồng đọc-kiểm-tra-tính tiền-tăng đếm trong một khóa theo từng đơn, hoặc dùng khóa idempotency tại cổng thanh toán.

So sánh kết quả

Kết quả từ các lần chạy của tôi:

Cả 3 mức đều tìm ra lỗi tính tiền kép, và cả 3 đều áp dụng khóa theo từng đơn, nên các đơn không liên quan chạy song song. Phần thứ 2 này là tiêu điểm nếu bạn so với 3.7: ở đó, low bọc mọi thứ trong 1 khóa toàn cục giữ trong lúc gọi mạng, và khóa theo đơn chỉ xuất hiện ở medium. Trên 3.8, low viết thiết kế tốt hơn đó với 0 token suy nghĩ, trong 7,8 giây, với chi phí chưa đến 1/3 xu.

Vậy các mức giờ đem lại gì? Độ sâu kiểm toán. Đoạn mã này có 4 chế độ lỗi riêng biệt (tính tiền kép, KeyError khi xóa đồng thời, tính lại sau khi đường dẫn thành công xóa trạng thái, và tăng bộ đếm không nguyên tử), và high là mức duy nhất nêu đủ 4; low bỏ sót trường hợp tính lại, và medium bỏ sót bộ đếm. 

high cũng là mức duy nhất làm rõ ngữ nghĩa đường dẫn lỗi của bản sửa: khi hết số lần thử, các lệnh gọi sau trả về False thay vì tính tiền lại.

Cột suy nghĩ là nơi tuyên bố "3.8 làm việc chăm hơn" của Google hiện lên ngay trong terminal. Với cùng prompt trên 3.7, medium tăng từ 2.343 token suy nghĩ lên 3.158, và high từ 2.217 lên 4.512, xấp xỉ gấp đôi, và token thêm mang lại phân tích đầy đủ hơn chứ không phải kết luận khác. Độ trễ tăng tương ứng ở lần chạy này (7,8 s, 16,6 s, 25,5 s), nhưng thời gian một lần chạy trên các model này dao động, nên hãy so sánh số token hơn là giây.

Chọn mặc định và khi nào nâng mức

Đây là nguyên tắc kinh nghiệm của tôi cho các mức suy luận:

• Trên 3.8, low xứng đáng vai trò lớn hơn gợi ý mặc định medium của Google: nó đưa ra bản sửa đúng, thiết kế tốt với 0 token suy nghĩ, nên hãy bắt đầu ở đây cho mọi thứ con người sẽ đọc trước khi quyết định (phân loại sơ bộ, bản nháp, tóm tắt, mã bạn sẽ review). 

• Giữ medium cho nơi đầu ra được chuyển đi mà không ai đọc, vì suy nghĩ thêm mang lại phân tích đầy đủ hơn về chế độ lỗi, và một pipeline không ai đọc chính là nơi chế độ lỗi bạn không liệt kê sẽ xảy ra.

• Dành high cho đầu ra mà chính đường dẫn lỗi là sản phẩm, như luồng thanh toán, di trú, hay bất cứ thứ gì người kiểm duyệt sẽ kiểm toán từng dòng. Trong lần chạy của tôi, đây là mức duy nhất bắt đủ 4 lỗi và mô tả điều xảy ra sau khi hết lần thử.

Với chi phí của high gấp 6,6 lần low, sự đánh đổi này đọc rất khác ở mức $3,75 cho 1M token đầu ra bây giờ so với $7,50 sau 31/12/2026, nên hãy nâng mức theo từng yêu cầu thay vì toàn cục.

Một lối thoát đáng biết là Google nêu 3.7 Flash vẫn được hỗ trợ đầy đủ cho khối lượng công việc ưu tiên hiệu suất. Nếu sự cẩn trọng thêm của 3.8 tốn nhiều hơn nhu cầu tác vụ, ở lại với gemini-3.7-flash cho khối lượng đó là lựa chọn được hỗ trợ, không phải mánh mẹo.

Trích xuất dữ liệu có cấu trúc từ PDF như thế nào?

Gemini 3.8 Flash đọc trực tiếp PDF làm đầu vào, nên bạn có thể gửi hóa đơn hay báo cáo và đặt câu hỏi về nó. Tôi dùng một hóa đơn nhà cung cấp 1 trang với số hóa đơn, ngày tháng, 4 dòng hạng mục, và tổng tiền.

Đính kèm PDF vào prompt

Hãy tải lên một PDF hóa đơn cục bộ bằng Files API. Files API xử lý lưu trữ và bộ nhớ đệm tệp trên hạ tầng của Google:

	from google import genai
	client = genai.Client()
	print("Uploading invoice...")
	doc = client.files.upload(file="invoice_aug_2026.pdf")
	print(f"File uploaded: {doc.uri}\n")

	interaction = client.interactions.create(
	   model="gemini-3.8-flash",
	   input=[
	       {
	           "type": "text",
	           "text": "Extract the invoice number, total amount due, and due date.",
	       },
	       {"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
	   ],
	)
	print(interaction.output_text)

Đầu ra từ hóa đơn của tôi:

Cả 3 giá trị đều đúng. Tải lên diễn ra một lần, và tệp tiếp tục khả dụng cho các yêu cầu sau, điều quan trọng khi bạn hỏi hơn 1 câu về cùng tài liệu. Câu trả lời trả về dạng gạch đầu dòng markdown, phù hợp để đọc và không phù hợp để đưa vào pipeline.

Ép JSON bằng response schema

Để nhận JSON thay vì văn xuôi, truyền một schema trong response_format. Trên Interactions API, đây là tham số cấp cao nhất; thiết lập responseMimeType bên trong generationConfig mà bạn thấy trong hướng dẫn cũ thuộc về endpoint kế thừa generateContent.

import json

from google import genai
from pydantic import BaseModel

client = genai.Client()


class Invoice(BaseModel):
    invoice_number: str
    total_due_usd: float
    due_date: str  # ISO 8601


doc = client.files.upload(file="invoice_aug_2026.pdf")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "text",
            "text": "Extract the invoice number, total amount due in USD, and due date.",
        },
        {"type": "document", "uri": doc.uri, "mime_type": doc.mime_type},
    ],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Invoice.model_json_schema(),
    },
)

invoice = json.loads(interaction.output_text)
print(invoice)

Đây là đầu ra tôi nhận được: 

Lớp Pydantic của bạn định nghĩa các trường bắt buộc và kiểu dữ liệu, trong khi model_json_schema() sinh JSON schema mà Gemini API yêu cầu. Sau khi xử lý, json.loads() chuyển đầu ra của model thành dict Python chuẩn. Từ đây, dữ liệu có cấu trúc sẵn sàng để chuyển thành một dòng DataFrame, ghi vào cơ sở dữ liệu, hoặc thêm vào Google Sheet.

Hỏi tiếp với previous_interaction_id

Cho câu hỏi thứ 2 về cùng tài liệu, truyền id của lượt thứ 1 làm previous_interaction_id. Máy chủ đã có PDF và trao đổi đầu, nên bạn không gửi lại cái nào:

follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input="List each line item on the invoice with its amount.",
)

print(follow_up.output_text)

Nó trả về đủ 4 hạng mục theo thứ tự, gồm cả dòng compute lặp lại, mà không bình luận về sự lặp. Đó là hành vi đúng với câu hỏi; nếu bạn muốn đánh dấu bất thường, hãy yêu cầu điều đó. 

Đáng nói là 3.7 cũng hành xử giống hệt ở đây, nên sự cẩn trọng thêm của 3.8 áp dụng cho suy luận của chính nó, không tự nguyện kiểm toán khi bạn không yêu cầu.

2 điều cần biết về cuộc gọi này: 

• response_format không được mang theo, vì nó có phạm vi theo interaction, nên lượt này trả về văn xuôi. 

• Và interactions được lưu mặc định (store=True) trong 55 ngày ở gói trả phí và 1 ngày ở gói miễn phí; store=False khiến cuộc gọi không trạng thái, nhưng bạn sẽ không thể xâu chuỗi previous_interaction_id từ nó.

Thêm Function Calling vào Gemini 3.8 Flash như thế nào?

Function calling trên Gemini 3.8 Flash là một vòng lặp: model yêu cầu công cụ, mã của bạn chạy nó, bạn gửi kết quả về, và model viết câu trả lời cuối. Phần này xây vòng lặp đó bằng tay.

Nếu bạn muốn Google chạy vòng lặp cho bạn với agent đa công cụ được quản lý, hãy đọc hướng dẫn về  "Managed Agents" trong Gemini API. Và nếu agent là đích đến dài hạn, khóa học Building AI Agents with Google ADK xây một trợ lý hỗ trợ khách hàng đầy đủ trên cùng các nguyên thủy.

Định nghĩa công cụ và thực thi vòng lặp interaction

Công cụ là lookup_exchange_rate(currency, date), dựa trên một dict trong bộ nhớ nhỏ, để ví dụ chạy không cần API ngoài. Khai báo là một JSON schema. Model không bao giờ chạy hàm; nó trả về một bước function_call yêu cầu mã của bạn:

import json

from google import genai

client = genai.Client()

# Local "data source" standing in for a real FX API
RATES = {
    ("USD", "2026-08-03"): 87.42,
    ("USD", "2026-08-10"): 87.15,
    ("EUR", "2026-08-03"): 95.08,
}


def lookup_exchange_rate(currency: str, date: str) -> dict:
    rate = RATES.get((currency.upper(), date))
    if rate is None:
        return {"error": f"No rate for {currency} on {date}"}
    return {"currency": currency.upper(), "date": date, "inr_rate": rate}


rate_tool = {
    "type": "function",
    "name": "lookup_exchange_rate",
    "description": "Look up the INR exchange rate for a currency on a date (YYYY-MM-DD).",
    "parameters": {
        "type": "object",
        "properties": {
            "currency": {"type": "string", "description": "ISO code, e.g. USD"},
            "date": {"type": "string", "description": "YYYY-MM-DD"},
        },
        "required": ["currency", "date"],
    },
}

# Turn 1: the model decides to call the tool
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What was the USD to INR exchange rate on 2026-08-03?",
    tools=[rate_tool],
)

fc_step = next(s for s in interaction.steps if s.type == "function_call")
print(f"Model requested: {fc_step.name}({fc_step.arguments})")

# Your code executes the function locally
result = lookup_exchange_rate(**fc_step.arguments)

# Turn 2: send the result back; tools must be re-specified (interaction-scoped)
final = client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input=[
        {
            "type": "function_result",
            "name": fc_step.name,
            "call_id": fc_step.id,
            "result": [{"type": "text", "text": json.dumps(result)}],
        }
    ],
    tools=[rate_tool],
)

print(final.output_text)

Đầu ra: 

3 điều đã xảy ra:  

1. Lượt 1 trả về một bước function_call với tên, đối số có cấu trúc, và một id.

2. Python của bạn chạy tra cứu.

3. Lượt 2 gửi một khối function_result tham chiếu đến lời gọi đó. 

Tham số tools được truyền lại ở lượt 2 vì cùng lý do response_format phải truyền lại ở phần PDF: previous_interaction_id mang lịch sử, không mang cấu hình.

Lỗi function-calling trên Gemini 3.x

Nếu vòng lặp công cụ hỏng, gần như luôn do 1 trong 2 nguyên nhân. 

Thứ nhất, mọi kết quả phải ánh xạ lại lời gọi của nó. Trên Interactions API, đó là call_id và name trên khối function_result; trên API kế thừa generateContent, FunctionResponse phải khớp id và name của FunctionCall liền trước. Cả hai đều không tùy chọn trên Gemini 3.x.

Thứ hai, lỗi Malformed_Function_Call thường xảy ra khi model phát ra bình luận trước khi gọi công cụ. Hướng dẫn nhà phát triển 3.8 của Google khuyên dọn sạch văn bản dẫn trước công cụ, định dạng hướng dẫn nội dòng với \n\n, và bọc ghi chú làm việc trong một lời gọi hàm riêng thay vì văn bản thô. Siết chặt system instruction; đừng retry mù quáng.

Những gì sẽ hỏng khi chuyển sang Gemini 3.8 Flash?

Tùy thuộc vào điểm xuất phát. 

• Từ Gemini 3.7 Flash: không gì cả. Thay chuỗi model thành gemini-3.8-flash, và mọi đoạn trong bài này chạy không chỉnh sửa, vì bề mặt API giống hệt. 

• Từ Gemini 3.6 Flash hoặc sớm hơn, cấu hình model cần cùng một cuộc kiểm tra 15 phút như trước.

Danh sách kiểm tra di trú (từ 3.6 Flash hoặc sớm hơn)

Thực hiện theo thứ tự. Mục 1 đến 3 gây lỗi 400 ngay; mục 4 và 5 gây vấn đề chất lượng âm thầm.

1. Đổi ID model thành gemini-3.8-flash.

2. Xóa tham số sampling đã chết: temperature, top_p, và top_k bị bỏ qua hoặc bị từ chối trên Gemini 3.x, và frequency_penalty, presence_penalty, candidate_count ném lỗi API chủ động. Loại cả 6 khỏi cấu hình kế thừa.

3. Thay thinking_budget bằng thinking_level: chỉ dùng low, medium, hoặc high. Giá trị minimal cũ trả về lỗi xác thực. Gửi cả thinking_budget và thinking_level trong một yêu cầu sẽ trả 400.

4. Xóa các lượt model được điền sẵn: loại chúng khỏi mọi hội thoại bạn dựng, và đảm bảo lượt người dùng cuối có văn bản không rỗng. Payload lịch sử không thể kết thúc bằng lượt model.

5. Chuẩn hóa luồng nhiều lượt: dựa vào previous_interaction_id thay vì phát lại lịch sử phía client. Bạn phải truyền lại tools, system_instruction, và generation_config ở mọi lượt cần chúng.

Google xuất bản phiên bản chuẩn trong tài liệu model Gemini API, gồm cả lộ trình tự động nếu tác nhân mã hóa của bạn hỗ trợ kỹ năng. Dẫu vậy, hãy tự đọc một lần; một di trú tự động sẽ không nói cho bạn biết vì sao temperature=0.2 lại có ở đó ngay từ đầu.

Lỗi bạn sẽ gặp trong sản xuất

Đây là 4 mã trạng thái đáng để nối handler, và ý nghĩa của mỗi mã trên API này:

Còn 2 điều nữa:

• Đặt timeout rõ ràng cho client khi kết hợp thinking_level: "high" với vòng lặp công cụ dài, vì request treo còn tệ hơn request lỗi, và sự cẩn trọng thêm của 3.8 khiến các lần suy luận dài có khả năng xảy ra hơn, không phải ít hơn. 

• Và log interaction.id với mọi yêu cầu; đó là tay cầm của bạn để truy xuất, gỡ lỗi, hoặc xóa các interaction lưu trữ sau này.

Kết luận

Mọi thứ trong bài này xuất phát từ 3 dịch chuyển. Interactions API thay đổi quy ước gọi, thinking_level thay thế mọi núm sampling bạn từng tinh chỉnh, và trạng thái phía máy chủ qua previous_interaction_id là điều biến câu hỏi tiếp theo về PDF và vòng lặp công cụ thành những lượt 1 dòng thay vì bài tập phát lại lịch sử. Gemini 3.8 Flash không đổi bề mặt đó; nó thay đổi mức độ làm việc bên trong, vì vậy các phép đo trong bài này được thực hiện mới trên 3.8 thay vì tái sử dụng từ 3.7.

Trước khi tin khuyến nghị về mức của tôi, hãy trỏ script so sánh vào một tác vụ trong backlog của chính bạn; mức thắng ở bài toán tranh chấp thử lại thanh toán có thể thua trên khối lượng tạo SQL của bạn. 

Khi những cuộc gọi API đơn lẻ không còn đủ và bạn muốn hệ thống AI sản xuất, lộ trình Associate AI Engineer for Developers của chúng tôi bao quát toàn bộ con đường, và lộ trình Associate AI Engineer for Data Scientists làm điều tương tự từ phía dữ liệu.