Live API

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"],
}

การอัปเดตเนื้อหาเพิ่มเติม

ใช้การอัปเดตแบบเพิ่มเพื่อส่งอินพุตข้อความ สร้างบริบทของเซสชัน หรือกู้คืนบริบทของเซสชัน สำหรับบริบทสั้นๆ คุณสามารถส่งการโต้ตอบแบบทีละขั้นเพื่อแสดงลำดับเหตุการณ์ที่แน่นอนได้ ดังนี้

PythonJSON
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 โดยเป็นส่วนหนึ่งของการกำหนดค่าเซสชัน

PythonJSON
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 โทเค็น

การผสานรวมกับบุคคลที่สาม

สําหรับการติดตั้งใช้งานเว็บและแอปบนอุปกรณ์เคลื่อนที่ คุณสามารถดูตัวเลือกต่อไปนี้