Saídas previstas | OpenAI API

As Saídas previstas permitem acelerar as respostas da API de Chat Completions quando muitos dos tokens de saída já são conhecidos. Isso é mais comum ao gerar novamente um arquivo de texto ou código com pequenas modificações. Você pode fornecer sua previsão usando o parâmetro de requisição prediction em Chat Completions.

As Saídas previstas já estão disponíveis nas versões mais recentes dos modelos gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini e gpt-4.1-nano. Continue lendo para saber como usar as Saídas previstas para reduzir a latência nas suas aplicações.

Exemplo de refatoração de código

As Saídas previstas são especialmente úteis para gerar novamente documentos de texto e arquivos de código com pequenas modificações. Digamos que você queira que o modelo GPT-4o refatore um trecho de código JavaScript e altere a propriedade username da classe User para email:

1
2
3
4
5
6
7class User {
  firstName = "";
  lastName = "";
  username = "";
}

export default User;

A maior parte do arquivo permanecerá inalterada, exceto pela linha 4 acima. Se você usar o texto atual do arquivo de código como previsão, poderá gerar novamente o arquivo inteiro com menor latência. Em arquivos maiores, essa economia de tempo se acumula rapidamente.

Veja abaixo um exemplo de uso do parâmetro prediction nos nossos SDKs para prever que a saída final do modelo será muito semelhante ao nosso arquivo de código original, que usamos como texto da previsão.

Refatore uma classe JavaScript com uma saída prevista

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41import OpenAI from "openai";

const code = `
class User {
  firstName = "";
  lastName = "";
  username = "";
}

export default User;
`.trim();

const openai = new OpenAI();

const refactorPrompt = `
Replace the "username" property with an "email" property. Respond only
with code, and with no markdown formatting.
`;

const completion = await openai.chat.completions.create({
  model: "gpt-4.1",
  messages: [
    {
      role: "user",
      content: refactorPrompt,
    },
    {
      role: "user",
      content: code,
    },
  ],
  store: true,
  prediction: {
    type: "content",
    content: code,
  },
});

// Inspect returned data
console.log(completion);
console.log(completion.choices[0].message.content);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30from openai import OpenAI

code = """
class User {
  firstName = "";
  lastName = "";
  username = "";
}

export default User;
""".strip()

refactor_prompt = """
Replace the "username" property with an "email" property. Respond only
with code, and with no markdown formatting.
"""

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-4.1",
    messages=[
        {"role": "user", "content": refactor_prompt},
        {"role": "user", "content": code},
    ],
    prediction={"type": "content", "content": code},
)

print(completion)
print(completion.choices[0].message.content)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42package main

import (
	"context"
	"fmt"
	"strings"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/shared"
)

func main() {
	client := openai.NewClient()
	code := strings.TrimSpace(`
class User {
  firstName = "";
  lastName = "";
  username = "";
}

export default User;
`)
	refactorPrompt := strings.TrimSpace(`
Replace the "username" property with an "email" property. Respond only
with code, and with no markdown formatting.
`)
	completion, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
		Model: shared.ChatModelGPT4_1,
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.UserMessage(refactorPrompt),
			openai.UserMessage(code),
		},
		Store: openai.Bool(true),
		Prediction: openai.ChatCompletionPredictionContentParam{
			Content: openai.ChatCompletionPredictionContentContentUnionParam{OfString: openai.String(code)},
		},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(completion.Choices[0].Message.Content)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import com.openai.models.chat.completions.ChatCompletionPredictionContent;

String code =
    """
    class User {
      firstName: string = "";
      lastName: string = "";
      username: string = "";
    }

    export default User;
    """;
String refactorPrompt =
    "Replace the \"username\" property with an \"email\" property. "
        + "Respond only with code, and with no markdown formatting.";

ChatCompletionCreateParams params =
    ChatCompletionCreateParams.builder()
        .model("gpt-4.1")
        .addUserMessage(refactorPrompt)
        .addUserMessage(code)
        .prediction(ChatCompletionPredictionContent.builder().content(code).build())
        .store(true)
        .build();

client.chat().completions().create(params).choices().stream()
    .flatMap(choice -> choice.message().content().stream())
    .forEach(System.out::println);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32using OpenAI.Chat;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
string model = "gpt-4.1";
ChatClient client = new(model, key);

string code =
    """
    class User {
      firstName = "";
      lastName = "";
      username = "";
    }

    export default User;
    """;
ChatCompletionOptions options = new()
{
    OutputPrediction = ChatOutputPrediction.CreateStaticContentPrediction(code),
};
ChatCompletion completion = await client.CompleteChatAsync(
    [
        new UserChatMessage(
            "Replace the username property with an email property. Respond only with code, and with no markdown formatting."
        ),
        new UserChatMessage(code),
    ],
    options
);

Console.WriteLine(completion.Content[0].Text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36require "openai"

client = OpenAI::Client.new
code = <<~CODE
  class User {
    firstName: string = "";
    lastName: string = "";
    username: string = "";
  }

  export default User;
CODE
refactor_prompt = <<~PROMPT
  Replace the "username" property with an "email" property. Respond only
  with code, and with no markdown formatting.
PROMPT
completion = client.chat.completions.create(
  model: "gpt-4.1",
  messages: [
    {
      role: :user,
      content: refactor_prompt
    },
    {
      role: :user,
      content: code
    }
  ],
  prediction: {
    type: :content,
    content: code
  },
  store: true
)

puts(completion.choices.fetch(0).message.content)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20curl https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {
        "role": "user",
        "content": "Replace the username property with an email property. Respond only with code, and with no markdown formatting."
      },
      {
        "role": "user",
        "content": "$CODE_CONTENT_HERE"
      }
    ],
    "prediction": {
        "type": "content",
        "content": "$CODE_CONTENT_HERE"
    }
  }'

Além do código refatorado, a resposta do modelo contém dados de uso como os mostrados nesta versão abreviada, sem o campo choices:

12345678910111213141516171819{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1786652188,
  "model": "gpt-4.1-2025-04-14",
  "usage": {
    "prompt_tokens": 59,
    "completion_tokens": 24,
    "total_tokens": 83,
    "prompt_tokens_details": { "cached_tokens": 0, "audio_tokens": 0 },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 14,
      "rejected_prediction_tokens": 2
    }
  },
  "system_fingerprint": "fp_6ddb4f7408"
}

Observe os campos accepted_prediction_tokens e rejected_prediction_tokens no objeto usage. Neste exemplo, 14 tokens da previsão foram usados para acelerar a resposta, enquanto 2 foram rejeitados.

Observe que os tokens rejeitados continuam sendo cobrados como os demais tokens de conclusão gerados pela API. Por isso, as Saídas previstas podem aumentar o custo das suas requisições.

Exemplo de streaming

A redução de latência com as Saídas previstas é ainda maior quando você usa streaming nas respostas da API. Veja um exemplo do mesmo caso de uso de refatoração de código, agora usando streaming nos SDKs da OpenAI.

Saídas previstas com streaming

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43import OpenAI from "openai";

const code = `
class User {
  firstName = "";
  lastName = "";
  username = "";
}

export default User;
`.trim();

const openai = new OpenAI();

const refactorPrompt = `
Replace the "username" property with an "email" property. Respond only
with code, and with no markdown formatting.
`;

const completion = await openai.chat.completions.create({
  model: "gpt-4.1",
  messages: [
    {
      role: "user",
      content: refactorPrompt,
    },
    {
      role: "user",
      content: code,
    },
  ],
  store: true,
  prediction: {
    type: "content",
    content: code,
  },
  stream: true,
});

// Inspect returned data
for await (const chunk of completion) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32from openai import OpenAI

code = """
class User {
  firstName = "";
  lastName = "";
  username = "";
}

export default User;
""".strip()

refactor_prompt = """
Replace the "username" property with an "email" property. Respond only
with code, and with no markdown formatting.
"""

client = OpenAI()

stream = client.chat.completions.create(
    model="gpt-4.1",
    messages=[
        {"role": "user", "content": refactor_prompt},
        {"role": "user", "content": code},
    ],
    prediction={"type": "content", "content": code},
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46package main

import (
	"context"
	"fmt"
	"strings"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/shared"
)

func main() {
	client := openai.NewClient()
	code := strings.TrimSpace(`
class User {
  firstName = "";
  lastName = "";
  username = "";
}

export default User;
`)
	refactorPrompt := strings.TrimSpace(`
Replace the "username" property with an "email" property. Respond only
with code, and with no markdown formatting.
`)
	stream := client.Chat.Completions.NewStreaming(context.Background(), openai.ChatCompletionNewParams{
		Model: shared.ChatModelGPT4_1,
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.UserMessage(refactorPrompt),
			openai.UserMessage(code),
		},
		Store: openai.Bool(true),
		Prediction: openai.ChatCompletionPredictionContentParam{
			Content: openai.ChatCompletionPredictionContentContentUnionParam{OfString: openai.String(code)},
		},
	})
	for stream.Next() {
		if len(stream.Current().Choices) > 0 {
			fmt.Print(stream.Current().Choices[0].Delta.Content)
		}
	}
	if err := stream.Err(); err != nil {
		panic(err)
	}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.http.StreamResponse;
import com.openai.models.chat.completions.ChatCompletionChunk;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import com.openai.models.chat.completions.ChatCompletionPredictionContent;

String code =
    """
    class User {
      firstName: string = "";
      lastName: string = "";
      username: string = "";
    }

    export default User;
    """;
String refactorPrompt =
    "Replace the \"username\" property with an \"email\" property. "
        + "Respond only with code, and with no markdown formatting.";

ChatCompletionCreateParams params =
    ChatCompletionCreateParams.builder()
        .model("gpt-4.1")
        .addUserMessage(refactorPrompt)
        .addUserMessage(code)
        .prediction(ChatCompletionPredictionContent.builder().content(code).build())
        .store(true)
        .build();

try (StreamResponse<ChatCompletionChunk> stream =
    client.chat().completions().createStreaming(params)) {
  stream.stream()
      .flatMap(chunk -> chunk.choices().stream())
      .flatMap(choice -> choice.delta().content().stream())
      .forEach(System.out::print);
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39using OpenAI.Chat;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
string model = "gpt-4.1";
ChatClient client = new(model, key);

string code =
    """
    class User {
      firstName = "";
      lastName = "";
      username = "";
    }

    export default User;
    """;
ChatCompletionOptions options = new()
{
    OutputPrediction = ChatOutputPrediction.CreateStaticContentPrediction(code),
};

await foreach (
    StreamingChatCompletionUpdate update in client.CompleteChatStreamingAsync(
        [
            new UserChatMessage(
                "Replace the username property with an email property. Respond only with code, and with no markdown formatting."
            ),
            new UserChatMessage(code),
        ],
        options
    )
)
{
    foreach (ChatMessageContentPart part in update.ContentUpdate)
    {
        Console.Write(part.Text);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36require "openai"

client = OpenAI::Client.new
code = <<~CODE
  class User {
    firstName: string = "";
    lastName: string = "";
    username: string = "";
  }

  export default User;
CODE
refactor_prompt = <<~PROMPT
  Replace the "username" property with an "email" property. Respond only
  with code, and with no markdown formatting.
PROMPT
stream = client.chat.completions.stream(
  model: "gpt-4.1",
  messages: [
    {
      role: :user,
      content: refactor_prompt
    },
    {
      role: :user,
      content: code
    }
  ],
  prediction: {
    type: :content,
    content: code
  },
  store: true
)

stream.text.each { |text| print(text) }

Posição do texto previsto na resposta

O texto que você fornece como previsão pode aparecer em qualquer parte da resposta gerada e ainda assim reduzir a latência da resposta. Digamos que o texto previsto seja o servidor Hono simples mostrado abaixo:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25import { serve } from "@hono/node-server";
import { serveStatic } from "@hono/node-server/serve-static";
import { Hono } from "hono";

const app = new Hono();

app.get("/api", (c) => {
  return c.text("Hello Hono!");
});

// You will need to build the client code first: `pnpm run ui:build`.
app.use(
  "/*",
  serveStatic({
    rewriteRequestPath: (path) => `./dist${path}`,
  })
);

const port = 3000;
console.log(`Server is running on port ${port}`);

serve({
  fetch: app.fetch,
  port,
});

Você poderia pedir ao modelo para gerar novamente o arquivo com um prompt como este:

Add a get route to this application that responds with
the text "hello world". Generate the entire application
file again with this route added, and with no other
markdown formatting.

A resposta ao prompt poderia ser algo assim:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29import { serve } from "@hono/node-server";
import { serveStatic } from "@hono/node-server/serve-static";
import { Hono } from "hono";

const app = new Hono();

app.get("/api", (c) => {
  return c.text("Hello Hono!");
});

app.get("/hello", (c) => {
  return c.text("hello world");
});

// You will need to build the client code first: `pnpm run ui:build`.
app.use(
  "/*",
  serveStatic({
    rewriteRequestPath: (path) => `./dist${path}`,
  })
);

const port = 3000;
console.log(`Server is running on port ${port}`);

serve({
  fetch: app.fetch,
  port,
});

Uma versão abreviada da resposta do modelo, sem o campo choices, ainda mostraria tokens de previsão aceitos, mesmo com o texto da previsão aparecendo tanto antes quanto depois do novo conteúdo adicionado à resposta:

12345678910111213141516171819{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1731014771,
  "model": "gpt-4o-2024-08-06",
  "usage": {
    "prompt_tokens": 203,
    "completion_tokens": 159,
    "total_tokens": 362,
    "prompt_tokens_details": { "cached_tokens": 0, "audio_tokens": 0 },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 60,
      "rejected_prediction_tokens": 0
    }
  },
  "system_fingerprint": "fp_9ee9e968ea"
}

Desta vez, nenhum token de previsão foi rejeitado, pois todo o conteúdo do arquivo fornecido como previsão foi usado na resposta final. Boa! 🔥

Limitações

Ao usar as Saídas previstas, considere os seguintes fatores e limitações.

As Saídas previstas são compatíveis apenas com as séries de modelos GPT-4o, GPT-4o-mini, GPT-4.1, GPT-4.1-mini e GPT-4.1-nano.
Ao fornecer uma previsão, os tokens fornecidos que não fizerem parte da conclusão final ainda serão cobrados pelas tarifas de tokens de conclusão. Consulte a propriedade rejected_prediction_tokens do objeto usage para saber quantos tokens não foram usados na resposta final.
Os seguintes parâmetros da API não são compatíveis com as Saídas previstas:
- n: valores maiores que 1 não são aceitos
- logprobs: não há suporte
- presence_penalty: valores maiores que 0 não são aceitos
- frequency_penalty: valores maiores que 0 não são aceitos
- audio: as Saídas previstas não são compatíveis com entradas e saídas de áudio
- modalities: somente modalidades text são aceitas
- max_completion_tokens: não há suporte
- tools: atualmente, a chamada de função não é compatível com as Saídas previstas

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Recursos

APIs legadas

Escolha um modelo

Texto e código

Criação de prompts

Raciocínio

Imagens e vídeo

Tempo real e áudio

Modelos especializados

API de Agentes

SDK de Agentes

ChatKit

Pesquisa e recuperação

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolva com voz

Conexões

Processamento de áudio

Entre em produção

Desempenho e qualidade

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Plan

Build

Test and publish

Conversion specs

Guias

Recursos

Primeiros passos

Guias

File Upload

API

Measurement

Advertiser API

Referência da API

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Amplie os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Amplie e automatize

Ambientes

Desenvolva com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

ChatGPT Work

Identidade e autenticação

Acesso, política e modelos do workspace

Controles de plug-ins e conectores

Uso, governança e conformidade

Implantação e provedores de modelos

Comunidade

Blog

Comunidade

Blog