Multimodal Live API, Gemini ile düşük gecikmeli iki yönlü ses ve video etkileşimi sağlar. Multimodal Live API'yi kullanarak son kullanıcılara doğal, insana benzeyen sesli sohbet deneyimi ve sesli komutları kullanarak modelin yanıtlarını kesintiye uğratma olanağı sunabilirsiniz. Model, metin, ses ve video girişini işleyebilir ve metin ile ses çıkışı sağlayabilir.
Çoklu Formatlı Canlı API'yi Google AI Studio'da deneyebilirsiniz.
Multimodal Live API'yi kullanma
Bu bölümde, Multimodal Live API'nin SDK'larımızdan biriyle nasıl kullanılacağı açıklanmaktadır. Temel WebSockets API hakkında daha fazla bilgi için aşağıdaki WebSockets API referansı bölümüne bakın.
Metin gönderme ve alma
import asyncio
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"
config = {"response_modalities": ["TEXT"]}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
while True:
message = input("User> ")
if message.lower() == "exit":
break
await session.send(input=message, end_of_turn=True)
async for response in session.receive():
if response.text is not None:
print(response.text, end="")
if __name__ == "__main__":
asyncio.run(main())
Ses alma
Aşağıdaki örnekte, ses verilerinin nasıl alınacağı ve .wav
dosyasına nasıl yazılacağı gösterilmektedir.
import asyncio
import wave
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"
config = {"response_modalities": ["AUDIO"]}
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
wf = wave.open("audio.wav", "wb")
wf.setnchannels(1)
wf.setsampwidth(2)
wf.setframerate(24000)
message = "Hello? Gemini are you there?"
await session.send(input=message, end_of_turn=True)
async for idx,response in async_enumerate(session.receive()):
if response.data is not None:
wf.writeframes(response.data)
# Comment this out to print audio data info
# if response.server_content.model_turn is not None:
# print(response.server_content.model_turn.parts[0].inline_data.mime_type)
wf.close()
if __name__ == "__main__":
asyncio.run(main())
Ses biçimleri
Multimodal Live API aşağıdaki ses biçimlerini destekler:
- Giriş ses biçimi: 16 kHz little-endian'da ham 16 bit PCM ses
- Çıkış ses biçimi: 24 kHz little-endian'da ham 16 bit PCM ses
Ses ve video aktarma
Sistem talimatları
Sistem talimatları, bir modelin davranışını belirli ihtiyaçlarınıza ve kullanım alanlarınıza göre yönlendirmenize olanak tanır. Sistem talimatları, kurulum yapılandırmasında ayarlanabilir ve oturum boyunca geçerli kalır.
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"],
}
Artımlı içerik güncellemeleri
Metin girişi göndermek, oturum bağlamı oluşturmak veya oturum bağlamını geri yüklemek için artımlı güncellemeleri kullanın. Kısa bağlamlarda, tam etkinlik sırasını temsil etmek için adım adım etkileşimler gönderebilirsiniz:
from google.genai import types
turns = [
types.Content(parts=[types.Part(text="What is the capital of France?")], role="user"),
types.Content(parts=[types.Part(text="Paris")], role="model")
]
await session.send(input=types.LiveClientContent(turns=turns))
turns = [types.Content(parts=[types.Part(text="What is the capital of Germany?")], role="user")]
await session.send(input=types.LiveClientContent(turns=turns, turn_complete=True))
{
"clientContent": {
"turns": [
{
"parts":[
{
"text": ""
}
],
"role":"user"
},
{
"parts":[
{
"text": ""
}
],
"role":"model"
}
],
"turnComplete": true
}
}
Daha uzun bağlamlarda, sonraki etkileşimler için bağlam penceresini boşaltmak amacıyla tek bir mesaj özeti sağlamanız önerilir.
Sesleri değiştirme
Multimodal Live API şu sesleri destekler: Aoede, Charon, Fenrir, Kore ve Puck.
Ses belirlemek için oturum yapılandırmasının bir parçası olarak speechConfig
nesnesinde ses adını ayarlayın:
from google.genai import types
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
speech_config=types.SpeechConfig(
voice_config=types.VoiceConfig(
prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
)
)
)
{
"voiceConfig": {
"prebuiltVoiceConfig": {
"voiceName": "Kore"
}
}
}
İşlev çağrısını kullanma
Multimodal Live API ile araçları tanımlayabilirsiniz. İşlev çağırma hakkında daha fazla bilgi edinmek için İşlev çağırma eğitimi başlıklı makaleyi inceleyin.
Araçlar, oturum yapılandırmasının bir parçası olarak tanımlanmalıdır:
config = types.LiveConnectConfig(
response_modalities=["TEXT"],
tools=[set_light_values]
)
async with client.aio.live.connect(model=model, config=config) as session:
await session.send(input="Turn the lights down to a romantic level", end_of_turn=True)
async for response in session.receive():
print(response.tool_call)
Model, tek bir istemden birden fazla işlev çağrısı ve çıktılarını zincirlemek için gereken kodu oluşturabilir. Bu kod, korumalı bir ortamda yürütülerek sonraki BidiGenerateContentToolCall iletilerini oluşturur. Yürütme, her işlev çağrısının sonuçları hazır olana kadar duraklatılır. Bu sayede sıralı işleme sağlanır.
Müşteri, BidiGenerateContentToolResponse ile yanıt vermelidir.
Ses girişleri ve ses çıkışları, modelin işlev çağrısı kullanma özelliğini olumsuz etkiler.
Kesintileri ele alma
Kullanıcılar istedikleri zaman modelin çıktısını kesintiye uğratabilir. Ses etkinliği algılama (VAD) bir kesinti algıladığında devam eden oluşturma işlemi iptal edilir ve atılır. Oturum geçmişinde yalnızca istemciye gönderilmiş olan bilgiler saklanır. Ardından sunucu, kesintiyi bildirmek için bir BidiGenerateContentServerContent mesajı gönderir.
Ayrıca Gemini sunucusu, bekleyen tüm işlev çağrılarını atar ve iptal edilen çağrıların kimliklerini içeren bir BidiGenerateContentServerContent
mesajı gönderir.
async for response in session.receive():
if response.server_content.interrupted is not None:
# The generation was interrupted
Sınırlamalar
Projenizi planlarken Multimodal Live API ve Gemini 2.0'ın aşağıdaki sınırlamalarını göz önünde bulundurun.
İstemci kimlik doğrulaması
Multimodal Live API yalnızca sunucudan sunucuya kimlik doğrulama sağlar ve doğrudan istemci kullanımı için önerilmez. Multimodal Live API ile güvenli kimlik doğrulama için istemci girişi, bir ara uygulama sunucusu üzerinden yönlendirilmelidir.
Görüşme geçmişi
Model, oturum içi etkileşimleri takip eder ancak ileti dizisi geçmişi depolanmaz. Bir oturum sona erdiğinde ilgili bağlam silinir.
Önceki bir oturumu geri yüklemek veya modele kullanıcı etkileşimlerinin geçmiş bağlamını sağlamak için uygulamanın kendi sohbet günlüğünü tutması ve bu bilgileri yeni bir oturumun başında göndermek için bir BidiGenerateContentClientContent mesajı kullanması gerekir.
Maksimum oturum süresi
Oturum süresi, ses için en fazla 15 dakika veya ses ve video için en fazla 2 dakika ile sınırlıdır. Oturum süresi sınırı aşıldığında bağlantı sonlandırılır.
Model, bağlam boyutuyla da sınırlıdır. Video ve ses akışlarının yanı sıra büyük miktarda içerik göndermek, oturumun daha erken sonlandırılmasına neden olabilir.
Ses etkinliği algılama (VAD)
Model, sürekli bir ses girişi akışında otomatik olarak ses etkinliği algılama (VAD) işlemi gerçekleştirir. VAD her zaman etkindir ve parametreleri yapılandırılamaz.
Jeton sayısı
Jeton sayısı desteklenmez.
Hız sınırları
Aşağıdaki hız sınırları geçerlidir:
- API anahtarı başına 3 eşzamanlı oturum
- Dakikada 4 milyon jeton
WebSockets API referansı
Multimodal Live API, WebSockets kullanan durum bilgisine sahip bir API'dir. Bu bölümde, WebSockets API ile ilgili ek ayrıntılar bulabilirsiniz.
Oturum sayısı
WebSocket bağlantısı, istemci ile Gemini sunucusu arasında bir oturum oluşturur. Bir istemci yeni bir bağlantı başlattıktan sonra oturum, sunucuyla mesaj alışverişinde bulunarak şunları yapabilir:
- Gemini sunucusuna metin, ses veya video gönderme.
- Gemini sunucusundan ses, metin veya işlev çağrısı istekleri alma
Bağlantı kurulduktan sonraki ilk mesaj, model, oluşturma parametreleri, sistem talimatları ve araçları içeren oturum yapılandırmasını ayarlar.
Aşağıdaki örnek yapılandırmaya bakın. SDK'lardaki ad büyük/küçük harf kullanımında farklılıklar olabileceğini unutmayın. Python SDK yapılandırma seçeneklerini buradan inceleyebilirsiniz.
{
"model": string,
"generationConfig": {
"candidateCount": integer,
"maxOutputTokens": integer,
"temperature": number,
"topP": number,
"topK": integer,
"presencePenalty": number,
"frequencyPenalty": number,
"responseModalities": [string],
"speechConfig": object
},
"systemInstruction": string,
"tools": [object]
}
Mesaj gönderin
WebSocket bağlantısı üzerinden mesaj alışverişi yapmak için istemcinin açık bir WebSocket bağlantısı üzerinden JSON nesnesi göndermesi gerekir. JSON nesnesi, aşağıdaki nesne grubundaki alanlardan tam olarak birine sahip olmalıdır:
{
"setup": BidiGenerateContentSetup,
"clientContent": BidiGenerateContentClientContent,
"realtimeInput": BidiGenerateContentRealtimeInput,
"toolResponse": BidiGenerateContentToolResponse
}
Desteklenen istemci mesajları
Desteklenen istemci mesajlarını aşağıdaki tabloda görebilirsiniz:
Mesaj | Açıklama |
---|---|
BidiGenerateContentSetup |
İlk mesajda gönderilecek oturum yapılandırması |
BidiGenerateContentClientContent |
İstemciden gönderilen mevcut sohbetin artımlı içerik güncellemesi |
BidiGenerateContentRealtimeInput |
Gerçek zamanlı ses veya video girişi |
BidiGenerateContentToolResponse |
Sunucudan alınan ToolCallMessage yanıtı |
İleti alma
Gemini'den mesaj almak için WebSocket "mesaj" etkinliğini dinleyin ve ardından sonucu, desteklenen sunucu mesajlarının tanımına göre ayrıştırın.
Aşağıdakilere bakın:
async with client.aio.live.connect(model='...', config=config) as session:
await session.send(input='Hello world!', end_of_turn=True)
async for message in session.receive():
print(message)
Sunucu mesajlarında aşağıdaki nesne grubundan tam olarak bir alan bulunur:
{
"setupComplete": BidiGenerateContentSetupComplete,
"serverContent": BidiGenerateContentServerContent,
"toolCall": BidiGenerateContentToolCall,
"toolCallCancellation": BidiGenerateContentToolCallCancellation
}
Desteklenen sunucu mesajları
Desteklenen sunucu mesajlarını aşağıdaki tabloda görebilirsiniz:
Mesaj | Açıklama |
---|---|
BidiGenerateContentSetupComplete |
Kurulum tamamlandığında istemciden gönderilen bir BidiGenerateContentSetup mesajı |
BidiGenerateContentServerContent |
Müşteri mesajına yanıt olarak model tarafından oluşturulan içerik |
BidiGenerateContentToolCall |
İstemcinin işlev çağrılarını çalıştırmasını ve yanıtları eşleşen kimliklerle döndürmesini isteme |
BidiGenerateContentToolCallCancellation |
Kullanıcı model çıkışını kesintiye uğrattığı için bir işlev çağrısı iptal edildiğinde gönderilir |
Mesajlar ve etkinlikler
BidiGenerateContentClientContent
İstemciden gönderilen mevcut sohbetin artımlı güncellemesi. Buradaki tüm içerikler koşulsuz olarak ileti dizisine eklenir ve içerik oluşturmak için modele verilen istemin bir parçası olarak kullanılır.
Buradaki bir mesaj, mevcut model oluşturma işlemini kesintiye uğratır.
Alanlar | |
---|---|
turns[] |
İsteğe bağlı. Modelle olan mevcut görüşmeye eklenen içerik. Tek turlu sorgular için bu tek bir örnektir. Birden fazla dönüş içeren sorgular için bu, sohbet geçmişini ve son isteği içeren yinelenen bir alandır. |
turn_ |
İsteğe bağlı. Doğru ise sunucu içeriği oluşturma işleminin, şu anda birikmiş istemle başlaması gerektiğini belirtir. Aksi takdirde sunucu, oluşturma işlemini başlatmadan önce ek mesaj bekler. |
BidiGenerateContentRealtimeInput
Gerçek zamanlı olarak gönderilen kullanıcı girişi.
Bu, BidiGenerateContentClientContent
ile birkaç açıdan farklıdır:
- Model oluşturma işlemine kesinti vermeden sürekli olarak gönderilebilir.
BidiGenerateContentClientContent
veBidiGenerateContentRealtimeInput
arasında ardışık olarak yerleştirilmiş verileri karıştırmak gerekirse sunucu en iyi yanıtı verecek şekilde optimizasyon yapmaya çalışır ancak bu konuda garanti verilmez.- Sıranın sonu açıkça belirtilmez, bunun yerine kullanıcı etkinliğinden (ör. konuşmanın sonu) türetilir.
- Dönüş bitmeden önce bile veriler, modelden gelen yanıtın hızlı bir şekilde başlatılması için optimize edilmek üzere artımlı olarak işlenir.
- Her zaman kullanıcının girişi olarak kabul edilir (ileti dizisi geçmişini doldurmak için kullanılamaz). Kesintisiz olarak sürekli gönderilebilir. Model, kullanıcı konuşmasının başlangıcını ve sonunu otomatik olarak algılar ve yanıtın aktarılmasını buna göre başlatır veya sonlandırır. Veriler, geldikçe artımlı olarak işlenir ve gecikme en aza indirilir.
Alanlar | |
---|---|
media_ |
İsteğe bağlı. Medya girişi için satır içi bayt verileri. |
BidiGenerateContentServerContent
İstemci mesajlarına yanıt olarak model tarafından oluşturulan artımlı sunucu güncellemesi.
İçerik, gerçek zamanlı olarak değil, mümkün olduğunca hızlı bir şekilde oluşturulur. İstemciler, içeriği arabelleğe alıp gerçek zamanlı olarak oynatmayı seçebilir.
Alanlar | |
---|---|
turn_ |
Yalnızca çıkış. True (Doğru) ise modelin oluşturulmasının tamamlandığını gösterir. Oluşturma işlemi yalnızca ek istemci mesajlarına yanıt olarak başlar. |
interrupted |
Yalnızca çıkış. Doğru ise bir istemci mesajının mevcut model oluşturma işlemini kesintiye uğrattığını gösterir. İstemci içeriği gerçek zamanlı olarak oynatıyorsa bu, oynatmayı durdurup mevcut oynatma sırasını boşaltmak için iyi bir sinyaldir. |
grounding_ |
Yalnızca çıkış. Oluşturulan içerik için temel meta veriler. |
model_ |
Yalnızca çıkış. Modelin, kullanıcıyla devam eden görüşmenin bir parçası olarak oluşturduğu içerik. |
BidiGenerateContentSetup
İlk ve tek istemci mesajında gönderilecek mesaj. Akış oturumu boyunca geçerli olacak yapılandırmayı içerir.
Müşteriler, ek mesaj göndermeden önce bir BidiGenerateContentSetupComplete
mesajı beklemelidir.
Alanlar | |
---|---|
model |
Zorunlu. Modelin kaynak adı. Bu, modelin kullanacağı bir kimlik görevi görür. Biçim: |
generation_ |
İsteğe bağlı. Oluşturma yapılandırması. Aşağıdaki alanlar desteklenmez:
|
system_ |
İsteğe bağlı. Kullanıcı, model için sistem talimatları sağladı. Not: Parçalarda yalnızca metin kullanılmalıdır. Her bölümdeki içerik ayrı bir paragrafta yer alır. |
tools[] |
İsteğe bağlı. Modelin sonraki yanıtı oluşturmak için kullanabileceği
|
BidiGenerateContentSetupComplete
Bu türde alan yoktur.
İstemciden gelen bir BidiGenerateContentSetup
mesajına yanıt olarak gönderilir.
BidiGenerateContentToolCall
İstemciden işlev çağrılarını yürütmesini ve eşleşen id
ile yanıtları döndürmesini isteyin.
Alanlar | |
---|---|
function_ |
Yalnızca çıkış. Yürütülecek işlev çağrısı. |
BidiGenerateContentToolCallCancellation
Belirtilen id
'ler içeren daha önce verilen bir ToolCallMessage
'nin yürütülmemesi ve iptal edilmesi gerektiğini müşteriye bildiren bildirim. Bu araç çağrılarının yan etkileri varsa istemciler araç çağrılarını geri almaya çalışabilir. Bu mesaj yalnızca istemcilerin sunucu sırasını kesintiye uğrattığı durumlarda gösterilir.
Alanlar | |
---|---|
ids[] |
Yalnızca çıkış. İptal edilecek araç çağrılarının kimlikleri. |
BidiGenerateContentToolResponse
Sunucudan alınan bir ToolCall
için istemci tarafından oluşturulan yanıt. Ayrı FunctionResponse
nesneleri, id
alanı tarafından ilgili FunctionCall
nesneleriyle eşleştirilir.
Tek değerli ve sunucudan aktarılan GenerateContent API'lerinde işlev çağrısının Content
parçalarının değiştirilmesiyle gerçekleştiğini, çift yönlü GenerateContent API'lerinde ise işlev çağrısının bu özel mesaj grubu üzerinden gerçekleştiğini unutmayın.
Alanlar | |
---|---|
function_ |
İsteğe bağlı. İşlev çağrılarına verilen yanıt. |
Yaygın türler hakkında daha fazla bilgi
Sık kullanılan API kaynak türleri Blob
,
Content
, FunctionCall
, FunctionResponse
, GenerationConfig
,
GroundingMetadata
ve Tool
hakkında daha fazla bilgi edinmek için İçerik oluşturma başlıklı makaleyi inceleyin.
Üçüncü taraf entegrasyonları
Web ve mobil uygulama dağıtımları için aşağıdaki seçenekleri inceleyebilirsiniz: