Chamada de funções
A chamada de função permite a conexão de modelos como o sabiá-3 a ferramentas e sistemas externos do lado do cliente. Com essa funcionalidade, é possível criar agentes que executam tarefas autônomas, interagindo com APIs e sistemas externos para realizar ações específicas, como consultar dados, automatizar processos ou tomar decisões.
Aqui está um exemplo de como fornecer ferramentas para o sabiá-3 usando a API de mensagens:
Como usar a chamada de funções
Exemplo 1: Previsão do tempo
Neste tutorial, vamos criar um assistente de conversação que pode fornecer previsões do tempo em tempo real para o usuário. O assistente usará a biblioteca OpenAI para interagir com o usuário, identificar as coordenadas geográficas necessárias e, em seguida, fará chamadas à API da Open-Meteo para obter os dados meteorológicos. Vamos abordar cada etapa e detalhar o código.
Passo 1: Definindo a Função para Consulta da Previsão do Tempo
Primeiro, criamos uma função que fará a consulta da previsão do tempo utilizando a API da Open-Meteo. Essa função será chamada pelo assistente assim que ele identificar as coordenadas do local desejado.
import requests
def consultar_previsao_tempo(latitude, longitude):
BASE_URL = "https://api.open-meteo.com/v1/forecast"
# Parâmetros para a chamada da API, incluindo a latitude, longitude e o fuso horário
params = {
'latitude': latitude,
'longitude': longitude,
'current_weather': True,
'timezone': 'America/Sao_Paulo'
}
response = requests.get(BASE_URL, params=params)
# Se a resposta for bem-sucedida (código 200), extraímos os dados necessários
if response.status_code == 200:
dados = response.json()
temperatura = dados['current_weather']['temperature']
condicao = dados['current_weather']['weathercode']
return {
"temperatura": temperatura,
"condicao": condicao
}
else:
# Caso haja algum erro, retornamos uma mensagem de erro
return {"erro": "Erro ao obter a previsão do tempo."}
Passo 2: Configurando a Chamada de Funções no Modelo
Agora, criamos a estrutura para registrar a função consultar_previsao_tempo como uma função que pode ser chamada automaticamente pelo assistente com base nas necessidades da conversa. Essa função será exposta à API de conversação.
functions = [
{
"name": "consultar_previsao_tempo",
"description": "Obtém a previsão do tempo para uma localização com base em coordenadas.",
"parameters": {
"type": "object",
"properties": {
"latitude": {
"type": "number",
"description": "Latitude da cidade."
},
"longitude": {
"type": "number",
"description": "Longitude da cidade."
}
},
"required": ["latitude", "longitude"]
}
}
]
Aqui, registramos a função consultar_previsao_tempo, especificando os parâmetros que ela espera (latitude e longitude), para que o assistente possa utilizá-la. O modelo saberá chamar essa função quando perceber que a pergunta do usuário está relacionada ao clima.
Passo 3: Interagindo com o Assistente e Chamando a Função
Agora, configuramos o cliente para interagir com o usuário e determinar quando a função de previsão do tempo deve ser chamada. O assistente será configurado para entender a conversa e identificar quando deve buscar dados da previsão do tempo.
import openai
import os
client = openai.OpenAI(
api_key=os.environ.get("MARITACA_API_KEY"), # Insira sua chave de API aqui
base_url="https://chat.maritaca.ai/api",
)
response = client.chat.completions.create(
model="sabia-3",
messages=[
{"role": "system", "content": "Você é um assistente que fornece previsão do tempo."},
{"role": "user", "content": "Qual é a previsão do tempo para o Rio de Janeiro?"}
],
tools=functions, # Aqui registramos as funções que o assistente pode chamar
)
Passo 4: Extraindo e Utilizando os Argumentos da Função
Após a interação com o assistente, ele pode determinar que a função consultar_previsao_tempo deve ser chamada. A resposta do assistente incluirá os argumentos necessários (como a latitude e longitude) para fazer a consulta.
No código abaixo, mostramos como extrair os argumentos, transformar o formato (se necessário) e fazer a consulta da previsão do tempo:
import json
function_call = response.choices[0].message.tool_calls[0].function.arguments
function_call_json = json.loads(function_call)
# Extraímos latitude e longitude dos argumentos retornados
latitude = function_call_json['latitude']
longitude = function_call_json['longitude']
# Fazemos a chamada à API de previsão do tempo com os dados retornados
previsao = consultar_previsao_tempo(latitude, longitude)
print(previsao)
Finalmente, o resultado da previsão do tempo (temperatura e condições climáticas) é exibido.
Exemplo 2: Usuários e Respostas Personalizadas
Neste exemplo, vamos criar um assistente de conversação que interage com o usuário para fornecer os IDs de clientes com base em seus nomes. Usaremos a função get_user_id para gerar IDs fictícios para os nomes fornecidos. Em seguida, calcularemos a soma dos dois IDs e responderemos ao usuário com o resultado.
Passo 1: Definindo a Função get_user_id
A função get_user_id é responsável por retornar um ID aleatório para cada nome de usuário passado. Neste caso, simulamos a geração de IDs usando a função random.randint().
import random
# Função que retorna um ID aleatório para o nome fornecido
def get_user_id(name):
return random.randint(1, 100)
Passo 2: Configurando a Chamada de Funções no Modelo
A seguir, configuramos o assistente para registrar a função get_user_id, permitindo que ela seja chamada sempre que o assistente detectar a necessidade de obter um ID com base no nome do cliente.
tools = [
{
"type": "function",
"function": {
"name": "get_user_id",
"description": "Get the id of an user given the user name",
"parameters": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the user"
}
},
"required": ["name"],
"additionalProperties": False
}
}
}
]