API de respostas da OpenAI: O guia definitivo para desenvolvedores

O que é a API de respostas da OpenAI?

A API de respostas é a API mais nova e mais avançada da OpenAI. Ele combina os pontos fortes das APIs Chat Completions e Assistants em uma única interface simplificada. Lançado em março de 2025, ele mantém os recursos conhecidos e oferece uma abordagem mais integrada para a criação de aplicativos de IA. 

A principal inovação é a forma como ele simplifica o desenvolvimento, manipulando automaticamente a lógica de orquestração e integrando nativamente as ferramentas internas da OpenAI para pesquisa na Web e pesquisa de arquivos, sem a necessidade de implementação personalizada.

Neste tutorial, mostraremos como usar a API de respostas em seus projetos. Você verá como ele lida com a geração de texto, trabalha com imagens e fornece respostas de fluxo contínuo. Examinaremos as ferramentas integradas que tornam o desenvolvimento mais rápido e direto do que antes, mostrando a você como essas ferramentas funcionam juntas dentro da estrutura da API. 

Ao final deste guia, você entenderá quando usar a API Responses em vez de outras opções do OpenAI e como esse conhecimento pode ajudá-lo a criar aplicativos mais eficientes com menos código e esforço. Se você não conhece a API OpenAI, confira nosso curso introdutório, Trabalhando com a API OpenAIpara você começar sua jornada de desenvolvimento de aplicativos com tecnologia de IA.

Primeiros passos com a API de respostas

A API de respostas oferece uma interface mais simplificada e fácil de usar para interagir com os modelos da OpenAI, combinando o que antes exigia uma sintaxe complexa e detalhada em uma solução elegante. 

Antes de nos aprofundarmos em casos de uso específicos, vamos configurar nosso ambiente e entender a sintaxe básica.

from openai import OpenAI
import os
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

# Initialize the client
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

Essa etapa de inicialização cria um objeto cliente que tratará de todas as solicitações de API que você fizer. O pacote dotenv ajuda a gerenciar a chave da API com segurança por meio de variáveis de ambiente, em vez de codificá-la no script - uma prática recomendada que torna o código mais portátil e seguro em diferentes ambientes.

Geração de conteúdo com a API de respostas

O uso mais simples da API de respostas é a geração de conteúdo de texto. Vamos explorar um cenário do mundo real: suponha que você esteja criando uma plataforma de comércio eletrônico e precise gerar automaticamente descrições de produtos atraentes com base nos detalhes básicos do produto.

Tradicionalmente, isso exigiria uma engenharia cuidadosa e várias iterações. Com a API de respostas, você pode criar uma função simples que lida com isso de forma elegante:

def generate_product_description(product_name, features, target_audience):
   response = client.responses.create(
       model="gpt-4o",
       instructions="You are a professional copywriter specialized in creating concise, compelling product descriptions. Focus on benefits rather than just features.",
       input=f"""
       Create a product description for {product_name}.
       Key features:
       - {features[0]}
       - {features[1]}
       - {features[2]}
       Target audience: {target_audience}
       Keep it under 150 words.
       """,
       temperature=0.7,
       max_output_tokens=200
   )
  
   return response.output_text

# Example usage
headphones_desc = generate_product_description(
   "NoiseGuard Pro Headphones",
   ["Active noise cancellation", "40-hour battery life", "Memory foam ear cushions"],
   "Business travelers and remote workers"
)

print(headphones_desc)

Saída:

Experience unparalleled focus and comfort with NoiseGuard Pro Headphones—your perfect travel and work companion. 
Designed for business travelers and remote workers, these headphones feature cutting-edge active noise cancellation to block out distractions, allowing you to concentrate on what truly matters. 
With an impressive 40-hour battery life, you can enjoy uninterrupted productivity or relaxation on even the longest journeys. 
The luxurious memory foam ear cushions ensure a snug, comfortable fit for all-day wear, reducing fatigue and enhancing your listening experience. 
Elevate your work and travel with NoiseGuard Pro—where clarity meets comfort.

Com apenas algumas linhas de código, criamos um texto com qualidade de marketing que normalmente exigiria um redator profissional. A função também é reutilizável - basta alterar os parâmetros e você poderá gerar descrições para qualquer produto em seu catálogo.

Este exemplo demonstra os principais padrões ao usar a API de respostas:

1. O parâmetro instructions atua como um prompt do sistema, definindo o comportamento e o contexto da IA.
2. O parâmetro temperature (0-2) controla a aleatoriedade - valores mais baixos produzem resultados mais determinísticos, enquanto valores mais altos introduzem mais criatividade.
3. O parâmetro max_output_tokens limita o comprimento da resposta, o que ajuda a controlar os custos e a garantir resultados concisos.
4. O objeto de resposta contém o texto gerado na propriedade output_text.

Análise de imagens para aplicações práticas

Muitos aplicativos do mundo real precisam processar texto e imagens. Por exemplo, as plataformas de comércio eletrônico precisam analisar as fotos dos produtos, os sistemas de moderação de conteúdo precisam revisar os envios e os aplicativos de mídia social precisam entender o conteúdo visual.

A API de respostas é excelente em tarefas multimodais, como análise de imagens, sem exigir pontos de extremidade separados ou código de integração complexo:

def analyze_product_image(image_url):
   response = client.responses.create(
       model="gpt-4o",
       instructions="You are a product photography expert and e-commerce consultant.",
       input=[
           {"role": "user", "content": "Analyze this product image and provide the following details:\n1. Product category\n2. Key visible features\n3. Potential quality issues\n4. Suggested improvements for the product photography"},
           {
               "role": "user",
               "content": [
                   {
                       "type": "input_image",
                       "image_url": image_url
                   }
               ],
           },
       ],
       temperature=0.2
   )
  
   return response.output_text

# Example with a sports team image
analysis = analyze_product_image("https://upload.wikimedia.org/wikipedia/commons/a/a5/Barcelona_fc_lamina_elgrafico.jpg")
print(analysis)

Saída:

1. **Product Category**: Sports team memorabilia or vintage sports photography.

2. **Key Visible Features**:
  - The image features a group of individuals in sports uniforms, likely a football (soccer) team.
  - The uniforms have distinct vertical stripes in red and blue.
  - A football is visible in the foreground.
  - The setting appears to be an outdoor field, possibly a stadium.

...

Essa função poderia ser integrada a uma plataforma de comércio eletrônico para analisar automaticamente as fotos dos produtos quando os comerciantes as carregam. O sistema poderia fornecer feedback imediato sobre a qualidade da imagem e sugerir melhorias, levando a melhores taxas de conversão por meio de listagens de maior qualidade - tudo sem revisão manual.

Ao trabalhar com imagens, você deve passar uma matriz de objetos de mensagem para o parâmetro de entrada em vez de uma cadeia de caracteres, cada um com uma função e valores de conteúdo.

 O conteúdo da imagem é especificado como um objeto com type: input_image e um image_url. Você pode combinar texto e imagens na mesma solicitação, permitindo interações multimodais avançadas.

Implementação de streaming para aplicativos responsivos

Os usuários esperam um feedback instantâneo. Esperar vários segundos por uma resposta de IA pode acabar com o envolvimento. Por isso, o streaming é essencial para criar experiências de usuário responsivas, especialmente em aplicativos de bate-papo ou em tempo real.

Imagine que você está criando uma ferramenta de análise de feedback do cliente para uma equipe de produtos. Em vez de fazê-los esperar pela análise completa, você pode transmitir os resultados à medida que eles são gerados:

def analyze_customer_feedback(feedback_text):
   print("Analyzing customer feedback in real-time:")
  
   stream = client.responses.create(
       model="gpt-4o",
       instructions="Extract key sentiments, product issues, and actionable insights from this feedback.",
       input=feedback_text,
       stream=True,
       temperature=0.3,
       max_output_tokens=500
   )
  
   full_response = ""
   print("\nAnalysis results:")
   for event in stream:
       if event.type == "response.output_text.delta":
           print(event.delta, end="")
           full_response += event.delta
       elif event.type == "response.error":
           print(f"\nError occurred: {event.error}")
  
   return full_response

# Example with a complex customer review
feedback = """
I've been using the SmartHome Hub for about 3 months now. The voice recognition is fantastic
and the integration with my existing devices was mostly seamless. However, the app crashes
at least once a day, and the night mode feature often gets stuck until I restart the system.
Customer support was helpful but couldn't fully resolve the app stability issues.
"""

analysis_result = analyze_customer_feedback(feedback)

Em um aplicativo real, você substituiria as declarações do print por atualizações da interface do usuário, permitindo que seus usuários vejam a análise se formando em tempo real - da mesma forma que os aplicativos de bate-papo modernos mostram a IA "pensando" à medida que gera uma resposta. Isso cria uma experiência mais envolvente e dá aos usuários um feedback imediato de que sua solicitação está sendo processada.

A implementação de streaming funciona da seguinte forma:

1. Definindo stream=True no método de criação
2. Processar a resposta como um iterável de eventos com tipos específicos
3. Tratamento de diferentes tipos de eventos separadamente: response.output_text.delta para blocos de conteúdo, response.error para erros

Agora que abordamos a funcionalidade básica da API de respostas, vamos explorar as ferramentas integradas que aprimoram ainda mais seus recursos.

Ferramentas integradas da API de respostas da OpenAI

A API de respostas integra algumas ferramentas internas que estendem seus recursos além da geração básica de texto. Essas ferramentas permitem que os desenvolvedores criem aplicativos mais avançados sem a necessidade de códigos de integração complexos ou várias chamadas de API.

Pesquisa na Web: acesso a informações em tempo real

A ferramenta de pesquisa na Web permite que a API de respostas recupere informações atuais da Internet, abordando a limitação de LLMs restritos aos seus dados de treinamento.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
   model="gpt-4o",
   tools=[{"type": "web_search_preview"}],
   input="What are some news related to the stock market?",
)

print(response.output_text)

Saída:

Recent developments in the stock market have been significantly influenced by escalating trade tensions between the United States and China. On April 5, 2025, President Donald Trump announced an additional 34% tariff on Chinese goods, raising total tariffs to 54% this year. In response, China imposed reciprocal 34% tariffs on U.S. products and introduced export restrictions on certain rare earth elements. These actions led to a sharp global market selloff, with the S&P 500 falling 9% for the week, marking the steepest decline since the pandemic. (reuters.com)

…..


## Escalating US-China Trade Tensions Impact Global Markets:
- [China says 'market has spoken' after US tariffs spark selloff](https://www.reuters.com/world/china/china-says-market-has-spoken-after-us-tariffs-spark-selloff-2025-04-05/?utm_source=openai)
- [Trump touts "economic revolution" as economists warn of recession](https://www.axios.com/2025/04/05/trump-tariffs-stock-market-recession?utm_source=openai)
- [Believe it or not, there were some winners in the stock market this week](https://apnews.com/article/ce81e9ae6fb463dc763dfaa464778343?utm_source=openai)

A ferramenta de pesquisa na Web executa várias operações quando ativada, desde a análise da consulta até a síntese de informações de várias fontes com as devidas citações. Esse recurso abre possibilidades para aplicativos ricos em informações, como ferramentas de análise financeira que fornecem percepções de mercado, plataformas de agregação de notícias que combinam várias fontes ou recursos educacionais que complementam o conteúdo principal com pesquisas atuais.

Um dos principais benefícios dessa ferramenta é a capacidade de fornecer informações oportunas sem a necessidade de criar e manter uma integração de pesquisa personalizada ou um sistema de raspagem da Web. A ferramenta lida com o processo de pesquisa e apresenta os resultados com as devidas citações para manter a transparência sobre as fontes de informação.

Pesquisa de arquivos: extração de informações de documentos

Enquanto a pesquisa na Web traz conhecimento externo para o seu aplicativo, a ferramenta de pesquisa de arquivos se concentra em desbloquear informações de documentos. Essa ferramenta permite que a API pesquise e extraia informações de documentos que foram carregados no OpenAI.

A ferramenta de pesquisa de arquivos permite vários recursos importantes:

• Pesquisa em vários tipos de arquivos (PDFs, documentos do Word, apresentações, etc.).
• Encontrar informações específicas em documentos com base em consultas de linguagem natural.
• Extração e síntese de informações de vários documentos simultaneamente.
• Fornecer citações de seções específicas dos documentos de origem.
• Suporte a consultas complexas que fazem referência a informações em vários arquivos.

Esse recurso é adequado para casos de uso de análise de documentos, como extração de informações de contratos legais, análise de documentos de pesquisa ou criação de bases de conhecimento a partir de documentação técnica. A ferramenta pode identificar seções relevantes em vários documentos e sintetizar informações em resposta a consultas específicas.

A implementação requer primeiro o upload de arquivos para o ponto de extremidade de arquivos da OpenAI e, em seguida, a passagem dos IDs de arquivo para a API de respostas ao fazer uma consulta. Isso cria um fluxo de trabalho simplificado para aplicativos que precisam fazer referência a informações específicas em documentos sem exigir que os usuários pesquisem manualmente.

Uso do computador: recursos de interação da interface

Com base na compreensão de textos e documentos, a ferramenta de uso do computador amplia os recursos de IA para o domínio da interação da interface. Essa ferramenta representa um avanço significativo que preenche a lacuna entre a compreensão da linguagem e a manipulação da interface do usuário.

A ferramenta de uso do computador pode realizar uma variedade de interações de interface:

• Navegue em sites e aplicativos da Web de forma autônoma.
• Preencha os formulários com as informações apropriadas.
• Extraia dados de páginas da Web e aplicativos.
• Execute processos de várias etapas em diferentes telas.
• Interaja com elementos como botões, menus suspensos e campos de texto.
• Compreender o contexto e a finalidade dos diferentes elementos da interface.

As possíveis aplicações incluem automação de processos para tarefas repetitivas, assistência guiada para fluxos de trabalho complexos e melhorias de acessibilidade para usuários que têm dificuldade com interfaces tradicionais. A ferramenta pode ser usada para automatizar o preenchimento de formulários, navegar em sites complexos ou realizar testes de interfaces de usuário.

A tecnologia funciona permitindo que a IA veja e interaja com os elementos da tela, compreenda o contexto e execute ações com base em instruções de linguagem natural. Isso cria possibilidades de automação e assistência que, de outra forma, exigiriam o desenvolvimento especializado de código específico da interface.

Recursos adicionais da ferramenta

O ecossistema de ferramentas da API de respostas continua a crescer, com a OpenAI adicionando regularmente novos recursos. A documentação abrangente sobre ferramentas abrange detalhes de implementação de todas as ferramentas atualmente disponíveis, enquanto o artigo sobre novas ferramentas para agentes de construção fornece um contexto estratégico sobre como essas ferramentas estão evoluindo.

Essas ferramentas integradas oferecem recursos avançados prontos para uso, mas muitos aplicativos exigem conexão com serviços especializados ou sistemas proprietários. É aqui que a chamada de função se torna essencial, permitindo que você estenda a API de respostas com suas próprias ferramentas personalizadas e serviços externos - o foco da nossa próxima seção.

Chamada de função na API de respostas

Embora as ferramentas integradas ofereçam recursos avançados, muitos aplicativos exigem conexão com serviços especializados ou sistemas proprietários. A chamada de função permite que você estenda a API de respostas com suas próprias ferramentas personalizadas, permitindo que o modelo determine quando e como chamar suas funções com base na entrada do usuário.

A chamada de função cria uma ponte entre a compreensão da linguagem da IA e seus sistemas externos, seja para recuperar taxas de câmbio, calcular distâncias ou verificar a disponibilidade de compromissos. Esse padrão segue um fluxo de trabalho claro:

1. Você define funções que a IA pode usar, especificando parâmetros e seus tipos.
2. A IA decide quando chamar essas funções com base nas consultas do usuário.
3. Seu código executa as funções com os parâmetros fornecidos pela IA.
4. Você retorna os resultados para a IA, que os incorpora à sua resposta.

Criando uma ferramenta de conversão de moeda

Vamos implementar uma função simples de conversão de moeda como exemplo:

# Dictionary of exchange rates (relative to USD)
exchange_rates = {
   "USD": 1.0,
   "EUR": 0.93,
   "GBP": 0.79,
   "JPY": 153.2,
   "CAD": 1.37,
   "AUD": 1.52
}

def convert_currency(amount, from_currency, to_currency):
   """Convert an amount from one currency to another."""
   # Normalize currency codes to uppercase
   from_currency = from_currency.upper()
   to_currency = to_currency.upper()
  
   # Check if currencies are supported
   if from_currency not in exchange_rates:
       return {"error": f"Currency not supported: {from_currency}"}
   if to_currency not in exchange_rates:
       return {"error": f"Currency not supported: {to_currency}"}
  
   # Convert to USD first, then to target currency
   amount_in_usd = amount / exchange_rates[from_currency]
   converted_amount = amount_in_usd * exchange_rates[to_currency]
  
   return {
       "original_amount": amount,
       "from_currency": from_currency,
       "to_currency": to_currency,
       "converted_amount": round(converted_amount, 2)
   }

Essa função recebe três parâmetros: o valor a ser convertido, a moeda de origem e a moeda de destino. Ele executa uma conversão simples usando taxas de câmbio predefinidas e retorna um resultado estruturado com os detalhes da conversão.

Definindo a função para a API de respostas

Agora, precisamos informar o modelo sobre nossa função para que ele possa decidir quando chamá-la:

from openai import OpenAI
import json

client = OpenAI()

tools = [
   {
       "type": "function",
       "name": "convert_currency",
       "description": "Convert an amount from one currency to another using current exchange rates",
       "parameters": {
           "type": "object",
           "properties": {
               "amount": {
                   "type": "number",
                   "description": "The amount of money to convert"
               },
               "from_currency": {
                   "type": "string",
                   "description": "The currency code to convert from (e.g., USD, EUR, GBP)"
               },
               "to_currency": {
                   "type": "string",
                   "description": "The currency code to convert to (e.g., USD, EUR, GBP)"
               }
           },
           "required": ["amount", "from_currency", "to_currency"],
           "additionalProperties": False
       },
       "strict": True
   }
]

Essa definição especifica claramente:

• O nome da função convert_currency que corresponde à nossa função Python.
• Uma descrição que explica quando a função deve ser usada.
• Três parâmetros necessários com seus tipos e descrições.
• O sinalizador strict: true garante que o modelo siga exatamente nossas especificações de parâmetros.

Tratamento de uma consulta do usuário

Vamos simular uma conversa em que um usuário pergunta sobre conversão de moeda:

input_messages = [
   {"role": "user", "content": "How much is 100 euros in Japanese yen?"}
]

response = client.responses.create(
   model="gpt-4o",
   input=input_messages,
   tools=tools,
)

Quando o modelo vê essa pergunta sobre conversão de moeda, ele reconhece que deve usar nossa função. Ele identifica isso automaticamente:

• O valor é 100
• A moeda de origem é o euro (EUR)
• A moeda alvo é o iene japonês (JPY)

Processamento da chamada de função

Agora, extraímos os detalhes da chamada de função e executamos nossa função:

tool_call = response.output[0]
print(f"Function called: {tool_call.name}")
print(f"Arguments: {tool_call.arguments}")

args = json.loads(tool_call.arguments)

# Execute the function with the parameters determined by the model
conversion_result = convert_currency(**args)
print(f"Function results: {conversion_result}")

O modelo traduziu a consulta de linguagem natural em parâmetros estruturados. Em seguida, nossa função realiza o cálculo com base nesses parâmetros e retorna o valor convertido.

Retorno dos resultados da função para o modelo

Por fim, enviamos os resultados de volta ao modelo para que ele possa gerar uma resposta fácil de usar:

input_messages.append(tool_call)  # append model's function call message
input_messages.append(
   {  # append result message
       "type": "function_call_output",
       "call_id": tool_call.call_id,
       "output": json.dumps(conversion_result)
   }
)

response_2 = client.responses.create(
   model="gpt-4o",
   input=input_messages,
   tools=tools,
)
print(response_2.output_text)

Saída:

100 euros is equal to 16,473.12 Japanese yen based on current exchange rates.

O modelo pegou nossos dados brutos de conversão e os transformou em uma resposta natural e legível por humanos. Ele interpretou corretamente o resultado numérico e o apresentou em um formato apropriado para moeda.

Colocando tudo junto

Em um aplicativo real, você desejará encapsular todo esse processo em uma única interface que lide com o fluxo da conversa sem problemas. Veja como você pode criar um assistente completo que gerencia todo o processo de chamada de função:

def currency_assistant(user_message, conversation_history=None):
   """A complete assistant that handles currency conversion queries."""
   if conversation_history is None:
       conversation_history = []
  
   # Add the user's new message to the conversation
   conversation_history.append({"role": "user", "content": user_message})
  
   # Define available tools (our currency conversion function)
   tools = [{
       "type": "function",
       "name": "convert_currency",
       "description": "Convert an amount from one currency to another using current exchange rates",
       "parameters": {
           "type": "object",
           "properties": {
               "amount": {
                   "type": "number",
                   "description": "The amount of money to convert"
               },
               "from_currency": {
                   "type": "string",
                   "description": "The currency code to convert from (e.g., USD, EUR, GBP)"
               },
               "to_currency": {
                   "type": "string",
                   "description": "The currency code to convert to (e.g., USD, EUR, GBP)"
               }
           },
           "required": ["amount", "from_currency", "to_currency"],
           "additionalProperties": False
       },
       "strict": True
   }]
  
   # Get initial response from the model
   response = client.responses.create(
       model="gpt-4o",
       input=conversation_history,
       tools=tools,
   )
  
   # Check if the model wants to call a function
   if response.output and isinstance(response.output, list) and response.output[0].type == "function_call":
       tool_call = response.output[0]
      
       # Process the function call
       args = json.loads(tool_call.arguments)
       result = convert_currency(**args)
      
       # Add the function call and its result to the conversation
       conversation_history.append(tool_call)
       conversation_history.append({
           "type": "function_call_output",
           "call_id": tool_call.call_id,
           "output": json.dumps(result)
       })
      
       # Get the final response with the function results incorporated
       final_response = client.responses.create(
           model="gpt-4o",
           input=conversation_history,
           tools=tools,
       )
      
       return final_response.output_text, conversation_history
   else:
       # If no function call was needed, return the direct response
       return response.output_text, conversation_history

# Example usage
response, conversation = currency_assistant("How much is 50 British pounds in Australian dollars?")
print("Assistant:", response)

# Continue the conversation
response, conversation = currency_assistant("And what if I wanted to convert 200 Canadian dollars instead?", conversation)
print("Assistant:", response)

Essa implementação:

1. Mantém o histórico da conversa para fornecer contexto para perguntas de acompanhamento.
2. Trata de todo o processo de chamada de função em uma única interface.
3. Determina quando a chamada de função é necessária e quando o modelo pode responder diretamente.
4. Oferece suporte a conversas com vários turnos em que o contexto anterior é importante.

Com essa abordagem, você pode criar experiências de conversação perfeitas, em que os usuários interagem naturalmente sem estar cientes da complexa chamada de função que ocorre nos bastidores. O assistente lida com a transição entre a compreensão da linguagem natural, as chamadas de funções estruturadas e a geração de linguagem natural.

A criação de aplicativos mais complexos pode envolver:

1. Suporte a várias funções, cada uma para diferentes tipos de consultas.
2. Gerenciando a autenticação e a autorização para operações confidenciais.
3. Implementação de tratamento e recuperação de erros mais sofisticados.
4. Adição de registro e monitoramento para uso e desempenho da função.
5. Criação de interfaces de usuário que suportam texto, voz ou interações multimodais.

A chamada de função permite que a API de respostas conecte entradas de linguagem natural com seus serviços e dados. Isso cria uma ponte entre as solicitações do usuário e os sistemas de negócios, permitindo que os usuários façam solicitações em linguagem simples, enquanto o aplicativo lida com os detalhes da implementação técnica em segundo plano.

Além da chamada de função, outro recurso avançado da API de respostas é a capacidade de gerar saídas estruturadas. Esse recurso complementa a chamada de função, fornecendo uma maneira de receber respostas em formatos específicos que se alinham às necessidades do seu aplicativo.

Saídas estruturadas com a API de respostas

Ao criar aplicativos de IA, você geralmente precisa de respostas em um formato específico para facilitar a integração com seus sistemas. A API de respostas oferece suporte a saídas estruturadas que permitem que você receba dados em um formato bem definido e consistente, em vez de texto em formato livre. Esse recurso é particularmente valioso quando você precisa:

1. Extraia informações específicas de textos não estruturados.
2. Transforme as entradas do usuário em dados estruturados.
3. Garanta formatos de resposta consistentes para o processamento downstream.
4. Integre as saídas de IA diretamente com bancos de dados ou APIs.

As saídas estruturadas reduzem a necessidade de análise e validação adicionais, tornando seus aplicativos mais robustos e fáceis de manter.

Extração de informações sobre produtos a partir de descrições

Vamos explorar um exemplo prático: imagine que você está criando uma plataforma de comércio eletrônico e precisa extrair automaticamente os detalhes do produto de descrições não estruturadas para preencher seu banco de dados.

from openai import OpenAI
import json

client = OpenAI()

product_description = """
Our Premium Laptop Backpack is perfect for professionals and students alike.
Made with water-resistant material, it features padded compartments that fit
laptops up to 15.6 inches. The backpack includes 3 main storage areas,
5 smaller pockets, and has an integrated USB charging port. Available in
navy blue, black, and gray. Current retail price: $79.99, though it's
currently on sale for $64.99 until the end of the month.
"""

response = client.responses.create(
   model="gpt-4o",
   input=f"Extract structured product information from this description: {product_description}",
   text={
       "format": {
           "type": "json_schema",
           "name": "product_details",
           "schema": {
               "type": "object",
               "properties": {
                   "product_name": {"type": "string"},
                   "category": {"type": "string"},
                   "features": {"type": "array", "items": {"type": "string"}},
                   "colors": {"type": "array", "items": {"type": "string"}},
                   "pricing": {
                       "type": "object",
                       "properties": {
                           "regular_price": {"type": "number"},
                           "sale_price": {"type": "number"},
                           "currency": {"type": "string"},
                       },
                       "additionalProperties": False,
                       "required": ["regular_price", "sale_price", "currency"],
                   },
               },
               "required": ["product_name", "features", "colors", "pricing","category"],
               "additionalProperties": False,
           },
           "strict": True,
       }
   },
)

product_data = json.loads(response.output_text)
print(json.dumps(product_data, indent=2))

Saída:

{
 "product_name": "Premium Laptop Backpack",
 "category": "Backpack",
 "features": [
   "Water-resistant material",
   "Padded compartments for laptops up to 15.6 inches",
   "3 main storage areas",
   "5 smaller pockets",
   "Integrated USB charging port"
 ],
 "colors": [
   "Navy blue",
   "Black",
   "Gray"
 ],
 "pricing": {
   "regular_price": 79.99,
   "sale_price": 64.99,
   "currency": "USD"
 }
}

Esses dados JSON formatados agora podem ser integrados diretamente ao seu banco de dados de produtos, eliminando a necessidade de lógica de análise personalizada e reduzindo a chance de erros.

Compreensão da configuração de saída estruturada

O segredo para obter resultados estruturados eficazes e sem erros é definir adequadamente o esquema. Vamos detalhar os elementos importantes da configuração:

text={
   "format": {
       "type": "json_schema",        # Specifies we're using JSON Schema
       "name": "product_details",    # A descriptive name for this schema
       "schema": {
           # Your JSON Schema definition here
           "type": "object",
           "properties": {
               # Each property with type information, e.g.
               "product_name": {"type": "string"},
               # ... other properties
           },
           "required": ["product_name", ...], # All other properties
           "additionalProperties": False
       },
       "strict": True                # Enforce schema constraints strictly
   }
}

Os componentes mais importantes são:

1. Definição do esquema: Descreve a estrutura, incluindo todas as propriedades e seus tipos.
2. Campos obrigatórios: Lista as propriedades que devem ser incluídas na resposta.
3. Propriedades adicionais: Quando definido como False, evita campos extras não definidos no esquema.
4. Modo estrito: Quando True, garante que o modelo siga o esquema com precisão.

Dicas práticas para usar saídas estruturadas

Para obter melhores resultados com saídas estruturadas, siga estas diretrizes:

1. Projete seu esquema cuidadosamente: Inclua todos os campos obrigatórios, mas mantenha o foco nas informações essenciais.
2. Use tipos de dados apropriados: Combine os tipos de esquema com a forma como você usará os dados (números para cálculos, cadeias de caracteres para texto).
3. Defina restrições claras: Use enum para campos com opções limitadas e minimum /maximum para limites numéricos.
4. Teste com entradas variadas: Certifique-se de que seu esquema lida com diferentes formatos de entrada e casos extremos.
5. Inclua descrições claras: A adição de descrições aos campos ajuda o modelo a interpretar quais informações devem ser extraídas.

Comparação com a API de conclusões de chat

Embora a API de respostas forneça saídas estruturadas por meio do esquema JSON, a API de conclusões de chat oferece uma abordagem alternativa usando modelos Pydantic, que é muito mais simples:

from pydantic import BaseModel, Field
from typing import List, Optional
from openai import OpenAI

client = OpenAI()

class ProductDetails(BaseModel):
   product_name: str
   category: str = Field(default=None)
   features: List[str]
   specifications: Optional[dict] = None
   colors: List[str]
   pricing: dict

# With Chat Completions API
completion = client.beta.chat.completions.parse(
   model="gpt-4o",
   messages=[
       {"role": "system", "content": "Extract structured product information."},
       {"role": "user", "content": product_description}
   ],
   response_format=ProductDetails
)

pydantic_product = completion.choices[0].message.parsed

Cada abordagem tem seus benefícios:

• A API de respostas usa o esquema JSON padrão diretamente na chamada de API
• A API Chat Completions se integra ao sistema de tipos do Python por meio do Pydantic

Se você me perguntar, eu usaria a API Chat Completions para evitar escrever esquemas JSON brutos. Isso até que, é claro, a OpenAI adicione suporte para modelos Pydantic à API de respostas.

Para obter mais informações, consulte a Documentação da API de respostas para saídas estruturadas.

Conclusão

A API OpenAI Responses simplifica a forma como os desenvolvedores interagem com os modelos de linguagem, combinando os pontos fortes das APIs anteriores em uma interface unificada que exige menos código e complexidade. Ele oferece suporte à geração de texto, análise de imagem, chamada de função e saídas estruturadas, tornando os recursos de IA mais acessíveis e permitindo que os desenvolvedores se concentrem na solução de problemas de negócios em vez de desafios de integração.

À medida que você continua sua jornada com a API de respostas, esses recursos adicionais podem ser úteis para aprofundar sua compreensão e expandir suas habilidades de implementação:

• Trabalhando com a API OpenAI
• Programa de fundamentos da OpenAI
• GPT-4.5: O que há de novo no modelo mais recente da OpenAI
• Pesquisa profunda com a OpenAI
• Tutorial de chamada de função do GPT-4.5
• Tutorial da API do GPT-4.5
• Tutorial do SDK de agentes da OpenAI