Hướng dẫn cho nhà phát triển Gemini 3

Gemini 3 là nhóm mô hình thông minh nhất của chúng tôi cho đến nay, được xây dựng dựa trên nền tảng suy luận tiên tiến. Công cụ này được thiết kế để hiện thực hoá mọi ý tưởng bằng cách thành thạo quy trình làm việc dựa trên tác nhân, lập trình tự động và các tác vụ đa phương thức phức tạp. Hướng dẫn này trình bày các tính năng chính của họ mô hình Gemini 3 và cách khai thác tối đa mô hình này.

Tư duy cấp cao/linh hoạt Tư duy cấp thấp

Theo mặc định, Gemini 3 Pro sử dụng tư duy linh hoạt để suy luận thông qua các câu lệnh. Để có câu trả lời nhanh hơn và có độ trễ thấp hơn khi không cần suy luận phức tạp, bạn có thể giới hạn mức độ suy nghĩ của mô hình ở low.

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
)

print(response.text)

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
  });

  console.log(response.text);
}

run();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Find the race condition in this multi-threaded C++ snippet: [code here]"}]
    }]
  }'

Khám phá

Khám phá bộ sưu tập các ứng dụng Gemini 3 để xem cách mô hình này xử lý khả năng lập luận nâng cao, lập trình tự động và các nhiệm vụ phức tạp có nhiều phương thức.

Làm quen với Gemini 3

Gemini 3 Pro là mô hình đầu tiên trong dòng mô hình mới. gemini-3-pro-preview phù hợp nhất với những nhiệm vụ phức tạp đòi hỏi kiến thức rộng lớn về thế giới và khả năng suy luận nâng cao trên nhiều phương thức.

* Giá được tính cho mỗi 1 triệu mã thông báo. Giá niêm yết là giá cho văn bản tiêu chuẩn; giá cho chế độ nhập đa phương thức có thể khác.

Để biết giới hạn tốc độ chi tiết, giá theo lô và thông tin bổ sung, hãy xem trang mô hình.

Các tính năng mới của API trong Gemini 3

Gemini 3 giới thiệu các thông số mới được thiết kế để giúp nhà phát triển kiểm soát độ trễ, chi phí và độ trung thực đa phương thức tốt hơn.

Cấp độ tư duy

Tham số thinking_level kiểm soát độ sâu tối đa của quy trình suy luận nội bộ của mô hình trước khi mô hình tạo ra một phản hồi. Gemini 3 coi những cấp độ này là hạn mức tương đối cho việc suy nghĩ thay vì đảm bảo nghiêm ngặt về số lượng mã thông báo. Nếu bạn không chỉ định thinking_level, Gemini 3 Pro sẽ mặc định là high.

• low: Giảm thiểu độ trễ và chi phí. Phù hợp nhất với các ứng dụng có hướng dẫn đơn giản, trò chuyện hoặc có thông lượng cao
• medium: (Sắp ra mắt), không được hỗ trợ khi ra mắt
• high (Mặc định): Tối đa hoá độ sâu suy luận. Mô hình có thể mất nhiều thời gian hơn đáng kể để đạt được mã thông báo đầu tiên, nhưng đầu ra sẽ được lý luận cẩn thận hơn.

Độ phân giải của nội dung nghe nhìn

Gemini 3 giới thiệu khả năng kiểm soát chi tiết đối với quy trình xử lý hình ảnh đa phương thức thông qua tham số media_resolution. Độ phân giải cao hơn giúp cải thiện khả năng đọc văn bản nhỏ hoặc xác định các chi tiết nhỏ của mô hình, nhưng làm tăng mức sử dụng mã thông báo và độ trễ. Tham số media_resolution xác định số lượng mã thông báo tối đa được phân bổ cho mỗi khung hình đầu vào của hình ảnh hoặc video.

Giờ đây, bạn có thể đặt độ phân giải thành media_resolution_low, media_resolution_medium hoặc media_resolution_high cho từng phần nội dung nghe nhìn hoặc trên toàn cầu (thông qua generation_config). Nếu không chỉ định, mô hình sẽ sử dụng các giá trị mặc định tối ưu dựa trên loại nội dung nghe nhìn.

Chế độ cài đặt được đề xuất

from google import genai
from google.genai import types
import base64

# The media_resolution parameter is currently only available in the v1alpha API version.
client = genai.Client(http_options={'api_version': 'v1alpha'})

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents=[
        types.Content(
            parts=[
                types.Part(text="What is in this image?"),
                types.Part(
                    inline_data=types.Blob(
                        mime_type="image/jpeg",
                        data=base64.b64decode("..."),
                    ),
                    media_resolution={"level": "media_resolution_high"}
                )
            ]
        )
    ]
)

print(response.text)

import { GoogleGenAI } from "@google/genai";

// The media_resolution parameter is currently only available in the v1alpha API version.
const ai = new GoogleGenAI({ apiVersion: "v1alpha" });

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: [
      {
        parts: [
          { text: "What is in this image?" },
          {
            inlineData: {
              mimeType: "image/jpeg",
              data: "...",
            },
            mediaResolution: {
              level: "media_resolution_high"
            }
          }
        ]
      }
    ]
  });

  console.log(response.text);
}

run();

curl "https://generativelanguage.googleapis.com/v1alpha/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        { "text": "What is in this image?" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "..."
          },
          "mediaResolution": {
            "level": "media_resolution_high"
          }
        }
      ]
    }]
  }'

Nhiệt độ

Đối với Gemini 3, bạn nên giữ thông số nhiệt độ ở giá trị mặc định là 1.0.

Mặc dù các mô hình trước đây thường được hưởng lợi từ việc điều chỉnh nhiệt độ để kiểm soát tính sáng tạo so với tính xác định, nhưng khả năng suy luận của Gemini 3 được tối ưu hoá cho chế độ cài đặt mặc định. Việc thay đổi nhiệt độ (đặt nhiệt độ dưới 1.0) có thể dẫn đến hành vi không mong muốn, chẳng hạn như lặp lại hoặc giảm hiệu suất, đặc biệt là trong các nhiệm vụ phức tạp về toán học hoặc lý luận.

Chữ ký của suy nghĩ

Gemini 3 sử dụng Chữ ký suy luận để duy trì ngữ cảnh suy luận trong các lệnh gọi API. Các chữ ký này là biểu thị được mã hoá của quy trình suy nghĩ nội bộ của mô hình. Để đảm bảo mô hình duy trì khả năng suy luận, bạn phải trả lại các chữ ký này cho mô hình trong yêu cầu của mình đúng như khi nhận được:

• Gọi hàm (Nghiêm ngặt): API thực thi quy trình xác thực nghiêm ngặt đối với "Lượt hiện tại". Nếu thiếu chữ ký, bạn sẽ gặp lỗi 400.
• Văn bản/Trò chuyện: Chúng tôi không bắt buộc xác thực, nhưng việc bỏ qua chữ ký sẽ làm giảm khả năng lập luận và chất lượng câu trả lời của mô hình.

Gọi hàm (xác thực nghiêm ngặt)

Khi Gemini tạo một functionCall, Gemini sẽ dựa vào thoughtSignature để xử lý chính xác đầu ra của công cụ trong lượt tiếp theo. "Lượt hiện tại" bao gồm tất cả các bước của Mô hình (functionCall) và Người dùng (functionResponse) đã diễn ra kể từ tin nhắn Người dùng text tiêu chuẩn gần đây nhất.

• Lệnh gọi một hàm: Phần functionCall chứa một chữ ký. Bạn phải trả lại thiết bị.
• Lệnh gọi hàm song song: Chỉ phần functionCall đầu tiên trong danh sách sẽ chứa chữ ký. Bạn phải trả lại các bộ phận theo đúng thứ tự đã nhận.
• Nhiều bước (Tuần tự): Nếu mô hình gọi một công cụ, nhận được kết quả và gọi một công cụ khác (trong cùng một lượt), thì cả hai lệnh gọi hàm đều có chữ ký. Bạn phải trả về tất cả chữ ký tích luỹ trong nhật ký.

Văn bản và truyền trực tuyến

