API de llamada de función

La llamada a función mejora la capacidad de los LLM para proporcionar respuestas relevantes y contextuales.

Puedes proporcionar funciones personalizadas a un modelo generativo de IA con la API de llamada a función. El modelo no invoca estas funciones directamente, sino que genera un resultado de datos estructurados que especifica el nombre de la función y los argumentos sugeridos. Este resultado permite llamar a API externas o sistemas de información como bases de datos, sistemas de administración de relaciones con clientes y repositorios de documentos. El LLM puede usar el resultado de la API para mejorar la calidad de la respuesta.

Modelos compatibles:

  • Gemini 1.0 Pro
    • gemini-1.0-pro
    • gemini-1.0-pro-001
    • gemini-1.0-pro-002
  • Gemini 1.5 Pro
    • gemini-1.5-pro-preview-0409

Limitaciones:

  • La cantidad máxima de funciones que se pueden proporcionar es 64.
  • FunctionCallingConfig está en vista previa y solo está disponible para "gemini-1.5-pro-preview-0409".

Sintaxis

  • PROJECT_ID = PROJECT_ID
  • REGION = REGION
  • MODEL_ID = MODEL_ID

curl

https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/publishers/google/models/${MODEL_ID}:generateContent \
  -d '{
    "contents": [{
      ...
    }],
    "tools": [{
      "function_declarations": [
        {
          ...
        }
      ]
    }]
  }'

Python

gemini_model = GenerativeModel(
    MODEL_ID,
    generation_config=generation_config,
    tools=[
        Tool(
            function_declarations=[
                FunctionDeclaration(
                    ...
                )
            ]
        )
    ],
)

Lista de parámetros

FunctionDeclaration

Una representación estructurada de una declaración de función según lo definido por la especificación de OpenAPI 3.0 que representa una función para la que el modelo puede generar entradas JSON.

Parámetros

name

string

El nombre de la función a la que se llamará.

description

Opcional: string

Descripción y propósito de la función

parameters

Opcional: Schema

Describe los parámetros para esta función en el formato de objeto de esquema JSON de OpenAPI: especificación de OpenAPI 3.0

response

Opcional: Schema

Describe el resultado de esta función en formato de esquema JSON.

FunctionCallingConfig [Vista previa]

Esta es una configuración adicional para usar la función de llamada a función que solo está disponible para “gemini-1.5-pro-preview-0409”.

Parámetros

mode

Opcional: enum/string[]

  • AUTO: Es el comportamiento predeterminado del modelo; el modelo decide predecir una llamada a una función o una respuesta de lenguaje natural.
  • NONE: El modelo no predecirá ninguna llamada a función. El comportamiento del modelo es el mismo que cuando no se pasa ninguna declaración de función.
  • ANY: El modelo está limitado a predecir siempre una sola llamada a función.

Cuando se configura allowed_function_names, la llamada a la función prevista se limita a cualquiera de los allowed_function_names. De forma predeterminada, la llamada a la función prevista será cualquiera de los function_declarations proporcionados.

allowed_function_names

Opcional: string[]

Nombres de las funciones a llamar. Solo se establece cuando mode es ANY. Los nombres de las funciones deben coincidir con [FunctionDeclaration.name]. Con el modo configurado como ANY, el modelo predecirá una llamada a función a partir del conjunto de nombres de función proporcionados.

Esquema

El esquema se usa para definir el formato de los datos de entrada y salida en una llamada a función. Una representación estructurada de una declaración de función según lo definido en la especificación del esquema de OpenAPI 3.0.

Parámetros
Tipo

string

Enum. El tipo de datos. Debe ser uno de los siguientes:

  • STRING
  • INTEGER
  • BOOLEAN
  • NUMBER
  • ARRAY
  • OBJECT
description

Opcional: string

Descripción de los datos.
enum

Opcional: string[]

Valores posibles del elemento de Type.STRING con formato de enumeración.
items

Opcional: Schema[]

Esquema de los elementos de Type.ARRAY
properties

Opcional: Schema

Esquema de las propiedades de Type.OBJECT
required

Opcional: string[]

Propiedades obligatorias de Type.OBJECT.
nullable

Opcional: bool

Indica si el valor puede ser null.

Ejemplos

  • PROJECT_ID = PROJECT_ID
  • REGION = REGION
  • MODEL_ID = MODEL_ID

Caso de uso básico

A continuación, se muestra un ejemplo de cómo puedes enviar una consulta y declaraciones de funciones al modelo.

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/publishers/google/models/${MODEL_ID}:generateContent \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "What is the weather in Boston?"
      }]
    }],
    "tools": [{
      "function_declarations": [
        {
          "name": "get_current_weather",
          "description": "Get the current weather in a given location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              }
            },
            "required": [
              "location"
            ]
          }
        }
      ]
    }]
  }'

