Wywoływanie funkcji za pomocą interfejsu Gemini API

Wywoływanie funkcji umożliwia łączenie modeli z zewnętrznymi narzędziami i interfejsami API. Zamiast generowania odpowiedzi tekstowych model rozumie, kiedy wywołać konkretne funkcje, i przekazuje niezbędne parametry do wykonania działań w świecie rzeczywistym. Dzięki temu model może pełnić rolę łącznika między językiem naturalnym a działaniami i danymi w świecie rzeczywistym. Wywoływanie funkcji ma 3 główne zastosowania:

• Rozszerzanie wiedzy: dostęp do informacji z zewnętrznych źródeł, takich jak bazy danych, interfejsy API i bazy wiedzy.
• Rozszerzanie możliwości: korzystanie z narzędzi zewnętrznych do wykonywania obliczeń i rozszerzania ograniczeń modelu, np. korzystania z kalkulatora lub tworzenia wykresów.
• Wykonywanie działań: interakcja z systemami zewnętrznymi za pomocą interfejsów API, np. planowanie spotkań, tworzenie faktur, wysyłanie e-maili czy sterowanie urządzeniami inteligentnego domu.

Pobierz informacje o pogodzie Zaplanuj spotkanie Utwórz wykres

Jak działa wywoływanie funkcji

Wywoływanie funkcji wymaga uporządkowanej interakcji między aplikacją, modelem i funkcjami zewnętrznymi. Oto zestawienie tego procesu:

1. Zdefiniuj deklarację funkcji: zdefiniuj deklarację funkcji w kodzie aplikacji. Deklaracje funkcji opisują nazwę funkcji, parametry i jej przeznaczenie w modelu.
2. Wywołaj LLM z deklaracjami funkcji: wyślij do modelu prompt użytkownika wraz z deklaracjami funkcji. Analizuje ono żądanie i określa, czy wywołanie funkcji będzie przydatne. Jeśli tak, zwraca on w odpowiedzi ustrukturyzowany obiekt JSON.
3. Wykonywanie kodu funkcji (Twoja odpowiedzialność): model niesam nie wykonuje funkcji. Twoja aplikacja musi przetworzyć odpowiedź i sprawdzić, czy zawiera ona wywołanie funkcji.
   • Tak: wyodrębnij nazwę i argumenty funkcji oraz wykonaj odpowiednią funkcję w aplikacji.
   • Nie: model podał bezpośrednią odpowiedź tekstową na prompt (ten przepływ jest mniej podkreślony w tym przykładzie, ale jest możliwym wynikiem).
4. Tworzenie przyjaznych dla użytkownika odpowiedzi: jeśli funkcja została wykonana, przechwyć jej wynik i prześlij go z powrotem do modelu w kolejnych turach rozmowy. Na podstawie wyniku wygeneruje ostateczną, przyjazną dla użytkownika odpowiedź, która zawiera informacje z wywołania funkcji.

Ten proces może być powtarzany przez wiele tur, co umożliwia tworzenie złożonych interakcji i przepływów pracy. Model obsługuje też wywoływanie wielu funkcji w jednym kroku (równoległe wywoływanie funkcji) i w kolejności (kompozycyjne wywoływanie funkcji).

Krok 1. Zdefiniuj deklarację funkcji

Zdefiniuj funkcję i jej deklarację w kodzie aplikacji, która umożliwia użytkownikom ustawianie wartości światła i wysyłanie żądań do interfejsu API. Ta funkcja może wywoływać usługi zewnętrzne lub interfejsy API.

from google.genai import types

# Define a function that the model can call to control smart lights
set_light_values_declaration = {
    "name": "set_light_values",
    "description": "Sets the brightness and color temperature of a light.",
    "parameters": {
        "type": "object",
        "properties": {
            "brightness": {
                "type": "integer",
                "description": "Light level from 0 to 100. Zero is off and 100 is full brightness",
            },
            "color_temp": {
                "type": "string",
                "enum": ["daylight", "cool", "warm"],
                "description": "Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.",
            },
        },
        "required": ["brightness", "color_temp"],
    },
}

# This is the actual function that would be called based on the model's suggestion
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}

import { Type } from '@google/genai';

// Define a function that the model can call to control smart lights
const setLightValuesFunctionDeclaration = {
  name: 'set_light_values',
  description: 'Sets the brightness and color temperature of a light.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      brightness: {
        type: Type.NUMBER,
        description: 'Light level from 0 to 100. Zero is off and 100 is full brightness',
      },
      color_temp: {
        type: Type.STRING,
        enum: ['daylight', 'cool', 'warm'],
        description: 'Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.',
      },
    },
    required: ['brightness', 'color_temp'],
  },
};

/**
* Set the brightness and color temperature of a room light. (mock API)
* @param {number} brightness - Light level from 0 to 100. Zero is off and 100 is full brightness
* @param {string} color_temp - Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.
* @return {Object} A dictionary containing the set brightness and color temperature.
*/
function setLightValues(brightness, color_temp) {
  return {
    brightness: brightness,
    colorTemperature: color_temp
  };
}

Krok 2. Wywołuj model za pomocą deklaracji funkcji

Po zdefiniowaniu deklaracji funkcji możesz poprosić model o jej użycie. Analizuje prompt i deklaracje funkcji, a następnie odpowiada bezpośrednio lub wywołuje funkcję. Jeśli funkcja zostanie wywołana, obiekt odpowiedzi będzie zawierać sugestię wywołania funkcji.

from google import genai

# Generation Config with Function Declaration
tools = types.Tool(function_declarations=[set_light_values_declaration])
config = types.GenerateContentConfig(tools=[tools])

# Configure the client
client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))

# Define user prompt
contents = [
    types.Content(
        role="user", parts=[types.Part(text="Turn the lights down to a romantic level")]
    )
]

# Send request with function declarations
response = client.models.generate_content(
    model="gemini-2.0-flash", config=config, contents=contents
)

print(response.candidates[0].content.parts[0].function_call)

import { GoogleGenAI } from '@google/genai';

// Generation Config with Function Declaration
const config = {
  tools: [{
    functionDeclarations: [setLightValuesFunctionDeclaration]
  }]
};

// Configure the client
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

// Define user prompt
const contents = [
  {
    role: 'user',
    parts: [{ text: 'Turn the lights down to a romantic level' }]
  }
];

// Send request with function declarations
const response = await ai.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: contents,
  config: config
});

console.log(response.functionCalls[0]); 

Następnie model zwraca obiekt functionCall w schemacie zgodnym z OpenAPI, który określa sposób wywołania co najmniej jednej z deklarowanych funkcji, aby odpowiedzieć na pytanie użytkownika.

id=None args={'color_temp': 'warm', 'brightness': 25} name='set_light_values'

{
  name: 'set_light_values',
  args: { brightness: 25, color_temp: 'warm' }
}

Krok 3. Wykonaj kod funkcji set_light_values

Wyodrębnij szczegóły wywołania funkcji z odpowiedzi modelu, przeanalizuj argumenty i wykonaj funkcję set_light_values w naszym kodzie.

# Extract tool call details
tool_call = response.candidates[0].content.parts[0].function_call

if tool_call.name == "set_light_values":
    result = set_light_values(**tool_call.args)
    print(f"Function execution result: {result}")

// Extract tool call details
const tool_call = response.functionCalls[0]

let result;
if (tool_call.name === 'set_light_values') {
  result = setLightValues(tool_call.args.brightness, tool_call.args.color_temp);
  console.log(`Function execution result: ${JSON.stringify(result)}`);
}

Krok 4. Utwórz przyjazną dla użytkownika odpowiedź z wynikiem funkcji i ponownie wywołaj model

Na koniec należy przesłać wynik wykonania funkcji z powrotem do modelu, aby mógł on uwzględnić te informacje w ostatecznej odpowiedzi dla użytkownika.

# Create a function response part
function_response_part = types.Part.from_function_response(
    name=tool_call.name,
    response={"result": result},
)

# Append function call and result of the function execution to contents
contents.append(types.Content(role="model", parts=[types.Part(function_call=tool_call)])) # Append the model's function call message
contents.append(types.Content(role="user", parts=[function_response_part])) # Append the function response

final_response = client.models.generate_content(
    model="gemini-2.0-flash",
    config=config,
    contents=contents,
)

print(final_response.text)

// Create a function response part
const function_response_part = {
  name: tool_call.name,
  response: { result }
}

// Append function call and result of the function execution to contents
contents.push({ role: 'model', parts: [{ functionCall: tool_call }] });
contents.push({ role: 'user', parts: [{ functionResponse: function_response_part }] });

// Get the final response from the model
const final_response = await ai.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: contents,
  config: config
});

console.log(final_response.text);

To kończy proces wywoływania funkcji. Model użył funkcji set_light_values do wykonania działania związanego z żądaniem użytkownika.

Deklaracje funkcji

Gdy w promptach implementujesz wywoływanie funkcji, tworzysz obiekt tools, który zawiera co najmniej 1 element function declarations. Funkcje definiujesz za pomocą kodu JSON, a dokładnie wybranego podzbioru formatu schematu OpenAPI. Jedna deklaracja funkcji może zawierać te parametry:

• name (ciąg znaków): unikalna nazwa funkcji (get_weather_forecast, send_email). Używaj opisowych nazw bez spacji ani znaków specjalnych (używaj znaków podkreślenia lub wielkich liter).
• description (string): przejrzyste i szczegółowe wyjaśnienie celu i możliwości funkcji. Jest to kluczowe, aby model wiedział, kiedy użyć funkcji. Bądź konkretny i w razie potrzeby podaj przykłady („znajduje kina na podstawie lokalizacji i opcjonalnie tytułu filmu, który jest obecnie wyświetlany w kinach”).
• parameters (obiekt): definiuje parametry wejściowe, których oczekuje funkcja.
  • type (ciąg znaków): określa ogólny typ danych, np. object.
  • properties (obiekt): zawiera listę poszczególnych parametrów z poszczególnymi:
    • type (ciąg znaków): typ danych parametru, np. string, integer, boolean, array.
    • description (ciąg znaków): opis przeznaczenia i formatu parametru. Podaj przykłady i ograniczenia („Miasto i stan, np. „San Francisco, CA” lub kod pocztowy, np. 95616).
    • enum (tabelka, opcjonalnie): jeśli wartości parametrów pochodzą z niezmiennego zbioru, użyj typu „enum”, aby podać dozwolone wartości zamiast opisywać je w opisie. Pomaga to zwiększyć dokładność („enum”: [„daylight”, „cool”, „warm”]).
  • required (tablica): tablica ciągów znaków zawierająca nazwy parametrów, które są wymagane do działania funkcji.

równoległe wywoływanie funkcji;

Oprócz wywołania funkcji w jednym obrocie możesz też wywołać wiele funkcji naraz. Wywoływanie funkcji równoległe umożliwia wykonywanie wielu funkcji jednocześnie i jest używane, gdy funkcje nie są od siebie zależne. Jest to przydatne w takich sytuacjach jak zbieranie danych z wielu niezależnych źródeł, np. pobieranie danych o klientach z różnych baz danych lub sprawdzanie poziomów zapasów w różnych magazynach czy wykonywanie wielu działań, np. przekształcanie mieszkania w dyskotekę.

power_disco_ball = {
    "name": "power_disco_ball",
    "description": "Powers the spinning disco ball.",
    "parameters": {
        "type": "object",
        "properties": {
            "power": {
                "type": "boolean",
                "description": "Whether to turn the disco ball on or off.",
            }
        },
        "required": ["power"],
    },
}

start_music = {
    "name": "start_music",
    "description": "Play some music matching the specified parameters.",
    "parameters": {
        "type": "object",
        "properties": {
            "energetic": {
                "type": "boolean",
                "description": "Whether the music is energetic or not.",
            },
            "loud": {
                "type": "boolean",
                "description": "Whether the music is loud or not.",
            },
        },
        "required": ["energetic", "loud"],
    },
}

dim_lights = {
    "name": "dim_lights",
    "description": "Dim the lights.",
    "parameters": {
        "type": "object",
        "properties": {
            "brightness": {
                "type": "number",
                "description": "The brightness of the lights, 0.0 is off, 1.0 is full.",
            }
        },
        "required": ["brightness"],
    },
}

import { Type } from '@google/genai';

const powerDiscoBall = {
  name: 'power_disco_ball',
  description: 'Powers the spinning disco ball.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      power: {
        type: Type.BOOLEAN,
        description: 'Whether to turn the disco ball on or off.'
      }
    },
    required: ['power']
  }
};

const startMusic = {
  name: 'start_music',
  description: 'Play some music matching the specified parameters.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      energetic: {
        type: Type.BOOLEAN,
        description: 'Whether the music is energetic or not.'
      },
      loud: {
        type: Type.BOOLEAN,
        description: 'Whether the music is loud or not.'
      }
    },
    required: ['energetic', 'loud']
  }
};