Đối với tính năng trò chuyện hoặc tạo văn bản thông thường, chúng tôi không đảm bảo sẽ có chữ ký.

• Không truyền trực tuyến: Phần nội dung cuối cùng của phản hồi có thể chứa thoughtSignature, mặc dù không phải lúc nào cũng có. Nếu có một giá trị được trả về, bạn nên gửi giá trị đó trở lại để duy trì hiệu suất tốt nhất.
• Phát trực tuyến: Nếu được tạo, chữ ký có thể xuất hiện trong một đoạn cuối cùng chứa phần văn bản trống. Đảm bảo trình phân tích cú pháp luồng của bạn kiểm tra chữ ký ngay cả khi trường văn bản trống.

Ví dụ về mã

// Model Response (Turn 1, Step 1)
  {
    "role": "model",
    "parts": [
      {
        "functionCall": { "name": "check_flight", "args": {...} },
        "thoughtSignature": "<Sig_A>" // SAVE THIS
      }
    ]
  }

// User Request (Turn 1, Step 2)
[
  { "role": "user", "parts": [{ "text": "Check flight AA100..." }] },
  { 
    "role": "model", 
    "parts": [
      { 
        "functionCall": { "name": "check_flight", "args": {...} }, 
        "thoughtSignature": "<Sig_A>" // REQUIRED
      } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": { "name": "check_flight", "response": {...} } }] }
]

// Model Response (Turn 1, Step 3)
{
  "role": "model",
  "parts": [
    {
      "functionCall": { "name": "book_taxi", "args": {...} },
      "thoughtSignature": "<Sig_B>" // SAVE THIS
    }
  ]
}

// User Request (Turn 1, Step 4)
[
  // ... previous history ...
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "check_flight", ... }, "thoughtSignature": "<Sig_A>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] },
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "book_taxi", ... }, "thoughtSignature": "<Sig_B>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] }
]

// User Request (Sending Parallel Results)
[
  {
    "role": "user",
    "parts": [
      { "text": "Check the weather in Paris and London." }
    ]
  },
  {
    "role": "model",
    "parts": [
      // 1. First Function Call has the signature
      {
        "functionCall": { "name": "check_weather", "args": { "city": "Paris" } },
        "thoughtSignature": "<Signature_A>" 
      },
      // 2. Subsequent parallel calls DO NOT have signatures
      {
        "functionCall": { "name": "check_weather", "args": { "city": "London" } }
      } 
    ]
  },
  {
    "role": "user",
    "parts": [
      // 3. Function Responses are grouped together in the next block
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "15C" } }
      },
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "12C" } }
      }
    ]
  }
]

// User Request (Follow-up question)
[
  { 
    "role": "user", 
    "parts": [{ "text": "What are the risks of this investment?" }] 
  },
  { 
    "role": "model", 
    "parts": [
      {
        "text": "I need to calculate the risk step-by-step. First, I'll look at volatility...",
        "thoughtSignature": "<Signature_C>" // Recommended to include
      }
    ]
  },
  { 
    "role": "user", 
    "parts": [{ "text": "Summarize that in one sentence." }] 
  }
]

Di chuyển từ các mô hình khác

Nếu bạn đang chuyển dấu vết của cuộc trò chuyện từ một mô hình khác (ví dụ: Gemini 2.5) hoặc chèn một lệnh gọi hàm tuỳ chỉnh không phải do Gemini 3 tạo, bạn sẽ không có chữ ký hợp lệ.

Để bỏ qua quy trình xác thực nghiêm ngặt trong những trường hợp cụ thể này, hãy điền vào trường chuỗi giả cụ thể sau: "thoughtSignature": "context_engineering_is_the_way_to_go"

Kết quả có cấu trúc bằng các công cụ

Gemini 3 cho phép bạn kết hợp Đầu ra có cấu trúc với các công cụ tích hợp, bao gồm Căn cứ vào Google Tìm kiếm, Ngữ cảnh URL và Thực thi mã.

from google import genai
from google.genai import types
from pydantic import BaseModel, Field
from typing import List

