Modelos de linguagem grandes (LLMs) são poderosos na resolução de muitos tipos de problemas. No entanto, eles são limitados pelas seguintes limitações:
- Eles são congelados após o treinamento, levando a um conhecimento desatualizado.
- Eles não podem consultar nem modificar dados externos.
As chamadas de função podem resolver essas deficiências. A chamada de função às vezes é chamada de uso de ferramentas porque permite que o modelo use ferramentas externas, como APIs e funções.
Ao enviar um comando para o LLM, você também
fornece ao modelo um conjunto de ferramentas que ele pode usar para responder ao comando do usuário. Por
exemplo, você pode fornecer uma função get_weather que usa um parâmetro de local
e retorna informações sobre as condições climáticas nesse local.
Ao processar uma solicitação, o modelo pode optar por delegar determinadas
tarefas de processamento de dados às funções que você identifica. O modelo não
chama as funções diretamente. Em vez disso, o modelo fornece uma saída de dados estruturados
que inclui a função a ser chamada e os valores de parâmetro a serem usados. Por exemplo, para
um comando What is the weather like in Boston?, o modelo pode delegar o processamento
à função get_weather e fornecer o valor de parâmetro de local Boston, MA.
É possível usar a saída estruturada do modelo para invocar APIs externas. Por
exemplo, você pode se conectar a uma API de serviço meteorológico, fornecer o local
Boston, MA e receber informações sobre temperatura, cobertura de nuvens e condições
do vento.
É possível então fornecer a saída da API de volta ao modelo, permitindo que ele conclua a resposta ao comando. No exemplo de clima, o modelo pode fornecer a
seguinte resposta: It is currently 38 degrees Fahrenheit in Boston, MA with partly cloudy skies.
Modelos compatíveis
Os modelos a seguir oferecem suporte à chamada de função:
| Modelo | Versão | Estágio de inicialização da chamada de função | Suporte à chamada de função paralela | Compatibilidade com chamadas de função forçada |
|---|---|---|---|---|
| Gemini 1.0 Pro | all versions |
Disponibilidade geral | Não | Não |
| Gemini 1.5 Flash | all versions |
Disponibilidade geral | Sim | Sim |
| Gemini 1.5 Pro | all versions |
Disponibilidade geral | Sim | Sim |
Casos de uso de chamada de funções
É possível usar a chamada de função para as seguintes tarefas:
| Caso de uso | Exemplo de descrição | Link de exemplo |
|---|---|---|
| Integrar com APIs externas | Receber informações meteorológicas usando uma API meteorológica | Tutorial do notebook |
| Converter endereços em coordenadas de latitude/longitude | Tutorial do notebook | |
| Converter moedas usando uma API de câmbio | Codelab | |
| Criar chatbots avançados | Responder às perguntas dos clientes sobre produtos e serviços | Tutorial do notebook |
| Criar um assistente para responder a perguntas financeiras e de notícias sobre empresas | Tutorial do notebook | |
| Estruturar e controlar chamadas de função | Extrair entidades estruturadas de dados de registro brutos | Tutorial do notebook |
| Extrair um ou vários parâmetros da entrada do usuário | Tutorial do notebook | |
| Processar listas e estruturas de dados aninhadas em chamadas de função | Tutorial do notebook | |
| Processar o comportamento de chamada de função | Processar respostas e chamadas de função paralelas | Tutorial do notebook |
| Gerenciar quando e quais funções o modelo pode chamar | Tutorial do notebook | |
| Consultar bancos de dados com linguagem natural | Converter perguntas em linguagem natural em consultas SQL para o BigQuery | App de exemplo |
| Chamada de função multimodal | Use imagens, vídeos, áudios e PDFs como entrada para acionar chamadas de função | Tutorial do notebook |
Confira outros casos de uso:
Interpretar comandos de voz: crie funções que correspondam a tarefas no veículo. Por exemplo, crie funções que liguem o rádio ou ativem o ar-condicionado. Envie arquivos de áudio com os comandos de voz do usuário ao modelo e peça que ele converta o áudio em texto e identifique a função que o usuário quer chamar.
Automatizar fluxos de trabalho com base em gatilhos ambientais: crie funções para representar processos que podem ser automatizados. Forneça dados de sensores ambientais ao modelo e peça que ele analise e processe os dados para determinar se um ou mais fluxos de trabalho precisam ser ativados. Por exemplo, um modelo pode processar dados de temperatura em um armazém e ativar uma função de sprinkler.
Automatizar a atribuição de tíquetes de suporte: forneça ao modelo tíquetes de suporte, registros e regras baseadas no contexto. Peça ao modelo para processar todas essas informações e determinar a quem o tíquete será atribuído. Chame uma função para atribuir o tíquete à pessoa sugerida pelo modelo.
Recuperar informações de uma base de conhecimento: crie funções que recuperem e resumam artigos acadêmicos sobre um determinado assunto. Permita que o modelo responda perguntas sobre matérias acadêmicas e forneça citações das respectivas respostas.
Como criar um aplicativo de chamada de função
Para permitir que um usuário interaja com o modelo e use a chamada de função, crie um código que execute as seguintes tarefas:
- Configure o ambiente.
- Definir e descrever um conjunto de funções disponíveis usando declarações de função.
- Enviar o comando de um usuário e as declarações da função para o modelo.
- Invoque uma função usando a saída de dados estruturados do modelo.
- Forneça a saída da função ao modelo.
Crie um aplicativo que gerencie todas essas tarefas. Pode ser um chatbot de texto, um agente de voz, um fluxo de trabalho automatizado ou qualquer outro programa.
É possível usar a chamada de função para gerar uma única resposta de texto ou para permitir uma sessão de chat. As respostas de texto ad hoc são úteis para tarefas específicas de negócio, incluindo a geração de código. As sessões de chat são úteis em cenários de conversa com formato livre, em que um usuário provavelmente fará perguntas complementares.
Se você usar a chamada de função para gerar uma única resposta, forneça ao modelo o contexto completo da interação. Por outro lado, se você usar a chamada da função no contexto de uma sessão de chat, ela armazenará o contexto por você e o incluirá em todas as solicitações do modelo. Em ambos os casos, a Vertex AI armazenará o histórico da interação no lado do cliente.
Este guia demonstra como usar chamadas de função para gerar uma única resposta de texto. Para conferir um exemplo completo, consulte Exemplos de texto. Para saber como usar a chamada de função para permitir uma sessão de chat, consulte exemplos de chat.
Etapa 1: configurar seu ambiente
Importar os módulos necessários e inicializar o modelo
Python
import vertexai
from vertexai.generative_models import (
Content,
FunctionDeclaration,
GenerationConfig,
GenerativeModel,
Part,
Tool,
)
# Initialize Vertex AI
# TODO(developer): Update and un-comment below lines
# PROJECT_ID = 'your-project-id'
vertexai.init(project=PROJECT_ID, location="us-central1")
# Initialize Gemini model
model = GenerativeModel(model_name="gemini-1.5-flash-002")
Etapa 2: declarar um conjunto de funções
O aplicativo precisa declarar um conjunto de funções que o modelo pode usar para processar o modelo.
O número máximo de declarações de função que podem ser fornecidas com a solicitação é 128.
Você precisa fornecer declarações de função em um formato de esquema compatível
com o esquema da OpenAPI. A Vertex AI oferece suporte limitado ao esquema da OpenAPI. Os seguintes
atributos são aceitos: type, nullable, required, format,
description, properties, items, enum. Não são aceitos os seguintes atributos: default, optional, maximum, oneOf. Para conferir as práticas recomendadas relacionadas às declarações de função, incluindo dicas para nomes e descrições, consulte
Práticas recomendadas.
Se você usar a API REST, especifique o esquema usando JSON. Se você usar o
SDK da Vertex AI para Python, poderá especificar o esquema manualmente usando um dicionário Python ou automaticamente com a função auxiliar from_func.
JSON
{
"contents": ...,
"tools": [
{
"function_declarations": [
{
"name": "find_movies",
"description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"description": {
"type": "string",
"description": "Any kind of description including category or genre, title words, attributes, etc."
}
},
"required": [
"description"
]
}
},
{
"name": "find_theaters",
"description": "find theaters based on location and optionally movie title which are is currently playing in theaters",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"movie": {
"type": "string",
"description": "Any movie title"
}
},
"required": [
"location"
]
}
},
{
"name": "get_showtimes",
"description": "Find the start times for movies playing in a specific theater",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"movie": {
"type": "string",
"description": "Any movie title"
},
"theater": {
"type": "string",
"description": "Name of the theater"
},
"date": {
"type": "string",
"description": "Date for requested showtime"
}
},
"required": [
"location",
"movie",
"theater",
"date"
]
}
}
]
}
]
}
Dicionário do Python
A declaração de função a seguir usa um único parâmetro string:
function_name = "get_current_weather"
get_current_weather_func = FunctionDeclaration(
name=function_name,
description="Get the current weather in a given location",
# Function parameters are specified in JSON schema format
parameters={
"type": "object",
"properties": {
"location": {"type": "string", "description": "The city name of the location for which to get the weather."}
},
},
)
A declaração de função a seguir usa parâmetros de objeto e matriz:
extract_sale_records_func = FunctionDeclaration(
name="extract_sale_records",
description="Extract sale records from a document.",
parameters={
"type": "object",
"properties": {
"records": {
"type": "array",
"description": "A list of sale records",
"items": {
"description": "Data for a sale record",
"type": "object",
"properties": {
"id": {"type": "integer", "description": "The unique id of the sale."},
"date": {"type": "string", "description": "Date of the sale, in the format of MMDDYY, e.g., 031023"},
"total_amount": {"type": "number", "description": "The total amount of the sale."},
"customer_name": {"type": "string", "description": "The name of the customer, including first name and last name."},
"customer_contact": {"type": "string", "description": "The phone number of the customer, e.g., 650-123-4567."},
},
"required": ["id", "date", "total_amount"],
},
},
},
"required": ["records"],
},
)
Python da função
O exemplo de código abaixo declara uma função que multiplica uma matriz de números e usa from_func para gerar o esquema FunctionDeclaration.
# Define a function. Could be a local function or you can import the requests library to call an API
def multiply_numbers(numbers):
"""
Calculates the product of all numbers in an array.
Args:
numbers: An array of numbers to be multiplied.
Returns:
The product of all the numbers. If the array is empty, returns 1.
"""
if not numbers: # Handle empty array
return 1
product = 1
for num in numbers:
product *= num
return product
multiply_number_func = FunctionDeclaration.from_func(multiply_numbers)
'''
multiply_number_func contains the following schema:
name: "multiply_numbers"
description: "Calculates the product of all numbers in an array."
parameters {
type_: OBJECT
properties {
key: "numbers"
value {
description: "An array of numbers to be multiplied."
title: "Numbers"
}
}
required: "numbers"
description: "Calculates the product of all numbers in an array."
title: "multiply_numbers"
}
'''
Etapa 3: enviar o comando e as declarações de função para o modelo
Quando o usuário fornece um comando, o aplicativo precisa fornecer ao modelo o comando do usuário e as declarações da função. Para configurar como o modelo gera resultados, o aplicativo pode fornecer ao modelo uma configuração de geração. Para configurar como o modelo usa as declarações de função, o aplicativo pode fornecer ao modelo uma configuração de ferramenta.
Definir o comando do usuário
Este é um exemplo de comando do usuário: "Como está o clima em Boston?"
Confira a seguir um exemplo de como definir a solicitação do usuário:
Python
# Define the user's prompt in a Content object that we can reuse in model calls
user_prompt_content = Content(
role="user",
parts=[
Part.from_text("What is the weather like in Boston?"),
],
)
Para conferir as práticas recomendadas relacionadas à solicitação do usuário, consulte Práticas recomendadas: prompt do usuário.
Configuração de geração
O modelo pode gerar diferentes resultados para diferentes valores de parâmetros. O parâmetro de temperatura controla o grau de aleatoriedade nesta geração.
Temperaturas mais baixas são boas para funções que exigem valores de parâmetro
determinísticos, enquanto temperaturas mais altas são boas para funções com parâmetros que
aceitam valores de parâmetros mais diversos ou criativos. Uma temperatura de 0 é determinista Nesse caso, as respostas para uma determinada solicitação são, na maioria, deterministas, mas uma pequena quantidade de
variação ainda é possível. Para saber mais, consulte API Gemini.
Para definir esse parâmetro, envie uma configuração de geração (generation_config)
com o prompt e as declarações da função. É possível atualizar o
parâmetro temperature durante uma conversa por chat usando a API Vertex AI
e um generation_config atualizado. Para ver um exemplo de configuração do parâmetro temperature, consulte Como enviar o prompt e as declarações da função.
Para as práticas recomendadas relacionadas à configuração de geração, consulte Práticas recomendadas: configuração de geração.
Configuração da ferramenta
É possível impor algumas restrições sobre como o modelo precisa usar as declarações de função que você fornece. Por exemplo, em vez de permitir que o modelo escolha entre uma resposta de linguagem natural e uma chamada de função, é possível forçar o modelo a prever apenas chamadas de função ("chamada de função forçada" ou "chamada de função com geração controlada"). Também é possível fornecer ao modelo um conjunto completo de declarações de função, mas restringir as respostas a um subconjunto dessas funções.
Para colocar essas restrições, envie uma configuração de ferramenta (tool_config) com
o comando e as declarações da função. Na configuração, é possível
especificar um dos seguintes modos:
| Modo | Descrição |
|---|---|
AUTO |
O comportamento padrão do modelo. O modelo decide se quer prever chamadas de função ou uma resposta de linguagem natural. |
ANY |
O modelo é restrito a sempre prever uma chamada de função. Se allowed_function_names não for fornecido, o modelo vai escolher entre todas as declarações de função disponíveis. Se allowed_function_names for fornecido, o modelo vai escolher entre o conjunto de funções permitidas. |
NONE |
O modelo não deve prever chamadas de função. Esse comportamento é equivalente a uma solicitação de modelo sem declarações de função associadas. |
Para uma lista de modelos compatíveis com o modo ANY ("chamada de função forçada"),
consulte modelos compatíveis.
Para saber mais, consulte API de chamada de função.
Como enviar o comando e as declarações de função
Veja a seguir um exemplo de como enviar o comando e as declarações
de função ao modelo e restringir o modelo para prever apenas
chamadas de função get_current_weather.
Python
# Define a tool that includes some of the functions that we declared earlier
tool = Tool(
function_declarations=[get_current_weather_func, extract_sale_records_func, multiply_number_func],
)
# Send the prompt and instruct the model to generate content using the Tool object that you just created
response = model.generate_content(
user_prompt_content,
generation_config=GenerationConfig(temperature=0),
tools=[tool],
tool_config=ToolConfig(
function_calling_config=ToolConfig.FunctionCallingConfig(
# ANY mode forces the model to predict only function calls
mode=ToolConfig.FunctionCallingConfig.Mode.ANY,
# Allowed function calls to predict when the mode is ANY. If empty, any of
# the provided function calls will be predicted.
allowed_function_names=["get_current_weather"],
)
)
)
Se o modelo determinar que precisa da saída de uma função específica, a resposta que o aplicativo recebe do modelo conterá o nome da função e os valores de parâmetro com os quais a função precisa ser chamada.
Veja a seguir um exemplo de resposta de modelo para o comando do usuário "Como está o clima em Boston?". O modelo propõe chamar a função get_current_weather com o parâmetro Boston, MA.
candidates {
content {
role: "model"
parts {
function_call {
name: "get_current_weather"
args {
fields {
key: "location"
value {
string_value: "Boston, MA"
}
}
}
}
}
}
...
}
Para comandos como "Receber detalhes do clima em Nova Délhi e São Francisco?", o modelo pode propor várias chamadas de função paralelas. Para saber mais, consulte o Exemplo de chamada de função paralela.
Etapa 4: invocar uma API externa
Se o aplicativo receber o nome da função e os valores de parâmetro do modelo, ele precisará se conectar a uma API externa e chamar a função.
O exemplo a seguir usa dados sintéticos para simular um payload de resposta de uma API externa:
Python
# Check the function name that the model responded with, and make an API call to an external system
if (response.candidates[0].function_calls[0].name == "get_current_weather"):
# Extract the arguments to use in your API call
location = response.candidates[0].function_calls[0].args["location"]
# Here you can use your preferred method to make an API request to fetch the current weather, for example:
# api_response = requests.post(weather_api_url, data={"location": location})
# In this example, we'll use synthetic data to simulate a response payload from an external API
api_response = """{ "location": "Boston, MA", "temperature": 38, "description": "Partly Cloudy",
"icon": "partly-cloudy", "humidity": 65, "wind": { "speed": 10, "direction": "NW" } }"""
Para conferir as práticas recomendadas relacionadas à invocação de API, consulte Práticas recomendadas: invocação de API.
Etapa 5: fornecer a saída da função ao modelo
Depois que um aplicativo recebe uma resposta de uma API externa, ele precisa fornecer essa resposta ao modelo. Veja a seguir um exemplo de como fazer isso usando Python:
Python
response = model.generate_content(
[
user_prompt_content, # User prompt
response.candidates[0].content, # Function call response
Content(
parts=[
Part.from_function_response(
name="get_current_weather",
response={
"content": api_response, # Return the API response to Gemini
},
)
],
),
],
tools=[weather_tool],
)
# Get the model summary response
summary = response.text
Se o modelo propôs várias chamadas de função paralelas, o aplicativo precisa fornecer todas as respostas de volta ao modelo. Para saber mais, consulte o Exemplo de chamada de função paralela.
O modelo pode determinar que a saída de outra função é necessária para responder ao comando. Nesse caso, a resposta que o aplicativo recebe do modelo contém outro nome de função e outro conjunto de valores de parâmetro.
Se o modelo determinar que a resposta da API é suficiente para responder ao comando do usuário, ele criará uma resposta com linguagem natural e a retornará para o aplicativo. Nesse caso, o aplicativo precisa transmitir a resposta de volta ao usuário. Confira a seguir um exemplo de resposta:
It is currently 38 degrees Fahrenheit in Boston, MA with partly cloudy skies. The humidity is 65% and the wind is blowing at 10 mph from the northwest.
Exemplos de chamada de função
Exemplos de texto
É possível usar a chamada de função para gerar uma única resposta de texto. As respostas de texto ad hoc são úteis para tarefas específicas de negócio, incluindo a geração de código.
Se você usar a chamada de função para gerar uma única resposta, forneça ao modelo o contexto completo da interação. A Vertex AI armazena o histórico da interação no lado do cliente.
Python
Este exemplo demonstra um cenário de texto com uma só função e um só comando. Ele usa a classe GenerativeModel e os respectivos métodos. Para mais informações sobre como usar o SDK da Vertex AI para Python com os modelos multimodais do Gemini, consulte Introdução às classes multimodais no SDK da Vertex AI para Python.
Python
Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.
C#
Este exemplo demonstra um cenário de texto com uma só função e um só comando.
C#
Antes de testar esse exemplo, siga as instruções de configuração para C# no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para C#.
Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Este exemplo demonstra um cenário de texto com uma só função e um só comando.
Node.js
Antes de testar essa amostra, siga as instruções de configuração para Node.js Guia de início rápido da Vertex AI: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Node.js.
Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
REST
Este exemplo demonstra um cenário de texto com três funções e um só comando.
Neste exemplo, você chama o modelo de IA generativa duas vezes.
- Na primeira chamada, você fornece ao modelo o comando e as declarações da função.
- Na segunda chamada, você fornece a resposta da API ao modelo.
Primeira solicitação de modelo
A solicitação precisa definir um comando no parâmetro text. Esse exemplo define
o seguinte comando: "Quais cinemas em Mountain View exibem o filme da Barbie?".
A solicitação também precisa definir uma ferramenta (tools) com um conjunto de declarações
de função (functionDeclarations). Essas declarações de função precisam ser
especificadas em um formato compatível com o
esquema da OpenAPI. Este exemplo
define as seguintes funções:
find_moviesencontra títulos de filmes em exibição nos cinemas.find_theatresencontra cinemas com base na localização.get_showtimesencontra os horários de início dos filmes em exibição em um cinema específico.
Para saber mais sobre os parâmetros da solicitação de modelo, consulte a API Gemini.
Substitua my-project pelo nome do projeto do Google Cloud.
Primeira solicitação de modelo
PROJECT_ID=my-project
MODEL_ID=gemini-1.0-pro
API=streamGenerateContent
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/publishers/google/models/${MODEL_ID}:${API} -d '{
"contents": {
"role": "user",
"parts": {
"text": "Which theaters in Mountain View show the Barbie movie?"
}
},
"tools": [
{
"function_declarations": [
{
"name": "find_movies",
"description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"description": {
"type": "string",
"description": "Any kind of description including category or genre, title words, attributes, etc."
}
},
"required": [
"description"
]
}
},
{
"name": "find_theaters",
"description": "find theaters based on location and optionally movie title which are is currently playing in theaters",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"movie": {
"type": "string",
"description": "Any movie title"
}
},
"required": [
"location"
]
}
},
{
"name": "get_showtimes",
"description": "Find the start times for movies playing in a specific theater",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"movie": {
"type": "string",
"description": "Any movie title"
},
"theater": {
"type": "string",
"description": "Name of the theater"
},
"date": {
"type": "string",
"description": "Date for requested showtime"
}
},
"required": [
"location",
"movie",
"theater",
"date"
]
}
}
]
}
]
}'
Para o comando "Quais cinemas em Mountain View exibem o filme da Barbie?", o modelo
pode retornar a função find_theatres com os parâmetros Barbie e
Mountain View, CA.
Resposta à primeira solicitação de modelo
[{
"candidates": [
{
"content": {
"parts": [
{
"functionCall": {
"name": "find_theaters",
"args": {
"movie": "Barbie",
"location": "Mountain View, CA"
}
}
}
]
},
"finishReason": "STOP",
"safetyRatings": [
{
"category": "HARM_CATEGORY_HARASSMENT",
"probability": "NEGLIGIBLE"
},
{
"category": "HARM_CATEGORY_HATE_SPEECH",
"probability": "NEGLIGIBLE"
},
{
"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
"probability": "NEGLIGIBLE"
},
{
"category": "HARM_CATEGORY_DANGEROUS_CONTENT",
"probability": "NEGLIGIBLE"
}
]
}
],
"usageMetadata": {
"promptTokenCount": 9,
"totalTokenCount": 9
}
}]
Segunda solicitação de modelo
Esse exemplo usa dados sintéticos em vez de chamar a API externa.
Há dois resultados, cada um com dois parâmetros (name e address):
name:AMC Mountain View 16,address:2000 W El Camino Real, Mountain View, CA 94040name:Regal Edwards 14,address:245 Castro St, Mountain View, CA 94040
Substitua my-project pelo nome do projeto do Google Cloud.
Segunda solicitação de modelo
PROJECT_ID=my-project
MODEL_ID=gemini-1.0-pro
API=streamGenerateContent
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/publishers/google/models/${MODEL_ID}:${API} -d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Which theaters in Mountain View show the Barbie movie?"
}]
}, {
"role": "model",
"parts": [{
"functionCall": {
"name": "find_theaters",
"args": {
"location": "Mountain View, CA",
"movie": "Barbie"
}
}
}]
}, {
"parts": [{
"functionResponse": {
"name": "find_theaters",
"response": {
"name": "find_theaters",
"content": {
"movie": "Barbie",
"theaters": [{
"name": "AMC Mountain View 16",
"address": "2000 W El Camino Real, Mountain View, CA 94040"
}, {
"name": "Regal Edwards 14",
"address": "245 Castro St, Mountain View, CA 94040"
}]
}
}
}
}]
}],
"tools": [{
"functionDeclarations": [{
"name": "find_movies",
"description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
"parameters": {
"type": "OBJECT",
"properties": {
"location": {
"type": "STRING",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"description": {
"type": "STRING",
"description": "Any kind of description including category or genre, title words, attributes, etc."
}
},
"required": ["description"]
}
}, {
"name": "find_theaters",
"description": "find theaters based on location and optionally movie title which are is currently playing in theaters",
"parameters": {
"type": "OBJECT",
"properties": {
"location": {
"type": "STRING",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"movie": {
"type": "STRING",
"description": "Any movie title"
}
},
"required": ["location"]
}
}, {
"name": "get_showtimes",
"description": "Find the start times for movies playing in a specific theater",
"parameters": {
"type": "OBJECT",
"properties": {
"location": {
"type": "STRING",
"description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
},
"movie": {
"type": "STRING",
"description": "Any movie title"
},
"theater": {
"type": "STRING",
"description": "Name of the theater"
},
"date": {
"type": "STRING",
"description": "Date for requested showtime"
}
},
"required": ["location", "movie", "theater", "date"]
}
}]
}]
}'
A resposta do modelo pode ser semelhante a esta:
Resposta à segunda solicitação de modelo
{
"candidates": [
{
"content": {
"parts": [
{
"text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14."
}
]
}
}
],
"usageMetadata": {
"promptTokenCount": 9,
"candidatesTokenCount": 27,
"totalTokenCount": 36
}
}
Exemplos de chat
É possível usar a chamada de função para permitir uma sessão de chat. As sessões de chat são úteis em cenários de conversa com formato livre, em que um usuário provavelmente fará perguntas complementares.
Se você usar a chamada de função no contexto de uma sessão de chat, ela armazenará o contexto por você e o incluirá em todas as solicitações do modelo. A Vertex AI armazena o histórico da interação no lado do cliente.
Python
Neste exemplo, demonstramos um cenário de chat com duas funções e dois comandos sequenciais. Ele usa a classe GenerativeModel e os respectivos métodos. Para mais informações sobre como usar o SDK da Vertex AI para Python com os modelos multimodais, consulte Introdução às classes multimodais no SDK da Vertex AI para Python.
Para saber como instalar ou atualizar o Python, consulte Instalar o SDK da Vertex AI para Python. Para mais informações, consulte a documentação de referência da API Python.
Java
Antes de testar esse exemplo, siga as instruções de configuração para Java no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Java.
Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Antes de testar esse exemplo, siga as instruções de configuração para Go no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Go.
Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Antes de testar esse exemplo, siga as instruções de configuração para Node.js no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Node.js.
Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Exemplo de chamada de função paralela
Para comandos como "Receber detalhes do clima em Nova Délhi e São Francisco?", o modelo pode propor várias chamadas de função paralelas. Para conferir uma lista de modelos que oferecem suporte à chamada de função paralela, consulte Modelos compatíveis.
REST
Este exemplo demonstra um cenário com uma função get_current_weather.
O prompt do usuário é "Receber detalhes do clima em Nova Délhi e São Francisco?". O
modelo propõe duas chamadas de função get_current_weather paralelas: uma com o
parâmetro New Delhi e outra com o parâmetro San Francisco.
Para saber mais sobre os parâmetros da solicitação de modelo, consulte a API Gemini.
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"functionCall": {
"name": "get_current_weather",
"args": {
"location": "New Delhi"
}
}
},
{
"functionCall": {
"name": "get_current_weather",
"args": {
"location": "San Francisco"
}
}
}
]
},
...
}
],
...
}
O comando a seguir demonstra como fornecer a saída da função para o modelo. Substitua my-project pelo nome do projeto do Google Cloud.
Solicitação de modelo
PROJECT_ID=my-project
MODEL_ID=gemini-1.5-pro-002
VERSION="v1"
LOCATION="us-central1"
ENDPOINT=${LOCATION}-aiplatform.googleapis.com
API="generateContent"
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://${ENDPOINT}/${VERSION}/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:${API} -d '{
"contents": [
{
"role": "user",
"parts": {
"text": "What is difference in temperature in New Delhi and San Francisco?"
}
},
{
"role": "model",
"parts": [
{
"functionCall": {
"name": "get_current_weather",
"args": {
"location": "New Delhi"
}
}
},
{
"functionCall": {
"name": "get_current_weather",
"args": {
"location": "San Francisco"
}
}
}
]
},
{
"role": "user",
"parts": [
{
"functionResponse": {
"name": "get_current_weather",
"response": {
"temperature": 30.5,
"unit": "C"
}
}
},
{
"functionResponse": {
"name": "get_current_weather",
"response": {
"temperature": 20,
"unit": "C"
}
}
}
]
}
],
"tools": [
{
"function_declarations": [
{
"name": "get_current_weather",
"description": "Get the current weather in a specific 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"
]
}
}
]
}
]
}'
A resposta de linguagem natural criada pelo modelo é semelhante a esta:
Resposta do modelo
[
{
"candidates": [
{
"content": {
"parts": [
{
"text": "The temperature in New Delhi is 30.5C and the temperature in San Francisco is 20C. The difference is 10.5C. \n"
}
]
},
"finishReason": "STOP",
...
}
]
...
}
]
Python
Práticas recomendadas para chamadas de função
Nome da função
O nome da função precisa começar com uma letra ou sublinhado e conter apenas caracteres a-z, A-Z, 0-9, sublinhados, pontos ou traços com um comprimento máximo de 64.
Descrição da função
Escreva as descrições das funções de maneira clara e detalhada. Por exemplo, para uma função book_flight_ticket:
- Veja a seguir um exemplo de uma descrição boa da função:
book flight tickets after confirming users' specific requirements, such as time, departure, destination, party size and preferred airline - Veja a seguir um exemplo de uma descrição ruim da função:
book flight ticket
Parâmetros de função
Os nomes de parâmetros de função e atributos aninhados precisam começar com uma letra ou um sublinhado e conter apenas caracteres a-z, A-Z, 0-9 ou sublinhados com um comprimento máximo de 64. Não use caracteres de ponto (.), traço (-) ou espaço nos nomes dos parâmetros de função e nos atributos aninhados.
Em vez disso, use o caractere de sublinhado (_) ou qualquer outro caractere.
Descrições
Escreva descrições claras e detalhadas dos parâmetros, incluindo detalhes como formato ou valores preferidos. Por exemplo, para uma função book_flight_ticket:
- Veja a seguir um exemplo bom de uma descrição de parâmetro
departure:Use the 3 char airport code to represent the airport. For example, SJC or SFO. Don't use the city name. - Veja a seguir um exemplo ruim de uma descrição de parâmetro
departure:the departure airport
Tipos
Se possível, use parâmetros fortemente tipados para reduzir as alucinações do modelo. Por exemplo, se os valores de parâmetro forem de um conjunto finito, adicione um campo enum em vez de colocar o conjunto de valores na descrição. Se o valor
do parâmetro for sempre um número inteiro, defina o tipo como integer em vez de number.
Instruções do sistema
Ao usar funções com parâmetros de data, hora ou local, inclua a data, a hora ou as informações de local relevantes (por exemplo, cidade e país) na instrução do sistema. Isso garante que o modelo tenha o contexto necessário para processar a solicitação com precisão, mesmo que a solicitação do usuário não tenha detalhes.
Comando do usuário
Para melhores resultados, adicione ao início os seguintes detalhes antes do comando do usuário:
- Contexto adicional para o modelo, por exemplo,
You are a flight API assistant to help with searching flights based on user preferences.. - Detalhes ou instruções sobre como e quando usar as funções, por exemplo,
Don't make assumptions on the departure or destination airports. Always use a future date for the departure or destination time. - Instruções para fazer perguntas esclarecedoras se as consultas do usuário forem ambíguas, por exemplo,
Ask clarifying questions if not enough information is available.
Configuração de geração
Para o parâmetro de temperatura, use 0 ou outro valor baixo. Isso instrui o modelo a gerar resultados mais confiáveis e reduz alucinações.
Invocação da API
Se o modelo propor a invocação de uma função que envia uma ordem, atualiza um banco de dados ou tem consequências significativas, valide a chamada de função com o usuário antes de executá-la.
Preços
Os preços da chamada de funções são baseados no número de caracteres nas entradas e saídas de texto. Para saber mais, consulte os preços da Vertex AI.
Aqui, a entrada de texto (comando) se refere ao comando do usuário sobre o turno da conversa atual, as declarações de função para o turno da conversa atual e o histórico da conversa. O histórico da conversa inclui as consultas, as chamadas de função e as respostas de função das interações anteriores. A Vertex AI trunca o histórico da conversa em 32.000 caracteres.
Saída de texto (resposta) refere-se às chamadas de função e às respostas de texto da rodada de conversa atual.
A seguir
Consulte a referência da API para chamada de função.
Saiba mais sobre as extensões da Vertex AI.
Saiba mais sobre o LangChain na Vertex AI.