const dimLights = {
  name: 'dim_lights',
  description: 'Dim the lights.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      brightness: {
        type: Type.NUMBER,
        description: 'The brightness of the lights, 0.0 is off, 1.0 is full.'
      }
    },
    required: ['brightness']
  }
};

Wywołaj model za pomocą instrukcji, która może korzystać ze wszystkich określonych narzędzi. W tym przykładzie użyto elementu tool_config. Więcej informacji znajdziesz w artykule o konfigurowaniu wywoływania funkcji.

from google import genai
from google.genai import types

# Set up function declarations
house_tools = [
    types.Tool(function_declarations=[power_disco_ball, start_music, dim_lights])
]

config = {
    "tools": house_tools,
    "automatic_function_calling": {"disable": True},
    # Force the model to call 'any' function, instead of chatting.
    "tool_config": {"function_calling_config": {"mode": "any"}},
}

# Configure the client
client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))

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
print("Example 1: Forced function calling")
for fn in response.function_calls:
    args = ", ".join(f"{key}={val}" for key, val in fn.args.items())
    print(f"{fn.name}({args})")

import { GoogleGenAI } from '@google/genai';

// Set up function declarations
const houseFns = [powerDiscoBall, startMusic, dimLights];

const config = {
    tools: [{
        functionDeclarations: houseFns
    }],
    // Force the model to call 'any' function, instead of chatting.
    toolConfig: {
        functionCallingConfig: {
        mode: 'any'
        }
    }
};

// Configure the client
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

// Create a chat session
const chat = ai.chats.create({
    model: 'gemini-2.0-flash',
    config: config
});
const response = await chat.sendMessage({message: 'Turn this place into a party!'});

// Print out each of the function calls requested from this single call
console.log("Example 1: Forced function calling");
for (const fn of response.functionCalls) {
    const args = Object.entries(fn.args)
        .map(([key, val]) => `${key}=${val}`)
        .join(', ');
    console.log(`${fn.name}(${args})`);
}

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.

Pakiet Python SDK obsługuje funkcję automatycznego wywoływania funkcji, która konwertuje funkcję Pythona na deklaracje i za Ciebie obsługuje cykl wykonywania i odpowiedzi funkcji. Poniżej przedstawiamy przykład zastosowania Disco.

from google import genai
from google.genai import types

# Actual implementation functions
def power_disco_ball_impl(power: bool) -> dict:
    """Powers the spinning disco ball.

    Args:
        power: Whether to turn the disco ball on or off.

    Returns:
        A status dictionary indicating the current state.
    """
    return {"status": f"Disco ball powered {'on' if power else 'off'}"}

def start_music_impl(energetic: bool, loud: bool) -> dict:
    """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:
        A dictionary containing the music settings.
    """
    music_type = "energetic" if energetic else "chill"
    volume = "loud" if loud else "quiet"
    return {"music_type": music_type, "volume": volume}

def dim_lights_impl(brightness: float) -> dict:
    """Dim the lights.

    Args:
        brightness: The brightness of the lights, 0.0 is off, 1.0 is full.

    Returns:
        A dictionary containing the new brightness setting.
    """
    return {"brightness": brightness}

config = {
    "tools": [power_disco_ball_impl, start_music_impl, dim_lights_impl],
}

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("\nExample 2: Automatic function calling")
print(response.text)
# I've turned on the disco ball, started playing loud and energetic music, and dimmed the lights to 50% brightness. Let's get this party started!

Wywoływanie funkcji kompozytowej

Gemini 2.0 obsługuje kompozycyjne wywoływanie funkcji, co oznacza, że model może łączyć ze sobą wiele wywołań funkcji. Na przykład, aby odpowiedzieć na pytanie „Podaj temperaturę w mojej bieżącej lokalizacji”, interfejs Gemini API może wywołać funkcję get_current_location() i funkcję get_weather(), która przyjmuje lokalizację jako parametr.

# Light control schemas
turn_on_the_lights_schema = {'name': 'turn_on_the_lights'}
turn_off_the_lights_schema = {'name': 'turn_off_the_lights'}

prompt = """
  Hey, can you write run some python code to turn on the lights, wait 10s and then turn off the lights?
  """

tools = [
    {'code_execution': {}},
    {'function_declarations': [turn_on_the_lights_schema, turn_off_the_lights_schema]}
]

await run(prompt, tools=tools, modality="AUDIO")

// Light control schemas
const turnOnTheLightsSchema = { name: 'turn_on_the_lights' };
const turnOffTheLightsSchema = { name: 'turn_off_the_lights' };

const prompt = `
  Hey, can you write run some python code to turn on the lights, wait 10s and then turn off the lights?
`;

const tools = [
  { codeExecution: {} },
  { functionDeclarations: [turnOnTheLightsSchema, turnOffTheLightsSchema] }
];

await run(prompt, tools=tools, modality="AUDIO")

Tryby wywoływania funkcji

Interfejs Gemini API umożliwia kontrolowanie sposobu, w jaki model korzysta z dostępnych narzędzi (deklaracji funkcji). W szczególności możesz ustawić tryb w sekcji function_calling_config.

• AUTO (Default): model decyduje, czy wygenerować odpowiedź w języku naturalnym, czy zasugerować wywołanie funkcji na podstawie promptu i kontekstu. Jest to najbardziej elastyczny tryb i zalecany w większości scenariuszy.
• ANY: model jest ograniczony do przewidywania wywołania funkcji i gwarantuje przestrzeganie schematu funkcji. Jeśli nie podasz wartości allowed_function_names, model może wybrać dowolną z podanych deklaracji funkcji. Jeśli allowed_function_names jest podane jako lista, model może wybierać tylko funkcje z tej listy. Użyj tego trybu, jeśli chcesz, aby funkcja była wywoływana w odpowiedzi na każdy prompt (jeśli dotyczy).

• NONE: model nie może wywoływać funkcji. Jest to równoznaczne z wysłaniem żądania bez deklaracji funkcji. Możesz go użyć, aby tymczasowo wyłączyć wywoływanie funkcji bez usuwania definicji narzędzi.

from google.genai import types

# Configure function calling mode
tool_config = types.ToolConfig(
    function_calling_config=types.FunctionCallingConfig(
        mode="ANY", allowed_function_names=["get_current_temperature"]
    )
)

# Create the generation config
config = types.GenerateContentConfig(
    temperature=0,
    tools=[tools],  # not defined here.
    tool_config=tool_config,
)

import { FunctionCallingConfigMode } from '@google/genai';

// Configure function calling mode
const toolConfig = {
  functionCallingConfig: {
    mode: FunctionCallingConfigMode.ANY,
    allowedFunctionNames: ['get_current_temperature']
  }
};

// Create the generation config
const config = {
  temperature: 0,
  tools: tools, // not defined here.
  toolConfig: toolConfig,
};

Automatyczne wywoływanie funkcji (tylko Python)

Korzystając z pakietu Python SDK, możesz przekazywać funkcje Pythona bezpośrednio jako narzędzia. Pakiet SDK automatycznie konwertuje funkcję Pythona na deklaracje i zajmuje się wykonywaniem wywołania funkcji oraz cyklem odpowiedzi. Pakiet Python SDK automatycznie:

1. Wykrywa odpowiedzi na wywołania funkcji z modelu.
2. Wywołaj odpowiednią funkcję Pythona w kodze.
3. Wysyła odpowiedź funkcji z powrotem do modelu.
4. Zwraca ostateczną tekstową odpowiedź modelu.

Aby z niej skorzystać, zdefiniuj funkcję z podpowiedziami typu i opisem funkcji, a potem prześlij samą funkcję (a nie deklarację JSON) jako narzędzie:

from google import genai
from google.genai import types

# Define the function with type hints and docstring
def get_current_temperature(location: str) -> dict:
    """Gets the current temperature for a given location.

    Args:
        location: The city and state, e.g. San Francisco, CA

    Returns:
        A dictionary containing the temperature and unit.
    """
    # ... (implementation) ...
    return {"temperature": 25, "unit": "Celsius"}

# Configure the client and model
client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))  # Replace with your actual API key setup
config = types.GenerateContentConfig(
    tools=[get_current_temperature]
)  # Pass the function itself

# Make the request
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="What's the temperature in London?",
    config=config,
)

print(response.text)  # The SDK handles the function call and returns the final text

Funkcję automatycznego wywoływania możesz wyłączyć:

# To disable automatic function calling:
config = types.GenerateContentConfig(
    tools=[get_current_temperature],
    automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True)
)

Deklaracja schematu automatycznej funkcji

Automatyczne wyodrębnianie schematu z funkcji Pythona nie działa we wszystkich przypadkach. Na przykład nie obsługuje przypadków, w których opisujesz pola zagnieżdżonego obiektu słownika. 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:

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.
print(fn_decl.to_json_dict())

Korzystanie z wielu narzędzi: łączenie narzędzi natywnych z wywoływaniem funkcji

Dzięki Gemini 2.0 możesz jednocześnie włączyć wiele narzędzi, łącząc narzędzia natywne z funkcjami wywołania. Oto przykład, w którym żądanie korzystające z interfejsu Live API aktywuje 2 narzędzia: Grounding with Google Search i wykonanie kodu.

# Multiple tasks example - combining lights, code execution, and search
prompt = """
  Hey, I need you to do three things for me.

    1.  Turn on the lights.
    2.  Then compute the largest prime palindrome under 100000.
    3.  Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024.

  Thanks!
  """

tools = [
    {'google_search': {}},
    {'code_execution': {}},
    {'function_declarations': [turn_on_the_lights_schema, turn_off_the_lights_schema]} # not defined here.
]

# Execute the prompt with specified tools in audio modality
await run(prompt, tools=tools, modality="AUDIO")

// Multiple tasks example - combining lights, code execution, and search
const prompt = `
  Hey, I need you to do three things for me.

    1.  Turn on the lights.
    2.  Then compute the largest prime palindrome under 100000.
    3.  Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024.

  Thanks!
`;

const tools = [
  { googleSearch: {} },
  { codeExecution: {} },
  { functionDeclarations: [turnOnTheLightsSchema, turnOffTheLightsSchema] } // not defined here.
];

// Execute the prompt with specified tools in audio modality
await run(prompt, {tools: tools, modality: "AUDIO"});

Deweloperzy Pythona mogą wypróbować to w notatniku Live API Tool Use.

Obsługiwane modele

Modele eksperymentalne nie są uwzględniane. Ich możliwości znajdziesz na stronie Przegląd modelu.

Sprawdzone metody

• Opis funkcji i parametrów: opisy powinny być bardzo jasne i precyzyjne. Model korzysta z nich, aby wybrać odpowiednią funkcję i podać odpowiednie argumenty.
• Nazewnictwo: używaj opisowych nazw funkcji (bez spacji, kropek ani łączników).
• Zalecane wpisywanie: aby ograniczyć liczbę błędów, używaj w przypadku parametrów konkretnych typów (liczb całkowitych, ciągów znaków i enumeracji). Jeśli parametr ma ograniczony zbiór prawidłowych wartości, użyj typu wyliczonego.
• Projektowanie promptu:
  • Podawanie kontekstu: określ rolę modelu (np. „Jesteś pomocnym asystentem pogody”).
  • Podawaj instrukcje: określ, jak i kiedy używać funkcji (np. „Nie zgaduj dat; zawsze używaj przyszłej daty do prognoz”.
  • Zachęć do wyjaśnienia: w razie potrzeby poproś model o zadanie pytań uściślających.
• Temperatura: używaj niskiej temperatury (np. 0) w celu uzyskania bardziej deterministycznych i niezawodnych wywołań funkcji.
• Weryfikacja: jeśli wywołanie funkcji ma istotne konsekwencje (np. złożenie zamówienia), przed jego wykonaniem sprawdź, czy użytkownik wyraził na nie zgodę.
• Obsługa błędów: w funkcjach zastosuj niezawodną obsługę błędów, aby sprawnie obsługiwać nieoczekiwane dane wejściowe lub błędy interfejsu API. zwracać przydatne komunikaty o błędach, których model może używać do generowania przydatnych odpowiedzi dla użytkownika;
• Bezpieczeństwo: podczas wywoływania zewnętrznych interfejsów API należy pamiętać o zabezpieczeniach. Używaj odpowiednich mechanizmów uwierzytelniania i autoryzacji. Unikaj ujawniania danych poufnych w wywołaniach funkcji.
• Limity tokenów: opisy funkcji i parametry są wliczane do limitu tokenów wejściowych. Jeśli osiągasz limity tokenów, rozważ ograniczenie liczby funkcji lub długości opisów oraz podziel skomplikowane zadania na mniejsze, bardziej skoncentrowane zestawy funkcji.

Uwagi i ograniczenia

• Obsługiwany jest tylko podzbiór schematu OpenAPI.
• Obsługiwane typy parametrów w Pythonie są ograniczone.
• Automatyczne wywoływanie funkcji jest funkcją tylko w pakiecie Python SDK.