Definir Funções em Python
Nesta página
Da Teoria ao Código
Agora que compreende o processo de cinco passos e a estrutura do JSON Schema, é altura de escrever código Python real. Nesta lição, vai criar funções, redigir as suas especificações e preparar tudo para a API da Mistral — tudo o que precisa de existir antes de efetuar a primeira chamada de rede.
Instalar o SDK da Mistral
Comece por instalar o pacote oficial:
pip install mistralai
De seguida, configure a sua chave de API. As boas práticas ditam que nunca deve codificá-la diretamente nos seus ficheiros de origem. Em vez disso, leia-a a partir de uma variável de ambiente, para que possa fazer commit do seu código para o controlo de versões em segurança.
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Criar Funções Python
Vejamos um exemplo prático: um sistema de rastreio de pagamentos suportado por um DataFrame do Pandas. Este é um exemplo clássico da documentação da Mistral e ilustra perfeitamente o conceito — aqui, o DataFrame desempenha o papel que uma base de dados teria em produção.
import pandas as pd
import json
# Payment data
data = {
"transaction_id": ["T1001", "T1002", "T1003", "T1004", "T1005"],
"customer_id": ["C001", "C002", "C003", "C002", "C001"],
"payment_amount": [125.50, 89.99, 350.00, 45.00, 210.75],
"payment_date": ["2026-03-15", "2026-03-16", "2026-03-17", "2026-03-17", "2026-03-18"],
"payment_status": ["paid", "paid", "pending", "paid", "failed"]
}
df = pd.DataFrame(data)
Segue-se o código que acede efetivamente a estes dados. Estas são funções Python padrão; nada na sua implementação sugere que um LLM as vai acionar.
def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
"""Retrieves the status of a payment by its ID."""
if transaction_id in df["transaction_id"].values:
status = df[df["transaction_id"] == transaction_id]["payment_status"].values[0]
return json.dumps({"status": status})
return json.dumps({"error": f"Transaction {transaction_id} not found"})
def retrieve_payment_date(df: pd.DataFrame, transaction_id: str) -> str:
"""Retrieves the date of a payment by its ID."""
if transaction_id in df["transaction_id"].values:
date = df[df["transaction_id"] == transaction_id]["payment_date"].values[0]
return json.dumps({"date": date})
return json.dumps({"error": f"Transaction {transaction_id} not found"})
Dois detalhes de implementação merecem a sua atenção. Primeiro, estas funções devolvem sempre uma cadeia JSON, nunca um objeto Python bruto. Este é o formato que o modelo espera como resultado de uma ferramenta, pelo que json.dumps() é obrigatório. Segundo, tratam explicitamente o caso em que uma transação não é encontrada, em vez de lançarem uma exceção. Este erro, formatado como JSON, retorna ao modelo tal como qualquer outro resultado, permitindo-lhe informar educadamente o utilizador de que a transação T9999 não existe. Verá mais adiante no curso porque é que este reflexo é essencial.
Escrever Especificações JSON
Cada função necessita de uma especificação para que o modelo a possa compreender. Aqui, aplica a estrutura da lição anterior às duas funções acima — note a correspondência estrita entre os campos name e os nomes reais das funções Python.
tools = [
{
"type": "function",
"function": {
"name": "retrieve_payment_status",
"description": "Retrieves the status of a payment (paid, pending, failed) "
"based on the transaction ID.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Unique transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
},
{
"type": "function",
"function": {
"name": "retrieve_payment_date",
"description": "Retrieves the date a payment was made "
"based on the transaction ID.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Unique transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
}
]
Organizar Funções num Dicionário
O modelo devolve um nome de função como uma cadeia de caracteres. Precisa de uma forma de mapear essa cadeia para o objeto executável correspondente, sem recorrer a eval ou a uma cascata de instruções if. Um dicionário de despacho resolve este problema em três linhas.
from functools import partial
# Bind the DataFrame to each function
available_functions = {
"retrieve_payment_status": partial(retrieve_payment_status, df),
"retrieve_payment_date": partial(retrieve_payment_date, df),
}
O functools.partial resolve uma dificuldade específica e real. As suas funções esperam dois argumentos — o DataFrame e o ID —, mas o modelo fornece apenas um. O modelo não sabe nada sobre df, nem deve saber. O partial preenche esse primeiro parâmetro de uma vez por todas. Este mesmo mecanismo aplica-se a ligações a bases de dados, clientes HTTP ou tokens de autenticação. A invocação dinâmica torna-se então trivial.
function_name = "retrieve_payment_status"
function_params = {"transaction_id": "T1001"}
result = available_functions[function_name](**function_params)
# → '{"status": "paid"}'
A Opção tool_choice
Ao enviar estas ferramentas para a API, o parâmetro tool_choice decide quanta liberdade concede ao modelo. São possíveis três valores.
# The model decides whether to use a tool or respond directly (default)
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="auto"
)
# Force the model to use a tool
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="any"
)
# Prevent the model from using tools
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="none"
)
O modo "auto" é o mais comum em produção, e por boas razões: um assistente de rastreio de pagamentos deve poder dizer “olá” sem desencadear uma consulta à base de dados. O modelo responde diretamente a perguntas gerais e utiliza funções apenas quando relevante. Uma lição completa mais adiante no curso aborda casos de uso específicos para any e none.
Pontos-chave
- As funções devem devolver cadeias JSON — nunca objetos Python brutos
- Utilize um dicionário de despacho para mapear nomes de funções para as suas implementações
- O
functools.partialé ideal para pré-preencher parâmetros como ligações a bases de dados ou DataFrames - O
tool_choicecontrola se o modelo pode ou deve utilizar funções (auto,any,none) - Trate sempre os casos de erro nas suas funções (parâmetros inválidos, dados em falta)