class MatchResult(BaseModel):
    winner: str = Field(description="The name of the winner.")
    final_match_score: str = Field(description="The final match score.")
    scorers: List[str] = Field(description="The name of the scorer.")

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Search for all details for the latest Euro.",
    config={
        "tools": [
            {"google_search": {}},
            {"url_context": {}}
        ],
        "response_mime_type": "application/json",
        "response_json_schema": MatchResult.model_json_schema(),
    },  
)

result = MatchResult.model_validate_json(response.text)
print(result)

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ai = new GoogleGenAI({});

const matchSchema = z.object({
  winner: z.string().describe("The name of the winner."),
  final_match_score: z.string().describe("The final score."),
  scorers: z.array(z.string()).describe("The name of the scorer.")
});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: "Search for all details for the latest Euro.",
    config: {
      tools: [
        { googleSearch: {} },
        { urlContext: {} }
      ],
      responseMimeType: "application/json",
      responseJsonSchema: zodToJsonSchema(matchSchema),
    },
  });

  const match = matchSchema.parse(JSON.parse(response.text));
  console.log(match);
}

run();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Search for all details for the latest Euro."}]
    }],
    "tools": [
      {"googleSearch": {}},
      {"urlContext": {}}
    ],
    "generationConfig": {
        "responseMimeType": "application/json",
        "responseJsonSchema": {
            "type": "object",
            "properties": {
                "winner": {"type": "string", "description": "The name of the winner."},
                "final_match_score": {"type": "string", "description": "The final score."},
                "scorers": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "The name of the scorer."
                }
            },
            "required": ["winner", "final_match_score", "scorers"]
        }
    }
  }'

Di chuyển từ Gemini 2.5

Gemini 3 là dòng mô hình mạnh mẽ nhất của chúng tôi cho đến nay và có những bước cải tiến so với Gemini 2.5 Pro. Khi di chuyển, hãy cân nhắc những điều sau:

• Tư duy: Nếu trước đây bạn đang sử dụng kỹ thuật tạo câu lệnh phức tạp (chẳng hạn như Chuỗi suy luận) để buộc Gemini 2.5 suy luận, hãy thử Gemini 3 với thinking_level: "high" và câu lệnh đơn giản.
• Chế độ cài đặt nhiệt độ: Nếu mã hiện tại của bạn đặt nhiệt độ một cách rõ ràng (đặc biệt là ở giá trị thấp cho đầu ra xác định), thì bạn nên xoá tham số này và sử dụng giá trị mặc định 1.0 của Gemini 3 để tránh các vấn đề tiềm ẩn về vòng lặp hoặc hiệu suất giảm sút đối với các tác vụ phức tạp.
• Hiểu tệp PDF và tài liệu: Độ phân giải OCR mặc định cho tệp PDF đã thay đổi. Nếu bạn dựa vào hành vi cụ thể để phân tích cú pháp tài liệu dày đặc, hãy kiểm thử chế độ cài đặt media_resolution_high mới để đảm bảo độ chính xác liên tục.
• Mức tiêu thụ mã thông báo: Việc di chuyển sang Gemini 3 Pro mặc định có thể tăng mức sử dụng mã thông báo cho tệp PDF nhưng giảm mức sử dụng mã thông báo cho video. Nếu các yêu cầu hiện vượt quá cửa sổ ngữ cảnh do độ phân giải mặc định cao hơn, bạn nên giảm rõ ràng độ phân giải của nội dung nghe nhìn.
• Phân đoạn hình ảnh: Gemini 3 Pro không hỗ trợ các chức năng phân đoạn hình ảnh (trả về mặt nạ ở cấp độ pixel cho các đối tượng). Đối với những khối lượng công việc yêu cầu phân đoạn hình ảnh gốc, bạn nên tiếp tục sử dụng Gemini 2.5 Flash khi đã tắt tính năng suy luận hoặc Gemini Robotics-ER 1.5.

Khả năng tương thích với OpenAI

Đối với những người dùng sử dụng lớp tương thích OpenAI, các tham số tiêu chuẩn sẽ tự động được liên kết với các tham số tương đương của Gemini:

• reasoning_effort (OAI) tương ứng với thinking_level (Gemini). Lưu ý rằng reasoning_effort trung bình sẽ ánh xạ đến thinking_level cao.

Các phương pháp hay nhất để đưa ra câu lệnh

Gemini 3 là một mô hình suy luận, do đó bạn cần thay đổi cách đưa ra câu lệnh.

• Hướng dẫn chính xác: Nhập câu lệnh một cách ngắn gọn. Gemini 3 phản hồi tốt nhất khi nhận được chỉ dẫn trực tiếp và rõ ràng. Công cụ này có thể phân tích quá mức các kỹ thuật tạo câu lệnh dài dòng hoặc quá phức tạp được dùng cho các mô hình cũ.
• Mức độ chi tiết của câu trả lời: Theo mặc định, Gemini 3 ít chi tiết hơn và ưu tiên cung cấp câu trả lời trực tiếp, hiệu quả. Nếu trường hợp sử dụng của bạn yêu cầu một nhân cách trò chuyện hoặc "hay trò chuyện" hơn, bạn phải hướng dẫn rõ ràng cho mô hình trong câu lệnh (ví dụ: "Giải thích điều này với vai trò là một trợ lý thân thiện và hay trò chuyện").
• Quản lý bối cảnh: Khi làm việc với các tập dữ liệu lớn (ví dụ: toàn bộ sách, cơ sở mã hoặc video dài), hãy đặt hướng dẫn hoặc câu hỏi cụ thể của bạn ở cuối câu lệnh, sau bối cảnh dữ liệu. Cố định lập luận của mô hình vào dữ liệu được cung cấp bằng cách bắt đầu câu hỏi bằng một cụm từ như "Dựa trên thông tin ở trên...".

Tìm hiểu thêm về các chiến lược thiết kế câu lệnh trong hướng dẫn kỹ thuật tạo câu lệnh.

Câu hỏi thường gặp

1. Thời điểm ngừng cập nhật kiến thức của Gemini 3 Pro là khi nào? Gemini 3 có thời điểm ngừng cập nhật kiến thức là tháng 1 năm 2025. Để biết thông tin mới nhất, hãy sử dụng công cụ Căn cứ tìm kiếm.

2. Hạn mức cửa sổ ngữ cảnh là bao nhiêu? Gemini 3 Pro hỗ trợ cửa sổ ngữ cảnh đầu vào 1 triệu token và đầu ra tối đa 64.000 token.

3. Gemini 3 Pro có gói miễn phí không? Bạn có thể dùng thử mô hình này miễn phí trong Google AI Studio, nhưng hiện tại, Gemini API không có cấp miễn phí cho gemini-3-pro-preview.

4. Mã thinking_budget cũ của tôi có còn hoạt động không? Có, thinking_budget vẫn được hỗ trợ để đảm bảo khả năng tương thích ngược, nhưng bạn nên di chuyển sang thinking_level để có hiệu suất dễ dự đoán hơn. Không sử dụng cả hai trong cùng một yêu cầu.

5. Gemini 3 có hỗ trợ Batch API không? Có, Gemini 3 hỗ trợ Batch API.

6. Context Caching có được hỗ trợ không? Có, Gemini 3 có hỗ trợ tính năng Lưu vào bộ nhớ đệm theo bối cảnh. Số lượng mã thông báo tối thiểu cần thiết để bắt đầu lưu vào bộ nhớ đệm là 2.048 mã thông báo.

7. Gemini 3 hỗ trợ những công cụ nào? Gemini 3 hỗ trợ Google Tìm kiếm, Tìm kiếm tệp, Thực thi mã và Ngữ cảnh URL. Công cụ này cũng hỗ trợ tính năng Gọi hàm tiêu chuẩn cho các công cụ tuỳ chỉnh của riêng bạn. Xin lưu ý rằng Google Maps và Computer Use hiện không được hỗ trợ.

Các bước tiếp theo

• Bắt đầu sử dụng Sổ tay Gemini 3
• Hãy xem hướng dẫn chuyên biệt về các cấp độ tư duy trong Sổ tay và cách di chuyển từ ngân sách tư duy sang các cấp độ tư duy.