İşlev çağrısı eğiticisi

İşlev çağrısı, üretken modellerden yapılandırılmış veri çıkışları almanızı kolaylaştırır. Ardından bu çıkışları kullanarak diğer API'leri çağırabilir ve yanıt verilerini modele uygun hale getirmemize yardımcı olur. Başka bir deyişle, işlev çağrısı üretken modelleri harici sistemlere bağlarsınız. Böylece, en güncel ve doğru bilgileri içerir.

Gemini modellerine işlevlerin açıklamalarını sağlayabilirsiniz. Bunlar, uygulamanızın dilinde yazdığınız işlevlerdir (yani Google Cloud Functions değildir). Model, sizden bir işlevi çağırmanızı ve sonuç; modelin sorgunuzu ele almasına yardımcı olur.

Henüz yapmadıysanız Öğrenmek için işlev çağrısına giriş daha fazla bilgi verebilir. Dilerseniz bu özelliği şurada deneyin: Google Colab veya Gemini API Cookbook deposu.

Aydınlatma kontrolü için örnek API

Bir uygulama programlaması ile temel bir ışıklandırma kontrol sisteminiz olduğunu düşünün API'sını kullanıyor ve kullanıcıların ışıkları basit bir şekilde kontrol etmesine izin vermek metin istekleri. Işıklandırmayı yorumlamak için İşlev Çağrısı özelliğini kullanabilirsiniz ışıklandırmayı ayarlamak için kullanıcılardan gelen istekleri değiştirme ve bunları API çağrılarına dönüştürme değerler. Bu varsayımsal aydınlatma kontrol sistemi, ışığın parlaklığını ve renk sıcaklığını iki ayrı parametre olarak kontrol etmenize olanak tanır:

Parametre Tür Zorunlu Açıklama
brightness sayı evet 0 ile 100 arasında değişen ışık seviyesi. Sıfır kapalı, 100 tam parlaklık.
colorTemperature dize evet Aydınlatma armatürünün renk sıcaklığı (daylight, cool veya warm).

Basitlik sağlaması açısından, bu hayali aydınlatma sisteminde yalnızca tek bir ışığa sahiptir, böylece kullanıcı bir oda veya yer belirtmesi gerekmiyor. Aşağıda örnek bir JSON isteği verilmiştir ışık seviyesini %50 olarak değiştirmek için ışık kontrolü API'sine gönderebilirsin gün ışığı renk sıcaklığını kullanarak:

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

Bu eğiticide, Gemini API için İşlev Çağrısı'nın nasıl kontrol etmek için kullanıcıların ışıklandırma isteklerini yorumlamak ve API ayarlarıyla eşlemek ışığın parlaklık ve renk sıcaklığı değerlerini yansıtabilir.

Başlamadan önce: Projenizi ve API anahtarınızı oluşturun

Gemini API'yi çağırmadan önce projenizi ayarlamanız ve API anahtarınız.

API işlevi tanımlama

API isteğinde bulunan bir işlev oluşturun. Bu işlev, uygulamanızın kodunda tanımlanmalıdır ancak uygulamanızın dışındaki hizmetleri veya API'leri çağırabilir. Gemini API bu işlevi doğrudan çalmaz. Bu nedenle, uygulama kodunuz aracılığıyla bu işlevin nasıl ve ne zaman çalışacağını kontrol edebilirsiniz. Bu eğitimde, yalnızca istenen aydınlatma değerlerini döndüren bir örnek API işlevi tanımlanmıştır:

def set_light_values(brightness, color_temp):
    """Set the brightness and color temperature of a room light. (mock API).

    Args:
        brightness: Light level from 0 to 100. Zero is off and 100 is full brightness
        color_temp: Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.

    Returns:
        A dictionary containing the set brightness and color temperature.
    """
    return {
        "brightness": brightness,
        "colorTemperature": color_temp
    }

Model tarafından bir işlev çağrısında kullanılacak bir işlev oluşturduğunuzda işlev ve parametre açıklamalarına mümkün olduğunca fazla ayrıntı eklemeniz gerekir. Üretken model bu bilgileri kullanarak hangi fonksiyonunu seçin ve fonksiyondaki parametrelere değerler için çağrısına bir tıklama URL'si eklemeniz gerekir.

Model başlatma sırasında işlevleri bildirme

Bir modelde işlev çağrısını kullanmak istediğinizde model nesnesini başlatırken işlevlerinizi tanımlamanız gerekir. İşlevleri modelin tools parametresi:

model = genai.GenerativeModel(model_name='gemini-1.5-flash',
                              tools=[set_light_values])

İşlev çağrısı oluşturma

İşlev bildirimlerinizle modeli başlattıktan sonra, tanımlanan işleve sahip modeli kullanır. İşlev çağrısını sohbet istemi (sendMessage()), çünkü işlev çağrısı genellikle önceki istemlerin ve yanıtların bağlamına bakın.

chat = model.start_chat()
response = chat.send_message('Dim the lights so the room feels cozy and warm.')
response.text

Python SDK'sının ChatSession sınıfı, sohbet geçmişini sizin için yöneterek sohbet oturumlarını yönetmeyi kolaylaştırır. SDK'nın işlevi otomatik olarak çağırması için enable_automatic_function_calling değerini kullanabilirsiniz.

# Create a chat session that automatically makes suggested function calls
chat = model.start_chat(enable_automatic_function_calling=True)

Paralel işlev çağrısı

Yukarıda açıklanan temel işlev çağrısına ek olarak, tek bir dönüşte birden fazla işlevi de çağırabilirsiniz. Bu bölümde, paralel işlev çağrısını nasıl kullanabileceğinize ilişkin bir örnek gösterilmektedir.

Araçları tanımlayın.

def power_disco_ball(power: bool) -> bool:
    """Powers the spinning disco ball."""
    print(f"Disco ball is {'spinning!' if power else 'stopped.'}")
    return True


def start_music(energetic: bool, loud: bool, bpm: int) -> str:
    """Play some music matching the specified parameters.

    Args:
      energetic: Whether the music is energetic or not.
      loud: Whether the music is loud or not.
      bpm: The beats per minute of the music.

    Returns: The name of the song being played.
    """
    print(f"Starting music! {energetic=} {loud=}, {bpm=}")
    return "Never gonna give you up."


def dim_lights(brightness: float) -> bool:
    """Dim the lights.

    Args:
      brightness: The brightness of the lights, 0.0 is off, 1.0 is full.
    """
    print(f"Lights are now set to {brightness:.0%}")
    return True

Şimdi de modeli, belirtilen tüm araçları kullanabilecek bir talimatla çağırın.

# Set the model up with tools.
house_fns = [power_disco_ball, start_music, dim_lights]

model = genai.GenerativeModel(model_name="gemini-1.5-flash", tools=house_fns)

# Call the API.
chat = model.start_chat()
response = chat.send_message("Turn this place into a party!")

# Print out each of the function calls requested from this single call.
for part in response.parts:
    if fn := part.function_call:
        args = ", ".join(f"{key}={val}" for key, val in fn.args.items())
        print(f"{fn.name}({args})")

power_disco_ball(power=True)
start_music(energetic=True, loud=True, bpm=120.0)
dim_lights(brightness=0.3)

Basılan sonuçların her biri, modelin istediği tek bir işlev çağrısını yansıtır. Sonuçları geri göndermek için yanıtları istendiği sırada ekleyin.

# Simulate the responses from the specified tools.
responses = {
    "power_disco_ball": True,
    "start_music": "Never gonna give you up.",
    "dim_lights": True,
}

# Build the response parts.
response_parts = [
    genai.protos.Part(function_response=genai.protos.FunctionResponse(name=fn, response={"result": val}))
    for fn, val in responses.items()
]

response = chat.send_message(response_parts)
print(response.text)

Let's get this party started! I've turned on the disco ball, started playing some upbeat music, and dimmed the lights. 🎶✨  Get ready to dance! 🕺💃

İşlev çağrısı veri türü eşleme

Python işlevlerinden otomatik şema ayıklama işlemi her durumda çalışmaz. Örneğin: İç içe yerleştirilmiş bir sözlük nesnesinin alanlarını tanımladığınız durumları işlemez ancak API bunu destekler. API, aşağıdaki türlerin herhangi birini açıklayabilir:

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

google.ai.generativelanguage istemci kitaplığı, size tam kontrol sağlayan düşük düzey türlere erişim sağlar.

Öncelikle modelin _tools özelliğine göz atın. Bu özellik, modele ilettiğiniz 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.5-flash',
                             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,genai.protos.Tool API'ye gidin. Basılı biçim tanıdık gelmiyorsa bunun nedeni Google protobuf sınıfları olmasıdır. Her genai.protos.Tool (bu örnekte 1) şunları içeren bir liste içerir: genai.protos.FunctionDeclarations: Bir fonksiyon ile ilgili tanımı, bağımsız değişkenlerdir.

Burada, genai.protos sınıf. Bu sınıfların yalnızca değillerse API'nin uygulama görmezden gelinir. Bu nedenle, bu yöntem otomatik işlev çağırma ile çalışmaz ancak işlevlerin her zaman uygulanması gerekmez.

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

Diğer bir deyişle, 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']} }]}

genai.protos.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, genai.protos.Tool veya araç listesi temsilini

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

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

Tıpkı modelin, hesap makinesinin multiply işlevini çağıran bir genai.protos.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

Sohbete devam etmek için sonucu modele gönderin:

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