Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Definir Funções em Python

Aula 4 de 14 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Da Teoria ao Código
  2. Instalar o SDK da Mistral
  3. Criar Funções Python
  4. Escrever Especificações JSON
  5. Organizar Funções num Dicionário
  6. A Opção tool_choice
  7. Pontos-chave

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_choice controla 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)