Live API

Live API تعامل صوتی و تصویری دو جهته با تأخیر کم با Gemini را امکان پذیر می کند. با استفاده از Live API، می‌توانید تجربه مکالمات صوتی طبیعی و شبیه انسان را در اختیار کاربران نهایی قرار دهید و با استفاده از دستورات صوتی، پاسخ‌های مدل را قطع کنید. این مدل می تواند ورودی متن، صدا و تصویر را پردازش کند و می تواند متن و خروجی صدا را ارائه دهد.

می‌توانید Live API را در Google AI Studio امتحان کنید.

چه خبر است

برای آخرین ویژگی‌ها و قابلیت‌های جدید در Live API، Changelog را بررسی کنید!

از Live API استفاده کنید

این بخش نحوه استفاده از Live API را با یکی از SDK های ما شرح می دهد. برای اطلاعات بیشتر در مورد WebSockets API اساسی، به مرجع WebSockets API مراجعه کنید.

برای استفاده از همه ویژگی‌ها، مطمئن شوید که آخرین نسخه SDK را نصب کنید، به عنوان مثال، pip install -U google-genai .

ارسال و دریافت متن

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")
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 از فرمت های صوتی زیر پشتیبانی می کند:

  • فرمت صوتی ورودی: صدای خام 16 بیتی PCM با فرکانس 16 کیلوهرتز کمی اندین
  • فرمت صدای خروجی: صدای خام 16 بیتی PCM با فرکانس 24 کیلوهرتز کمی 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)

JSON

{
  "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")
        )
    )
)

JSON

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

تغییر زبان

Live API از چندین زبان پشتیبانی می کند.

برای تغییر زبان، کد زبان را در شی speechConfig به عنوان بخشی از پیکربندی جلسه تنظیم کنید:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        language_code="de-DE",
    )
)

از ابزار استفاده کنید

می‌توانید ابزارهایی مانند فراخوانی تابع ، اجرای کد و جستجوی Google را با Live API تعریف کنید.

از فراخوانی تابع استفاده کنید

شما می توانید اعلان های تابع را به عنوان بخشی از پیکربندی جلسه تعریف کنید. برای کسب اطلاعات بیشتر به آموزش فراخوانی تابع مراجعه کنید.

پس از دریافت تماس های ابزار، مشتری باید با لیستی از اشیاء FunctionResponse با استفاده از روش 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())

از یک اعلان واحد، مدل می تواند چندین فراخوانی تابع و کدهای لازم برای زنجیره خروجی های آنها را ایجاد کند. این کد در محیط sandbox اجرا می شود و پیام های BidiGenerateContentToolCall بعدی را ایجاد می کند. اجرا متوقف می شود تا زمانی که نتایج هر فراخوانی در دسترس باشد، که پردازش متوالی را تضمین می کند.

ورودی‌ها و خروجی‌های صوتی بر توانایی مدل برای استفاده از فراخوانی تابع تأثیر منفی می‌گذارند.

از اجرای کد استفاده کنید

شما می توانید اجرای کد را به عنوان بخشی از پیکربندی جلسه تعریف کنید. برای کسب اطلاعات بیشتر به آموزش اجرای کد مراجعه کنید.

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())

می توانید Grounding با جستجوی Google را به عنوان بخشی از پیکربندی جلسه فعال کنید. برای کسب اطلاعات بیشتر به آموزش Grounding مراجعه کنید.

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())

چندین ابزار را با هم ترکیب کنید

می توانید چندین ابزار را در 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}

وقفه ها را مدیریت کنید

کاربران می توانند خروجی مدل را در هر زمانی قطع کنند. هنگامی که تشخیص فعالیت صوتی (VAD) یک وقفه را تشخیص می‌دهد، تولید در حال انجام لغو و کنار گذاشته می‌شود. فقط اطلاعاتی که قبلاً برای مشتری ارسال شده است در تاریخچه جلسه حفظ می شود. سپس سرور یک پیام BidiGenerateContentServerContent برای گزارش وقفه ارسال می کند.

بعلاوه، سرور Gemini هرگونه تماس تابع معلق را کنار می گذارد و یک پیام BidiGenerateContentServerContent با شناسه تماس های لغو شده ارسال می کند.

async for response in session.receive():
    if response.server_content.interrupted is True:
        # The generation was interrupted

پیکربندی تشخیص فعالیت صوتی (VAD)

می توانید تشخیص فعالیت صوتی (VAD) را پیکربندی یا غیرفعال کنید.

از VAD خودکار استفاده کنید

به‌طور پیش‌فرض، مدل به‌طور خودکار VAD را روی یک جریان ورودی صوتی پیوسته انجام می‌دهد. VAD را می توان با فیلد realtimeInputConfig.automaticActivityDetection پیکربندی راه اندازی پیکربندی کرد.

هنگامی که جریان صوتی برای بیش از یک ثانیه متوقف می‌شود (مثلاً به دلیل خاموش کردن میکروفون توسط کاربر)، باید یک رویداد audioStreamEnd ارسال شود تا هر صدای ذخیره شده در حافظه پنهان پاک شود. مشتری می تواند در هر زمانی ارسال داده های صوتی را از سر بگیرد.

# 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())

با send_realtime_input ، API به طور خودکار بر اساس VAD به صدا پاسخ می دهد. در حالی که send_client_content پیام‌ها را به ترتیب به بافت مدل اضافه می‌کند، send_realtime_input برای پاسخگویی به هزینه ترتیب‌بندی قطعی بهینه می‌شود.

VAD خودکار را پیکربندی کنید

برای کنترل بیشتر بر فعالیت VAD، می توانید پارامترهای زیر را پیکربندی کنید. برای اطلاعات بیشتر به مرجع API مراجعه کنید.

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

VAD خودکار را غیرفعال کنید

از طرف دیگر، VAD خودکار را می‌توان با تنظیم realtimeInputConfig.automaticActivityDetection.disabled روی true در پیام راه‌اندازی غیرفعال کرد. در این پیکربندی، کلاینت مسئول تشخیص گفتار کاربر و ارسال پیام های activityStart و activityEnd در زمان های مناسب است. یک audioStreamEnd در این پیکربندی ارسال نشده است. در عوض، هرگونه وقفه در جریان با یک پیام 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())
    # ...

تعداد توکن ها را دریافت کنید

می توانید تعداد کل نشانه های مصرف شده را در قسمت usageMetadata پیام سرور برگشتی پیدا کنید.

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}")

مدت زمان جلسه را افزایش دهید

حداکثر مدت جلسه را می توان با دو مکانیسم تا نامحدود افزایش داد:

علاوه بر این، قبل از پایان جلسه یک پیام GoAway دریافت خواهید کرد که به شما امکان می دهد اقدامات بیشتری انجام دهید.

فشرده سازی پنجره زمینه را فعال کنید

برای فعال کردن جلسات طولانی تر و جلوگیری از قطع ناگهانی اتصال، می توانید فشرده سازی پنجره زمینه را با تنظیم فیلد 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(),
        )
    ),
)

پیکربندی از سرگیری جلسه

برای جلوگیری از خاتمه جلسه هنگامی که سرور به طور دوره ای اتصال WebSocket را بازنشانی می کند، فیلد sessionResumption را در پیکربندی راه اندازی پیکربندی کنید.

عبور از این پیکربندی باعث می‌شود سرور پیام‌های SessionResumptionUpdate را ارسال کند، که می‌توان با ارسال آخرین نشانه Resumption به عنوان SessionResumptionConfig.handle از اتصال بعدی، جلسه را از سر گرفت.

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())

قبل از قطع شدن جلسه پیامی دریافت کنید

سرور یک پیام GoAway ارسال می کند که سیگنال می دهد که اتصال فعلی به زودی قطع خواهد شد. این پیام شامل timeLeft است که زمان باقیمانده را نشان می‌دهد و به شما امکان می‌دهد تا قبل از اینکه اتصال به‌عنوان ABORTED قطع شود، اقدامات بیشتری انجام دهید.

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)

هنگامی که نسل کامل شد پیامی دریافت کنید

سرور یک پیام GenerationComplete می فرستد که سیگنال می دهد که مدل تولید پاسخ را به پایان رسانده است.

async for response in session.receive():
    if response.server_content.generation_complete is True:
        # The generation is complete

وضوح رسانه را تغییر دهید

می توانید با تنظیم فیلد mediaResolution به عنوان بخشی از پیکربندی جلسه، وضوح رسانه را برای رسانه ورودی مشخص کنید:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)

رونوشت های صوتی را دریافت کنید

می توانید رونویسی خروجی صدای مدل را فعال کنید. زبان رونویسی از پاسخ مدل استنباط می شود.

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())

محدودیت ها

هنگام برنامه ریزی پروژه خود، محدودیت های زیر را در مورد Live API و Gemini 2.0 در نظر بگیرید.

روش های پاسخگویی

در پیکربندی جلسه فقط می توانید یک حالت پاسخ ( TEXT یا AUDIO ) را در هر جلسه تنظیم کنید. تلاش برای تنظیم هر دو منجر به پیام خطای پیکربندی می شود. این بدان معناست که می‌توانید مدل را طوری پیکربندی کنید که با متن یا صدا پاسخ دهد، اما نه هر دو در یک جلسه.

احراز هویت مشتری

Live API فقط احراز هویت سرور به سرور را ارائه می دهد و برای استفاده مستقیم از مشتری توصیه نمی شود. ورودی مشتری باید از طریق یک سرور برنامه میانی برای احراز هویت امن با Live API هدایت شود.

مدت زمان جلسه

مدت زمان جلسه را می توان با فعال کردن فشرده سازی جلسه تا نامحدود افزایش داد. بدون فشرده سازی، جلسات فقط صوتی به 15 دقیقه و جلسات صوتی به علاوه ویدیو به 2 دقیقه محدود می شود. تجاوز از این محدودیت ها بدون فشرده سازی، اتصال را قطع می کند.

علاوه بر این، می‌توانید از سرگیری جلسه را به گونه‌ای پیکربندی کنید که به مشتری اجازه دهد جلسه‌ای را که خاتمه یافته است از سر بگیرد.

پنجره زمینه

یک جلسه دارای محدودیت پنجره زمینه 32 هزار توکن است.

زبان های پشتیبانی شده

Live API از زبان های زیر پشتیبانی می کند:

زبان کد BCP-47
آلمانی (آلمان) de-DE
انگلیسی (استرالیا) en-AU
انگلیسی (بریتانیا) en-GB
انگلیسی (هند) en-IN
انگلیسی (ایالات متحده) en-US
اسپانیایی (ایالات متحده آمریکا) es-US
فرانسوی (فرانسه) fr-FR
هندی (هند) سلام ورود
پرتغالی (برزیل) pt-BR
عربی (عمومی) ar-XA
اسپانیایی (اسپانیا) es-ES
فرانسوی (کانادا) fr-CA
اندونزیایی (اندونزی) شناسه
ایتالیایی (ایتالیا) it-IT
ژاپنی (ژاپن) ja-JP
ترکی (ترکیه) tr-TR
ویتنامی (ویتنام) vi-VN
بنگالی (هند) bn-IN
گجراتی (هند) gu-IN
کانادا (هند) kn-IN
مالایالام (هند) ml-IN
مراتی (هند) mr-IN
تامیل (هند) ta-IN
تلوگو (هند) te-IN
هلندی (هلند) nl-NL
کره ای (کره جنوبی) ko-KR
چینی ماندارین (چین) cmn-CN
لهستانی (لهستان) pl-PL
روسی (روسیه) ru-RU
تایلندی (تایلند) th-TH

ادغام های شخص ثالث

برای استقرار برنامه های وب و تلفن همراه، می توانید گزینه های زیر را بررسی کنید:

،

Live API تعامل صوتی و تصویری دو جهته با تأخیر کم با Gemini را امکان پذیر می کند. با استفاده از Live API، می‌توانید تجربه مکالمات صوتی طبیعی و شبیه انسان را در اختیار کاربران نهایی قرار دهید و با استفاده از دستورات صوتی، پاسخ‌های مدل را قطع کنید. این مدل می تواند ورودی متن، صدا و تصویر را پردازش کند و می تواند متن و خروجی صدا را ارائه دهد.

می‌توانید Live API را در Google AI Studio امتحان کنید.

چه خبر است

برای آخرین ویژگی‌ها و قابلیت‌های جدید در Live API، Changelog را بررسی کنید!

از Live API استفاده کنید

این بخش نحوه استفاده از Live API را با یکی از SDK های ما شرح می دهد. برای اطلاعات بیشتر در مورد WebSockets API اساسی، به مرجع WebSockets API مراجعه کنید.

برای استفاده از همه ویژگی‌ها، مطمئن شوید که آخرین نسخه SDK را نصب کنید، به عنوان مثال، pip install -U google-genai .

ارسال و دریافت متن

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")
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 از فرمت های صوتی زیر پشتیبانی می کند:

  • فرمت صوتی ورودی: صدای خام 16 بیتی PCM با فرکانس 16 کیلوهرتز کمی اندین
  • فرمت صدای خروجی: صدای خام 16 بیتی PCM با فرکانس 24 کیلوهرتز کمی 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)

JSON

{
  "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")
        )
    )
)

JSON

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

تغییر زبان

Live API از چندین زبان پشتیبانی می کند.

برای تغییر زبان، کد زبان را در شی speechConfig به عنوان بخشی از پیکربندی جلسه تنظیم کنید:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        language_code="de-DE",
    )
)

از ابزار استفاده کنید

می‌توانید ابزارهایی مانند فراخوانی تابع ، اجرای کد و جستجوی Google را با Live API تعریف کنید.

از فراخوانی تابع استفاده کنید

شما می توانید اعلان های تابع را به عنوان بخشی از پیکربندی جلسه تعریف کنید. برای کسب اطلاعات بیشتر به آموزش فراخوانی تابع مراجعه کنید.

پس از دریافت تماس های ابزار، مشتری باید با لیستی از اشیاء FunctionResponse با استفاده از روش 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())

از یک اعلان واحد، مدل می تواند چندین فراخوانی تابع و کدهای لازم برای زنجیره خروجی های آنها را ایجاد کند. این کد در محیط sandbox اجرا می شود و پیام های BidiGenerateContentToolCall بعدی را ایجاد می کند. اجرا متوقف می شود تا زمانی که نتایج هر فراخوانی در دسترس باشد، که پردازش متوالی را تضمین می کند.

ورودی‌ها و خروجی‌های صوتی بر توانایی مدل برای استفاده از فراخوانی تابع تأثیر منفی می‌گذارند.

از اجرای کد استفاده کنید

شما می توانید اجرای کد را به عنوان بخشی از پیکربندی جلسه تعریف کنید. برای کسب اطلاعات بیشتر به آموزش اجرای کد مراجعه کنید.

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())

می توانید Grounding با جستجوی Google را به عنوان بخشی از پیکربندی جلسه فعال کنید. برای کسب اطلاعات بیشتر به آموزش Grounding مراجعه کنید.

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())

چندین ابزار را با هم ترکیب کنید

می توانید چندین ابزار را در 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}

وقفه ها را مدیریت کنید

کاربران می توانند خروجی مدل را در هر زمانی قطع کنند. هنگامی که تشخیص فعالیت صوتی (VAD) یک وقفه را تشخیص می‌دهد، تولید در حال انجام لغو و کنار گذاشته می‌شود. فقط اطلاعاتی که قبلاً برای مشتری ارسال شده است در تاریخچه جلسه حفظ می شود. سپس سرور یک پیام BidiGenerateContentServerContent برای گزارش وقفه ارسال می کند.

بعلاوه، سرور Gemini هرگونه تماس تابع معلق را کنار می گذارد و یک پیام BidiGenerateContentServerContent با شناسه تماس های لغو شده ارسال می کند.

async for response in session.receive():
    if response.server_content.interrupted is True:
        # The generation was interrupted

پیکربندی تشخیص فعالیت صوتی (VAD)

می توانید تشخیص فعالیت صوتی (VAD) را پیکربندی یا غیرفعال کنید.

از VAD خودکار استفاده کنید

به‌طور پیش‌فرض، مدل به‌طور خودکار VAD را روی یک جریان ورودی صوتی پیوسته انجام می‌دهد. VAD را می توان با فیلد realtimeInputConfig.automaticActivityDetection پیکربندی راه اندازی پیکربندی کرد.

هنگامی که جریان صوتی برای بیش از یک ثانیه متوقف می‌شود (مثلاً به دلیل خاموش کردن میکروفون توسط کاربر)، باید یک رویداد audioStreamEnd ارسال شود تا هر صدای ذخیره شده در حافظه پنهان پاک شود. مشتری می تواند در هر زمانی ارسال داده های صوتی را از سر بگیرد.

# 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())

با send_realtime_input ، API به طور خودکار بر اساس VAD به صدا پاسخ می دهد. در حالی که send_client_content پیام‌ها را به ترتیب به بافت مدل اضافه می‌کند، send_realtime_input برای پاسخگویی به هزینه ترتیب‌بندی قطعی بهینه می‌شود.

VAD خودکار را پیکربندی کنید

برای کنترل بیشتر بر فعالیت VAD، می توانید پارامترهای زیر را پیکربندی کنید. برای اطلاعات بیشتر به مرجع API مراجعه کنید.

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

VAD خودکار را غیرفعال کنید

