Đây là hướng dẫn toàn diện trình bày các chức năng và cấu hình có trong Live API. Hãy xem trang Bắt đầu sử dụng Live API để biết thông tin tổng quan và mã mẫu cho các trường hợp sử dụng phổ biến.
Trước khi bắt đầu
- Làm quen với các khái niệm cốt lõi: Nếu bạn chưa làm việc này, trước tiên hãy đọc trang Bắt đầu sử dụng Live API . Phần này sẽ giới thiệu cho bạn các nguyên tắc cơ bản của Live API, cách hoạt động và các phương pháp triển khai khác nhau.
- Dùng thử Live API trong AI Studio: Bạn có thể thấy việc dùng thử Live API trong Google AI Studio là hữu ích trước khi bắt đầu xây dựng. Để sử dụng Live API trong Google AI Studio, hãy chọn Stream (Phát trực tiếp).
So sánh mô hình
Bảng sau đây tóm tắt những điểm khác biệt chính giữa mô hình Gemini 3.1 Flash Live Preview và Gemini 2.5 Flash Live Preview:
| Tính năng | Bản xem trước trực tiếp Gemini 3.1 Flash | Bản xem trước trực tiếp Gemini 2.5 Flash |
|---|---|---|
| Tư duy | Sử dụng thinkingLevel để kiểm soát độ sâu tư duy bằng các chế độ cài đặt như minimal, low, medium và high. Mặc định là minimal để tối ưu hoá cho độ trễ thấp nhất. Xem phần Các cấp và ngân sách của chiến dịch suy nghĩ. |
Sử dụng thinkingBudget để đặt số lượng mã thông báo tư duy. Tính năng tư duy linh hoạt được bật theo mặc định. Đặt thinkingBudget thành 0 để tắt. Xem phần Các cấp và ngân sách của chiến dịch suy nghĩ. |
| Nhận phản hồi | Một sự kiện trên máy chủ có thể chứa nhiều phần nội dung cùng lúc (ví dụ: inlineData và bản chép lời). Đảm bảo mã của bạn xử lý tất cả các phần trong mỗi sự kiện để tránh bỏ lỡ nội dung. |
Mỗi sự kiện trên máy chủ chỉ chứa một phần nội dung. Các phần được phân phối trong các sự kiện riêng biệt. |
| Nội dung của khách hàng | send_client_content chỉ được hỗ trợ để gieo hạt nhật ký bối cảnh ban đầu (cần đặt initial_history_in_client_content trong cấu hình phiên). Để gửi tin nhắn văn bản trong cuộc trò chuyện, hãy sử dụng send_realtime_input. |
send_client_content được hỗ trợ trong suốt cuộc trò chuyện để gửi các bản cập nhật nội dung gia tăng và thiết lập ngữ cảnh. |
| Bật chế độ xem mức độ phù hợp | Giá trị mặc định là TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO. Lượt phản hồi của mô hình bao gồm hoạt động âm thanh được phát hiện và tất cả các khung hình video. |
Giá trị mặc định là TURN_INCLUDES_ONLY_ACTIVITY. Lượt phản hồi của mô hình chỉ bao gồm hoạt động được phát hiện. |
VAD tuỳ chỉnh (activity_start/activity_end) |
Được hỗ trợ. Tắt VAD tự động và gửi tin nhắn activityStart và activityEnd theo cách thủ công để kiểm soát ranh giới lượt lời. |
Được hỗ trợ. Tắt VAD tự động và gửi tin nhắn activityStart và activityEnd theo cách thủ công để kiểm soát ranh giới lượt lời. |
| Cấu hình VAD tự động | Được hỗ trợ. Định cấu hình các tham số như start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms và silence_duration_ms. |
Được hỗ trợ. Định cấu hình các tham số như start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms và silence_duration_ms. |
Gọi hàm không đồng bộ (behavior: NON_BLOCKING) |
Không được hỗ trợ. Chỉ có thể gọi hàm theo trình tự. Mô hình sẽ không bắt đầu phản hồi cho đến khi bạn gửi phản hồi của công cụ. | Được hỗ trợ. Đặt behavior thành NON_BLOCKING trong một khai báo hàm để cho phép mô hình tiếp tục tương tác trong khi hàm chạy. Kiểm soát cách mô hình xử lý các phản hồi bằng tham số scheduling (INTERRUPT, WHEN_IDLE hoặc SILENT). |
| Âm thanh chủ động | Không được hỗ trợ | Được hỗ trợ. Khi được bật, mô hình có thể chủ động quyết định không phản hồi nếu nội dung đầu vào không liên quan. Đặt proactive_audio thành true trong cấu hình proactivity (yêu cầu v1beta). |
| Đối thoại cảm xúc | Không được hỗ trợ | Được hỗ trợ. Mô hình sẽ điều chỉnh phong cách phản hồi cho phù hợp với cách diễn đạt và giọng điệu của câu lệnh đầu vào. Đặt enable_affective_dialog thành true trong cấu hình phiên (yêu cầu v1beta). |
Để di chuyển từ Gemini 2.5 Flash Live sang Gemini 3.1 Flash Live, hãy xem hướng dẫn di chuyển.
Thiết lập kết nối
Ví dụ sau đây minh hoạ cách tạo một kết nối bằng khoá API:
Python
import asyncio
from google import genai
client = genai.Client()
model = "gemini-3.1-flash-live-preview"
config = {"response_modalities": ["AUDIO"]}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
print("Session started")
# Send content...
if __name__ == "__main__":
asyncio.run(main())
JavaScript
import { GoogleGenAI, Modality } from '@google/genai';
const ai = new GoogleGenAI({});
const model = 'gemini-3.1-flash-live-preview';
const config = { responseModalities: [Modality.AUDIO] };
async function main() {
const session = await ai.live.connect({
model: model,
callbacks: {
onopen: function () {
console.debug('Opened');
},
onmessage: function (message) {
console.debug(message);
},
onerror: function (e) {
console.debug('Error:', e.message);
},
onclose: function (e) {
console.debug('Close:', e.reason);
},
},
config: config,
});
console.debug("Session started");
// Send content...
session.close();
}
main();
Phương thức tương tác
Các phần sau đây cung cấp ví dụ và bối cảnh hỗ trợ cho nhiều phương thức đầu vào và đầu ra có trong Live API.
Đang gửi âm thanh
Bạn cần gửi âm thanh dưới dạng dữ liệu PCM thô (âm thanh PCM thô 16 bit, 16 kHz, little-endian).
Python
# Assuming 'chunk' is your raw PCM audio bytes
await session.send_realtime_input(
audio=types.Blob(
data=chunk,
mime_type="audio/pcm;rate=16000"
)
)
JavaScript
// Assuming 'chunk' is a Buffer of raw PCM audio
session.sendRealtimeInput({
audio: {
data: chunk.toString('base64'),
mimeType: 'audio/pcm;rate=16000'
}
});
Định dạng âm thanh
Dữ liệu âm thanh trong Live API luôn là PCM 16 bit, little-endian, thô. Đầu ra âm thanh luôn sử dụng tốc độ lấy mẫu là 24 kHz. Âm thanh đầu vào vốn là 16 kHz, nhưng Live API sẽ lấy lại mẫu nếu cần, vì vậy, bạn có thể gửi bất kỳ tốc độ lấy mẫu nào. Để truyền tốc độ lấy mẫu của âm thanh đầu vào, hãy đặt loại MIME của mỗi Blob chứa âm thanh thành một giá trị như audio/pcm;rate=16000.
Nhận âm thanh
Các câu trả lời bằng âm thanh của mô hình được nhận dưới dạng các khối dữ liệu.