Live API - WebSockets API reference

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

WebSocket bağlantısı

Oturum başlatmak için şu websocket uç noktasına bağlanın:

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent

Oturum yapılandırması

Bağlantı kurulduktan sonraki ilk mesaj, model, oluşturma parametreleri, sistem talimatları ve araçları içeren oturum yapılandırmasını ayarlar.

Oturum sırasında model dışındaki yapılandırma parametrelerini değiştirebilirsiniz.

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,
    "mediaResolution": object
  },
  "systemInstruction": string,
  "tools": [object]
}

API alanı hakkında daha fazla bilgi için generationConfig bölümüne bakın.

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, video veya metin 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 usageMetadata alanı bulunabilir ancak bu alan dışında BidiGenerateContentServerMessage mesajındaki diğer alanlardan tam olarak bir alan yer alır. (messageType birleştirme işlemi JSON'da ifade edilmediğinden alan, mesajın üst düzeyinde görünür.)

Mesajlar ve etkinlikler

ActivityEnd

Bu türde alan yoktur.

Kullanıcı etkinliğinin sonunu işaret eder.

ActivityHandling

Kullanıcı etkinliğini işleme yöntemleri.

Sıralamalar
ACTIVITY_HANDLING_UNSPECIFIED Belirtilmemişse varsayılan davranış START_OF_ACTIVITY_INTERRUPTS olur.
START_OF_ACTIVITY_INTERRUPTS Doğru ise etkinliğin başlatılması, modelin yanıtını kesintiye uğratır ("ara verme" olarak da bilinir). Modelin mevcut yanıtı, kesinti anında kesilir. Bu varsayılan davranıştır.
NO_INTERRUPTION Modelin yanıtı kesintiye uğramaz.

ActivityStart

Bu türde alan yoktur.

Kullanıcı etkinliğinin başlangıcını işaret eder.

AudioTranscriptionConfig

Bu türde alan yoktur.

Ses transkripti yapılandırması.

AutomaticActivityDetection

Etkinliğin otomatik olarak algılanmasını yapılandırır.

Alanlar
disabled

bool

İsteğe bağlı. Etkinleştirilirse (varsayılan) algılanan ses ve metin girişi etkinlik olarak sayılır. Devre dışı bırakılırsa istemcinin etkinlik sinyalleri göndermesi gerekir.
startOfSpeechSensitivity

StartSensitivity

İsteğe bağlı. Konuşmanın algılanma olasılığını belirler.
prefixPaddingMs

int32

İsteğe bağlı. Konuşma başlangıcı kaydedilmeden önce algılanan konuşmanın gerekli süresi. Bu değer ne kadar düşük olursa konuşma başlangıcı algılama o kadar hassas olur ve daha kısa konuşmalar tanınabilir. Ancak bu, yanlış pozitif olasılığını da artırır.
endOfSpeechSensitivity

EndSensitivity

İsteğe bağlı. Algılanan konuşmanın sona erme olasılığını belirler.
silenceDurationMs

int32

İsteğe bağlı. Konuşma sonu kaydedilmeden önce algılanan konuşma dışı seslerin (ör. sessizlik) gerekli süresi. Bu değer ne kadar büyük olursa kullanıcının etkinliğini kesintiye uğratmadan konuşma aralıkları o kadar uzun olabilir ancak bu, modelin gecikmesini artırır.

BidiGenerateContentClientContent

İstemciden gönderilen mevcut sohbetin artımlı güncellemesi. Buradaki tüm içerikler koşulsuz olarak ileti dizisi geçmişine 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[]

Content

İ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.
turnComplete

bool

İ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.

Farklı modlar (ses, video ve metin) eşzamanlı akışlar olarak işlenir. Bu akışlardaki sıralama garanti edilmez.

Bu, BidiGenerateContentClientContent'ten birkaç açıdan farklıdır:

  • Model oluşturma işlemine kesinti vermeden sürekli olarak gönderilebilir.
  • BidiGenerateContentClientContent ve BidiGenerateContentRealtimeInput arasında ardışık olarak yerleştirilmiş verileri karıştırmak gerekirse sunucu en iyi yanıt için 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.
Alanlar
mediaChunks[]

Blob

İsteğe bağlı. Medya girişi için satır içi bayt verileri. Birden fazla mediaChunks desteklenmez. İlk mediaChunks hariç diğer tüm mediaChunks'ler yok sayılır.

KULLANIMDAN KALDIRILDI: Bunun yerine audio, video veya text öğelerinden birini kullanın.
audio

Blob

İsteğe bağlı. Bunlar, gerçek zamanlı ses giriş akışını oluşturur.
video

Blob

İsteğe bağlı. Bunlar, gerçek zamanlı video giriş akışını oluşturur.
activityStart

ActivityStart

İsteğe bağlı. Kullanıcı etkinliğinin başlangıcını işaret eder. Bu yalnızca otomatik (ör. sunucu tarafı) etkinlik algılama devre dışıysa gönderilebilir.
activityEnd

ActivityEnd

İsteğe bağlı. Kullanıcı etkinliğinin sonunu işaret eder. Bu yalnızca otomatik (ör. sunucu tarafı) etkinlik algılama devre dışıysa gönderilebilir.
audioStreamEnd

bool

İsteğe bağlı. Mikrofonun kapatılması gibi nedenlerle ses akışının sona erdiğini gösterir.

Bu yalnızca otomatik etkinlik algılama etkinleştirildiğinde (varsayılan olarak etkindir) gönderilmelidir.

İstemci, sesli mesaj göndererek yayını yeniden açabilir.
text

string

İsteğe bağlı. Bunlar, anlık metin giriş akışını oluşturur.

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
generationComplete

bool

Yalnızca çıkış. True (Doğru) ise modelin oluşturulmasının tamamlandığını gösterir.

Model oluşturulurken kesintiye uğradığında kesintiye uğrayan turda "generation_complete" mesajı gönderilmez. "interrupted > turn_complete" mesajı gönderilir.

Model gerçek zamanlı oynatmayı varsaydığında, generation_complete ile turn_complete arasında, modelin oynatmanın bitmesini beklemesinden kaynaklanan bir gecikme olur.
turnComplete

bool

Yalnızca çıkış. Doğru ise modelin sırasını tamamladığını gösterir. Oluşturma işlemi yalnızca ek istemci mesajlarına yanıt olarak başlar.
interrupted

bool

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 mevcut oynatma sırasını durdurup boşaltmak için iyi bir sinyaldir.
groundingMetadata

GroundingMetadata

Yalnızca çıkış. Oluşturulan içerik için temel meta veriler.
outputTranscription

BidiGenerateContentTranscription

Yalnızca çıkış. Ses transkriptini çıkışa aktarın. Transkript, diğer sunucu mesajlarından bağımsız olarak gönderilir ve özellikle serverContent ile bu outputTranscription arasında garanti edilen bir sıralama yoktur.
modelTurn

Content

Yalnızca çıkış. Modelin, kullanıcıyla devam eden görüşmenin bir parçası olarak oluşturduğu içerik.

BidiGenerateContentServerMessage

BidiGenerateContent çağrısı için yanıt mesajı.

Alanlar
usageMetadata

UsageMetadata

Yalnızca çıkış. Yanıtlarla ilgili kullanım meta verileri.
Birlik alanı messageType. Mesajın türü. messageType yalnızca aşağıdakilerden biri olabilir:
setupComplete

BidiGenerateContentSetupComplete

Yalnızca çıkış. Kurulum tamamlandığında istemciden gelen bir BidiGenerateContentSetup mesajına yanıt olarak gönderilir.
serverContent

BidiGenerateContentServerContent

Yalnızca çıkış. İstemci mesajlarına yanıt olarak model tarafından oluşturulan içerik.
toolCall

BidiGenerateContentToolCall

Yalnızca çıkış. İstemciden functionCalls'yi yürütmesini ve eşleşen id ile yanıtları döndürmesini isteyin.
toolCallCancellation

BidiGenerateContentToolCallCancellation

Yalnızca çıkış. Belirtilen id'ların yer aldığı daha önce verilen bir ToolCallMessage'nin iptal edilmesi gerektiğini belirten müşteri bildirimi.
goAway

GoAway

Yalnızca çıkış. Sunucunun yakında bağlantısını keseceğini belirten bir bildirim.
sessionResumptionUpdate

SessionResumptionUpdate

Yalnızca çıkış. Oturum devam ettirme durumunun güncellenmesi.

BidiGenerateContentSetup

İlk (ve yalnızca ilk) BidiGenerateContentClientMessage'te gönderilecek mesaj. Akış RPC'si süresince geçerli olacak yapılandırmayı içerir.

Müşteriler ek mesaj göndermeden önce bir BidiGenerateContentSetupComplete mesajı beklemelidir.

Alanlar
model

string

Zorunlu. Modelin kaynak adı. Bu, modelin kullanacağı bir kimlik görevi görür.

Biçim: models/{model}
generationConfig

GenerationConfig

İsteğe bağlı. Oluşturma yapılandırması.

Aşağıdaki alanlar desteklenmez:

  • responseLogprobs
  • responseMimeType
  • logprobs
  • responseSchema
  • stopSequence
  • routingConfig
  • audioTimestamp
systemInstruction

Content

İsteğe bağlı. Kullanıcı, model için sistem talimatları sağladı.

Not: Bölümlerde yalnızca metin kullanılmalıdır ve her bölümdeki içerik ayrı bir paragrafta yer alır.
tools[]

Tool

İsteğe bağlı. Modelin sonraki yanıtı oluşturmak için kullanabileceği Tools öğelerinin listesi.

Tool, sistemin modelin bilgisi ve kapsamı dışında bir işlem veya işlem grubu gerçekleştirmek için harici sistemlerle etkileşime geçmesini sağlayan bir kod parçasıdır.
realtimeInputConfig

RealtimeInputConfig

İsteğe bağlı. Gerçek zamanlı girişin işlenmesini yapılandırır.
sessionResumption

SessionResumptionConfig

İsteğe bağlı. Oturum devam ettirme mekanizmasını yapılandırır.

Bu parametre dahil edilirse sunucu SessionResumptionUpdate ileti gönderir.
contextWindowCompression

ContextWindowCompressionConfig

İsteğe bağlı. Bağlam penceresi sıkıştırma mekanizmasını yapılandırır.

Bu parametre dahil edilirse sunucu, yapılandırılmış uzunluğu aştığında bağlamın boyutunu otomatik olarak azaltır.
outputAudioTranscription

AudioTranscriptionConfig

İsteğe bağlı. Ayarlanırsa modelin ses çıkışının transkriptini etkinleştirir. Transkript, yapılandırılmışsa çıkış sesi için belirtilen dil koduyla uyumlu olur.

BidiGenerateContentSetupComplete

Bu türde alan yoktur.

İstemciden gelen bir BidiGenerateContentSetup mesajına yanıt olarak gönderilir.

BidiGenerateContentToolCall

İstemciden functionCalls'yi yürütmesini ve eşleşen id ile yanıtları döndürmesini isteyin.

Alanlar
functionCalls[]

FunctionCall

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[]

string

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
functionResponses[]

FunctionResponse

İsteğe bağlı. İşlev çağrılarına verilen yanıt.

BidiGenerateContentTranscription

Ses transkripti (giriş veya çıkış).

Alanlar
text

string

Transkript metni.

ContextWindowCompressionConfig

Bağlam penceresi sıkıştırmasını etkinleştirir. Bu, modelin bağlam penceresini belirli bir uzunluktan aşmayacak şekilde yönetme mekanizmasıdır.

Alanlar
Birlik alanı compressionMechanism. Kullanılan bağlam penceresi sıkıştırma mekanizması. compressionMechanism yalnızca aşağıdakilerden biri olabilir:
slidingWindow

SlidingWindow

Kaydırmalı pencere mekanizması.
triggerTokens

int64

Bir bağlam penceresi sıkıştırmasını tetiklemek için gereken jeton sayısı (bir tur çalıştırmadan önce).

Daha kısa bağlam aralıkları daha hızlı model yanıtlarına neden olabileceğinden bu, kaliteyi gecikmeye karşı dengelemek için kullanılabilir. Ancak sıkıştırma işlemleri geçici bir gecikmeye neden olacağından sık sık tetiklenmemelidir.

Ayarlanmamışsa varsayılan olarak modelin bağlam aralığı sınırının% 80'i kullanılır. Bu durumda, sonraki kullanıcı isteği/model yanıtı için% 20'lik bir pay kalır.

EndSensitivity

Konuşmanın sonunun nasıl algılandığını belirler.

Sıralamalar
END_SENSITIVITY_UNSPECIFIED Varsayılan değer END_SENSITIVITY_HIGH'tır.
END_SENSITIVITY_HIGH Otomatik algılama, konuşmayı daha sık sonlandırır.
END_SENSITIVITY_LOW Otomatik algılama, konuşmayı daha az keser.

GoAway

Sunucunun yakında bağlantısını keseceğini belirten bir bildirim.

Alanlar
timeLeft

Duration

Bağlantının ABORTED olarak sonlandırılmasına kalan süre.

Bu süre hiçbir zaman modele özgü minimum süreden az olmaz. Bu süre, modelin ücret sınırlarıyla birlikte belirtilir.

RealtimeInputConfig

BidiGenerateContent'te gerçek zamanlı giriş davranışını yapılandırır.

Alanlar
automaticActivityDetection

AutomaticActivityDetection

İsteğe bağlı. Ayarlanmamışsa otomatik etkinlik algılama varsayılan olarak etkindir. Otomatik ses algılama devre dışıysa istemcinin etkinlik sinyalleri göndermesi gerekir.
activityHandling

ActivityHandling

İsteğe bağlı. Etkinliğin ne gibi bir etkisi olduğunu tanımlar.
turnCoverage

TurnCoverage

İsteğe bağlı. Kullanıcının sırasına hangi girişin dahil edileceğini tanımlar.

SessionResumptionConfig

Oturum devam ettirme yapılandırması.

Bu mesaj, oturum yapılandırmasına BidiGenerateContentSetup.sessionResumption olarak dahil edilir. Yapılandırılmışsa sunucu SessionResumptionUpdate ileti gönderir.

Alanlar
handle

string

Önceki bir oturumun herkese açık kullanıcı adı. Aksi takdirde yeni bir oturum oluşturulur.

Oturum sapları, önceki bağlantılardaki SessionResumptionUpdate.token değerlerinden gelir.

SessionResumptionUpdate

Oturum devam ettirme durumunun güncellenmesi.

Yalnızca BidiGenerateContentSetup.sessionResumption ayarlandıysa gönderilir.

Alanlar
newHandle

string

Devam ettirilebilecek bir durumu temsil eden yeni herkese açık kullanıcı adı. resumable=false ise boştur.
resumable

bool

Geçerli oturum bu noktada devam ettirilebiliyorsa doğru değerini döndürür.

Oturumun bazı noktalarında devam ettirme işlemi yapılamaz. Örneğin, model işlev çağrıları yürüttüğünde veya oluştururken. Oturum bu durumdayken devam ettirildiğinde (önceki oturum jetonu kullanılarak) bazı veriler kaybolur. Bu durumlarda newHandle boş olur ve resumable yanlış olur.

SlidingWindow

SlidingWindow yöntemi, bağlam penceresinin başındaki içeriği atarak çalışır. Sonuç olarak elde edilen bağlam, her zaman bir USER rolü dönüşümünün başında başlar. Sistem talimatları ve BidiGenerateContentSetup.prefixTurns her zaman sonucun başında yer alır.

Alanlar
targetTokens

int64

Saklanacak hedef jeton sayısı. Varsayılan değer trigger_tokens/2'dir.

Bağlam penceresinin bazı bölümlerinin atılması geçici bir gecikmeye neden olur. Bu nedenle, sık sık sıkıştırma işlemi yapılmasını önlemek için bu değer kalibre edilmelidir.

StartSensitivity

Konuşmanın başlangıcının nasıl algılandığını belirler.

Sıralamalar
START_SENSITIVITY_UNSPECIFIED Varsayılan değer START_SENSITIVITY_HIGH'tır.
START_SENSITIVITY_HIGH Otomatik algılama, konuşmanın başlangıcını daha sık algılar.
START_SENSITIVITY_LOW Otomatik algılama, konuşmanın başlangıcını daha seyrek algılar.

TurnCoverage

Kullanıcının sırasına hangi girişin dahil edileceğiyle ilgili seçenekler.

Sıralamalar
TURN_COVERAGE_UNSPECIFIED Belirtilmemişse varsayılan davranış TURN_INCLUDES_ONLY_ACTIVITY olur.
TURN_INCLUDES_ONLY_ACTIVITY Kullanıcının sırası, yalnızca son sıradan sonraki etkinliği içerir.Etkin olmayan süreler (ör. ses akışındaki sessizlik) hariç tutulur. Bu varsayılan davranıştır.
TURN_INCLUDES_ALL_INPUT Kullanıcının sırası, son sıradan bu yana gerçekleşen tüm gerçek zamanlı girişleri (ör. ses akışındaki sessizlik) içerir.

UsageMetadata

Yanıtlarla ilgili kullanım meta verileri.

Alanlar
promptTokenCount

int32

Yalnızca çıkış. İstemdeki jeton sayısı. cachedContent ayarlandığında, bu değer yine toplam etkili istem boyutudur. Yani önbelleğe alınmış içerikteki jeton sayısını içerir.
cachedContentTokenCount

int32

İstemdeki önbelleğe alınmış kısımdaki (önbelleğe alınmış içerik) jeton sayısı
responseTokenCount

int32

Yalnızca çıkış. Oluşturulan tüm yanıt adaylarındaki toplam jeton sayısı.
toolUsePromptTokenCount

int32

Yalnızca çıkış. Araç kullanımı istemlerinde bulunan jetonların sayısı.
thoughtsTokenCount

int32

Yalnızca çıkış. Düşünme modelleri için düşünce jetonlarının sayısı.
totalTokenCount

int32

Yalnızca çıkış. Oluşturma isteği için toplam jeton sayısı (istem + yanıt adayları).
promptTokensDetails[]

ModalityTokenCount

Yalnızca çıkış. İstek girişinde işlenen modalitelerin listesi.
cacheTokensDetails[]

ModalityTokenCount

Yalnızca çıkış. İstek girişindeki önbelleğe alınmış içeriğin modalitelerinin listesi.
responseTokensDetails[]

ModalityTokenCount

Yalnızca çıkış. Yanıtta döndürülen modalitelerin listesi.
toolUsePromptTokensDetails[]

ModalityTokenCount

Yalnızca çıkış. Araç kullanımı istek girişleri için işlenen modalitelerin listesi.

Yaygın türler hakkında daha fazla bilgi

Sık kullanılan API kaynak türleri Blob, Content, FunctionCall, FunctionResponse, GenerationConfig, GroundingMetadata, ModalityTokenCount ve Tool hakkında daha fazla bilgi edinmek için İçerik oluşturma başlıklı makaleyi inceleyin.