از طرف دیگر، VAD خودکار را می‌توان با تنظیم realtimeInputConfig.automaticActivityDetection.disabled روی true در پیام راه‌اندازی غیرفعال کرد. در این پیکربندی، کلاینت مسئول تشخیص گفتار کاربر و ارسال پیام های activityStart و activityEnd در زمان های مناسب است. یک audioStreamEnd در این پیکربندی ارسال نشده است. در عوض، هرگونه وقفه در جریان با یک پیام 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())
    # ...

تعداد توکن ها را دریافت کنید

می توانید تعداد کل نشانه های مصرف شده را در قسمت usageMetadata پیام سرور برگشتی پیدا کنید.

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}")

مدت زمان جلسه را افزایش دهید

حداکثر مدت جلسه را می توان با دو مکانیسم تا نامحدود افزایش داد:

علاوه بر این، قبل از پایان جلسه یک پیام GoAway دریافت خواهید کرد که به شما امکان می دهد اقدامات بیشتری انجام دهید.

فشرده سازی پنجره زمینه را فعال کنید

برای فعال کردن جلسات طولانی تر و جلوگیری از قطع ناگهانی اتصال، می توانید فشرده سازی پنجره زمینه را با تنظیم فیلد 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(),
        )
    ),
)

پیکربندی از سرگیری جلسه

برای جلوگیری از خاتمه جلسه هنگامی که سرور به طور دوره ای اتصال WebSocket را بازنشانی می کند، فیلد sessionResumption را در پیکربندی راه اندازی پیکربندی کنید.

عبور از این پیکربندی باعث می‌شود سرور پیام‌های SessionResumptionUpdate را ارسال کند، که می‌توان با ارسال آخرین نشانه Resumption به عنوان SessionResumptionConfig.handle از اتصال بعدی، جلسه را از سر گرفت.

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())

قبل از قطع شدن جلسه پیامی دریافت کنید

سرور یک پیام GoAway ارسال می کند که سیگنال می دهد که اتصال فعلی به زودی قطع خواهد شد. این پیام شامل timeLeft است که زمان باقیمانده را نشان می‌دهد و به شما امکان می‌دهد تا قبل از اینکه اتصال به‌عنوان ABORTED قطع شود، اقدامات بیشتری انجام دهید.

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)

هنگامی که نسل کامل شد پیامی دریافت کنید

سرور یک پیام GenerationComplete می فرستد که سیگنال می دهد که مدل تولید پاسخ را به پایان رسانده است.

async for response in session.receive():
    if response.server_content.generation_complete is True:
        # The generation is complete

وضوح رسانه را تغییر دهید

می توانید با تنظیم فیلد mediaResolution به عنوان بخشی از پیکربندی جلسه، وضوح رسانه را برای رسانه ورودی مشخص کنید:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)

رونوشت های صوتی را دریافت کنید

می توانید رونویسی خروجی صدای مدل را فعال کنید. زبان رونویسی از پاسخ مدل استنباط می شود.

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())

محدودیت ها

هنگام برنامه ریزی پروژه خود، محدودیت های زیر را در مورد Live API و Gemini 2.0 در نظر بگیرید.

روش های پاسخگویی

در پیکربندی جلسه فقط می توانید یک حالت پاسخ ( TEXT یا AUDIO ) را در هر جلسه تنظیم کنید. تلاش برای تنظیم هر دو منجر به پیام خطای پیکربندی می شود. این بدان معناست که می‌توانید مدل را طوری پیکربندی کنید که با متن یا صدا پاسخ دهد، اما نه هر دو در یک جلسه.

احراز هویت مشتری

Live API فقط احراز هویت سرور به سرور را ارائه می دهد و برای استفاده مستقیم از مشتری توصیه نمی شود. ورودی مشتری باید از طریق یک سرور برنامه میانی برای احراز هویت امن با Live API هدایت شود.

مدت زمان جلسه

مدت زمان جلسه را می توان با فعال کردن فشرده سازی جلسه تا نامحدود افزایش داد. بدون فشرده سازی، جلسات فقط صوتی به 15 دقیقه و جلسات صوتی به علاوه ویدیو به 2 دقیقه محدود می شود. تجاوز از این محدودیت ها بدون فشرده سازی، اتصال را قطع می کند.

علاوه بر این، می‌توانید از سرگیری جلسه را به گونه‌ای پیکربندی کنید که به مشتری اجازه دهد جلسه‌ای را که خاتمه یافته است از سر بگیرد.

پنجره زمینه

یک جلسه دارای محدودیت پنجره زمینه 32 هزار توکن است.

زبان های پشتیبانی شده

Live API از زبان های زیر پشتیبانی می کند:

زبان کد BCP-47
آلمانی (آلمان) de-DE
انگلیسی (استرالیا) en-AU
انگلیسی (بریتانیا) en-GB
انگلیسی (هند) en-IN
انگلیسی (ایالات متحده) en-US
اسپانیایی (ایالات متحده آمریکا) es-US
فرانسوی (فرانسه) fr-FR
هندی (هند) سلام ورود
پرتغالی (برزیل) pt-BR
عربی (عمومی) ar-XA
اسپانیایی (اسپانیا) es-ES
فرانسوی (کانادا) fr-CA
اندونزیایی (اندونزی) شناسه
ایتالیایی (ایتالیا) it-IT
ژاپنی (ژاپن) ja-JP
ترکی (ترکیه) tr-TR
ویتنامی (ویتنام) vi-VN
بنگالی (هند) bn-IN
گجراتی (هند) gu-IN
کانادا (هند) kn-IN
مالایالام (هند) ml-IN
مراتی (هند) mr-IN
تامیل (هند) ta-IN
تلوگو (هند) te-IN
هلندی (هلند) nl-NL
کره ای (کره جنوبی) ko-KR
چینی ماندارین (چین) cmn-CN
لهستانی (لهستان) pl-PL
روسی (روسیه) ru-RU
تایلندی (تایلند) th-TH

ادغام های شخص ثالث

برای استقرار برنامه های وب و تلفن همراه، می توانید گزینه های زیر را بررسی کنید:

،

Live API تعامل صوتی و تصویری دو جهته با تأخیر کم با Gemini را امکان پذیر می کند. با استفاده از Live API، می‌توانید تجربه مکالمات صوتی طبیعی و شبیه انسان را در اختیار کاربران نهایی قرار دهید و با استفاده از دستورات صوتی، پاسخ‌های مدل را قطع کنید. این مدل می تواند ورودی متن، صدا و تصویر را پردازش کند و می تواند متن و خروجی صدا را ارائه دهد.

می‌توانید Live API را در Google AI Studio امتحان کنید.

چه خبر است

برای آخرین ویژگی‌ها و قابلیت‌های جدید در Live API، Changelog را بررسی کنید!

از Live API استفاده کنید

این بخش نحوه استفاده از Live API را با یکی از SDK های ما شرح می دهد. برای اطلاعات بیشتر در مورد WebSockets API اساسی، به مرجع WebSockets API مراجعه کنید.

برای استفاده از همه ویژگی‌ها، مطمئن شوید که آخرین نسخه SDK را نصب کنید، به عنوان مثال، pip install -U google-genai .

ارسال و دریافت متن

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")
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 از فرمت های صوتی زیر پشتیبانی می کند:

  • فرمت صوتی ورودی: صدای خام 16 بیتی PCM با فرکانس 16 کیلوهرتز کمی اندین
  • فرمت صدای خروجی: صدای خام 16 بیتی PCM با فرکانس 24 کیلوهرتز کمی 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)

JSON

{
  "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")
        )
    )
)

JSON

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

تغییر زبان

Live API از چندین زبان پشتیبانی می کند.

برای تغییر زبان، کد زبان را در شی speechConfig به عنوان بخشی از پیکربندی جلسه تنظیم کنید:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        language_code="de-DE",
    )
)

از ابزار استفاده کنید

می‌توانید ابزارهایی مانند فراخوانی تابع ، اجرای کد و جستجوی Google را با Live API تعریف کنید.

از فراخوانی تابع استفاده کنید

شما می توانید اعلان های تابع را به عنوان بخشی از پیکربندی جلسه تعریف کنید. برای کسب اطلاعات بیشتر به آموزش فراخوانی تابع مراجعه کنید.

پس از دریافت تماس های ابزار، مشتری باید با لیستی از اشیاء FunctionResponse با استفاده از روش 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())

از یک اعلان واحد، مدل می تواند چندین فراخوانی تابع و کدهای لازم برای زنجیره خروجی های آنها را ایجاد کند. این کد در محیط sandbox اجرا می شود و پیام های BidiGenerateContentToolCall بعدی را ایجاد می کند. اجرا متوقف می شود تا زمانی که نتایج هر فراخوانی در دسترس باشد، که پردازش متوالی را تضمین می کند.

ورودی‌ها و خروجی‌های صوتی بر توانایی مدل برای استفاده از فراخوانی تابع تأثیر منفی می‌گذارند.

از اجرای کد استفاده کنید

شما می توانید اجرای کد را به عنوان بخشی از پیکربندی جلسه تعریف کنید. برای کسب اطلاعات بیشتر به آموزش اجرای کد مراجعه کنید.

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())

می توانید Grounding با جستجوی Google را به عنوان بخشی از پیکربندی جلسه فعال کنید. برای کسب اطلاعات بیشتر به آموزش Grounding مراجعه کنید.

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())

چندین ابزار را با هم ترکیب کنید

می توانید چندین ابزار را در 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}

وقفه ها را مدیریت کنید

کاربران می توانند خروجی مدل را در هر زمانی قطع کنند. هنگامی که تشخیص فعالیت صوتی (VAD) یک وقفه را تشخیص می‌دهد، تولید در حال انجام لغو و کنار گذاشته می‌شود. فقط اطلاعاتی که قبلاً برای مشتری ارسال شده است در تاریخچه جلسه حفظ می شود. سپس سرور یک پیام BidiGenerateContentServerContent برای گزارش وقفه ارسال می کند.

بعلاوه، سرور Gemini هرگونه تماس تابع معلق را کنار می گذارد و یک پیام BidiGenerateContentServerContent با شناسه تماس های لغو شده ارسال می کند.

async for response in session.receive():
    if response.server_content.interrupted is True:
        # The generation was interrupted

پیکربندی تشخیص فعالیت صوتی (VAD)

می توانید تشخیص فعالیت صوتی (VAD) را پیکربندی یا غیرفعال کنید.

از VAD خودکار استفاده کنید

به‌طور پیش‌فرض، مدل به‌طور خودکار VAD را روی یک جریان ورودی صوتی پیوسته انجام می‌دهد. VAD را می توان با فیلد realtimeInputConfig.automaticActivityDetection پیکربندی راه اندازی پیکربندی کرد.

هنگامی که جریان صوتی برای بیش از یک ثانیه متوقف می‌شود (مثلاً به دلیل خاموش کردن میکروفون توسط کاربر)، باید یک رویداد audioStreamEnd ارسال شود تا هر صدای ذخیره شده در حافظه پنهان پاک شود. مشتری می تواند در هر زمانی ارسال داده های صوتی را از سر بگیرد.

# 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())

با send_realtime_input ، API به طور خودکار بر اساس VAD به صدا پاسخ می دهد. در حالی که send_client_content پیام‌ها را به ترتیب به بافت مدل اضافه می‌کند، send_realtime_input برای پاسخگویی به هزینه ترتیب‌بندی قطعی بهینه می‌شود.

VAD خودکار را پیکربندی کنید

برای کنترل بیشتر بر فعالیت VAD، می توانید پارامترهای زیر را پیکربندی کنید. برای اطلاعات بیشتر به مرجع API مراجعه کنید.

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

VAD خودکار را غیرفعال کنید

از طرف دیگر، VAD خودکار را می‌توان با تنظیم realtimeInputConfig.automaticActivityDetection.disabled روی true در پیام راه‌اندازی غیرفعال کرد. در این پیکربندی، کلاینت مسئول تشخیص گفتار کاربر و ارسال پیام های activityStart و activityEnd در زمان های مناسب است. یک audioStreamEnd در این پیکربندی ارسال نشده است. در عوض، هرگونه وقفه در جریان با یک پیام 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())
    # ...

تعداد توکن ها را دریافت کنید

می توانید تعداد کل نشانه های مصرف شده را در قسمت usageMetadata پیام سرور برگشتی پیدا کنید.

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}")

مدت زمان جلسه را افزایش دهید

حداکثر مدت جلسه را می توان با دو مکانیسم تا نامحدود افزایش داد:

علاوه بر این، قبل از پایان جلسه یک پیام GoAway دریافت خواهید کرد که به شما امکان می دهد اقدامات بیشتری انجام دهید.

فشرده سازی پنجره زمینه را فعال کنید

برای فعال کردن جلسات طولانی تر و جلوگیری از قطع ناگهانی اتصال، می توانید فشرده سازی پنجره زمینه را با تنظیم فیلد 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(),
        )
    ),
)

پیکربندی از سرگیری جلسه

برای جلوگیری از خاتمه جلسه هنگامی که سرور به طور دوره ای اتصال WebSocket را بازنشانی می کند، فیلد sessionResumption را در پیکربندی راه اندازی پیکربندی کنید.

عبور از این پیکربندی باعث می‌شود سرور پیام‌های SessionResumptionUpdate را ارسال کند، که می‌توان با ارسال آخرین نشانه Resumption به عنوان SessionResumptionConfig.handle از اتصال بعدی، جلسه را از سر گرفت.

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())

قبل از قطع شدن جلسه پیامی دریافت کنید

سرور یک پیام GoAway ارسال می کند که سیگنال می دهد که اتصال فعلی به زودی قطع خواهد شد. این پیام شامل timeLeft است که زمان باقیمانده را نشان می‌دهد و به شما امکان می‌دهد تا قبل از اینکه اتصال به‌عنوان ABORTED قطع شود، اقدامات بیشتری انجام دهید.

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)

هنگامی که نسل کامل شد پیامی دریافت کنید

سرور یک پیام GenerationComplete می فرستد که سیگنال می دهد که مدل تولید پاسخ را به پایان رسانده است.

async for response in session.receive():
    if response.server_content.generation_complete is True:
        # The generation is complete

وضوح رسانه را تغییر دهید

می توانید با تنظیم فیلد mediaResolution به عنوان بخشی از پیکربندی جلسه، وضوح رسانه را برای رسانه ورودی مشخص کنید:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)

رونوشت های صوتی را دریافت کنید

می توانید رونویسی خروجی صدای مدل را فعال کنید. زبان رونویسی از پاسخ مدل استنباط می شود.

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())

محدودیت ها

هنگام برنامه ریزی پروژه خود، محدودیت های زیر را در مورد Live API و Gemini 2.0 در نظر بگیرید.

روش های پاسخگویی

در پیکربندی جلسه فقط می توانید یک حالت پاسخ ( TEXT یا AUDIO ) را در هر جلسه تنظیم کنید. تلاش برای تنظیم هر دو منجر به پیام خطای پیکربندی می شود. این بدان معناست که می‌توانید مدل را طوری پیکربندی کنید که با متن یا صدا پاسخ دهد، اما نه هر دو در یک جلسه.

احراز هویت مشتری

Live API فقط احراز هویت سرور به سرور را ارائه می دهد و برای استفاده مستقیم از مشتری توصیه نمی شود. ورودی مشتری باید از طریق یک سرور برنامه میانی برای احراز هویت امن با Live API هدایت شود.

مدت زمان جلسه

مدت زمان جلسه را می توان با فعال کردن فشرده سازی جلسه تا نامحدود افزایش داد. بدون فشرده سازی، جلسات فقط صوتی به 15 دقیقه و جلسات صوتی به علاوه ویدیو به 2 دقیقه محدود می شود. تجاوز از این محدودیت ها بدون فشرده سازی، اتصال را قطع می کند.

علاوه بر این، می‌توانید از سرگیری جلسه را به گونه‌ای پیکربندی کنید که به مشتری اجازه دهد جلسه‌ای را که خاتمه یافته است از سر بگیرد.

پنجره زمینه

یک جلسه دارای محدودیت پنجره زمینه 32 هزار توکن است.

زبان های پشتیبانی شده

Live API از زبان های زیر پشتیبانی می کند:

زبان کد BCP-47
آلمانی (آلمان) de-DE
انگلیسی (استرالیا) en-AU
انگلیسی (بریتانیا) en-GB
انگلیسی (هند) en-IN
انگلیسی (ایالات متحده) en-US
اسپانیایی (ایالات متحده آمریکا) es-US
فرانسوی (فرانسه) fr-FR
هندی (هند) سلام ورود
پرتغالی (برزیل) pt-BR
عربی (عمومی) ar-XA
اسپانیایی (اسپانیا) es-ES
فرانسوی (کانادا) fr-CA
اندونزیایی (اندونزی) شناسه
ایتالیایی (ایتالیا) it-IT
ژاپنی (ژاپن) ja-JP
ترکی (ترکیه) tr-TR
ویتنامی (ویتنام) vi-VN
بنگالی (هند) bn-IN
گجراتی (هند) gu-IN
کانادا (هند) kn-IN
مالایالام (هند) ml-IN
مراتی (هند) mr-IN
تامیل (هند) ta-IN
تلوگو (هند) te-IN
هلندی (هلند) nl-NL
کره ای (کره جنوبی) ko-KR
چینی ماندارین (چین) cmn-CN
لهستانی (لهستان) pl-PL
روسی (روسیه) ru-RU
تایلندی (تایلند) th-TH

ادغام های شخص ثالث

برای استقرار برنامه های وب و تلفن همراه، می توانید گزینه های زیر را بررسی کنید:

،

Live API تعامل صوتی و تصویری دو جهته با تأخیر کم با Gemini را امکان پذیر می کند. با استفاده از Live API، می‌توانید تجربه مکالمات صوتی طبیعی و شبیه انسان را در اختیار کاربران نهایی قرار دهید و با استفاده از دستورات صوتی، پاسخ‌های مدل را قطع کنید. این مدل می تواند ورودی متن، صدا و تصویر را پردازش کند و می تواند متن و خروجی صدا را ارائه دهد.

می‌توانید Live API را در Google AI Studio امتحان کنید.

چه خبر است

برای آخرین ویژگی‌ها و قابلیت‌های جدید در Live API، Changelog را بررسی کنید!

از Live API استفاده کنید

این بخش نحوه استفاده از Live API را با یکی از SDK های ما شرح می دهد. برای اطلاعات بیشتر در مورد WebSockets API اساسی، به مرجع WebSockets API مراجعه کنید.

برای استفاده از همه ویژگی‌ها، مطمئن شوید که آخرین نسخه SDK را نصب کنید، به عنوان مثال، pip install -U google-genai .

ارسال و دریافت متن

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")
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 از فرمت های صوتی زیر پشتیبانی می کند:

  • فرمت صوتی ورودی: صدای خام 16 بیتی PCM با فرکانس 16 کیلوهرتز کمی اندین
  • فرمت صدای خروجی: صدای خام 16 بیتی PCM با فرکانس 24 کیلوهرتز کمی 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)

JSON

{
  "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")
        )
    )
)

JSON

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

تغییر زبان

Live API از چندین زبان پشتیبانی می کند.

برای تغییر زبان، کد زبان را در شی speechConfig به عنوان بخشی از پیکربندی جلسه تنظیم کنید:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        language_code="de-DE",
    )
)

از ابزار استفاده کنید

می‌توانید ابزارهایی مانند فراخوانی تابع ، اجرای کد و جستجوی Google را با Live API تعریف کنید.

از فراخوانی تابع استفاده کنید

شما می توانید اعلان های تابع را به عنوان بخشی از پیکربندی جلسه تعریف کنید. برای کسب اطلاعات بیشتر به آموزش فراخوانی تابع مراجعه کنید.

پس از دریافت تماس های ابزار، مشتری باید با لیستی از اشیاء FunctionResponse با استفاده از روش 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())

از یک اعلان واحد، مدل می تواند چندین فراخوانی تابع و کدهای لازم برای زنجیره خروجی های آنها را ایجاد کند. این کد در محیط sandbox اجرا می شود و پیام های BidiGenerateContentToolCall بعدی را ایجاد می کند. اجرا متوقف می شود تا زمانی که نتایج هر فراخوانی در دسترس باشد، که پردازش متوالی را تضمین می کند.

ورودی‌ها و خروجی‌های صوتی بر توانایی مدل برای استفاده از فراخوانی تابع تأثیر منفی می‌گذارند.

از اجرای کد استفاده کنید

شما می توانید اجرای کد را به عنوان بخشی از پیکربندی جلسه تعریف کنید. برای کسب اطلاعات بیشتر به آموزش اجرای کد مراجعه کنید.

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())

می توانید Grounding با جستجوی Google را به عنوان بخشی از پیکربندی جلسه فعال کنید. برای کسب اطلاعات بیشتر به آموزش Grounding مراجعه کنید.

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())

چندین ابزار را با هم ترکیب کنید

می توانید چندین ابزار را در 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}

وقفه ها را مدیریت کنید

کاربران می توانند خروجی مدل را در هر زمانی قطع کنند. هنگامی که تشخیص فعالیت صوتی (VAD) یک وقفه را تشخیص می‌دهد، تولید در حال انجام لغو و کنار گذاشته می‌شود. فقط اطلاعاتی که قبلاً برای مشتری ارسال شده است در تاریخچه جلسه حفظ می شود. سپس سرور یک پیام BidiGenerateContentServerContent برای گزارش وقفه ارسال می کند.

بعلاوه، سرور Gemini هرگونه تماس تابع معلق را کنار می گذارد و یک پیام BidiGenerateContentServerContent با شناسه تماس های لغو شده ارسال می کند.

async for response in session.receive():
    if response.server_content.interrupted is True:
        # The generation was interrupted

پیکربندی تشخیص فعالیت صوتی (VAD)

می توانید تشخیص فعالیت صوتی (VAD) را پیکربندی یا غیرفعال کنید.

از VAD خودکار استفاده کنید

به‌طور پیش‌فرض، مدل به‌طور خودکار VAD را روی یک جریان ورودی صوتی پیوسته انجام می‌دهد. VAD را می توان با فیلد realtimeInputConfig.automaticActivityDetection پیکربندی راه اندازی پیکربندی کرد.

هنگامی که جریان صوتی برای بیش از یک ثانیه متوقف می‌شود (مثلاً به دلیل خاموش کردن میکروفون توسط کاربر)، باید یک رویداد audioStreamEnd ارسال شود تا هر صدای ذخیره شده در حافظه پنهان پاک شود. مشتری می تواند در هر زمانی ارسال داده های صوتی را از سر بگیرد.

# 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())

با send_realtime_input ، API به طور خودکار بر اساس VAD به صدا پاسخ می دهد. در حالی که send_client_content پیام‌ها را به ترتیب به بافت مدل اضافه می‌کند، send_realtime_input برای پاسخگویی به هزینه ترتیب‌بندی قطعی بهینه می‌شود.

VAD خودکار را پیکربندی کنید

برای کنترل بیشتر بر فعالیت VAD، می توانید پارامترهای زیر را پیکربندی کنید. برای اطلاعات بیشتر به مرجع API مراجعه کنید.

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

VAD خودکار را غیرفعال کنید