Python

import vertexai
from vertexai.generative_models import (
    FunctionDeclaration,
    GenerativeModel,
    GenerationConfig,
    Part,
    Tool,
)

vertexai.init(project=PROJECT_ID, location=REGION)

# Specify a function declaration and parameters for an API request
get_current_weather_func = FunctionDeclaration(
    name="get_current_weather",
    description="Get the current weather in a given location",
    # Function parameters are specified in OpenAPI JSON schema format
    parameters={
        "type": "object",
        "properties": {"location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"}},
    },
)

# Define a tool that includes the above get_current_weather_func
weather_tool = Tool(
    function_declarations=[get_current_weather_func],
)

gemini_model = GenerativeModel(
    MODEL_ID, generation_config={"temperature": 0}, tools=[weather_tool]
)
model_response = gemini_model.generate_content("What is the weather in Boston?")

print(model_response)

Caso de uso avanzado

En el siguiente ejemplo, se muestra cómo pasar la configuración de generación y la configuración de la herramienta al modelo. La configuración de llamadas a función se puede usar para garantizar que el resultado del modelo sea siempre una llamada a función específica. Para lograrlo, configura el modo de llamada a función en ANY y especifica los nombres de funciones permitidas en el parámetro allowed_function_names. Cuando allowed_function_names está vacío, se puede mostrar cualquiera de las funciones proporcionadas.

  • MODEL_ID = gemini-1.5-pro-preview-0409

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${REGION}/publishers/google/models/${MODEL_ID}:generateContent \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Do you have the White Pixel 8 Pro 128GB in stock in the US?"
      }]
    }],
    "tools": [{
      "function_declarations": [
        {
          "name": "get_product_sku",
          "description": "Get the available inventory for a Google products, e.g: Pixel phones, Pixel Watches, Google Home etc",
          "parameters": {
            "type": "object",
            "properties": {
                "product_name": {"type": "string", "description": "Product name"}
            }
          }
        },
        {
          "name": "get_store_location",
          "description": "Get the location of the closest store",
          "parameters": {
            "type": "object",
            "properties": {"location": {"type": "string", "description": "Location"}},
          }
        }
      ]
    }],
    "tool_config": {
        "function_calling_config": {
            "mode":"ANY",
            "allowed_function_names": ["get_product_sku"]
       }
    },
    "generationConfig": {
      "temperature": 0.95,
      "topP": 1.0,
      "maxOutputTokens": 8192
    }
  }'

Python

import vertexai
from vertexai.generative_models import (
    FunctionDeclaration,
    GenerativeModel,
    GenerationConfig,
    Part,
    Tool,
    ToolConfig,
)

vertexai.init(project=PROJECT_ID, location=REGION)

# Specify a function declaration and parameters for an API request
get_product_info_func = FunctionDeclaration(
    name="get_product_sku",
    description="Get the available inventory for a Google products, e.g: Pixel phones, Pixel Watches, Google Home etc",
    # Function parameters are specified in OpenAPI JSON schema format
    parameters={
        "type": "object",
        "properties": {
            "product_name": {"type": "string", "description": "Product name"}
        },
    },
)

# Specify another function declaration and parameters for an API request
get_store_location_func = FunctionDeclaration(
    name="get_store_location",
    description="Get the location of the closest store",
    # Function parameters are specified in OpenAPI JSON schema format
    parameters={
        "type": "object",
        "properties": {"location": {"type": "string", "description": "Location"}},
    },
)

# Define a tool that includes the above functions
retail_tool = Tool(
    function_declarations=[
        get_product_info_func,
        get_store_location_func,
    ],
)

# Define a tool config for the above functions
retail_tool_config = ToolConfig(
    function_calling_config=ToolConfig.FunctionCallingConfig(
        # ANY mode forces the model to predict a function call
        mode=ToolConfig.FunctionCallingConfig.Mode.ANY,
        # List of functions that can be returned when the mode is ANY.
        # If the list is empty, any declared function can be returned.
        allowed_function_names=["get_product_sku"],
    )
)

generation_config = GenerationConfig(
    temperature=0.95, top_p=1.0, max_output_tokens=8192
)

gemini_model = GenerativeModel(
    MODEL_ID,
    generation_config=generation_config,
    tools=[retail_tool],
    tool_config=retail_tool_config,
)
model_response = gemini_model.generate_content(
    "Do you have the White Pixel 8 Pro 128GB in stock in the US?"
)

print(model_response)

Explora más

Para obtener documentación detallada, consulta lo siguiente: