Gemini API: Python ile işlev çağrısı

ai.google.dev'de görüntüleyin Google Colab'de çalıştır Kaynağı GitHub'da görüntüleyin

Gemini modellerine işlevlerin açıklamalarını sağlayabilirsiniz. Model, bir işlev çağırmanızı ve modelin sorgunuzu işlemesine yardımcı olmak için sonucu geri göndermenizi isteyebilir.

Kurulum

Python SDK'yı yükleme

Gemini API için Python SDK, google-generativeai paketinde yer alır. Pip kullanarak bağımlılığı yükleyin:

pip install -U -q google-generativeai

Paketleri içe aktar

Gerekli paketleri içe aktarın.

import pathlib
import textwrap
import time

import google.generativeai as genai


from IPython import display
from IPython.display import Markdown

def to_markdown(text):
  text = text.replace('•', '  *')
  return Markdown(textwrap.indent(text, '> ', predicate=lambda _: True))

API anahtarınızı oluşturma

Gemini API'yi kullanabilmek için önce bir API anahtarı edinmeniz gerekir. Anahtarınız yoksa Google AI Studio'da tek tıklamayla oluşturun.

API anahtarı alma

Colab'de, anahtarı sol paneldeki "🔑" simgesinin altında gizli anahtar yöneticisine ekleyin. API_KEY adını verin.

API anahtarınızı aldıktan sonra SDK'ya iletin. Bunu iki şekilde yapabilirsiniz:

  • Anahtarı, GOOGLE_API_KEY ortam değişkenine yerleştirin (SDK otomatik olarak oradan alır).
  • Anahtarı genai.configure(api_key=...) adlı cihaza verin
try:
    # Used to securely store your API key
    from google.colab import userdata

    # Or use `os.getenv('API_KEY')` to fetch an environment variable.
    GOOGLE_API_KEY=userdata.get('GOOGLE_API_KEY')
except ImportError:
    import os
    GOOGLE_API_KEY = os.environ['GOOGLE_API_KEY']

genai.configure(api_key=GOOGLE_API_KEY)

İşlevlerle İlgili Temel Bilgiler

genai.GenerativeModel oluştururken tools bağımsız değişkenine işlev listesi aktarabilirsiniz.

def multiply(a:float, b:float):
    """returns a * b."""
    return a*b

model = genai.GenerativeModel(model_name='gemini-1.0-pro',
                              tools=[multiply])

model

genai.GenerativeModel(
    model_name='models/gemini-1.0-pro',
    generation_config={},
    safety_settings={},
    tools=<google.generativeai.types.content_types.FunctionLibrary object at 0x10e73fe90>,
)

İşlev çağrısını kullanmak için önerilen yol sohbet arayüzü üzerinden yapılır. Bunun başlıca nedeni, FunctionCalls ürününün, sohbetin çok dönüşlü yapısına mükemmel uyum sağlamasıdır.

chat = model.start_chat(enable_automatic_function_calling=True)

Otomatik işlev çağrısı etkin durumdayken chat.send_message, model tarafından isterse işlevinizi otomatik olarak çağırır.

Görünüşe göre, doğru yanıtı içeren bir metin yanıtı döndürülmüştür:

response = chat.send_message('I have 57 cats, each owns 44 mittens, how many mittens is that in total?')
response.text

'The total number of mittens is 2508.'

57*44

2508

ChatSession.history sayfasına bakarsanız etkinliklerin sırasını görebilirsiniz:

  1. Soruyu gönderdiniz.
  2. Model bir glm.FunctionCall ile yanıt verdi.
  3. genai.ChatSession, işlevi yerel olarak yürüttü ve modeli geri bir glm.FunctionResponse gönderdi.
  4. Model, yanıtında işlev çıkışını kullandı.
for content in chat.history:
    part = content.parts[0]
    print(content.role, "->", type(part).to_dict(part))
    print('-'*80)

user -> {'text': 'I have 57 cats, each owns 44 mittens, how many mittens is that in total?'}
--------------------------------------------------------------------------------
model -> {'function_call': {'name': 'multiply', 'args': {'a': 57.0, 'b': 44.0} } }
--------------------------------------------------------------------------------
user -> {'function_response': {'name': 'multiply', 'response': {'result': 2508.0} } }
--------------------------------------------------------------------------------
model -> {'text': 'The total number of mittens is 2508.'}
--------------------------------------------------------------------------------

Genel olarak durum diyagramı şöyledir:

Model her zaman metin veya bir FunctionCall ile yanıt verebilir. Model bir FunctionCall gönderirse kullanıcı bir FunctionResponse ile yanıt vermelidir

Model, metin yanıtı döndürmeden önce birden çok işlev çağrısıyla yanıt verebilir ve işlev çağrıları, metin yanıtından önce gelir.

Bu işlemlerin tümü otomatik olarak gerçekleştiriliyor olsa da daha fazla denetime ihtiyacınız varsa şunları yapabilirsiniz:

  • Varsayılan enable_automatic_function_calling=False ayarını değiştirmeyin ve glm.FunctionCall yanıtlarını kendiniz işleyin.
  • Alternatif olarak, sohbet geçmişini yönetmeniz gereken GenerativeModel.generate_content hizmetini de kullanabilirsiniz.

[İsteğe bağlı] Düşük düzey erişim

Şemanın python işlevlerinden otomatik olarak ayıklanması her durumda çalışmaz. Örneğin: İç içe yerleştirilmiş bir sözlük nesnesinin alanlarını açıkladığınız durumları işlemez, ancak API bunu destekler. API aşağıdaki türlerin herhangi birini tanımlayabilir:

AllowedType = (int | float | bool | str | list['AllowedType'] | dict[str, AllowedType]

google.ai.generativelanguage istemci kitaplığı, alt düzey türlere erişim sunarak size tam denetim sağlar.

import google.ai.generativelanguage as glm

İlk olarak modelin _tools özelliğine göz atarak modele aktardığınız işlevleri nasıl tanımladığını görebilirsiniz:

def multiply(a:float, b:float):
    """returns a * b."""
    return a*b

model = genai.GenerativeModel(model_name='gemini-1.0-pro',
                             tools=[multiply])

model._tools.to_proto()

[function_declarations {
   name: "multiply"
   description: "returns a * b."
   parameters {
     type_: OBJECT
     properties {
       key: "b"
       value {
         type_: NUMBER
       }
     }
     properties {
       key: "a"
       value {
         type_: NUMBER
       }
     }
     required: "a"
     required: "b"
   }
 }]

Bu, API'ye gönderilecek glm.Tool nesnelerin listesini döndürür. Basılı biçim tanıdık değilse, bunun nedeni bunların Google protobuf sınıfları olmasıdır. Her glm.Tool (bu örnekte 1) bir işlevi ve bağımsız değişkenlerini açıklayan bir glm.FunctionDeclarations listesi içerir.

Burada, glm sınıfları kullanılarak yazılmış aynı çarpma işlevine ilişkin bir bildirim bulunmaktadır.

Bu sınıfların yalnızca API'nın işlevini açıkladığını, API'nin bir uygulamasını içermediğini unutmayın. Bu nedenle otomatik işlev çağrısında bu işlev işe yaramaz ancak işlevlerin her zaman uygulanması gerekmez.

calculator = glm.Tool(
    function_declarations=[
      glm.FunctionDeclaration(
        name='multiply',
        description="Returns the product of two numbers.",
        parameters=glm.Schema(
            type=glm.Type.OBJECT,
            properties={
                'a':glm.Schema(type=glm.Type.NUMBER),
                'b':glm.Schema(type=glm.Type.NUMBER)
            },
            required=['a','b']
        )
      )
    ])

Aynı şekilde, bunu JSON uyumlu bir nesne olarak tanımlayabilirsiniz:

calculator = {'function_declarations': [
      {'name': 'multiply',
       'description': 'Returns the product of two numbers.',
       'parameters': {'type_': 'OBJECT',
       'properties': {
         'a': {'type_': 'NUMBER'},
         'b': {'type_': 'NUMBER'} },
       'required': ['a', 'b']} }]}

glm.Tool(calculator)

function_declarations {
  name: "multiply"
  description: "Returns the product of two numbers."
  parameters {
    type_: OBJECT
    properties {
      key: "b"
      value {
        type_: NUMBER
      }
    }
    properties {
      key: "a"
      value {
        type_: NUMBER
      }
    }
    required: "a"
    required: "b"
  }
}

Her iki durumda da bir glm.Tool temsilini veya araç listesini iletirsiniz 

model = genai.GenerativeModel('gemini-pro', tools=calculator)
chat = model.start_chat()

response = chat.send_message(
    f"What's 234551 X 325552 ?",
)

Model, hesap makinesinin multiply işlevini çağıran bir glm.FunctionCall döndürmesinden önce olduğu gibi: 

response.candidates

[index: 0
content {
  parts {
    function_call {
      name: "multiply"
      args {
        fields {
          key: "b"
          value {
            number_value: 325552
          }
        }
        fields {
          key: "a"
          value {
            number_value: 234551
          }
        }
      }
    }
  }
  role: "model"
}
finish_reason: STOP
]

İşlevi kendiniz yürütün:

fc = response.candidates[0].content.parts[0].function_call
assert fc.name == 'multiply'

result = fc.args['a'] * fc.args['b']
result

76358547152.0

Görüşmeye devam etmek için sonucu modele gönderin:

response = chat.send_message(
    glm.Content(
    parts=[glm.Part(
        function_response = glm.FunctionResponse(
          name='multiply',
          response={'result': result}))]))

Özet

SDK'da temel işlev çağrısı desteklenir. Sohbet modunun kullanımı, karşılıklı iletişimin doğal yapısı nedeniyle daha kolay olduğunu unutmayın. İşlevleri çağırmaktan ve modelin metin yanıtı üretebilmesi için sonuçları modele geri göndermekten siz sorumlusunuz.