API Trực tiếp cho phép tương tác bằng giọng nói và video hai chiều có độ trễ thấp với Gemini. Khi sử dụng API Trực tiếp, bạn có thể mang đến cho người dùng cuối trải nghiệm trò chuyện tự nhiên, giống như con người và có thể cắt ngang câu trả lời của mô hình bằng lệnh thoại. Mô hình này có thể xử lý dữ liệu đầu vào là văn bản, âm thanh và video, đồng thời có thể cung cấp dữ liệu đầu ra là văn bản và âm thanh.
Bạn có thể dùng thử Live API trong Google AI Studio.
Sử dụng Live API
Phần này mô tả cách sử dụng API Trực tiếp với một trong các SDK của chúng tôi. Để biết thêm thông tin về API WebSockets cơ bản, hãy xem tài liệu tham khảo API WebSockets.
Gửi và nhận tin nhắn văn bản
import asyncio
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-live-001"
config = {"response_modalities": ["TEXT"]}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
while True:
message = input("User> ")
if message.lower() == "exit":
break
await session.send(input=message, end_of_turn=True)
async for response in session.receive():
if response.text is not None:
print(response.text, end="")
if __name__ == "__main__":
asyncio.run(main())
Nhận âm thanh
Ví dụ sau đây cho thấy cách nhận dữ liệu âm thanh và ghi dữ liệu đó vào tệp .wav.
import asyncio
import wave
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-live-001"
config = {"response_modalities": ["AUDIO"]}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
wf = wave.open("audio.wav", "wb")
wf.setnchannels(1)
wf.setsampwidth(2)
wf.setframerate(24000)
message = "Hello? Gemini are you there?"
await session.send(input=message, end_of_turn=True)
async for idx,response in async_enumerate(session.receive()):
if response.data is not None:
wf.writeframes(response.data)
# Un-comment this code to print audio data info
# if response.server_content.model_turn is not None:
# print(response.server_content.model_turn.parts[0].inline_data.mime_type)
wf.close()
if __name__ == "__main__":
asyncio.run(main())
Định dạng âm thanh
Live API hỗ trợ các định dạng âm thanh sau:
- Định dạng âm thanh đầu vào: Âm thanh PCM 16 bit thô ở 16 kHz little-endian
- Định dạng âm thanh đầu ra: Âm thanh PCM 16 bit thô ở 24 kHz little-endian
Truyền trực tuyến âm thanh và video
Hướng dẫn về hệ thống
Hướng dẫn hệ thống cho phép bạn điều hướng hành vi của một mô hình dựa trên các nhu cầu và trường hợp sử dụng cụ thể của bạn. Bạn có thể đặt hướng dẫn hệ thống trong cấu hình thiết lập và hướng dẫn này sẽ có hiệu lực trong toàn bộ phiên.
from google.genai import types
config = {
"system_instruction": types.Content(
parts=[
types.Part(
text="You are a helpful assistant and answer in a friendly tone."
)
]
),
"response_modalities": ["TEXT"],
}
Cập nhật nội dung tăng dần
Sử dụng các bản cập nhật gia tăng để gửi dữ liệu nhập văn bản, thiết lập ngữ cảnh phiên hoặc khôi phục ngữ cảnh phiên. Đối với ngữ cảnh ngắn, bạn có thể gửi các lượt tương tác từng bước để thể hiện trình tự sự kiện chính xác:
from google.genai import types
turns = [
types.Content(parts=[types.Part(text="What is the capital of France?")], role="user"),
types.Content(parts=[types.Part(text="Paris")], role="model")
]
await session.send(input=types.LiveClientContent(turns=turns))
turns = [types.Content(parts=[types.Part(text="What is the capital of Germany?")], role="user")]
await session.send(input=types.LiveClientContent(turns=turns, turn_complete=True))
{
"clientContent": {
"turns": [
{
"parts":[
{
"text": ""
}
],
"role":"user"
},
{
"parts":[
{
"text": ""
}
],
"role":"model"
}
],
"turnComplete": true
}
}
Đối với ngữ cảnh dài hơn, bạn nên cung cấp một bản tóm tắt thông báo duy nhất để giải phóng cửa sổ ngữ cảnh cho các lượt tương tác tiếp theo.
Thay đổi giọng nói
API Trực tiếp hỗ trợ các giọng nói sau: Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus và Zephyr.
Để chỉ định giọng nói, hãy đặt tên giọng nói trong đối tượng speechConfig như một phần của cấu hình phiên:
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
speech_config=types.SpeechConfig(
voice_config=types.VoiceConfig(
prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
)
)
)
{
"voiceConfig": {
"prebuiltVoiceConfig": {
"voiceName": "Kore"
}
}
}
Sử dụng lệnh gọi hàm
Bạn có thể xác định các công cụ bằng Live API. Hãy xem Hướng dẫn gọi hàm để tìm hiểu thêm về cách gọi hàm.
Bạn phải xác định các công cụ trong cấu hình phiên:
config = types.LiveConnectConfig(
response_modalities=["TEXT"],
tools=[set_light_values]
)
async with client.aio.live.connect(model=model, config=config) as session:
await session.send(input="Turn the lights down to a romantic level", end_of_turn=True)
async for response in session.receive():
print(response.tool_call)
Từ một câu lệnh duy nhất, mô hình có thể tạo nhiều lệnh gọi hàm và mã cần thiết để tạo chuỗi đầu ra. Mã này thực thi trong môi trường hộp cát, tạo các thông báo BidiGenerateContentToolCall tiếp theo. Quá trình thực thi sẽ tạm dừng cho đến khi có kết quả của từng lệnh gọi hàm, đảm bảo quá trình xử lý tuần tự.
Ứng dụng khách phải phản hồi bằng BidiGenerateContentToolResponse.
Đầu vào âm thanh và đầu ra âm thanh ảnh hưởng tiêu cực đến khả năng sử dụng lệnh gọi hàm của mô hình.
Xử lý các hoạt động gián đoạn
Người dùng có thể làm gián đoạn đầu ra của mô hình bất cứ lúc nào. Khi tính năng Phát hiện hoạt động giọng nói (VAD) phát hiện thấy một sự gián đoạn, quá trình tạo đang diễn ra sẽ bị huỷ và bị loại bỏ. Chỉ thông tin đã gửi đến ứng dụng mới được giữ lại trong nhật ký phiên. Sau đó, máy chủ sẽ gửi thông báo BidiGenerateContentServerContent để báo cáo sự gián đoạn.
Ngoài ra, máy chủ Gemini sẽ loại bỏ mọi lệnh gọi hàm đang chờ xử lý và gửi một thông báo BidiGenerateContentServerContent có mã nhận dạng của các lệnh gọi đã bị huỷ.
async for response in session.receive():
if response.server_content.interrupted is not None:
# The generation was interrupted
Định cấu hình tính năng phát hiện hoạt động bằng giọng nói (VAD)
Theo mặc định, mô hình này tự động thực hiện tính năng phát hiện hoạt động giọng nói (VAD) trên một luồng đầu vào âm thanh liên tục. Bạn có thể định cấu hình VAD bằng trường realtimeInputConfig.automaticActivityDetection của cấu hình thiết lập.
Khi luồng âm thanh bị tạm dừng hơn một giây (ví dụ: vì người dùng đã tắt micrô), bạn nên gửi một sự kiện audioStreamEnd để xoá mọi âm thanh đã lưu vào bộ nhớ đệm. Ứng dụng có thể tiếp tục gửi dữ liệu âm thanh bất cứ lúc nào.
Ngoài ra, bạn có thể tắt tính năng VAD tự động bằng cách đặt realtimeInputConfig.automaticActivityDetection.disabled thành true trong thông báo thiết lập. Trong cấu hình này, ứng dụng chịu trách nhiệm phát hiện lời nói của người dùng và gửi thông báo activityStart và activityEnd vào thời điểm thích hợp. audioStreamEnd không được gửi trong cấu hình này. Thay vào đó, mọi sự gián đoạn của luồng sẽ được đánh dấu bằng thông báo activityEnd.
Hỗ trợ SDK cho tính năng này sẽ ra mắt trong vài tuần tới.
Lấy số lượng mã thông báo
Bạn có thể tìm thấy tổng số mã thông báo đã sử dụng trong trường usageMetadata của thông báo máy chủ được trả về.
Hỗ trợ SDK cho tính năng này sẽ ra mắt trong vài tuần tới.
Định cấu hình tính năng tiếp tục phiên
Mặc dù thời lượng phiên bị giới hạn, nhưng bạn có thể định cấu hình trường sessionResumption của cấu hình thiết lập.
Việc truyền cấu hình này sẽ hỗ trợ tiếp tục phiên và khiến máy chủ gửi thông báo SessionResumptionUpdate. Thông báo này có thể được dùng để tiếp tục phiên bằng cách truyền mã thông báo tiếp tục gần đây nhất dưới dạng SessionResumptionConfig.handle của kết nối tiếp theo.
Nhận thông báo trước khi phiên ngắt kết nối
Máy chủ sẽ gửi một thông báo GoAway để báo hiệu rằng kết nối hiện tại sẽ sớm bị chấm dứt. Thông báo này bao gồm timeLeft, cho biết thời gian còn lại và cho phép bạn thực hiện hành động khác trước khi kết nối bị chấm dứt với trạng thái ABORTED (BỊ HUỶ).
Nhận thông báo khi quá trình tạo hoàn tất
Máy chủ sẽ gửi thông báo generationComplete để báo hiệu rằng mô hình đã hoàn tất việc tạo phản hồi.
Bật tính năng nén cửa sổ theo bối cảnh
Để bật các phiên dài hơn và tránh việc kết nối bị chấm dứt đột ngột, bạn có thể bật tính năng nén cửa sổ ngữ cảnh bằng cách đặt trường contextWindowCompression của cấu hình thiết lập.
Trong ContextWindowCompressionConfig, bạn có thể định cấu hình cơ chế cửa sổ trượt và số lượng mã thông báo kích hoạt quá trình nén.
Hỗ trợ SDK cho tính năng này sẽ ra mắt trong vài tuần tới.
Thay đổi độ phân giải nội dung nghe nhìn
Bạn có thể chỉ định độ phân giải nội dung nghe nhìn cho nội dung nghe nhìn đầu vào bằng cách đặt trường mediaResolution trong cấu hình phiên.
Hỗ trợ SDK cho tính năng này sẽ ra mắt trong vài tuần tới.
Các điểm hạn chế
Hãy cân nhắc các giới hạn sau đây của Live API và Gemini 2.0 khi bạn lên kế hoạch cho dự án.
Xác thực ứng dụng
API trực tiếp chỉ cung cấp tính năng xác thực máy chủ với máy chủ và không nên dùng cho ứng dụng khách trực tiếp. Dữ liệu đầu vào của ứng dụng khách phải được định tuyến thông qua một máy chủ ứng dụng trung gian để xác thực an toàn bằng API Trực tiếp.
Thời lượng phiên tối đa
Thời lượng phiên đào tạo được giới hạn ở tối đa 15 phút đối với âm thanh hoặc tối đa 2 phút đối với âm thanh và video. Khi thời lượng phiên vượt quá giới hạn, kết nối sẽ bị chấm dứt.
Mô hình cũng bị giới hạn bởi kích thước ngữ cảnh. Việc gửi các phần nội dung lớn cùng với luồng video và âm thanh có thể khiến phiên kết thúc sớm hơn.
Cửa sổ ngữ cảnh
Một phiên có giới hạn cửa sổ ngữ cảnh là 32 nghìn mã thông báo.
Các ứng dụng tích hợp của bên thứ ba
Đối với việc triển khai ứng dụng web và ứng dụng di động, bạn có thể khám phá các lựa chọn trong: