Live API ช่วยให้สามารถโต้ตอบด้วยเสียงและวิดีโอแบบ 2 ทิศทางที่มีเวลาในการตอบสนองต่ำกับ Gemini เมื่อใช้ Live API คุณจะมอบประสบการณ์การสนทนาด้วยเสียงที่เป็นธรรมชาติซึ่งคล้ายกับเสียงของมนุษย์ให้แก่ผู้ใช้ปลายทางได้ รวมถึงสามารถขัดจังหวะคำตอบของโมเดลโดยใช้คำสั่งเสียง โมเดลนี้สามารถประมวลผลอินพุตข้อความ เสียง และวิดีโอ รวมถึงแสดงผลลัพธ์เป็นข้อความและเสียง
คุณลองใช้ API แบบเรียลไทม์ได้ใน Google AI Studio
มีอะไรใหม่
Live API มีฟีเจอร์และความสามารถใหม่ๆ
ความสามารถใหม่:
- เสียงใหม่ 2 เสียงและภาษาใหม่ 30 ภาษา พร้อมภาษาเอาต์พุตที่กำหนดค่าได้
- โทเค็นความละเอียดรูปภาพที่กําหนดค่าได้ 66/256
- การส่งข้อมูลทุกรายการตลอดเวลาหรือเฉพาะตอนที่ผู้ใช้พูดเท่านั้น
- กำหนดค่าว่าอินพุตควรขัดจังหวะโมเดลหรือไม่
- การตรวจจับกิจกรรมเสียงที่กำหนดค่าได้และเหตุการณ์ไคลเอ็นต์ใหม่สำหรับการส่งสัญญาณสิ้นสุดการพูด
- จํานวนโทเค็น
- เหตุการณ์ไคลเอ็นต์สําหรับการส่งสัญญาณการสิ้นสุดสตรีม
- การสตรีมข้อความ
- การกลับมาทำงานของเซสชันที่กําหนดค่าได้ โดยระบบจะจัดเก็บข้อมูลเซสชันไว้ในเซิร์ฟเวอร์เป็นเวลา 24 ชั่วโมง
- รองรับเซสชันที่นานขึ้นด้วยหน้าต่างบริบทแบบเลื่อน
เหตุการณ์ของลูกค้าใหม่:
- สิ้นสุดสตรีมเสียง / ปิดไมโครโฟน
- เหตุการณ์เริ่มต้น/สิ้นสุดกิจกรรมสําหรับการควบคุมการเปลี่ยนเลนด้วยตนเอง
เหตุการณ์ใหม่ในเซิร์ฟเวอร์:
- การแจ้งเตือนให้หยุดแสดงที่บ่งบอกว่าต้องรีสตาร์ทเซสชัน
- การสร้างเสร็จสมบูรณ์แล้ว
ใช้ Live API
ส่วนนี้จะอธิบายวิธีใช้ Live API กับ SDK ของเรา ดูข้อมูลเพิ่มเติมเกี่ยวกับ WebSockets API พื้นฐานได้ที่ข้อมูลอ้างอิง WebSockets API
ส่งและรับข้อความ
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())
รับเสียง
ตัวอย่างต่อไปนี้แสดงวิธีรับข้อมูลเสียงและเขียนลงในไฟล์ .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_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())
รูปแบบเสียง
Live API รองรับรูปแบบเสียงต่อไปนี้
- รูปแบบเสียงอินพุต: เสียง PCM 16 บิตดิบที่ 16kHz แบบ Little-endian
- รูปแบบเสียงเอาต์พุต: เสียง PCM 16 บิตดิบที่ 24 kHz แบบ Little-endian
สตรีมเสียงและวิดีโอ
วิธีการของระบบ
คำสั่งของระบบช่วยให้คุณควบคุมลักษณะการทํางานของโมเดลตามความต้องการและกรณีการใช้งานที่เฉพาะเจาะจง คุณสามารถตั้งค่าวิธีการของระบบในการกําหนดค่าการตั้งค่าได้ และจะมีผลตลอดทั้งเซสชัน
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"],
}
การอัปเดตเนื้อหาเพิ่มเติม
ใช้การอัปเดตแบบเพิ่มเพื่อส่งอินพุตข้อความ สร้างบริบทของเซสชัน หรือกู้คืนบริบทของเซสชัน สำหรับบริบทสั้นๆ คุณสามารถส่งการโต้ตอบแบบทีละขั้นเพื่อแสดงลำดับเหตุการณ์ที่แน่นอนได้ ดังนี้
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)
{
"clientContent": {
"turns": [
{
"parts":[
{
"text": ""
}
],
"role":"user"
},
{
"parts":[
{
"text": ""
}
],
"role":"model"
}
],
"turnComplete": true
}
}
สำหรับบริบทที่ยาวขึ้น เราขอแนะนำให้ระบุข้อมูลสรุปของข้อความเดียวเพื่อเพิ่มพื้นที่ว่างในกรอบเวลาบริบทสำหรับการโต้ตอบครั้งต่อๆ ไป
เปลี่ยนเสียง
Live API รองรับเสียง Puck, Charon, Kore, Fenrir, Aoede, Leda, Orus และ Zephyr
หากต้องการระบุเสียง ให้ตั้งค่าชื่อเสียงภายในออบเจ็กต์ speechConfig
โดยเป็นส่วนหนึ่งของการกำหนดค่าเซสชัน
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"
}
}
}
ใช้การเรียกใช้ฟังก์ชัน
คุณกำหนดเครื่องมือได้ด้วย Live API ดูบทแนะนำเกี่ยวกับการเรียกใช้ฟังก์ชันเพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับการเรียกใช้ฟังก์ชัน
เครื่องมือต้องได้รับการกําหนดเป็นส่วนหนึ่งของการกําหนดค่าเซสชัน
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_client_content(
turns={
"role": "user",
"parts": [{"text": "Turn the lights down to a romantic level"}],
},
turn_complete=True,
)
async for response in session.receive():
print(response.tool_call)
จากพรอมต์เดียว โมเดลสามารถสร้างการเรียกฟังก์ชันหลายรายการและโค้ดที่จําเป็นต่อเชื่อมเอาต์พุต โค้ดนี้จะทํางานในสภาพแวดล้อมแซนด์บ็อกซ์ ซึ่งจะสร้างข้อความ BidiGenerateContentToolCall ตามมา การดำเนินการจะหยุดชั่วคราวจนกว่าผลลัพธ์ของการเรียกฟังก์ชันแต่ละรายการจะพร้อมใช้งาน ซึ่งช่วยให้การประมวลผลเป็นไปตามลำดับ
โดยลูกค้าควรตอบกลับด้วย BidiGenerateContentToolResponse
อินพุตและเอาต์พุตเสียงส่งผลเสียต่อความสามารถของโมเดลในการใช้การเรียกใช้ฟังก์ชัน
จัดการสิ่งรบกวน
ผู้ใช้สามารถขัดจังหวะเอาต์พุตของโมเดลได้ทุกเมื่อ เมื่อการตรวจจับกิจกรรมเสียงพูด (VAD) ตรวจพบการหยุดชะงัก ระบบจะยกเลิกและทิ้งการสร้างที่กำลังดำเนินอยู่ เฉพาะข้อมูลที่ส่งไปยังไคลเอ็นต์แล้วเท่านั้นที่จะยังคงอยู่ในประวัติเซสชัน จากนั้นเซิร์ฟเวอร์จะส่งข้อความ BidiGenerateContentServerContent เพื่อรายงานการหยุดชะงัก
นอกจากนี้ เซิร์ฟเวอร์ Gemini จะทิ้งการเรียกฟังก์ชันที่รอดำเนินการและส่งข้อความ BidiGenerateContentServerContent
พร้อมรหัสของการเรียกที่ถูกยกเลิก
async for response in session.receive():
if response.server_content.interrupted is not None:
# The generation was interrupted
กำหนดค่าการตรวจจับกิจกรรมเสียงพูด (VAD)
โดยค่าเริ่มต้น โมเดลจะตรวจหากิจกรรมเสียง (VAD) ในสตรีมอินพุตเสียงแบบต่อเนื่องโดยอัตโนมัติ คุณสามารถกําหนดค่า VAD ได้ด้วยช่อง realtimeInputConfig.automaticActivityDetection
ของการกําหนดค่าการตั้งค่า
เมื่อสตรีมเสียงหยุดชั่วคราวนานกว่า 1 วินาที (เช่น เนื่องจากผู้ใช้ปิดไมโครโฟน) คุณควรส่งเหตุการณ์ audioStreamEnd
เพื่อล้างเสียงที่แคชไว้ โดยลูกค้าสามารถส่งข้อมูลเสียงต่อได้ทุกเมื่อ
หรือจะปิดใช้ VAD อัตโนมัติโดยการตั้งค่า realtimeInputConfig.automaticActivityDetection.disabled
เป็น true
ในข้อความการตั้งค่าก็ได้ ในการกำหนดค่านี้ ไคลเอ็นต์มีหน้าที่รับผิดชอบในการตรวจจับเสียงพูดของผู้ใช้และส่งข้อความ activityStart
และ activityEnd
ในเวลาที่เหมาะสม ระบบจะไม่ส่ง audioStreamEnd
ในการกำหนดค่านี้ แต่ระบบจะแสดงข้อความ activityEnd
แทนเพื่อระบุว่าสตรีมหยุดชะงัก
การรองรับ SDK สําหรับฟีเจอร์นี้จะพร้อมใช้งานในอีกไม่กี่สัปดาห์ข้างหน้า
รับจํานวนโทเค็น
คุณดูจํานวนโทเค็นทั้งหมดที่ใช้ได้ในช่อง usageMetadata ของข้อความเซิร์ฟเวอร์ที่แสดงผล
from google.genai import types
async with client.aio.live.connect(
model='gemini-2.0-flash-live-001',
config=types.LiveConnectConfig(
response_modalities=['AUDIO'],
),
) as session:
# Session connected
while True:
await session.send_client_content(
turns=types.Content(role='user', parts=[types.Part(text='Hello world!')])
)
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}')
# 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
กำหนดค่าการกลับมาทำงานของเซสชัน
หากต้องการป้องกันไม่ให้เซสชันสิ้นสุดลงเมื่อเซิร์ฟเวอร์รีเซ็ตการเชื่อมต่อ WebSocket เป็นระยะ ให้กําหนดค่าช่อง sessionResumption ภายในการกําหนดค่าการตั้งค่า
การส่งผ่านการกำหนดค่านี้จะทำให้เซิร์ฟเวอร์ส่งข้อความ SessionResumptionUpdate ซึ่งสามารถใช้เพื่อกลับมาดำเนินการในเซสชันต่อได้โดยส่งโทเค็นการกลับมาทำงานต่อล่าสุดเป็น SessionResumptionConfig.handle
ของการเชื่อมต่อที่ตามมา
from google.genai import types
print(f"Connecting to the service with handle {previous_session_handle}...")
async with client.aio.live.connect(
model="gemini-2.0-flash-live-001",
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:
# Session connected
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
รับข้อความก่อนที่เซสชันจะตัดการเชื่อมต่อ
เซิร์ฟเวอร์ส่งข้อความ GoAway ซึ่งบ่งบอกว่าการเชื่อมต่อปัจจุบันจะสิ้นสุดลงในไม่ช้า ข้อความนี้มี timeLeft ซึ่งระบุเวลาที่เหลืออยู่และให้คุณดำเนินการเพิ่มเติมได้ก่อนที่การเชื่อมต่อจะสิ้นสุดลงโดยระบุว่า "ยกเลิก"
รับข้อความเมื่อการสร้างเสร็จสมบูรณ์
เซิร์ฟเวอร์จะส่งข้อความ generationComplete ที่บ่งบอกว่าโมเดลสร้างคำตอบเสร็จแล้ว
เปิดใช้การบีบอัดกรอบบริบท
หากต้องการให้เซสชันทำงานได้นานขึ้นและหลีกเลี่ยงการสิ้นสุดการเชื่อมต่ออย่างกะทันหัน คุณสามารถเปิดใช้การบีบอัดกรอบบริบทได้โดยตั้งค่าช่อง contextWindowCompression เป็นส่วนหนึ่งของการกำหนดค่าเซสชัน
ใน ContextWindowCompressionConfig คุณสามารถกําหนดค่ากลไกกรอบเวลาแบบเลื่อนและจํานวนโทเค็นที่จะทริกเกอร์การบีบอัด
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(),
)
),
)
เปลี่ยนความละเอียดของสื่อ
คุณสามารถระบุความละเอียดของสื่อสำหรับสื่ออินพุตได้โดยการตั้งค่าช่อง mediaResolution
เป็นส่วนหนึ่งของการกำหนดค่าเซสชัน ดังนี้
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)
ข้อจำกัด
โปรดคำนึงถึงข้อจำกัดต่อไปนี้ของ Live API และ Gemini 2.0 เมื่อวางแผนโปรเจ็กต์
การตรวจสอบสิทธิ์ไคลเอ็นต์
Live API มีการตรวจสอบสิทธิ์แบบเซิร์ฟเวอร์ต่อเซิร์ฟเวอร์เท่านั้น และเราไม่แนะนำให้ใช้กับไคลเอ็นต์โดยตรง อินพุตของไคลเอ็นต์ควรกำหนดเส้นทางผ่านเซิร์ฟเวอร์แอปพลิเคชันระดับกลางเพื่อการตรวจสอบสิทธิ์ที่ปลอดภัยกับ Live API
ระยะเวลาเซสชัน
คุณสามารถขยายระยะเวลาเซสชันได้ไม่จํากัดโดยเปิดใช้การบีบอัดเซสชัน หากไม่มีการบีบอัด เซสชันที่มีเฉพาะเสียงจะจำกัดไว้ที่ 15 นาที และเซสชันที่มีทั้งเสียงและวิดีโอจะจำกัดไว้ที่ 2 นาที การเกินขีดจำกัดเหล่านี้โดยไม่ใช้การบีบอัดจะสิ้นสุดการเชื่อมต่อ
หน้าต่างบริบท
เซสชันมีขีดจํากัดของกรอบเวลาบริบทที่ 32,000 โทเค็น
การผสานรวมกับบุคคลที่สาม
สําหรับการติดตั้งใช้งานเว็บและแอปบนอุปกรณ์เคลื่อนที่ คุณสามารถดูตัวเลือกต่อไปนี้