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

Code Interpreter: Executar Código na API

Aula 10 de 20 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Code Interpreter: Executar Código na API
  2. Ativar o Code Interpreter
  3. Inspecionar o Código Executado
  4. Fornecer Ficheiros como Entrada
  5. Recuperar Ficheiros Gerados
  6. Contentor e Ambiente
  7. Encadear Múltiplas Execuções
  8. Combinar com Outras Ferramentas
  9. Padrão: Pipeline de Análise Completa
  10. Pontos-chave

Atualizado em 2 de novembro de 2026 com base no guia oficial do Code Interpreter e no SDK openai: a ferramenta requer um parâmetro container (omisso em todos os exemplos anteriores, o que teria causado falhas), os ficheiros gerados aparecem nas anotações container_file_citation e são transferidos através da API de Contentores (não via client.files.content), e os resultados das chamadas denominam-se outputs (não results). As partes de texto de entrada utilizam o tipo input_text. Os ficheiros anexados a uma mensagem são carregados com o propósito user_data, que a OpenAI recomenda para entradas do modelo (File inputs). Fontes: Code Interpreter · File inputs.

Code Interpreter: Executar Código na API

Um modelo de linguagem prevê texto; não calcula. Peça-lhe a raiz quadrada de 1764 e ele produzirá o resultado mais provável com base no seu treino — muitas vezes correto, por vezes errado, sem forma de distinguir a diferença. O Code Interpreter elimina esta incerteza ao fornecer ao modelo um interpretador Python: ele escreve o cálculo, executa-o e devolve um resultado obtido, não um palpite.

A mudança é mais profunda do que parece. O modelo vê o resultado do seu próprio código, incluindo erros, pelo que pode autocorrigir-se e tentar novamente. Num ficheiro de dados cuja estrutura exata ninguém conhece, este ciclo supera qualquer instrução pré-escrita.

Ativar o Code Interpreter

Ativa-o adicionando a ferramenta ao array tools — nada para instalar, nenhum ambiente para aprovisionar. O modelo decide quando escrever código: responde diretamente a perguntas factuais, mas muda para a execução em caso de cálculos ou manipulação de dados.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Calculate the Fibonacci sequence up to the 20th term",
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)

print(response.output_text)

O modelo escreve o código Python, executa-o numa sandbox e integra os resultados na sua resposta.

Inspecionar o Código Executado

Adquira o hábito de ler este código, pelo menos durante o desenvolvimento. É a única forma de distinguir um bom resultado de um que esteja certo por acaso: uma média calculada ignorando silenciosamente valores em falta é numericamente correta, mas analiticamente falsa. A resposta não lho dirá; o código sim.

A resposta contém o código gerado e os seus resultados:

response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is the square root of 1764? Verify by squaring the result.",
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
    include=["code_interpreter_call.outputs"],  # to receive produced logs and images
)

for item in response.output:
    if item.type == "code_interpreter_call":
        print("--- Executed Code ---")
        print(item.code)
        print("--- Outputs ---")
        for output in item.outputs or []:
            print(output.logs if output.type == "logs" else output.url)

Fornecer Ficheiros como Entrada

A ferramenta entrega todo o seu valor quando trabalha com ficheiros. Carrega o ficheiro, referencia-o na chamada e o modelo abre-o efetivamente — lê as colunas reais, os tipos reais e os valores atípicos reais, em vez de raciocinar sobre uma descrição que possa ter fornecido.

# Upload the file
with open("sales_2025.csv", "rb") as f:
    file_obj = client.files.create(file=f, purpose="user_data")

# Use Code Interpreter with the file
response = client.responses.create(
    model="gpt-5.6-terra",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Analyze this sales file. "
                 "Give me the total by category and the best-performing month."},
                {"type": "input_file", "file_id": file_obj.id}
            ]
        }
    ],
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)

print(response.output_text)

Recuperar Ficheiros Gerados

O caminho inverso também funciona: o código produz um CSV limpo, um gráfico ou um livro Excel, e esses ficheiros são-lhe devolvidos. Permanecem no contentor, e a mensagem de resposta cita-os nas suas anotações do tipo container_file_citation, incluindo o ID do contentor, o ID do ficheiro e o nome do ficheiro. De seguida, transfere-os através da API de Contentores. Duas pequenas funções, reutilizadas em lições posteriores, encapsulam este fluxo:

def generated_files(response):
    """Files created by Code Interpreter, cited in message annotations."""
    for item in response.output:
        if item.type == "message":
            for part in item.content:
                for ann in getattr(part, "annotations", None) or []:
                    if ann.type == "container_file_citation":
                        yield ann


def download(client, ann, path):
    """Downloads a file from the container and returns its local path."""
    content = client.containers.files.content.retrieve(ann.file_id, container_id=ann.container_id)
    with open(path, "wb") as out:
        out.write(content.read())
    return path

Os ficheiros que fornece como entrada (input_file) são copiados automaticamente para o contentor: não precisa de carregar mais nada.

response = client.responses.create(
    model="gpt-5.6-terra",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Create a chart of sales by month "
                 "and export the cleaned data as a CSV."},
                {"type": "input_file", "file_id": file_obj.id}
            ]
        }
    ],
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)

# Retrieve generated files
for ann in generated_files(response):
    print(f"Generated file: {ann.filename}")
    download(client, ann, ann.filename)

Contentor e Ambiente

Conhecer as regras do contentor poupa tempo na depuração do que não pode funcionar. De acordo com a documentação da OpenAI:

  • é uma máquina virtual totalmente isolada (sandbox) onde o modelo executa Python;
  • a ferramenta requer um parâmetro container: {"type": "auto"} cria um contentor (ou reutiliza um de uma chamada anterior presente no contexto), enquanto um ID obtido via client.containers.create(...) força um contentor específico;
  • a memória é definida com memory_limit: 1g (padrão), 4g, 16g ou 64g, sendo os níveis superiores faturados às taxas de ferramentas integradas;
  • um contentor expira após 20 minutos de inatividade; os seus dados são então perdidos, por isso transfira quaisquer ficheiros que queira manter enquanto estiver ativo.

Não conte com acesso à rede a partir do código: forneça dados como entrada ou delegue a pesquisa na ferramenta Web Search.

# Example: the model can use pandas directly
response = client.responses.create(
    model="gpt-5.6-terra",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Load this CSV with pandas, "
                 "calculate descriptive statistics, and identify outliers."},
                {"type": "input_file", "file_id": file_obj.id}
            ]
        }
    ],
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)

Encadear Múltiplas Execuções

Execuções sucessivas partilham a mesma sessão: variáveis, DataFrames e importações do primeiro bloco permanecem disponíveis no seguinte, exatamente como num notebook. O modelo aproveita isto naturalmente — carrega, inspeciona e depois processa — tornando possível a análise em várias etapas sem recarregar tudo em cada fase.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="1. Generate 1000 random points from a normal distribution. "
          "2. Calculate the mean and standard deviation. "
          "3. Create a histogram. "
          "4. Perform a Shapiro-Wilk normality test.",
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)

# The model executes 4 code blocks sequentially
# Each block has access to variables from previous ones

Combinar com Outras Ferramentas

A combinação mais útil associa uma fonte de dados à capacidade de a processar: o File Search encontra a passagem relevante nos seus documentos, o Web Search traz dados de mercado e o Code Interpreter compara os dois numa tabela ou gráfico. Nenhuma destas ferramentas pode fazer o trabalho das outras.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Search the web for French GDP data from the last 10 years, "
          "then create a trend chart with a linear regression.",
    tools=[
        {"type": "web_search"},
        {"type": "code_interpreter", "container": {"type": "auto"}}
    ]
)

Padrão: Pipeline de Análise Completa

O exemplo final encadeia tudo o que foi referido acima num caso realista: um ficheiro de entrada, análise em várias etapas e produtos finais. Foque-se especialmente no formato do prompt — numerado, explícito sobre o resultado esperado — porque isso, muito mais do que o código Python que o acompanha, determina a qualidade do resultado.

def analyze_data(file_path: str, questions: list[str]) -> dict:
    """Data analysis pipeline with Code Interpreter."""
    # Upload
    with open(file_path, "rb") as f:
        file_obj = client.files.create(file=f, purpose="user_data")

    results = {}

    for question in questions:
        response = client.responses.create(
            model="gpt-5.6-terra",
            input=[
                {
                    "role": "user",
                    "content": [
                        {"type": "input_text", "text": question},
                        {"type": "input_file", "file_id": file_obj.id}
                    ]
                }
            ],
            tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
            instructions="Write clean, commented Python code. "
                        "Display intermediate results."
        )

        results[question] = response.output_text

    return results

# Usage
results = analyze_data("sales.csv", [
    "Give descriptive statistics for each numeric column",
    "What are the top 5 best-selling products?",
    "Is there seasonality in sales?"
])

Pontos-chave

  • O Code Interpreter executa Python num contentor isolado; o parâmetro container é obrigatório ({"type": "auto"} ou um ID)
  • Os ficheiros fornecidos como input_file são copiados automaticamente para o contentor
  • Os ficheiros gerados são citados como container_file_citation e transferidos via client.containers.files.content.retrieve
  • Um contentor expira após 20 minutos de inatividade: transfira o que quiser manter
  • Combine com Web Search e File Search para uma análise enriquecida