Gemini API'yi kullanarak işlev çağırma


Üretken modeller, birçok türde sorunu çözmede güçlüdür. Ancak aşağıdaki gibi sınırlamalarla karşılaşırlar:

  • Bu modeller eğitimden sonra dondurulur ve eski bilgilere yol açar.
  • Harici verileri sorgulayamaz veya değiştiremezler.

İşlev çağırma, bu sınırlamaların bazılarını aşmanıza yardımcı olabilir. İşlev çağrısı, bir modelin nihai yanıtını oluşturmak için API'ler ve işlevler gibi harici araçları kullanmasına olanak tanıdığı için bazen araç kullanımı olarak adlandırılır.

Google Cloud dokümanlarında işlev çağırma için kullanım alanları ile ilgili faydalı bir liste de dahil olmak üzere işlev çağırma hakkında daha fazla bilgi edinebilirsiniz.

İşlev çağrısı, Gemini 1.0 Pro, Gemini 1.5 Pro ve Gemini 1.5 Flash tarafından desteklenir.

Bu kılavuzda, bu sayfanın sonraki önemli bölümünde açıklanan örneğe benzer bir işlev çağrısı kurulumunu nasıl uygulayabileceğiniz gösterilmektedir. Uygulamanızda işlev çağrısını ayarlamak için genel olarak uygulamanız gereken adımlar şunlardır:

  1. Modele nihai yanıtını oluşturmak için ihtiyaç duyduğu bilgileri sağlayabilecek bir işlev yazın (örneğin, işlev harici bir API'yi çağırabilir).

  2. İşlevi ve parametrelerini açıklayan bir işlev bildirimi oluşturun.

  3. Modelin gerektiğinde işlevi nasıl kullanabileceğini bilmesi için model başlatma sırasında işlev bildirimini sağlayın.

  4. Uygulamanızı, modelin uygulamanızın işlevi çağırması için gerekli bilgileri gönderebileceği şekilde ayarlayın.

  5. Modelin nihai yanıtını oluşturabilmesi için işlevin yanıtını modele geri gönderin.

Kod uygulamaya geç

İşlev çağrısı örneğine genel bakış

Modele istek gönderirken modele nihai yanıtını oluşturmak için kullanabileceği bir dizi "araç" (ör. işlevler) de sağlayabilirsiniz. Bu işlevleri kullanmak ve çağırmak ("işlev çağırma") için modelin ve uygulamanızın birbirlerine bilgi aktarması gerekir. Bu nedenle, işlev çağırmanın önerilen yolu çoklu turlu sohbet arayüzüdür.

Kullanıcıların şu gibi bir istem girebileceği bir uygulamanız olduğunu varsayalım: What was the weather in Boston on October 17, 2024?.

Gemini modelleri bu hava durumu bilgilerini bilmiyor olabilir ancak bu bilgiyi sağlayabilecek harici bir hava durumu hizmeti API'si bildiğinizi varsayalım. Gemini modeline bu API'ye ve hava durumu bilgilerine giden bir yol vermek için işlev çağırma özelliğini kullanabilirsiniz.

Öncelikle, uygulamanızda şu giriş ve çıkışa sahip bu varsayımsal harici API ile etkileşime giren bir fetchWeather işlevi yazarsınız:

Parametre Tür Zorunlu Açıklama
Giriş
location Nesne Evet Hava durumunun alınacağı şehrin adı ve eyaleti.
Yalnızca ABD'deki şehirler desteklenir. Her zaman city ve state'den oluşan iç içe yerleştirilmiş bir nesne olmalıdır.
date Dize Evet Hava durumunun alınacağı tarih (her zaman YYYY-MM-DD biçiminde olmalıdır).
Çıkış
temperature Tamsayı Evet Sıcaklık (Fahrenhayt cinsinden)
chancePrecipitation Dize Evet Yağış ihtimali (yüzde olarak ifade edilir)
cloudConditions Dize Evet Bulut koşulları (clear, partlyCloudy, mostlyCloudy, cloudy değerlerinden biri)

Modeli başlatırken modele bu fetchWeather işlevinin var olduğunu ve gerekirse gelen istekleri işlemek için nasıl kullanılabileceğini bildirirsiniz. Buna "işlev beyanı" denir. Model, işlevi doğrudan çağırmaz. Bunun yerine, model gelen isteği işlerken fetchWeather işlevinin isteğe yanıt vermesine yardımcı olup olamayacağına karar verir. Model, işlevin gerçekten yararlı olabileceğine karar verirse uygulamanızın işlevi çağırmasına yardımcı olacak yapılandırılmış veriler oluşturur.

Gelen isteğe tekrar bakın: What was the weather in Boston on October 17, 2024?. Model, muhtemelen fetchWeather işlevinin yanıt oluşturmasına yardımcı olabileceğine karar verir. Model, fetchWeather için hangi giriş parametrelerinin gerekli olduğunu inceler ve ardından işlev için kabaca aşağıdaki gibi görünen yapılandırılmış giriş verileri oluşturur:

{
  functionName: fetchWeather,
  location: {
    city: Boston,
    state: Massachusetts  // the model can infer the state from the prompt
  },
  date: 2024-10-17
}

Model, bu yapılandırılmış giriş verilerini uygulamanıza iletir. Böylece uygulamanız fetchWeather işlevini çağırabilir. Uygulamanız, API'den hava koşullarını aldığında bilgileri modele iletir. Bu hava durumu bilgileri, modelin son işlemesini tamamlamasına ve What was the weather in Boston on October 17, 2024?

Model, aşağıdaki gibi doğal dildeki nihai bir yanıt verebilir: On October 17, 2024, in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

İşlev çağrısının uygulamanızdaki bir işlevle etkileşimde bulunan modele nasıl dahil olduğunu gösteren şema 

İşlev çağrısı uygulama

Başlamadan önce

Henüz yapmadıysanız Vertex AI in Firebase SDK'ları için başlangıç kılavuzunu tamamlayın. Aşağıdakilerin tümünü yaptığınızdan emin olun:

  1. Blaze fiyatlandırma planını kullanma ve gerekli API'leri etkinleştirme dahil olmak üzere yeni veya mevcut bir Firebase projesi oluşturun.

  2. Uygulamanızı Firebase'e bağlayın. Buna, uygulamanızı kaydetme ve Firebase yapılandırmanızı ekleme.

  3. SDK'yı ekleyip Vertex AI hizmetini ve üretken modeli uygulamanızda başlatın.

Uygulamanızı Firebase'e bağladıktan, SDK'yı ekledikten ve Vertex AI hizmetini ile üretken modeli başlattıktan sonra Gemini API işlevini çağırmaya hazırsınız.

Bu kılavuzun geri kalan adımlarında, İşlev çağrısı örneğine genel bakış bölümünde açıklanan iş akışına benzer bir işlev çağrısı kurulumunun nasıl uygulanacağı gösterilmektedir (bu sayfanın üst bölümüne bakın).

Bu işlev çağrısı örneğinin tam kod örneğini bu sayfanın ilerleyen kısmında görüntüleyebilirsiniz.

1. adım: İşlevi yazın

Kullanıcıların şu gibi bir istem girebileceği bir uygulamanız olduğunu varsayalım: What was the weather in Boston on October 17, 2024?. Gemini modelleri bu hava durumu bilgilerini bilmiyor olabilir. Ancak bu bilgileri sağlayabilecek harici bir hava durumu hizmeti API'si olduğunu varsayalım. Bu kılavuzdaki örnekte bu varsayımsal harici API kullanılmaktadır.

Uygulamanızda, varsayımsal harici API ile etkileşime geçecek ve modele nihai isteğini oluşturmak için ihtiyaç duyduğu bilgileri sağlayacak işlevi yazın. Bu hava durumu örneğinde, bu varsayımsal harici API'ye çağrı yapan bir fetchWeather işlevi olacaktır.

2. adım: İşlev beyanı oluşturun

Daha sonra modele sağlayacağınız işlev tanımını oluşturun (bu kılavuzun sonraki adımı).

Beyanınızda, işlev ve parametrelerinin açıklamalarına mümkün olduğunca fazla ayrıntı ekleyin.

Model, hangi işlevin seçileceğini ve işleve yapılan gerçek çağrı için parametre değerlerinin nasıl sağlanacağını belirlemek için işlev bildirimindeki bilgileri kullanır. Modelin işlevler arasında nasıl seçim yapabileceği ve bu seçimi nasıl kontrol edebileceğiniz hakkında bilgi edinmek için bu sayfanın sonraki kısmındaki Ek davranışlar ve seçenekler bölümüne bakın.

Sağladığınız şemayla ilgili aşağıdakileri unutmayın:

  • İşlev bildirimlerini OpenAPI şemasıyla uyumlu bir şema biçiminde sağlamanız gerekir. Vertex AI, OpenAPI şeması için sınırlı destek sunar.

    • Şu özellikler desteklenir: type, nullable, required, format, description, properties, items, enum.

    • Şu özellikler desteklenmez: default, optional, maximum, oneOf.

  • Vertex AI in Firebase SDK'larında, varsayılan olarak tüm alanlar optionalProperties dizisi içinde isteğe bağlı olarak belirtmediğiniz sürece zorunlu olarak kabul edilir. Bu isteğe bağlı alanlar için model, alanları doldurabilir veya atlayabilir. Bunun, Vertex AI Gemini API için varsayılan davranışın tam tersi olduğunu unutmayın.

Adlar ve açıklamalarla ilgili ipuçları da dahil olmak üzere işlev bildirimleriyle ilgili en iyi uygulamalar için Google Cloud dokümanlarında En iyi uygulamalar bölümüne bakın.

İşlev bildirimini şu şekilde yazabilirsiniz:

3. Adım: Modeli başlatırken işlev beyanını sağlayın

İstekte sağlayabileceğiniz maksimum işlev beyanı sayısı 128'dir. Modelin işlevler arasında nasıl seçim yapabileceği ve bu seçimi nasıl kontrol edebileceğiniz (işlev çağırma modunu ayarlamak için toolConfig kullanarak) hakkında bilgi edinmek için bu sayfanın sonraki kısmındaki Ek davranışlar ve seçenekler bölümüne bakın.

Gemini modelini ve isteğe bağlı olarak kullanım alanınıza ve uygulamanıza uygun konumu nasıl seçeceğinizi öğrenin.

4. adım: Harici API'yi çağırmak için işlevi çağırın

Model, fetchWeather işlevinin nihai bir yanıt oluşturmasına gerçekten yardımcı olabileceğine karar verirse uygulamanızın, model tarafından sağlanan yapılandırılmış giriş verilerini kullanarak bu işleve gerçek çağrıyı yapması gerekir.

Bilgilerin model ile uygulama arasında karşılıklı olarak aktarılması gerektiğinden, işlev çağrısının çok dönüşlü sohbet arayüzünü kullanmanız önerilir.

Aşağıdaki kod snippet'inde, modelin fetchWeather işlevini kullanmak istediği uygulamanıza nasıl bildirildiği gösterilmektedir. Ayrıca modelin, işlev çağrısı (ve temel harici API) için gerekli giriş parametresi değerlerini sağladığı gösterilir.

Bu örnekte, gelen istek What was the weather in Boston on October 17, 2024? istemini içeriyordu. Model bu istemden fetchWeather işlevi için gerekli olan giriş parametrelerini (yani city, state ve date) çıkardı.

5. Adım: Nihai yanıtı oluşturmak için işlevin çıktısını modele sağlayın

fetchWeather işlevi hava durumu bilgilerini döndürdükten sonra uygulamanızın bu bilgileri modele geri iletmesi gerekir.

Ardından model son işleme işlemini gerçekleştirir ve aşağıdaki gibi doğal dildeki nihai yanıtı oluşturur: On October 17, 2024 in Boston, it was 38 degrees Fahrenheit with partly cloudy skies.

Ek davranışlar ve seçenekler

Aşağıda, işlev çağırmayla ilgili kodunuza dahil etmeniz gereken bazı ek davranışlar ve kontrol edebileceğiniz seçenekler verilmiştir.

Model, bir işlevi tekrar veya başka bir işlevi çağırmayı isteyebilir.

Bir işlev çağrısından gelen yanıt, modelin nihai yanıtını oluşturması için yeterli değilse model ek bir işlev çağrısı isteyebilir veya tamamen farklı bir işlevin çağrılmasını isteyebilir. İkincisi yalnızca işlev bildirimi listenizdeki modele birden fazla işlev sağlarsanız gerçekleşebilir.

Uygulamanızın, modelin ek işlev çağrıları isteyebilir.

Model, aynı anda birden fazla işlevin çağrılmasını isteyebilir.

İşlev beyanı listenizde modele 128'e kadar işlev sağlayabilirsiniz. Bu doğrultuda model, nihai yanıtını oluşturmak için birden fazla işlevin gerekli olduğuna karar verebilir. Ayrıca bu işlevlerden bazılarını aynı anda çağırmaya karar verebilir. Buna paralel işlev çağrısı denir.

Uygulamanızın, modelin aynı anda birden fazla işlevin çalıştırılmasını isteyebileceğini hesaba katması ve işlevlerden gelen tüm yanıtları modele geri sağlaması gerekir.

Paralel işlev çağrısı, Gemini 1.5 Pro ve Gemini 1.5 Flash tarafından desteklenir.

Modelin işlevleri nasıl ve ne zaman çağırabileceğini kontrol edebilirsiniz.

Modelin sağlanan işlev tanımlarını nasıl ve kullanıp kullanmayacağı konusunda bazı kısıtlamalar koyabilirsiniz. Buna, işlev çağrı modunu ayarlama adı verilir. Aşağıda bazı örnekler verilmiştir:

  • Modelin anında doğal dil yanıtı ile işlev çağrısı arasında seçim yapmasına izin vermek yerine her zaman işlev çağrılarını kullanması için modele zorlayabilirsiniz. Buna zorunlu işlev çağırma denir.

  • Birden fazla işlev beyanı sağlarsanız modeli, yalnızca sağlanan işlevlerin bir alt kümesini kullanacak şekilde kısıtlayabilirsiniz.

Bu kısıtlamaları (veya modları), istem ve işlev beyanlarıyla birlikte bir araç yapılandırması (toolConfig) ekleyerek uygularsınız. Araç yapılandırmasında aşağıdaki modlardan birini belirtebilirsiniz. En kullanışlı mod ANY.

Mod Açıklama
AUTO Varsayılan model davranışı. Model, işlev çağrısı veya doğal dil yanıtı kullanılıp kullanılmayacağına karar verir.
ANY Modelde işlev çağrıları ("zorunlu işlev çağrısı") kullanılmalıdır. Modeli bir işlev alt kümesiyle sınırlamak için allowedFunctionNames içinde izin verilen işlev adlarını belirtin.
NONE Modelde işlev çağrıları kullanılmamalıdır. Bu davranış, ilişkili işlev beyanları olmayan bir model isteğine eşdeğerdir.

İşlev çağrısı modu, Gemini 1.5 Pro ve Gemini 1.5 Flash tarafından desteklenir.

Başka ne yapabilirsiniz?

Gemini API'ın diğer özelliklerini deneyin

İçerik oluşturmayı nasıl kontrol edeceğinizi öğrenin

Vertex AI Studio'i kullanarak istemler ve model yapılandırmalarıyla da denemeler yapabilirsiniz.

Gemini modelleri hakkında daha fazla bilgi

Çeşitli kullanım alanları için kullanılabilecek modeller ve bunların kotaları ve fiyatlandırması hakkında bilgi edinin.


Vertex AI in Firebase ile ilgili deneyiminiz hakkında geri bildirim verin