Samouczek wywoływania funkcji

Python Node.js Go Dart (Flutter) Android Swift Web REST

Funkcja wywoływania ułatwia uzyskiwanie uporządkowanych danych wyjściowych z modeli generatywnych. Następnie możesz używać tych danych do wywoływania innych interfejsów API i zwracania odpowiednich danych odpowiedzi do modelu. Innymi słowy, wywoływanie funkcji pomaga Ci łączyć modele generatywne z systemami zewnętrznymi, aby generowane treści zawierały jak najbardziej aktualne i dokładne informacje.

Możesz przekazywać modelom Gemini opisy funkcji. Są to funkcje napisane w języku aplikacji (czyli nie są to funkcje Google Cloud Functions). Model może poprosić o wywołanie funkcji i odesłanie wyniku, aby pomóc w obróbce zapytania.

Jeśli jeszcze tego nie zrobiłeś, zapoznaj się z artykułem Wprowadzenie do wywoływania funkcji, aby dowiedzieć się więcej. Możesz też wypróbować tę funkcję w Google Colab lub wyświetlić przykładowy kod w repozytorium Książka kucharska interfejsu Gemini API.

Przykład interfejsu API do sterowania oświetleniem

Wyobraź sobie, że masz podstawowy system sterowania oświetleniem z interfejsem programowania aplikacji (API) i chcesz umożliwić użytkownikom sterowanie światłami za pomocą prostych żądań tekstowych. Za pomocą funkcji wywoływania funkcji możesz interpretować żądania zmiany oświetlenia od użytkowników i przekształcać je w wywołania interfejsu API, aby ustawiać wartości oświetlenia. Ten hipotetyczny system sterowania oświetleniem umożliwia kontrolowanie jasności światła i jego temperatury barwowej, zdefiniowanych jako 2 osobne parametry:

W ramach uproszczenia tego wyimaginowanego systemu oświetlenia ma on tylko jedną lampę, więc użytkownik nie musi określać pokoju ani lokalizacji. Oto przykład żądania JSON, które możesz wysłać do interfejsu Lighting Control API, aby zmienić poziom światła na 50% przy użyciu temperatury barwowej światła dziennego:

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

W tym samouczku pokazujemy, jak skonfigurować wywołanie funkcji dla interfejsu Gemini API, aby interpretować żądania dotyczące oświetlenia użytkowników i mapować je na ustawienia interfejsu API w celu sterowania wartościami jasności i temperatury barwowej światła.

Zanim zaczniesz: skonfiguruj projekt i klucz interfejsu API

Zanim wywołasz interfejs Gemini API, musisz skonfigurować projekt i klucz interfejsu API.

Definiowanie funkcji interfejsu API

Utwórz funkcję, która wysyła żądanie do interfejsu API. Funkcję tę należy zdefiniować w kodzie aplikacji, ale może ona wywoływać usługi lub interfejsy API spoza aplikacji. Interfejs Gemini API nie wywołuje tej funkcji bezpośrednio, więc możesz kontrolować, jak i kiedy jest ona wykonywana za pomocą kodu aplikacji. Na potrzeby tego samouczka zdefiniowaliśmy w nim fikcyjną funkcję interfejsu API, która zwraca tylko żądane wartości oświetlenia:

def set_light_values(brightness: int, color_temp: str) -> dict[str, int | str]:
    """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
    }

Podczas tworzenia funkcji, która ma być używana w wywołaniu funkcji przez model, należy podać w opisie funkcji i parametrów jak najwięcej szczegółów. Model generatywny używa tych informacji do określenia, którą funkcję wybrać i jak podać wartości parametrów w wywołaniu funkcji.

Deklarowanie funkcji podczas inicjowania modelu

Jeśli chcesz używać wywoływania funkcji, definiujesz funkcje jako narzędzia w GenerateContentConfig wraz z innymi ustawieniami dotyczącymi generowania (np. temperatura lub tokeny zatrzymania).

from google.genai import types

config = types.GenerateContentConfig(tools=[set_light_values])

Można go też zdefiniować jako słownik Pythona.

config = {
    'tools': [set_light_values],
}

Generowanie wywołania funkcji

Po zdefiniowaniu deklaracji funkcji możesz poprosić model o jej użycie. Treści możesz generować bezpośrednio lub za pomocą interfejsu czatu.

from google import genai

client = genai.Client()

# Generate directly with generate_content.
response = client.models.generate_content(
    model='gemini-2.0-flash',
    config=config,
    contents='Turn the lights down to a romantic level'
)
print(response.text)

# Use the chat interface.
chat = client.chats.create(model='gemini-2.0-flash', config=config)
response = chat.send_message('Turn the lights down to a romantic level')
print(response.text)

W pakiecie Python SDK funkcje są wywoływane automatycznie. Jeśli chcesz obsługiwać każde wywołanie funkcji lub wykonywać inną logikę między wywołaniami, możesz wyłączyć tę opcję za pomocą flagi w konfiguracji generowania.

from google.genai import types

# Use strong types.
config = types.GenerateContentConfig(
    tools=[set_light_values],
    automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True)
)

# Use a dictionary.
config = {
    'tools': [set_light_values],
    'automatic_function_calling': {'disable': True},
}

Wywoływanie funkcji równolegle

Oprócz podstawowego wywoływania funkcji opisanego powyżej możesz też wywołać wiele funkcji w jednym ruchu. W tej sekcji znajdziesz przykład użycia wywołania funkcji równoległej.

Zdefiniuj narzędzia.

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

    Returns: The name of the song being played.
    """
    print(f"Starting music! {energetic=} {loud=}")
    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

Teraz wywołaj model z instrukcją, która może używać wszystkich określonych narzędzi. W tym przykładzie użyto funkcji tool_config. Aby dowiedzieć się więcej, przeczytaj artykuł o konfigurowaniu wywoływania funkcji.

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

config = {
    # Set the available functions.
    'tools': house_fns,
    # Disable AFC so you can inspect the results first.
    'automatic_function_calling': {'disable': True},
    # Force the model to act (call 'any' function), instead of chatting.
    'tool_config': {
        'function_calling_config': {
            'mode': 'any'
        }
    }
}

# Call the API.
chat = client.chats.create(model='gemini-2.0-flash', config=config)
response = chat.send_message('Turn this place into a party!')

# Print out each of the function calls requested from this single call.
for fn in response.function_calls:
  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)
dim_lights(brightness=0.3)

Każdy z wydrukowanych wyników odpowiada jednemu wywołaniu funkcji, o które poprosił model. Aby wysłać wyniki, dołącz odpowiedzi w tej samej kolejności, w jakiej zostały żądane.

Najprostszym sposobem jest pozostawienie włączonej opcji automatic_function_calling, aby pakiet SDK automatycznie obsługiwał wywołania funkcji i przekazywanie odpowiedzi.

config = {
    'tools': house_fns,
}

# Call the API.
chat = client.chats.create(model='gemini-2.0-flash', config=config)
response = chat.send_message('Do everything you need to this place into party!')

print(response.text)

Disco ball is spinning!
Starting music! energetic=True loud=True
Lights are now set to 50%
Alright, I've turned on the disco ball, started playing "Never gonna give you up.", and dimmed the lights. Let's get this party started!

Mapowanie typu danych wywołania funkcji

Automatyczne wyodrębnianie schematu z funkcji Pythona nie działa we wszystkich przypadkach. Na przykład nie obsługuje ona sytuacji, w której opisujesz pola zagnieżdżonego obiektu słownika, ale interfejs API obsługuje to. Interfejs API może opisywać te typy:

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

Aby zobaczyć, jak wygląda wywnioskowany schemat, możesz go przekonwertować za pomocą from_callable:

from pprint import pprint

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

fn_decl = types.FunctionDeclaration.from_callable(callable=multiply, client=client)

# to_json_dict() provides a clean JSON representation.
pprint(fn_decl.to_json_dict())

{'description': 'Returns a * b.',
 'name': 'multiply',
 'parameters': {'properties': {'a': {'type': 'NUMBER'},
                               'b': {'type': 'NUMBER'}},
                'type': 'OBJECT'}}

Te pola JSON są mapowane na odpowiadające im pola w schemacie Pydantic i można je opakować jako Tool.

config = types.GenerateContentConfig(
    tools=[types.Tool(function_declarations=[fn_decl])]
)

Oto deklaracja tej samej funkcji multiply napisanej przy użyciu klas genai.types. Pamiętaj, że te klasy tylko opisują funkcję interfejsu API, ale nie zawierają jej implementacji, więc to podejście nie działa w przypadku automatycznego wywoływania funkcji. Pozwala on jednak definiować funkcje, które nie są konkretnymi funkcjami Pythona (np. do zawijania zdalnego wywołania HTTP), i daje większą kontrolę nad wywołaniami funkcji (np. do zmiany function_calling_config, aby podążać za grafem stanu).

tool = types.Tool(function_declarations=[
    types.FunctionDeclaration(
        name="multiply",
        description="Returns a * b.",
        parameters=types.Schema(
            properties={
                'a': types.Schema(type='NUMBER'),
                'b': types.Schema(type='NUMBER'),
            },
            type='OBJECT',
        ),
    )
])
assert tool.function_declarations[0] == fn_decl