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.
Tính năng mới
Hãy xem Nhật ký thay đổi để biết các tính năng và chức năng mới nhất trong API trực tiếp!
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.
Để sử dụng tất cả tính năng, hãy nhớ cài đặt phiên bản SDK mới nhất, ví dụ:
pip install -U google-genai
.
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")
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_client_content(
turns={"role": "user", "parts": [{"text": message}]}, turn_complete=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")
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_client_content(
turns={"role": "user", "parts": [{"text": message}]}, turn_complete=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:
Python
turns = [
{"role": "user", "parts": [{"text": "What is the capital of France?"}]},
{"role": "model", "parts": [{"text": "Paris"}]},
]
await session.send_client_content(turns=turns, turn_complete=False)
turns = [{"role": "user", "parts": [{"text": "What is the capital of Germany?"}]}]
await session.send_client_content(turns=turns, turn_complete=True)
JSON
{
"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:
Python
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")
)
)
)
JSON
{
"voiceConfig": {
"prebuiltVoiceConfig": {
"voiceName": "Kore"
}
}
}
Thay đổi ngôn ngữ
API Trực tiếp hỗ trợ nhiều ngôn ngữ.
Để thay đổi ngôn ngữ, hãy đặt mã ngôn ngữ trong đối tượng speechConfig
là 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(
language_code="de-DE",
)
)
Sử dụng công cụ
Bạn có thể xác định các công cụ như Gọi hàm, Thực thi mã và Google Tìm kiếm bằng Live API.
Sử dụng lệnh gọi hàm
Bạn có thể xác định phần khai báo hàm trong cấu hình phiên. Hãy xem Hướng dẫn gọi hàm để tìm hiểu thêm.
Sau khi nhận được lệnh gọi công cụ, ứng dụng khách sẽ phản hồi bằng một danh sách các đối tượng FunctionResponse
bằng phương thức session.send_tool_response
.
import asyncio
from google import genai
from google.genai import types
client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"
# Simple function definitions
turn_on_the_lights = {"name": "turn_on_the_lights"}
turn_off_the_lights = {"name": "turn_off_the_lights"}
tools = [{"function_declarations": [turn_on_the_lights, turn_off_the_lights]}]
config = {"response_modalities": ["TEXT"], "tools": tools}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
prompt = "Turn on the lights please"
await session.send_client_content(turns={"parts": [{"text": prompt}]})
async for chunk in session.receive():
if chunk.server_content:
if chunk.text is not None:
print(chunk.text)
elif chunk.tool_call:
function_responses = []
for fc in tool_call.function_calls:
function_response = types.FunctionResponse(
id=fc.id,
name=fc.name,
response={ "result": "ok" } # simple, hard-coded function response
)
function_responses.append(function_response)
await session.send_tool_response(function_responses=function_responses)
if __name__ == "__main__":
asyncio.run(main())
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ự.
Đầ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.
Sử dụng tính năng Thực thi mã
Bạn có thể xác định quá trình thực thi mã trong cấu hình phiên. Hãy xem Hướng dẫn thực thi mã để tìm hiểu thêm.
import asyncio
from google import genai
from google.genai import types
client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"
tools = [{'code_execution': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
prompt = "Compute the largest prime palindrome under 100000."
await session.send_client_content(turns={"parts": [{"text": prompt}]})
async for chunk in session.receive():
if chunk.server_content:
if chunk.text is not None:
print(chunk.text)
model_turn = chunk.server_content.model_turn
if model_turn:
for part in model_turn.parts:
if part.executable_code is not None:
print(part.executable_code.code)
if part.code_execution_result is not None:
print(part.code_execution_result.output)
if __name__ == "__main__":
asyncio.run(main())
Sử dụng tính năng Làm dịu căng thẳng bằng Google Tìm kiếm
Bạn có thể bật tính năng Làm quen với Google Tìm kiếm trong cấu hình phiên. Hãy xem Hướng dẫn về việc nối đất để tìm hiểu thêm.
import asyncio
from google import genai
from google.genai import types
client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"
tools = [{'google_search': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
prompt = "When did the last Brazil vs. Argentina soccer match happen?"
await session.send_client_content(turns={"parts": [{"text": prompt}]})
async for chunk in session.receive():
if chunk.server_content:
if chunk.text is not None:
print(chunk.text)
# The model might generate and execute Python code to use Search
model_turn = chunk.server_content.model_turn
if model_turn:
for part in model_turn.parts:
if part.executable_code is not None:
print(part.executable_code.code)
if part.code_execution_result is not None:
print(part.code_execution_result.output)
if __name__ == "__main__":
asyncio.run(main())
Kết hợp nhiều công cụ
Bạn có thể kết hợp nhiều công cụ trong Live API:
prompt = """
Hey, I need you to do three things for me.
1. Compute the largest prime palindrome under 100000.
2. Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024?
3. Turn on the lights
Thanks!
"""
tools = [
{"google_search": {}},
{"code_execution": {}},
{"function_declarations": [turn_on_the_lights, turn_off_the_lights]},
]
config = {"response_modalities": ["TEXT"], "tools": tools}
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 True:
# 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)
Bạn có thể định cấu hình hoặc tắt tính năng phát hiện hoạt động giọng nói (VAD).
Sử dụng tính năng VAD tự động
Theo mặc định, mô hình sẽ tự động thực hiện 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.
# example audio file to try:
# URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
# !wget -q $URL -O sample.pcm
import asyncio
from pathlib import Path
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY")
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:
audio_bytes = Path("sample.pcm").read_bytes()
await session.send_realtime_input(
audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
)
# if stream gets paused, send:
# await session.send_realtime_input(audio_stream_end=True)
async for response in session.receive():
if response.text is not None:
print(response.text)
if __name__ == "__main__":
asyncio.run(main())
Với send_realtime_input
, API sẽ tự động phản hồi âm thanh dựa trên VAD. Mặc dù send_client_content
thêm thông báo vào ngữ cảnh mô hình theo thứ tự, nhưng send_realtime_input
được tối ưu hoá để phản hồi nhanh, nhưng phải trả giá bằng việc sắp xếp có tính chất xác định.
Định cấu hình VAD tự động
Để kiểm soát hoạt động VAD tốt hơn, bạn có thể định cấu hình các thông số sau. Hãy xem tài liệu tham khảo API để biết thêm thông tin.
from google.genai import types
config = {
"response_modalities": ["TEXT"],
"realtime_input_config": {
"automatic_activity_detection": {
"disabled": False, # default
"start_of_speech_sensitivity": types.StartSensitivity.START_SENSITIVITY_LOW,
"end_of_speech_sensitivity": types.EndSensitivity.END_SENSITIVITY_LOW,
"prefix_padding_ms": 20,
"silence_duration_ms": 100,
}
}
}
Tắt tính năng VAD tự động
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
.
config = {
"response_modalities": ["TEXT"],
"realtime_input_config": {"automatic_activity_detection": {"disabled": True}},
}
async with client.aio.live.connect(model=model, config=config) as session:
# ...
await session.send_realtime_input(activity_start=types.ActivityStart())
await session.send_realtime_input(
audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
)
await session.send_realtime_input(activity_end=types.ActivityEnd())
# ...
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ề.
async for message in session.receive():
# The server will periodically send messages that include UsageMetadata.
if message.usage_metadata:
usage = message.usage_metadata
print(
f"Used {usage.total_token_count} tokens in total. Response token breakdown:"
)
for detail in usage.response_tokens_details:
match detail:
case types.ModalityTokenCount(modality=modality, token_count=count):
print(f"{modality}: {count}")
Kéo dài thời lượng phiên
Bạn có thể mở rộng thời lượng phiên tối đa lên không giới hạn bằng hai cơ chế:
Ngoài ra, bạn sẽ nhận được một thông báo GoAway trước khi phiên kết thúc, cho phép bạn thực hiện các hành động khác.
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 bị ngắt kết nối độ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 trong cấu hình phiên.
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.
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
context_window_compression=(
# Configures compression with default parameters.
types.ContextWindowCompressionConfig(
sliding_window=types.SlidingWindow(),
)
),
)
Định cấu hình tính năng tiếp tục phiên
Để ngăn phiên bị chấm dứt khi máy chủ định kỳ đặt lại kết nối WebSocket, hãy định cấu hình trường sessionResumption trong cấu hình thiết lập.
Việc truyền cấu hình này sẽ khiến máy chủ gửi thông báo SessionResumptionUpdate. Bạn có thể dùng thông báo này để 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.
import asyncio
from google import genai
from google.genai import types
client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"
async def main():
print(f"Connecting to the service with handle {previous_session_handle}...")
async with client.aio.live.connect(
model=model,
config=types.LiveConnectConfig(
response_modalities=["AUDIO"],
session_resumption=types.SessionResumptionConfig(
# The handle of the session to resume is passed here,
# or else None to start a new session.
handle=previous_session_handle
),
),
) as session:
while True:
await session.send_client_content(
turns=types.Content(
role="user", parts=[types.Part(text="Hello world!")]
)
)
async for message in session.receive():
# Periodically, the server will send update messages that may
# contain a handle for the current state of the session.
if message.session_resumption_update:
update = message.session_resumption_update
if update.resumable and update.new_handle:
# The handle should be retained and linked to the session.
return update.new_handle
# For the purposes of this example, placeholder input is continually fed
# to the model. In non-sample code, the model inputs would come from
# the user.
if message.server_content and message.server_content.turn_complete:
break
if __name__ == "__main__":
asyncio.run(main())
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Ỷ).
async for response in session.receive():
if response.go_away is not None:
# The connection will soon be terminated
print(response.go_away.time_left)
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.
async for response in session.receive():
if response.server_content.generation_complete is True:
# The generation is complete
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:
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)
Nhận bản chép lời âm thanh
Bạn có thể bật tính năng chép lời đầu ra âm thanh của mô hình. Ngôn ngữ của bản chép lời được suy ra từ phản hồi của mô hình.
import asyncio
from google import genai
from google.genai import types
client = genai.Client(api_key="GEMINI_API_KEY")
model = "gemini-2.0-flash-live-001"
config = {"response_modalities": ["AUDIO"],
"output_audio_transcription": {}
}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
message = "Hello? Gemini are you there?"
await session.send_client_content(
turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
)
async for response in session.receive():
if response.server_content.model_turn:
print("Model turn:", response.server_content.model_turn)
if response.server_content.output_transcription:
print("Transcript:", response.server_content.output_transcription.text)
if __name__ == "__main__":
asyncio.run(main())
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.
Phương thức phản hồi
Bạn chỉ có thể đặt một phương thức phản hồi (TEXT
hoặc AUDIO
) cho mỗi phiên trong cấu hình phiên. Nếu bạn cố gắng đặt cả hai, bạn sẽ nhận được thông báo lỗi cấu hình. Điều này có nghĩa là bạn có thể định cấu hình mô hình để phản hồi bằng văn bản hoặc âm thanh, nhưng không thể phản hồi bằng cả hai trong cùng một phiê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
Bạn có thể kéo dài thời lượng phiên đến vô hạn bằng cách bật tính năng nén phiên. Nếu không nén, các phiên chỉ âm thanh sẽ bị giới hạn ở 15 phút và các phiên âm thanh cùng video sẽ bị giới hạn ở 2 phút. Nếu vượt quá các giới hạn này mà không nén, kết nối sẽ bị chấm dứt.
Ngoài ra, bạn có thể định cấu hình tính năng tiếp tục phiên để cho phép ứng dụng tiếp tục một phiên đã bị chấm dứt.
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.
Ngôn ngữ được hỗ trợ
Live API hỗ trợ các ngôn ngữ sau:
Ngôn ngữ | Mã BCP-47 |
---|---|
Tiếng Đức (Đức) | de-DE |
Tiếng Anh (Úc) | en-AU |
Tiếng Anh (Anh) | en-GB |
Tiếng Anh (Ấn Độ) | en-IN |
Tiếng Anh (Mỹ) | en-US |
Tiếng Tây Ban Nha (Mỹ) | es-US |
Tiếng Pháp (Pháp) | fr-FR |
Tiếng Hindi (Ấn Độ) | hi-IN |
Tiếng Bồ Đào Nha (Brazil) | pt-BR |
Tiếng Ả Rập (Chung) | ar-XA |
Tiếng Tây Ban Nha (Tây Ban Nha) | es-ES |
Tiếng Pháp (Canada) | fr-CA |
Tiếng Indo (Indonesia) | id-ID |
Tiếng Ý (Ý) | it-IT |
Tiếng Nhật (Nhật Bản) | ja-JP |
Tiếng Thổ Nhĩ Kỳ (Thổ Nhĩ Kỳ) | tr-TR |
Tiếng Việt (Việt Nam) | vi-VN |
Tiếng Bengal (Ấn Độ) | bn-IN |
Tiếng Gujarati (Ấn Độ) | gu-IN |
Tiếng Kannada (Ấn Độ) | kn-IN |
Tiếng Malayalam (Ấn Độ) | ml-IN |
Tiếng Marathi (Ấn Độ) | mr-IN |
Tiếng Tamil (Ấn Độ) | ta-IN |
Tiếng Telugu (Ấn Độ) | te-IN |
Tiếng Hà Lan (Hà Lan) | nl-NL |
Tiếng Hàn (Hàn Quốc) | ko-KR |
Tiếng Trung (Quan thoại) (Trung Quốc) | cmn-CN |
Tiếng Ba Lan (Ba Lan) | pl-PL |
Tiếng Nga (Nga) | ru-RU |
Tiếng Thái (Thái Lan) | th-TH |
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: