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

Migração Gradual para a API de Respostas

Aula 12 de 12 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Porquê e quando migrar
  2. Passo 1: Identificar as funcionalidades que utiliza
  3. Passo 2: Migrar chamadas básicas
  4. Passo 3: Migrar conversas de várias voltas
  5. Passo 4: Aproveitar as novas funcionalidades
  6. Estratégia de migração recomendada
  7. Pontos-chave
  8. Teste os seus conhecimentos

Atualizado a 3 de novembro de 2026: O mapeamento de parâmetros indicava anteriormente que max_tokens mantinha o seu nome na API de Respostas; a tabela da xAI altera-o para max_output_tokens, e os contadores de utilização também mudam de nome. Fonte: Comparação com Chat Completions.

Porquê e quando migrar

O endpoint Chat Completions está assinalado como legado. Continuará a funcionar, mas não receberá novas funcionalidades. Se a sua aplicação necessitar de ferramentas do lado do servidor (pesquisa na Web, execução de código), armazenamento de conversas ou raciocínio encriptado, a migração para a API de Respostas torna-se necessária.

A boa notícia: esta migração pode ocorrer gradualmente. Não precisa de reescrever tudo de uma vez.

Passo 1: Identificar as funcionalidades que utiliza

Antes de migrar, faça um balanço do que a sua aplicação utiliza com o Chat Completions:

# Audite o seu código existente
# Procure estes padrões:

# 1. Chamadas básicas (texto simples)
client.chat.completions.create(model=..., messages=...)

# 2. Streaming
client.chat.completions.create(..., stream=True)

# 3. Chamada de funções
client.chat.completions.create(..., tools=[...])

# 4. Visão (imagens)
# mensagens com conteúdo como array [text, image_url]

# 5. Parâmetros de geração
# temperature, max_tokens, top_p, stop, seed

As chamadas básicas e o streaming são os mais simples de migrar. A chamada de funções requer adaptação do formato. A visão funciona de forma semelhante.

Passo 2: Migrar chamadas básicas

Migrar uma chamada simples segue este padrão:

# ANTES — Chat Completions
response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)
texte = response.choices[0].message.content

# DEPOIS — API de Respostas
response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    instructions="You are a helpful assistant.",
    input="Hello!"
)
texte = response.output_text

Mapeamento de campos

As principais alterações são:

  • messages com papel system → instructions (parâmetro dedicado)
  • messages com papel user → input (cadeia de caracteres simples)
  • response.choices[0].message.content → response.output_text
  • max_tokens → max_output_tokens, de acordo com a tabela de mapeamento da xAI; temperature mantém o seu nome
  • response.usage.prompt_tokens e completion_tokens → input_tokens e output_tokens (detalhes: input_tokens_details.cached_tokens, output_tokens_details.reasoning_tokens)

Passo 3: Migrar conversas de várias voltas

É aqui que a API de Respostas simplifica as coisas. Em vez de reconstruir o histórico a cada pedido, encadeia-os por ID:

# ANTES — Chat Completions (gerir o histórico manualmente)
historique = [
    {"role": "system", "content": "You are a helpful assistant."}
]

def envoyer_message(texte: str) -> str:
    historique.append({"role": "user", "content": texte})
    response = client.chat.completions.create(
        model="grok-4.20-0309-reasoning",
        messages=historique
    )
    reponse = response.choices[0].message.content
    historique.append({"role": "assistant", "content": reponse})
    return reponse

# DEPOIS — API de Respostas (o servidor gere o histórico)
dernier_id = None

def envoyer_message(texte: str) -> str:
    response = client.responses.create(
        model="grok-4.20-0309-reasoning",
        instructions="You are a helpful assistant.",
        input=texte,
        previous_response_id=dernier_id
    )
    dernier_id = response.id
    return response.output_text

O código é mais simples e já não precisa de gerir manualmente o array de mensagens.

Passo 4: Aproveitar as novas funcionalidades

Uma vez migrado, pode alavancar funcionalidades exclusivas da API de Respostas:

Pesquisa na Web integrada

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What are the latest developments in generative AI?",
    tools=[{"type": "web_search"}]
)
# A resposta inclui citações com URLs de origem

Armazenamento de respostas

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Analyze this document...",
    store=True  # Mantém por 30 dias
)

# Recuperar mais tarde
stored = client.responses.retrieve(response.id)

Raciocínio encriptado

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Solve this complex problem...",
    include=["reasoning.encrypted_content"]
)
# O raciocínio encriptado pode ser reutilizado em pedidos subsequentes

Estratégia de migração recomendada

Em vez de migrar tudo de uma vez, proceda por etapas:

  1. Identificar as chamadas Chat Completions no seu código
  2. Classificá-las por complexidade (básico → streaming → chamada de funções)
  3. Migrar primeiro os novos endpoints ou funcionalidades (greenfield)
  4. Depois migrar as chamadas existentes mais simples
  5. Manter o Chat Completions para integrações de terceiros que o exijam (LangChain, etc.)

Coexistência temporária

É perfeitamente aceitável executar ambos os endpoints lado a lado durante a transição:

# Wrapper que abstrai o endpoint utilizado
class GrokClient:
    def __init__(self, use_responses: bool = False):
        self.use_responses = use_responses
        self.client = OpenAI(
            api_key=os.getenv("XAI_API_KEY"),
            base_url="https://api.x.ai/v1"
        )

    def generate(self, system: str, user_message: str) -> str:
        if self.use_responses:
            response = self.client.responses.create(
                model="grok-4.20-0309-reasoning",
                instructions=system,
                input=user_message
            )
            return response.output_text
        else:
            response = self.client.chat.completions.create(
                model="grok-4.20-0309-reasoning",
                messages=[
                    {"role": "system", "content": system},
                    {"role": "user", "content": user_message}
                ]
            )
            return response.choices[0].message.content

Esta abordagem permite-lhe mudar gradualmente, testando cada migração individualmente.

Pontos-chave

  • A migração pode ser gradual: não é necessário reescrever tudo de uma vez
  • Principais alterações: messages → input/instructions, choices[0].message.content → output_text
  • As conversas de várias voltas passam de um array de mensagens para um simples previous_response_id
  • A API de Respostas dá acesso a funcionalidades exclusivas (web_search, armazenamento, raciocínio encriptado)
  • Execute ambos os endpoints lado a lado durante a transição e migre por ordem de complexidade

Teste os seus conhecimentos

A API legada compreendida e a migração preparada.

1. O que significa o estatuto legado e sem estado do Chat Completions?

Resposta: O endpoint permanece suportado, mas deixa de evoluir: sendo sem estado, exige o reenvio de todo o histórico a cada chamada — a API de Respostas é o caminho moderno.

2. Quais os papéis que estruturam as mensagens?

Resposta: system (e developer), user, assistant — a estrutura, os pedidos, as respostas: todo o histórico recomeça a cada pedido.

3. Como utilizar código OpenAI existente com o Grok?

Resposta: Alterando o base_url para https://api.x.ai/v1 e a chave da API — a compatibilidade de formatos trata do resto, incluindo o SDK da OpenAI e o Vercel AI SDK.

4. O que lê na resposta e na utilização?

Resposta: choices transporta as respostas com finish_reason; usage detalha os tokens, incluindo reasoning_tokens para modelos de raciocínio — a base para o acompanhamento de custos.

5. Como migrar corretamente para a API de Respostas?

Resposta: Gradualmente: novos desenvolvimentos em Respostas, endpoints existentes convertidos um a um com novo teste de prompts — comparar os dois formatos guia a conversão.

Compreenda o legado, construa para o moderno: o plano de migração gradual do curso é o seu roteiro — sem «big bang».