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 bir sonraki ana 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ı ayarlamayla ilgili adımlar aşağıda verilmiştir:

  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 beyanı oluşturun.

  3. Modelin gerekirse işlevi nasıl kullanabileceğini bilmesi için model başlatılırken işlev beyanını 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 uygulama bölümüne atla

İş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 görüşme 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 bilgileri sağlayabilecek harici bir hava durumu hizmeti API'si olduğunu 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 bu varsayımsal harici API ile etkileşime geçen ve aşağıdaki giriş ve çıkışa sahip 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 Cloud koşulları (clear, partlyCloudy, mostlyCloudy, cloudy arasından 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ğırmıyor. 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 büyük olasılıkla 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 son 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, modelin uygulamanızdaki bir işlevle etkileşimde bulunmasını nasıl içerdiğini gösteren diyagram 

İşlev çağrısını 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ı kaydettirme ve Firebase yapılandırmanızı uygulamanıza ekleme dahil olmak üzere uygulamanızı Firebase'e bağlayın.

  3. SDK'yı ekleyin ve uygulamanızda Vertex AI hizmetini ve üretken modeli 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 ç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ıyı 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şlevin gerçek çağrısı için parametre değerlerinin nasıl sağlanacağını belirlemek amacıyla işlev beyanında bulunan 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 tanımlarını, 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 dizisinde 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 belgelerindeki 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.

Kullanım alanınıza ve uygulamanıza uygun bir Gemini modelini ve isteğe bağlı olarak bir konum seçmeyi öğ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şlevi gerçekten çağırması gerekir.

Bilgilerin model ile uygulama arasında gidip gelmesi gerektiğinden, işlev çağırmanın önerilen yolu çok turlu sohbet arayüzüdür.

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 temelindeki harici API) için gerekli giriş parametresi değerlerini sağladığını gösterir.

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 beyanı listenizde 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 nedenle model, nihai yanıtını oluşturmasına yardımcı olması için birden fazla işleve ihtiyaç duyduğuna karar verebilir. Ayrıca bu işlevlerden bazılarını aynı anda çağırmaya karar verebilir. Buna paralel işlev çağırma 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ğırma modunu ayarlama denir. 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'tür.

Mod Açıklama
AUTO Varsayılan model davranışı. Model, işlev çağrısı mı yoksa doğal dil yanıtı mı kullanılacağı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ğırma modu, Gemini 1.5 Pro ve Gemini 1.5 Flash tarafından desteklenir.

Başka neler 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ılabilen modeller ve bunların kotaları ile fiyatlandırması hakkında bilgi edinin.


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