API de chamada de função

A chamada de funções melhora a capacidade dos LLMs de fornecer respostas relevantes e contextuais.

É possível apresentar funções personalizadas para um modelo de IA generativa com a API de chamada de função. O modelo não invoca diretamente essas funções, mas gera uma saída de dados estruturados que especifica o nome da função e os argumentos sugeridos. Essa saída permite chamar APIs ou sistemas de informação externos, como bancos de dados, sistemas de gestão de relacionamento com o cliente e repositórios de documentos. A saída da API resultante pode ser usada pelo LLM para melhorar a qualidade da resposta.

Modelos compatíveis:

  • 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

Limitações:

  • O número máximo de funções que podem ser fornecidas é 64.
  • FunctionCallingConfig está em pré-lançamento e disponível apenas para "gemini-1.5-pro-preview-0409".

Sintaxe

  • 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

Uma representação estruturada de uma declaração de função, conforme definido pela especificação OpenAPI 3.0 (link em inglês) que representa uma função em que o modelo pode gerar entradas JSON.

Parâmetros

name

string

O nome da função a ser chamada.

description

Opcional: string

Descrição e propósito da função.

parameters

Opcional: Schema

Descreve os parâmetros para esta função no formato de objeto de esquema JSON da OpenAPI: especificação OpenAPI 3.0

response

Opcional: Schema

Descreve a saída dessa função no formato de esquema JSON.

FunctionCallingConfig [prévia]

Essa é uma configuração extra para usar o recurso de chamada de função que está disponível apenas para gemini-1.5-pro-preview-0409.

Parâmetros

mode

Opcional: enum/string[]

  • AUTO: comportamento padrão do modelo, em que ele decide prever uma chamada de função ou uma resposta de linguagem natural.
  • NONE: o modelo não vai prever nenhuma chamada de função. O comportamento do modelo é o mesmo que ocorre quando nenhuma declaração de função é transmitida.
  • ANY: o modelo é restrito a sempre prever uma única chamada de função.

Quando allowed_function_names é definido, a chamada de função prevista é limitada a qualquer um dos allowed_function_names. Por padrão, a chamada de função prevista será de qualquer um dos function_declarations fornecidos.

allowed_function_names

Opcional: string[]

Nomes de funções a serem chamadas. Definido apenas quando mode é ANY. Os nomes das funções precisam corresponder a [FunctionDeclaration.name]. Com o modo definido como ANY, o modelo prevê uma chamada de função do conjunto de nomes de função fornecido.

Esquema

O esquema é usado para definir o formato dos dados de entrada e saída em uma chamada de função. Uma representação estruturada de uma declaração de função, conforme definido pela especificação de Esquema da OpenAPI 3.0.

Parâmetros
Tipo

string

enumerado. O tipo dos dados. Precisa ser um dos:

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

Opcional: string

Descrição dos dados.
enum

Opcional: string[]

Valores possíveis do elemento de Type.STRING com formato de tipo enumerado.
items

Opcional: Schema[]

Esquema dos elementos de Type.ARRAY
properties

Opcional: Schema

Esquema das propriedades de Type.OBJECT
required

Opcional: string[]

Propriedades obrigatórias de Type.OBJECT.
nullable

Opcional: bool

Indica se o valor pode ser null.

Examplos

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

Caso de uso básico

Confira um exemplo de como enviar declarações de consulta e função para o 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 avançado

O exemplo a seguir demonstra como passar a configuração de geração e a configuração da ferramenta para o modelo. A configuração da chamada de função pode ser usada para garantir que a saída do modelo seja sempre uma chamada de função específica. Para fazer isso, defina o modo de chamada de função como ANY e especifique os nomes de funções permitidos no parâmetro allowed_function_names. Quando allowed_function_names está vazio, qualquer uma das funções fornecidas pode ser retornada.

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

Mais informações

Para consultar a documentação detalhada, acesse: