Tutorial sobre chamada de função

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

A chamada de função facilita a geração de saídas de dados estruturados de modelos generativos. Depois, use essas saídas para chamar outras APIs e retornar os dados de resposta relevantes ao modelo. Em outras palavras, a chamada de função ajuda você a conectar modelos generativos a sistemas externos, para que o conteúdo gerado inclua as informações mais atualizadas e precisas.

É possível fornecer descrições de funções aos modelos do Gemini. Essas são funções que você escreve na linguagem do seu app (ou seja, não são funções do Google Cloud). O modelo pode pedir que você chame uma função e envie de volta o resultado para ajudar o modelo a lidar com sua consulta.

Caso ainda não tenha feito isso, confira a Introdução à chamada de função para saber mais.

Exemplo de API para controle de iluminação

Imagine que você tem um sistema básico de controle de iluminação com uma interface de programação do aplicativo (API) e quer permitir que os usuários controlem as luzes usando solicitações de texto simples. Use o recurso de chamada de função para interpretar solicitações de mudança de iluminação dos usuários e convertê-las em chamadas de API para definir os valores de iluminação. Esse sistema hipotético de controle de iluminação permite controlar o brilho da luz e a temperatura da cor, definidas por dois parâmetros separados:

Para simplificar, esse sistema de iluminação imaginário tem apenas uma luz. Portanto, o usuário não precisa especificar um ambiente ou local. Veja um exemplo de solicitação JSON que pode ser enviada à API de controle de iluminação para mudar o nível de luz para 50% usando a temperatura da cor diurna:

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

Neste tutorial, mostramos como configurar uma chamada de função para a API Gemini para interpretar solicitações de iluminação dos usuários e mapeá-las para as configurações da API para controlar o brilho e os valores de temperatura da cor de uma luz.

Antes de começar: configurar o projeto e a chave de API

Antes de chamar a API Gemini, você precisa configurar seu projeto e sua chave de API.

dart pub add google_generative_ai

flutter pub add google_generative_ai

Definir uma função de API

Crie uma função que faça uma solicitação de API. Essa função precisa ser definida no código do aplicativo, mas pode chamar serviços ou APIs de fora do aplicativo. A API Gemini não chama essa função diretamente. Portanto, você pode controlar como e quando ela é executada pelo código do aplicativo. Para fins de demonstração, este tutorial define uma função de API simulada que apenas retorna os valores de iluminação solicitados:

Future<Map<String, Object?>> setLightValues(
  Map<String, Object?> arguments,
) async =>
    // This mock API returns the requested lighting values
    {
      'brightness': arguments['brightness'],
      'colorTemperature': arguments['colorTemp'],
    };

Criar declarações de função

Crie a declaração de função que você vai transmitir para o modelo generativo. Ao declarar uma função a ser usada pelo modelo, inclua o máximo de detalhes possível nas descrições da função e do parâmetro. O modelo generativo usa essas informações para determinar qual função selecionar e como fornecer valores para os parâmetros na chamada de função. O código abaixo mostra como declarar a função de controle de iluminação:

final lightControlTool = FunctionDeclaration(
    'setLightValues',
    'Set the brightness and color temperature of a room light.',
    Schema(SchemaType.object, properties: {
      'brightness': Schema(SchemaType.number,
          description: 'Light level from 0 to 100. '
              'Zero is off and 100 is full brightness.'),
      'colorTemperature': Schema(SchemaType.string,
          description: 'Color temperature of the light fixture, '
              'which can be `daylight`, `cool` or `warm`.'),
    }, requiredProperties: [
      'brightness',
      'colorTemperature'
    ]));

Declarar funções durante a inicialização do modelo

Para usar a chamada de função com um modelo, forneça as declarações da função ao inicializar o objeto do modelo. Para declarar funções, defina o parâmetro tools do modelo. O SDK do Dart também oferece suporte à declaração das funções como argumentos para as APIs generateContent ou generateContentStream.

final model = GenerativeModel(
  model: 'gemini-1.5-flash',
  apiKey: apiKey,

  // Specify the function declaration.
  tools: [
    Tool(functionDeclarations: [lightControlTool])
  ],
);

Gerar uma chamada de função

Depois de inicializar o modelo com as declarações de função, é possível solicitar o modelo com a função definida. Use a chamada de função com os comandos de chat (sendMessage()), já que ela geralmente se beneficia de ter o contexto de comandos e respostas anteriores.

final chat = model.startChat(); final prompt =
  'Dim the lights so the room feels cozy and warm.';

// Send the message to the generative model.
var response = await chat.sendMessage(Content.text(prompt));

final functionCalls = response.functionCalls.toList();
// When the model response with a function call, invoke the function.
if (functionCalls.isNotEmpty) {
  final functionCall = functionCalls.first;
  final result = switch (functionCall.name) {
    // Forward arguments to the hypothetical API.
    'setLightValues' => await setLightValues(functionCall.args),
    // Throw an exception if the model attempted to call a function that was
    // not declared.
    _ => throw UnimplementedError(
        'Function not implemented: ${functionCall.name}')
  };
  // Send the response to the model so that it can use the result to generate
  // text for the user.
  response = await chat
      .sendMessage(Content.functionResponse(functionCall.name, result));
}
// When the model responds with non-null text content, print it.
if (response.text case final text?) {
  print(text);
}