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

Saídas Estruturadas e Execução de Código

Aula 9 de 12 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Executar Código e Estruturar Resultados
  2. Funcionalidade do Grok 4 e Versões Posteriores
  3. Caso de Uso Típico: Cálculos Precisos
  4. Exemplo: Análise Estatística
  5. Combinar Pesquisa na Web e Execução de Código
  6. Limites da Execução de Código
  7. Pontos-chave

Atualizado a 2 de novembro de 2026. Com base na documentação da xAI: com o xai-sdk, as saídas estruturadas combinam-se com ferramentas criando a conversa (client.chat.create(..., tools=[code_execution()])) e, em seguida, chamando chat.parse(Schema), que devolve a resposta e o objeto tipado; o exemplo anterior chamava client.chat.parse(...) com argumentos de Chat Completions, um método que não existe em nenhum SDK. Fontes: Structured Outputs · Code Execution.

Executar Código e Estruturar Resultados

Combinar saídas estruturadas com execução de código permite ao modelo calcular resultados e devolvê-los num formato estruturado. O modelo escreve código, executa-o num ambiente isolado (sandbox) e formata a saída de acordo com o seu esquema.

Funcionalidade do Grok 4 e Versões Posteriores

Tal como a pesquisa na web, esta combinação está reservada aos modelos Grok 4 e posteriores — ou seja, toda a gama atual (Grok 4.5, Grok 4.3, variantes grok-4.20). Os modelos anteriores não suportavam a combinação de ferramentas com saídas estruturadas.

Caso de Uso Típico: Cálculos Precisos

A principal vantagem da execução de código com saídas estruturadas é a precisão de cálculo. Os LLM cometem regularmente erros aritméticos. Ao executar código, os resultados são matematicamente exatos.

from pydantic import BaseModel
from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import code_execution

client = Client()  # chave lida de XAI_API_KEY

class FinancialAnalysis(BaseModel):
    total_revenue: float
    total_cost: float
    gross_margin: float
    margin_percentage: float
    most_profitable_product: str
    least_profitable_product: str

chat = client.chat.create(
    model="grok-4.20-0309-reasoning",
    tools=[code_execution()],
)
chat.append(user("""Aqui estão as vendas trimestrais:
- Produto A: 150 unidades a 45 €, custo unitário 28 €
- Produto B: 320 unidades a 22 €, custo unitário 15 €
- Produto C: 85 unidades a 120 €, custo unitário 78 €

Calcule a análise financeira completa."""))

response, parsed = chat.parse(FinancialAnalysis)

print(f"Margem bruta: {parsed.gross_margin} €")
print(f"Margem: {parsed.margin_percentage}%")
print(f"Melhor produto: {parsed.most_profitable_product}")

O modelo escreverá um script Python para realizar os cálculos, executá-lo e, em seguida, formatar os resultados no esquema FinancialAnalysis.

Exemplo: Análise Estatística

class DescriptiveStatistics(BaseModel):
    mean: float
    median: float
    std_dev: float
    minimum: float
    maximum: float
    quartile_1: float
    quartile_3: float
    value_count: int

chat = client.chat.create(
    model="grok-4.20-0309-reasoning",
    tools=[code_execution()],
)
chat.append(user("""Calcule as estatísticas descritivas para estes dados:
[23, 45, 12, 67, 34, 89, 56, 78, 41, 33, 61, 25,
 72, 48, 55, 39, 64, 71, 28, 50]"""))

response, parsed = chat.parse(DescriptiveStatistics)

print(f"Média: {parsed.mean}")
print(f"Desvio padrão: {parsed.std_dev}")

Combinar Pesquisa na Web e Execução de Código

Pode ativar ambas as ferramentas simultaneamente:

class MarketAnalysis(BaseModel):
    company: str
    current_price: float
    change_30d: float
    avg_volume: float
    trend: str
    recommendation: str

from xai_sdk.tools import web_search

chat = client.chat.create(
    model="grok-4.20-0309-reasoning",
    tools=[web_search(), code_execution()],
)
chat.append(user("Analise as ações da Apple nos últimos 30 dias"))

response, parsed = chat.parse(MarketAnalysis)

O modelo irá buscar dados recentes na web e, em seguida, utilizar a execução de código para calcular variações e médias.

Limites da Execução de Código

  • O ambiente de execução é isolado e efémero
  • Pacotes Python comuns vêm pré-instalados (NumPy, Pandas, Matplotlib, SciPy)
  • O tempo de execução e a memória são limitados
  • Sem acesso à rede a partir do código executado
  • Os ficheiros criados não persistem entre chamadas

Pontos-chave

  • A execução de código + saídas estruturadas requer no mínimo o Grok 4 — toda a gama atual é compatível
  • O modelo escreve e executa código para cálculos precisos
  • Ative a ferramenta com code_execution() no xAI SDK, ou {"type": "code_interpreter"} na API de Respostas, e obtenha o objeto tipado com chat.parse(Schema)
  • Combinável com web_search para pesquisar e depois calcular
  • Ideal para análise financeira, estatística e matemática
  • Os resultados calculados são exatos, ao contrário das estimativas dos LLM