API Trực tiếp đa phương thức 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 đa phương thức, 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, đồng thời có thể ngắt lời phản hồ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ử API Trực tiếp đa phương thức trong Google AI Studio.
Sử dụng API Trực tiếp đa phương thức
Phần này mô tả cách sử dụng API Trực tiếp đa phương thức 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 bên dưới.
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-exp"
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-exp"
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)
# Comment this out 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
API Trực tiếp đa phương thức 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ể thiết lập 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 gia tăng
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
Multimodal Live API hỗ trợ các giọng nói sau: Aoede, Charon, Fenrir, Kore và Puck.
Để 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 API Trực tiếp đa phương thức. 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
Các điểm hạn chế
Hãy cân nhắc các giới hạn sau đây của API Trực tiếp đa phương thức 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 đa phương thức 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 đa phương thức.
Lịch sử cuộc trò chuyện
Mặc dù mô hình theo dõi các lượt tương tác trong phiên, nhưng nhật ký trò chuyện sẽ không được lưu trữ. Khi một phiên kết thúc, ngữ cảnh tương ứng sẽ bị xoá.
Để khôi phục một phiên trước đó hoặc cung cấp cho mô hình ngữ cảnh trước đây về các lượt tương tác của người dùng, ứng dụng phải duy trì nhật ký trò chuyện của riêng mình và sử dụng thông báo BidiGenerateContentClientContent để gửi thông tin này khi bắt đầu một phiên mới.
Thời lượng phiên tối đa
Thời lượng phiên đào tạo được giới hạn ở mức 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.
Phát hiện hoạt động giọng nói (VAD)
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. VAD luôn bật và các thông số của nó không thể định cấu hình.
Số lượng mã thông báo
Không hỗ trợ số lượng mã thông báo.
Giới hạn số lượng yêu cầu
Các giới hạn tốc độ sau đây sẽ được áp dụng:
- 3 phiên đồng thời cho mỗi khoá API
- 4 triệu mã thông báo mỗi phút
Tài liệu tham khảo API WebSocket
API trực tiếp đa phương thức là một API có trạng thái sử dụng WebSockets. Trong phần này, bạn sẽ tìm thấy thêm thông tin chi tiết về API WebSockets.
Phiên
Kết nối WebSocket thiết lập một phiên giữa ứng dụng và máy chủ Gemini. Sau khi ứng dụng khởi tạo một kết nối mới, phiên có thể trao đổi thông báo với máy chủ để:
- Gửi văn bản, âm thanh hoặc video đến máy chủ Gemini.
- Nhận yêu cầu gọi âm thanh, văn bản hoặc hàm từ máy chủ Gemini.
Thông báo ban đầu sau khi kết nối sẽ thiết lập cấu hình phiên, bao gồm mô hình, tham số tạo, hướng dẫn hệ thống và các công cụ.
Hãy xem cấu hình mẫu sau. Xin lưu ý rằng cách viết hoa tên trong SDK có thể khác nhau. Bạn có thể tra cứu các tuỳ chọn cấu hình SDK Python tại đây.
{
"model": string,
"generationConfig": {
"candidateCount": integer,
"maxOutputTokens": integer,
"temperature": number,
"topP": number,
"topK": integer,
"presencePenalty": number,
"frequencyPenalty": number,
"responseModalities": [string],
"speechConfig": object
},
"systemInstruction": string,
"tools": [object]
}
Gửi tin nhắn
Để trao đổi thông điệp qua kết nối WebSocket, ứng dụng phải gửi một đối tượng JSON qua kết nối WebSocket đang mở. Đối tượng JSON phải có chính xác một trường trong tập hợp đối tượng sau:
{
"setup": BidiGenerateContentSetup,
"clientContent": BidiGenerateContentClientContent,
"realtimeInput": BidiGenerateContentRealtimeInput,
"toolResponse": BidiGenerateContentToolResponse
}
Tin nhắn ứng dụng được hỗ trợ
Xem các thông báo ứng dụng được hỗ trợ trong bảng sau:
Thông điệp | Mô tả |
---|---|
BidiGenerateContentSetup |
Cấu hình phiên sẽ được gửi trong thông báo đầu tiên |
BidiGenerateContentClientContent |
Nội dung cập nhật gia tăng của cuộc trò chuyện hiện tại do ứng dụng gửi |
BidiGenerateContentRealtimeInput |
Đầu vào âm thanh hoặc video theo thời gian thực |
BidiGenerateContentToolResponse |
Phản hồi ToolCallMessage nhận được từ máy chủ |
Nhận tin nhắn
Để nhận thông báo từ Gemini, hãy theo dõi sự kiện "message" (thông báo) của WebSocket, sau đó phân tích cú pháp kết quả theo định nghĩa của thông báo máy chủ được hỗ trợ.
Xem các mục sau đây:
async with client.aio.live.connect(model='...', config=config) as session:
await session.send(input='Hello world!', end_of_turn=True)
async for message in session.receive():
print(message)
Thông báo của máy chủ sẽ có chính xác một trường trong tập hợp đối tượng sau:
{
"setupComplete": BidiGenerateContentSetupComplete,
"serverContent": BidiGenerateContentServerContent,
"toolCall": BidiGenerateContentToolCall,
"toolCallCancellation": BidiGenerateContentToolCallCancellation
}
Thông báo máy chủ được hỗ trợ
Xem các thông báo máy chủ được hỗ trợ trong bảng sau:
Thông điệp | Mô tả |
---|---|
BidiGenerateContentSetupComplete |
Tin nhắn BidiGenerateContentSetup từ ứng dụng khách, được gửi khi thiết lập xong |
BidiGenerateContentServerContent |
Nội dung do mô hình tạo ra để phản hồi thông báo của ứng dụng |
BidiGenerateContentToolCall |
Yêu cầu ứng dụng chạy các lệnh gọi hàm và trả về phản hồi bằng mã nhận dạng phù hợp |
BidiGenerateContentToolCallCancellation |
Được gửi khi lệnh gọi hàm bị huỷ do người dùng làm gián đoạn đầu ra của mô hình |
Tin nhắn và sự kiện
BidiGenerateContentClientContent
Nội dung cập nhật gia tăng của cuộc trò chuyện hiện tại do ứng dụng gửi. Tất cả nội dung ở đây được thêm vào nhật ký cuộc trò chuyện một cách vô điều kiện và được dùng làm một phần của câu lệnh cho mô hình để tạo nội dung.
Thông báo tại đây sẽ làm gián đoạn mọi hoạt động tạo mô hình hiện tại.
Trường | |
---|---|
turns[] |
Không bắt buộc. Nội dung được thêm vào cuộc trò chuyện hiện tại với mô hình. Đối với truy vấn một lượt, đây là một thực thể duy nhất. Đối với các truy vấn nhiều lượt, đây là trường lặp lại chứa nhật ký trò chuyện và yêu cầu mới nhất. |
turn_ |
Không bắt buộc. Nếu đúng, hãy cho biết rằng quá trình tạo nội dung máy chủ sẽ bắt đầu bằng lời nhắc hiện đã tích luỹ. Nếu không, máy chủ sẽ chờ thêm thông báo trước khi bắt đầu tạo. |
BidiGenerateContentRealtimeInput
Dữ liệu do người dùng nhập được gửi theo thời gian thực.
Phương thức này khác với BidiGenerateContentClientContent
ở một số điểm:
- Có thể gửi liên tục mà không bị gián đoạn để tạo mô hình.
- Nếu cần kết hợp dữ liệu được xen kẽ trên
BidiGenerateContentClientContent
vàBidiGenerateContentRealtimeInput
, máy chủ sẽ cố gắng tối ưu hoá để phản hồi tốt nhất, nhưng không có gì đảm bảo. - Điểm kết thúc lượt nói không được chỉ định rõ ràng, mà thay vào đó là bắt nguồn từ hoạt động của người dùng (ví dụ: kết thúc lời nói).
- Ngay cả trước khi kết thúc lượt, dữ liệu vẫn được xử lý dần để tối ưu hoá nhằm bắt đầu nhanh phản hồi từ mô hình.
- Luôn được giả định là dữ liệu đầu vào của người dùng (không thể dùng để điền sẵn nhật ký trò chuyện). Có thể gửi liên tục mà không bị gián đoạn. Mô hình này tự động phát hiện thời điểm bắt đầu và kết thúc lời nói của người dùng, đồng thời bắt đầu hoặc kết thúc truyền trực tuyến phản hồi cho phù hợp. Dữ liệu được xử lý tăng dần khi đến, giúp giảm thiểu độ trễ.
Trường | |
---|---|
media_ |
Không bắt buộc. Dữ liệu byte nội tuyến cho dữ liệu đầu vào đa phương tiện. |
BidiGenerateContentServerContent
Nội dung cập nhật máy chủ gia tăng do mô hình tạo ra để phản hồi thông báo của ứng dụng khách.
Nội dung được tạo nhanh nhất có thể chứ không phải theo thời gian thực. Ứng dụng có thể chọn lưu vào bộ đệm và phát theo thời gian thực.
Trường | |
---|---|
turn_ |
Chỉ có đầu ra. Nếu là true, cho biết mô hình đã tạo xong. Quá trình tạo sẽ chỉ bắt đầu khi phản hồi các thông báo khác của ứng dụng. Có thể được đặt cùng với |
interrupted |
Chỉ có đầu ra. Nếu đúng, cho biết một thông báo của ứng dụng đã làm gián đoạn quá trình tạo mô hình hiện tại. Nếu ứng dụng đang phát nội dung theo thời gian thực, thì đây là tín hiệu tốt để dừng và làm trống hàng đợi phát hiện tại. |
grounding_ |
Chỉ có đầu ra. Siêu dữ liệu cơ sở cho nội dung được tạo. |
model_ |
Chỉ có đầu ra. Nội dung mà mô hình đã tạo trong cuộc trò chuyện hiện tại với người dùng. |
BidiGenerateContentSetup
Thông báo sẽ được gửi trong thông báo đầu tiên và duy nhất của ứng dụng khách. Chứa cấu hình sẽ áp dụng trong suốt phiên phát trực tuyến.
Ứng dụng nên đợi thông báo BidiGenerateContentSetupComplete
trước khi gửi thêm thông báo.
Trường | |
---|---|
model |
Bắt buộc. Tên tài nguyên của mô hình. Đây là mã nhận dạng để Mô hình sử dụng. Định dạng |
generation_ |
Không bắt buộc. Cấu hình tạo. Các trường sau đây không được hỗ trợ:
|
system_ |
Không bắt buộc. Người dùng đã cung cấp hướng dẫn hệ thống cho mô hình. Lưu ý: Chỉ nên sử dụng văn bản trong các phần. Nội dung trong mỗi phần sẽ nằm trong một đoạn riêng. |
tools[] |
Không bắt buộc. Danh sách
|
BidiGenerateContentSetupComplete
Loại này không có trường nào.
Được gửi để phản hồi một thông báo BidiGenerateContentSetup
từ ứng dụng khách.
BidiGenerateContentToolCall
Yêu cầu ứng dụng thực thi các lệnh gọi hàm và trả về phản hồi bằng id
phù hợp.
Trường | |
---|---|
function_ |
Chỉ có đầu ra. Lệnh gọi hàm sẽ được thực thi. |
BidiGenerateContentToolCallCancellation
Thông báo cho ứng dụng khách rằng ToolCallMessage
đã phát hành trước đó với các id
được chỉ định không được thực thi và phải bị huỷ. Nếu có hiệu ứng phụ đối với các lệnh gọi công cụ đó, ứng dụng có thể cố gắng huỷ các lệnh gọi công cụ. Thông báo này chỉ xảy ra trong trường hợp ứng dụng khách làm gián đoạn lượt chuyển đổi máy chủ.
Trường | |
---|---|
ids[] |
Chỉ có đầu ra. Mã của các lệnh gọi công cụ cần huỷ. |
BidiGenerateContentToolResponse
Phản hồi do ứng dụng tạo cho một ToolCall
nhận được từ máy chủ. Các đối tượng FunctionResponse
riêng lẻ được so khớp với các đối tượng FunctionCall
tương ứng theo trường id
.
Xin lưu ý rằng trong API Tạo nội dung một chiều và API Tạo nội dung truyền trực tuyến qua máy chủ, việc gọi hàm diễn ra bằng cách trao đổi các phần Content
, trong khi trong API Tạo nội dung hai chiều, việc gọi hàm diễn ra qua các nhóm thông báo chuyên dụng này.
Trường | |
---|---|
function_ |
Không bắt buộc. Phản hồi cho các lệnh gọi hàm. |
Thông tin khác về các loại phổ biến
Để biết thêm thông tin về các loại tài nguyên API thường dùng Blob
, Content
, FunctionCall
, FunctionResponse
, GenerationConfig
, GroundingMetadata
và Tool
, hãy xem phần Tạo nội dung.
Các dịch vụ 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: