Google đã phát hành Gemini 3.1 Pro như là mô hình có khả năng nhất của họ cho đến nay. Các kỹ sư truy cập mô hình xem trước này thông qua Gemini API để giải quyết các tác vụ suy luận phức tạp, hiểu biết đa phương thức và quy trình làm việc tác nhân mà các thế hệ trước xử lý kém hiệu quả hơn. Các nhà phát triển tích hợp Gemini 3.1 Pro API đạt được hiệu suất hàng đầu với 1 triệu token đầu vào và 64 nghìn token đầu ra, đồng thời duy trì độ trễ thấp cho các hệ thống sản xuất.
Bạn bắt đầu hành trình của mình với mã định danh mô hình chính thức gemini-3.1-pro-preview. Google lưu trữ điểm cuối này tại https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent. API hỗ trợ cả lệnh gọi REST và các SDK chính thức giúp trừu tượng hóa sự phức tạp trong khi vẫn giữ toàn quyền kiểm soát.
Tìm hiểu Gemini 3.1 Pro: Các khả năng định nghĩa lại tích hợp AI
Gemini 3.1 Pro vượt xa các mô hình trước đây thông qua tư duy động tự nhiên, cải thiện việc sử dụng công cụ và hợp nhất đa phương thức vượt trội. Mô hình xử lý văn bản, hình ảnh độ phân giải cao, khung video, PDF lên đến 1000 trang và mã đồng thời trong cùng một cửa sổ ngữ cảnh. Do đó, các kỹ sư đạt được suy luận nhiều bước mạch lạc hơn mà không cần kỹ thuật prompt mở rộng.
Hơn nữa, mô hình giới thiệu cấu hình thinking_level. Bạn đặt tham số này thành high cho các tác vụ phân tích sâu hoặc low cho các kịch bản thông lượng cao. Mức high mặc định tự động kích hoạt các cơ chế chuỗi suy nghĩ nội bộ, giúp bạn tốn ít thời gian hơn để soạn các hướng dẫn suy luận rõ ràng.
Ngoài ra, Gemini 3.1 Pro hỗ trợ chữ ký tư duy (thought signatures). Các chuỗi được mã hóa này duy trì trạng thái hội thoại giữa các lượt khi bạn kết hợp gọi hàm với tạo hoặc chỉnh sửa hình ảnh. Bạn phải bao gồm giá trị thoughtSignature chính xác trong các yêu cầu tiếp theo; nếu không, API sẽ trả về lỗi 400. Cơ chế này đảm bảo hành vi xác định trong các vòng lặp tác nhân dài hạn.
Giới hạn kiến thức được đặt vào tháng 1 năm 2025. Do đó, bạn ghép nối mô hình với công cụ Google Search tích hợp sẵn để truy xuất thông tin mới. Sự kết hợp này mang lại các phản hồi có căn cứ, cập nhật mà không cần các pipeline tạo sinh tăng cường truy xuất thủ công.
Điều kiện tiên quyết để làm việc với Gemini 3.1 Pro API
Bạn chuẩn bị môi trường của mình trước khi viết bất kỳ mã nào. Đầu tiên, bạn cần một tài khoản Google có quyền truy cập vào Google AI Studio. Thứ hai, bạn xác minh rằng tính năng thanh toán đã được bật trên dự án Google Cloud được liên kết vì các mô hình xem trước áp dụng giới hạn tỷ lệ nghiêm ngặt trên các gói miễn phí. Thứ ba, bạn cài đặt Python 3.9+ hoặc Node.js 18+ tùy thuộc vào ngăn xếp ưa thích của bạn.
Hơn nữa, bạn phân bổ bộ nhớ cho các tải trọng đa phương thức lớn. Các tệp video và hình ảnh độ phân giải cao tiêu tốn token nhanh chóng, vì vậy bạn theo dõi mức sử dụng thông qua bảng điều khiển AI Studio. Các chuyên gia lập kế hoạch trước sẽ tránh được các lỗi hạn ngạch không mong muốn trong quá trình phát triển.
Lấy và bảo mật khóa API Gemini của bạn
Bạn điều hướng đến Google AI Studio và nhấp vào "Get API key". Bảng điều khiển tạo một khóa mới được liên kết với dự án của bạn. Bạn sao chép khóa ngay lập tức vì giao diện người dùng chỉ hiển thị khóa một lần duy nhất.
Bạn lưu trữ khóa dưới dạng biến môi trường GEMINI_API_KEY. Thực hành này giữ thông tin xác thực bên ngoài mã nguồn và cho phép khởi tạo SDK liền mạch trên các hệ điều hành. Trên Linux hoặc macOS, bạn chạy:
export GEMINI_API_KEY=your_actual_key_here
Trên Windows, bạn sử dụng:
set GEMINI_API_KEY=your_actual_key_here
Đối với các triển khai sản xuất, bạn xoay vòng khóa thường xuyên và hạn chế chúng thông qua các chính sách IAM của Google Cloud. Bạn không bao giờ để lộ khóa trong JavaScript phía client vì kẻ tấn công có thể lạm dụng nó để tiêu thụ token trái phép.
Cài đặt SDK GenAI chính thức của Google
SDK trừu tượng hóa các chi tiết HTTP và cung cấp các giao diện an toàn kiểu (type-safe). Bạn cài đặt phiên bản mới nhất bằng các lệnh sau:
Python
pip install -U google-genai
Node.js
npm install @google/genai
Gói này tự động đọc GEMINI_API_KEY từ môi trường. Nếu bạn thích cấu hình rõ ràng, bạn truyền khóa trong quá trình khởi tạo client. Tính linh hoạt này hỗ trợ cả phát triển cục bộ và môi trường container nơi các biến môi trường không thể thay đổi.
Thực hiện cuộc gọi đầu tiên đến Gemini 3.1 Pro API
Bạn khởi tạo client và gửi một lời nhắc văn bản đơn giản để xác minh kết nối.
Ví dụ Python
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-3.1-pro-preview",
contents="Giải thích sự khác biệt giữa Gemini 3.1 Pro và các mô hình trước đó theo thuật ngữ kỹ thuật.",
config=types.GenerateContentConfig(
thinking_level="high"
)
)
print(response.text)
Đối tượng phản hồi chứa văn bản được tạo cùng với siêu dữ liệu sử dụng. Bạn kiểm tra response.usage_metadata để theo dõi mức tiêu thụ token nhằm tối ưu hóa chi phí.
Tương đương cURL (Hữu ích cho kiểm thử Apidog)
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [{
"parts": [{"text": "Giải thích sự khác biệt giữa Gemini 3.1 Pro và các mô hình trước đó theo thuật ngữ kỹ thuật."}]
}],
"generationConfig": {
"thinking_level": "high"
}
}'
Bạn dán yêu cầu này trực tiếp vào Apidog. Nền tảng này phân tích cú pháp JSON, tô sáng cú pháp và cho phép bạn chuyển đổi giữa các môi trường với các khóa khác nhau. Do đó, bạn xác thực tiêu đề và tải trọng trước khi thực hiện thay đổi mã.
Ví dụ JavaScript
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const response = await ai.models.generateContent({
model: "gemini-3.1-pro-preview",
contents: "Giải thích sự khác biệt giữa Gemini 3.1 Pro và các mô hình trước đó theo thuật ngữ kỹ thuật.",
config: { thinking_level: "high" }
});
console.log(response.text);
}
main();
Bạn chạy các đoạn mã này và quan sát các câu trả lời mạch lạc, chính xác về mặt kỹ thuật. Mô hình tham chiếu các cải tiến kiến trúc như kiểm soát độ phân giải phương tiện nâng cao và điều phối công cụ tự nhiên.
Khám phá các điểm cuối cốt lõi và cấu trúc yêu cầu
Gemini API tập trung vào ba phương thức chính: generateContent, streamGenerateContent và countTokens. Bạn sử dụng generateContent cho các phản hồi đồng bộ và streamGenerateContent khi bạn hiển thị đầu ra một phần cho người dùng ngay lập tức.
Thân yêu cầu tuân theo một cấu trúc nhất quán:
contents: Mảng các tin nhắn dựa trên vai trò (người dùng/mô hình/hàm)tools: Mảng khai báo Google Search, code_execution hoặc hàm tùy chỉnhgenerationConfig: Kiểm soát thinking_level, nhiệt độ (giữ mặc định 1.0), maxOutputTokens, v.v.safetySettings: Ghi đè tùy chọn cho các bộ lọc nội dung
Bạn định nghĩa các hàm tùy chỉnh bằng lược đồ JSON. Sau đó, mô hình sẽ phát ra các phần functionCall mà bạn thực thi cục bộ và trả về dưới dạng các phần functionResponse. Vòng lặp đóng này cung cấp năng lượng cho các tác nhân tự trị tương tác với các API hoặc cơ sở dữ liệu bên ngoài.
Apidog vượt trội ở đây vì bạn nhập thông số kỹ thuật OpenAPI hoặc tự xây dựng lược đồ. Công cụ này xác thực các khai báo hàm của bạn so với định dạng mong đợi của mô hình và thậm chí mô phỏng các phản hồi trong thời gian thiết kế.
Cấu hình các tham số tạo sinh cho độ tin cậy sản xuất
Bạn điều chỉnh hành vi thông qua đối tượng generationConfig. Google khuyên nên giữ temperature ở mức 1.0 vì các giá trị thấp hơn làm giảm chất lượng suy luận trong các mô hình dòng Gemini 3. Thay vào đó, bạn điều chỉnh thinking_level để cân bằng độ trễ và độ sâu.
Các tham số chính bao gồm:
thinking_level: "low" | "high" (mặc định high)maxOutputTokens: tối đa 64 nghìnstopSequences: Mảng các chuỗi dừng việc tạo sinhresponseMimeType: "application/json" cho đầu ra có cấu trúcresponseJsonSchema: Lược đồ Pydantic hoặc Zod để phân tích cú pháp an toàn kiểu
Bạn kết hợp các đầu ra có cấu trúc với các công cụ để trích xuất JSON sạch từ tìm kiếm trên web hoặc thực thi mã. Ví dụ: bạn yêu cầu danh sách các tùy chọn chuyến bay, nhận các đối tượng được phân tích cú pháp và đưa chúng trực tiếp vào logic backend của bạn mà không cần biểu thức chính quy hoặc phân tích cú pháp thủ công.
Khai thác khả năng đa phương thức
Gemini 3.1 Pro xử lý hình ảnh, video và tài liệu một cách tự nhiên. Bạn bao gồm dữ liệu tệp dưới dạng base64 nội tuyến hoặc thông qua File API cho các tải lên lớn hơn.
Ví dụ đa phương thức Python
import base64
from google import genai
from google.genai import types
client = genai.Client()
# Read image
with open("diagram.png", "rb") as f:
image_bytes = f.read()
response = client.models.generate_content(
model="gemini-3.1-pro-preview",
contents=[
types.Content(
role="user",
parts=[
types.Part(text="Phân tích sơ đồ kiến trúc hệ thống này và đề xuất các tối ưu hóa."),
types.Part(
inline_data=types.Blob(
mime_type="image/png",
data=image_bytes
)
)
]
)
],
config=types.GenerateContentConfig(
media_resolution="media_resolution_high" # v1alpha endpoint if needed
)
)
print(response.text)
Bạn tải video lên bằng cách trích xuất khung hình hoặc gửi các clip ngắn trực tiếp. Mô hình hiểu các chuỗi thời gian và trả lời các câu hỏi về hành động trên các khung hình. Do đó, các chuyên gia xây dựng các công cụ phân tích video mà không cần các pipeline thị giác máy tính riêng biệt.
Apidog đơn giản hóa các thử nghiệm này. Bạn kéo và thả các tệp hình ảnh hoặc PDF vào thân yêu cầu, chọn loại MIME chính xác và gửi yêu cầu ngay lập tức. Nền tảng hiển thị các bản xem trước được hiển thị và cho phép bạn lặp lại các prompt mà không cần viết lại mã.
Triển khai gọi hàm và sử dụng công cụ
Bạn khai báo các công cụ trong cấu hình để bật hành vi tác nhân. Các công cụ tích hợp sẵn được hỗ trợ bao gồm google_search, code_execution, url_context và các hàm tùy chỉnh.
Ví dụ công cụ có cấu trúc
from pydantic import BaseModel, Field
from typing import List
class WeatherData(BaseModel):
city: str = Field(description="Tên thành phố")
temperature: float
condition: str
response = client.models.generate_content(
model="gemini-3.1-pro-preview",
contents="Lấy thời tiết hiện tại cho Tokyo và trả về dữ liệu có cấu trúc.",
config={
"tools": [{"google_search": {}}],
"response_mime_type": "application/json",
"response_json_schema": WeatherData.model_json_schema()
}
)
data = WeatherData.model_validate_json(response.text)
print(data)
Mô hình gọi công cụ tìm kiếm nội bộ, xử lý kết quả và trả về JSON đã được xác thực. Bạn nối chuỗi nhiều công cụ qua các lượt để tạo các tác nhân tinh vi có thể đặt chuyến đi, phân tích báo cáo hoặc kiểm soát các hệ thống bên ngoài.
Chữ ký tư duy đảm bảo tính liên tục. Bạn sao chép chữ ký từ mỗi phản hồi của mô hình và bao gồm nó trong tin nhắn người dùng tiếp theo khi có các lệnh gọi hàm. Yêu cầu này ngăn chặn sự trôi ngữ cảnh trong các cuộc hội thoại dài.
Kiểm thử và gỡ lỗi hiệu quả với Apidog
Bạn mở Apidog và tạo một dự án mới có tên “Gemini 3.1 Pro Integration.” Bạn thêm một biến toàn cục cho khóa API của mình và đặt URL cơ sở thành điểm cuối ngôn ngữ tạo sinh.
Tiếp theo, bạn tạo một bộ sưu tập cho các kịch bản khác nhau: chỉ văn bản, đa phương thức, gọi hàm và truyền trực tuyến. Apidog tự động tạo các đoạn mã cURL, Python và JavaScript từ mỗi yêu cầu đã lưu. Do đó, bạn duy trì một bộ tài liệu sống mà toàn bộ nhóm có thể tham khảo.
Khi bạn nhận được lỗi, Apidog làm nổi bật chính xác tiêu đề hoặc trường tải trọng đã gây ra sự cố. Bạn so sánh các phản hồi song song giữa các phiên bản mô hình hoặc mức độ tư duy. Nền tảng này cũng ghi lại lịch sử yêu cầu với dấu thời gian và mức sử dụng token, giúp bạn xây dựng các mô hình chi phí chính xác trước khi triển khai sản xuất.
Các chuyên gia tích hợp Apidog báo cáo chu kỳ lặp lại nhanh hơn 40-60% vì họ loại bỏ việc chuyển đổi ngữ cảnh giữa các trình chỉnh sửa mã và cửa sổ terminal. Gói miễn phí hỗ trợ các dự án cục bộ không giới hạn và khối lượng yêu cầu đủ cho hầu hết các quy trình phát triển.
Các kỹ thuật nâng cao: Truyền trực tuyến, lưu trữ ngữ cảnh và xử lý hàng loạt
Bạn bật truyền trực tuyến cho các giao diện người dùng phản hồi nhanh.
Truyền trực tuyến Python
response = client.models.generate_content(
model="gemini-3.1-pro-preview",
contents="Viết một thông số kỹ thuật chi tiết cho một dịch vụ vi mô mới.",
stream=True
)
for chunk in response:
print(chunk.text, end="", flush=True)
SDK trả về các phản hồi một phần để bạn hiển thị văn bản khi nó đến.
Bạn cũng sử dụng bộ nhớ đệm ngữ cảnh cho các tài liệu dài lặp lại. Bạn tải lên một PDF 500 trang một lần, lưu trữ ngữ cảnh đã xử lý và tham chiếu ID bộ nhớ đệm trong các lệnh gọi tiếp theo. Kỹ thuật này giảm đáng kể chi phí token và độ trễ cho các ứng dụng RAG doanh nghiệp.
Hỗ trợ Batch API cho phép bạn xử lý nhiều lời nhắc trong một yêu cầu duy nhất. Do đó, bạn phân tích hàng nghìn vé hỗ trợ qua đêm trong khi vẫn nằm trong giới hạn tỷ lệ.
Các trường hợp sử dụng thực tế và ví dụ mã sẵn sàng cho sản xuất
Trường hợp sử dụng 1: Phân tích tài liệu thông minh
Bạn xây dựng một hệ thống thu thập hợp đồng, trích xuất các điều khoản và gắn cờ rủi ro. Khả năng đa phương thức xác định các bảng và chữ ký trong các tệp PDF được quét.
Trường hợp sử dụng 2: Trợ lý mã hóa tự động
Bạn kết hợp công cụ code_execution với Gemini 3.1 Pro để gỡ lỗi, tái cấu trúc và kiểm tra mã trong một vòng lặp duy nhất. Mô hình viết Python, thực thi nó, kiểm tra hình ảnh hoặc nhật ký đầu ra và lặp lại cho đến khi tác vụ hoàn thành.
Trường hợp sử dụng 3: Tác nhân hỗ trợ khách hàng đa phương thức
Người dùng tải lên ảnh chụp màn hình lỗi. Tác nhân phân tích hình ảnh, tìm kiếm cơ sở kiến thức và trả về các bản sửa lỗi từng bước với ảnh chụp màn hình có chú thích được tạo thông qua mô hình hình ảnh.
Mỗi trường hợp sử dụng đều được hưởng lợi từ các nguyên mẫu Apidog. Bạn thiết kế cấu trúc tải trọng chính xác, kiểm tra các trường hợp biên với các tệp mẫu và xuất mã sẵn sàng sử dụng.
Các phương pháp hay nhất để kiểm soát chi phí và hiệu suất
Bạn giám sát mức sử dụng token sau mỗi cuộc gọi. Bạn đặt maxOutputTokens một cách thận trọng và sử dụng điểm cuối countTokens trước các hoạt động tốn kém. Bạn chỉ ưu tiên gemini-3.1-pro-preview cho các tác vụ phức tạp và chuyển các truy vấn đơn giản hơn sang các biến thể nhẹ hơn khi có sẵn.
Bạn triển khai lùi lũy thừa (exponential backoff) cho các lỗi giới hạn tỷ lệ. Bạn lưu trữ các phản hồi thường xuyên cục bộ hoặc thông qua Redis. Bạn luôn xác thực các đầu ra có cấu trúc bằng Pydantic hoặc các thư viện tương đương để phát hiện sự trôi lược đồ (schema drift) sớm.
Bảo mật vẫn là tối quan trọng. Bạn làm sạch đầu vào của người dùng trước khi gửi chúng đến mô hình. Bạn áp dụng cài đặt an toàn nội dung phù hợp với lĩnh vực của bạn. Bạn chỉ ghi nhật ký các số liệu sử dụng ẩn danh.
Khắc phục sự cố thường gặp
Lỗi 429 (Tài nguyên cạn kiệt) xuất hiện khi bạn vượt quá hạn ngạch. Bạn kiểm tra bảng điều khiển sử dụng AI Studio và yêu cầu giới hạn cao hơn thông qua hỗ trợ của Google Cloud.
Lỗi 400 (Đối số không hợp lệ) thường bắt nguồn từ việc thiếu chữ ký tư duy trong các lệnh gọi hàm đa lượt. Bạn xác minh rằng mỗi chữ ký phản hồi của mô hình được truyền lại trong yêu cầu tiếp theo.
Các yêu cầu đa phương thức không thành công khi kích thước tệp vượt quá giới hạn. Bạn nén hình ảnh hoặc sử dụng File API để lưu trữ liên tục.
Apidog giúp cô lập các vấn đề này vì bạn có thể phát lại các yêu cầu không thành công với các tham số đã sửa đổi ngay lập tức. Trình xác thực tích hợp sẵn sẽ gắn cờ các vấn đề về lược đồ trước cả khi bạn chạy mã.
So sánh Gemini API với Vertex AI
API dành cho nhà phát triển Gemini (ai.google.dev) cung cấp khả năng bắt đầu nhanh nhất và truy cập miễn phí. Vertex AI cung cấp các tính năng cấp doanh nghiệp như VPC Service Controls, các điểm cuối riêng tư và tích hợp IAM chặt chẽ hơn. Bạn di chuyển từ cái này sang cái kia bằng cách chỉ thay đổi khởi tạo client và điểm cuối mô hình. Các định dạng yêu cầu vẫn giống hệt nhau.
Hầu hết các nhóm bắt đầu với API dành cho nhà phát triển trong quá trình tạo nguyên mẫu và chuyển sang Vertex AI trước khi sản xuất. Quá trình chuyển đổi yêu cầu thay đổi mã tối thiểu.
Kết luận
Giờ đây bạn đã sở hữu một lộ trình kỹ thuật hoàn chỉnh cho Gemini 3.1 Pro API. Bạn hiểu rõ các khả năng của mô hình, luồng xác thực, tích hợp SDK, cấu hình nâng cao, đầu vào đa phương thức, điều phối công cụ và các phương pháp hay nhất trong sản xuất.
Sự kết hợp giữa sức mạnh suy luận của Gemini 3.1 Pro và môi trường kiểm thử trực quan của Apidog cho phép bạn triển khai các tính năng AI tinh vi nhanh hơn bao giờ hết. Bạn bắt đầu nhỏ với các lời nhắc văn bản, mở rộng sang các tác nhân đa phương thức và mở rộng quy mô một cách tự tin với các chiến lược giám sát và bộ nhớ đệm.
Lĩnh vực này phát triển nhanh chóng. Bạn hãy đánh dấu tài liệu chính thức tại ai.google.dev và thường xuyên truy cập lại dự án Apidog để tích hợp các tính năng mới.
Bạn đã có tất cả những gì cần thiết để xây dựng thế hệ ứng dụng thông minh tiếp theo. Hãy bắt đầu mã hóa ngay hôm nay, kiểm thử kỹ lưỡng với Apidog và đẩy lùi giới hạn của những gì AI có thể đạt được.
Hãy bắt đầu xây dựng với Gemini 3.1 Pro API ngay bây giờ. Tải xuống Apidog miễn phí và thay đổi cách bạn phát triển và kiểm thử các tích hợp AI.