از طرف دیگر، VAD خودکار را می‌توان با تنظیم realtimeInputConfig.automaticActivityDetection.disabled روی true در پیام راه‌اندازی غیرفعال کرد. در این پیکربندی، کلاینت مسئول تشخیص گفتار کاربر و ارسال پیام های activityStart و activityEnd در زمان های مناسب است. یک audioStreamEnd در این پیکربندی ارسال نشده است. در عوض، هرگونه وقفه در جریان با یک پیام 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())
    # ...

تعداد توکن ها را دریافت کنید

می توانید تعداد کل نشانه های مصرف شده را در قسمت usageMetadata پیام سرور برگشتی پیدا کنید.

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}")

مدت زمان جلسه را افزایش دهید

حداکثر مدت جلسه را می توان با دو مکانیسم تا نامحدود افزایش داد:

علاوه بر این، قبل از پایان جلسه یک پیام GoAway دریافت خواهید کرد که به شما امکان می دهد اقدامات بیشتری انجام دهید.

فشرده سازی پنجره زمینه را فعال کنید

برای فعال کردن جلسات طولانی تر و جلوگیری از قطع ناگهانی اتصال، می توانید فشرده سازی پنجره زمینه را با تنظیم فیلد 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(),
        )
    ),
)

پیکربندی از سرگیری جلسه

برای جلوگیری از خاتمه جلسه هنگامی که سرور به طور دوره ای اتصال WebSocket را بازنشانی می کند، فیلد sessionResumption را در پیکربندی راه اندازی پیکربندی کنید.

عبور از این پیکربندی باعث می‌شود سرور پیام‌های SessionResumptionUpdate را ارسال کند، که می‌توان با ارسال آخرین نشانه Resumption به عنوان SessionResumptionConfig.handle از اتصال بعدی، جلسه را از سر گرفت.

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())

قبل از قطع شدن جلسه پیامی دریافت کنید

سرور یک پیام GoAway ارسال می کند که سیگنال می دهد که اتصال فعلی به زودی قطع خواهد شد. این پیام شامل timeLeft است که زمان باقیمانده را نشان می‌دهد و به شما امکان می‌دهد تا قبل از اینکه اتصال به‌عنوان ABORTED قطع شود، اقدامات بیشتری انجام دهید.

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)

هنگامی که نسل کامل شد پیامی دریافت کنید

سرور یک پیام GenerationComplete می فرستد که سیگنال می دهد که مدل تولید پاسخ را به پایان رسانده است.

async for response in session.receive():
    if response.server_content.generation_complete is True:
        # The generation is complete

وضوح رسانه را تغییر دهید

می توانید با تنظیم فیلد mediaResolution به عنوان بخشی از پیکربندی جلسه، وضوح رسانه را برای رسانه ورودی مشخص کنید:

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,
)

رونوشت های صوتی را دریافت کنید

می توانید رونویسی خروجی صدای مدل را فعال کنید. زبان رونویسی از پاسخ مدل استنباط می شود.

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())

محدودیت ها

هنگام برنامه ریزی پروژه خود، محدودیت های زیر را در مورد Live API و Gemini 2.0 در نظر بگیرید.

روش های پاسخگویی

در پیکربندی جلسه فقط می توانید یک حالت پاسخ ( TEXT یا AUDIO ) را در هر جلسه تنظیم کنید. تلاش برای تنظیم هر دو منجر به پیام خطای پیکربندی می شود. این بدان معناست که می‌توانید مدل را طوری پیکربندی کنید که با متن یا صدا پاسخ دهد، اما نه هر دو در یک جلسه.

احراز هویت مشتری

Live API فقط احراز هویت سرور به سرور را ارائه می دهد و برای استفاده مستقیم از مشتری توصیه نمی شود. ورودی مشتری باید از طریق یک سرور برنامه میانی برای احراز هویت امن با Live API هدایت شود.

مدت زمان جلسه

مدت زمان جلسه را می توان با فعال کردن فشرده سازی جلسه تا نامحدود افزایش داد. بدون فشرده سازی، جلسات فقط صوتی به 15 دقیقه و جلسات صوتی به علاوه ویدیو به 2 دقیقه محدود می شود. تجاوز از این محدودیت ها بدون فشرده سازی، اتصال را قطع می کند.

علاوه بر این، می‌توانید از سرگیری جلسه را به گونه‌ای پیکربندی کنید که به مشتری اجازه دهد جلسه‌ای را که خاتمه یافته است از سر بگیرد.

پنجره زمینه

یک جلسه دارای محدودیت پنجره زمینه 32 هزار توکن است.

زبان های پشتیبانی شده

Live API از زبان های زیر پشتیبانی می کند:

زبان کد BCP-47
آلمانی (آلمان) de-DE
انگلیسی (استرالیا) en-AU
انگلیسی (بریتانیا) en-GB
انگلیسی (هند) en-IN
انگلیسی (ایالات متحده) en-US
اسپانیایی (ایالات متحده آمریکا) es-US
فرانسوی (فرانسه) fr-FR
هندی (هند) سلام ورود
پرتغالی (برزیل) pt-BR
عربی (عمومی) ar-XA
اسپانیایی (اسپانیا) es-ES
فرانسوی (کانادا) fr-CA
اندونزیایی (اندونزی) شناسه
ایتالیایی (ایتالیا) it-IT
ژاپنی (ژاپن) ja-JP
ترکی (ترکیه) tr-TR
ویتنامی (ویتنام) vi-VN
بنگالی (هند) bn-IN
گجراتی (هند) gu-IN
کانادا (هند) kn-IN
مالایالام (هند) ml-IN
مراتی (هند) mr-IN
تامیل (هند) ta-IN
تلوگو (هند) te-IN
هلندی (هلند) nl-NL
کره ای (کره جنوبی) ko-KR
چینی ماندارین (چین) cmn-CN
لهستانی (لهستان) pl-PL
روسی (روسیه) ru-RU
تایلندی (تایلند) th-TH

ادغام های شخص ثالث

برای استقرار برنامه های وب و تلفن همراه، می توانید گزینه های زیر را بررسی کنید: