Saídas previstas (versão prévia)

As saídas previstas podem melhorar a latência de resposta do modelo para chamadas de conclusão de chat em que são necessárias alterações mínimas em um corpo de texto maior. Se você estiver solicitando que o modelo forneça uma resposta em que uma grande parte da resposta esperada já seja conhecida, as saídas previstas poderão reduzir significativamente a latência dessa solicitação. Essa funcionalidade é particularmente adequada para cenários de codificação, incluindo preenchimento automático, detecção de erros e edição em tempo real, em que velocidade e capacidade de resposta são essenciais para desenvolvedores e usuários finais. Em vez de fazer o modelo regenerar todo o texto do zero, você pode indicar ao modelo que a maior parte da resposta já é conhecida passando o texto conhecido para o prediction parâmetro.

Pré-requisitos

Um modelo OpenAI do Azure implantado
Atualize a biblioteca de Python do OpenAI:
```
pip install --upgrade openai
```
Se você usar Microsoft Entra ID, instale também azure-identity:
```
pip install --upgrade azure-identity
```

Suporte ao modelo

gpt-4o-mini Versão: 2024-07-18
gpt-4o Versão: 2024-08-06
gpt-4o Versão: 2024-11-20
gpt-4.1 Versão: 2025-04-14
gpt-4.1-nano Versão: 2025-04-14
gpt-4.1-mini Versão: 2025-04-14

Suporte à API

Introduzido pela primeira vez em 2025-01-01-preview. Com suporte em todas as versões subsequentes.

Recursos sem suporte

No momento, as saídas previstas são somente texto. Esses recursos não podem ser usados em conjunto com o prediction parâmetro e as saídas previstas.

Chamada de ferramentas e função
modelos/entradas e saídas de áudio
n valores maiores que 1
logprobs
presence_penalty valores maiores que 0
frequency_penalty valores maiores que 0
max_completion_tokens

Nota

O recurso de saídas previsto está atualmente indisponível para modelos na região sudeste da Ásia.

Começando

Para demonstrar os conceitos básicos das saídas previstas, começaremos solicitando a um modelo que refatore o código do problema de programação FizzBuzz comum para substituir a instância de FizzBuzz por MSFTBuzz. Passaremos nosso código de exemplo para o modelo em dois lugares. Primeiro como parte de uma mensagem de usuário na messages matriz/lista e uma segunda vez como parte do conteúdo do novo prediction parâmetro.

Microsoft Entra ID
Chave de API

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(
  base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=token_provider,
)

code = """
for number in range(1, 101):
    if number % 3 == 0 and number % 5 == 0:
        print("FizzBuzz")
    elif number % 3 == 0:
        print("Fizz")
    elif number % 5 == 0:
        print("Buzz")
    else:
        print(number)
"""

instructions = """
Replace string `FizzBuzz` with `MSFTBuzz`. Respond only 
with code, and with no markdown formatting.
"""

completion = client.chat.completions.create(
    model="YOUR-DEPLOYMENT-NAME",
    messages=[
        {
            "role": "user",
            "content": instructions
        },
        {
            "role": "user",
            "content": code
        }
    ],
    prediction={
        "type": "content",
        "content": code
    },
)

print(completion.model_dump_json(indent=2))

import os
from openai import OpenAI

client = OpenAI(
  base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

code = """
for number in range(1, 101):
    if number % 3 == 0 and number % 5 == 0:
        print("FizzBuzz")
    elif number % 3 == 0:
        print("Fizz")
    elif number % 5 == 0:
        print("Buzz")
    else:
        print(number)
"""

instructions = """
Replace string `FizzBuzz` with `MSFTBuzz`. Respond only 
with code, and with no markdown formatting.
"""

completion = client.chat.completions.create(
  model="YOUR-DEPLOYMENT-NAME",
  messages=[
    {
      "role": "user",
      "content": instructions
    },
    {
      "role": "user",
      "content": code
    }
  ],
    prediction={
        "type": "content",
        "content": code
  },
)

print(completion.model_dump_json(indent=2))

Saída

{
  "id": "chatcmpl-AskZk3P5QGmefqobDw4Ougo6jLxSP",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "for number in range(1, 101):\n    if number % 3 == 0 and number % 5 == 0:\n        print(\"MSFTBuzz\")\n    elif number % 3 == 0:\n        print(\"Fizz\")\n    elif number % 5 == 0:\n        print(\"Buzz\")\n    else:\n        print(number)",
        "refusal": null,
        "role": "assistant",
        "audio": null,
        "function_call": null,
        "tool_calls": null
      },
      "content_filter_results": {
        "hate": {
          "filtered": false,
          "severity": "safe"
        },
        "protected_material_code": {
          "filtered": false,
          "detected": false
        },
        "protected_material_text": {
          "filtered": false,
          "detected": false
        },
        "self_harm": {
          "filtered": false,
          "severity": "safe"
        },
        "sexual": {
          "filtered": false,
          "severity": "safe"
        },
        "violence": {
          "filtered": false,
          "severity": "safe"
        }
      }
    }
  ],
  "created": 1737612112,
  "model": "gpt-4o-mini-2024-07-18",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": "fp_5154047bf2",
  "usage": {
    "completion_tokens": 77,
    "prompt_tokens": 124,
    "total_tokens": 201,
    "completion_tokens_details": {
      "accepted_prediction_tokens": 6,
      "audio_tokens": 0,
      "reasoning_tokens": 0,
      "rejected_prediction_tokens": 4
    },
    "prompt_tokens_details": {
      "audio_tokens": 0,
      "cached_tokens": 0
    }
  },
  "prompt_filter_results": [
    {
      "prompt_index": 0,
      "content_filter_results": {
        "hate": {
          "filtered": false,
          "severity": "safe"
        },
        "jailbreak": {
          "filtered": false,
          "detected": false
        },
        "self_harm": {
          "filtered": false,
          "severity": "safe"
        },
        "sexual": {
          "filtered": false,
          "severity": "safe"
        },
        "violence": {
          "filtered": false,
          "severity": "safe"
        }
      }
    }
  ]
}

Observe na saída os novos parâmetros de resposta para accepted_prediction_tokens e rejected_prediction_tokens:

  "usage": {
    "completion_tokens": 77,
    "prompt_tokens": 124,
    "total_tokens": 201,
    "completion_tokens_details": {
      "accepted_prediction_tokens": 6,
      "audio_tokens": 0,
      "reasoning_tokens": 0,
      "rejected_prediction_tokens": 4
    }

A accepted_prediction_tokens ajuda a reduzir a latência de resposta do modelo, mas qualquer rejected_prediction_tokens tem a mesma implicação de custo dos tokens de saída adicionais gerados pelo modelo. Por esse motivo, embora as saídas previstas possam melhorar os tempos de resposta do modelo, isso pode resultar em custos maiores. Você precisará avaliar e equilibrar o aumento do desempenho do modelo em relação aos possíveis aumentos de custo.

Também é importante entender que o uso de saídas preditivas não garante uma redução na latência. Uma solicitação grande com uma porcentagem maior de tokens de previsão rejeitados do que os tokens de previsão aceitos pode resultar em um aumento na latência de resposta do modelo, em vez de uma diminuição.

Nota

Ao contrário do cache de prompt que só funciona quando um número mínimo definido de tokens iniciais no início de uma solicitação é idêntico, as saídas previstas não são restritas pelo local do token. Mesmo que o texto de resposta contenha um novo resultado que será retornado antes do resultado previsto, accepted_prediction_tokens ainda poderá ocorrer.

Streaming

O aumento de desempenho de saídas previstas geralmente é mais óbvio se você estiver retornando suas respostas com o streaming habilitado.

Microsoft Entra ID
Chave de API

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(
  base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=token_provider,
)

code = """
for number in range(1, 101):
    if number % 3 == 0 and number % 5 == 0:
        print("FizzBuzz")
    elif number % 3 == 0:
        print("Fizz")
    elif number % 5 == 0:
        print("Buzz")
    else:
        print(number)
"""

instructions = """
Replace string `FizzBuzz` with `MSFTBuzz`. Respond only 
with code, and with no markdown formatting.
"""

completion = client.chat.completions.create(
    model="YOUR-DEPLOYMENT-NAME",
    messages=[
        {
            "role": "user",
            "content": instructions
        },
        {
            "role": "user",
            "content": code
        }
    ],
    prediction={
        "type": "content",
        "content": code
    },
    stream=True
)

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

import os
from openai import OpenAI

client = OpenAI(
  base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY"),
)

code = """
for number in range(1, 101):
    if number % 3 == 0 and number % 5 == 0:
        print("FizzBuzz")
    elif number % 3 == 0:
        print("Fizz")
    elif number % 5 == 0:
        print("Buzz")
    else:
        print(number)
"""

instructions = """
Replace string `FizzBuzz` with `MSFTBuzz`. Respond only 
with code, and with no markdown formatting.
"""

completion = client.chat.completions.create(
    model="YOUR-DEPLOYMENT-NAME",
    messages=[
        {
            "role": "user",
            "content": instructions
        },
        {
            "role": "user",
            "content": code
        }
    ],
    prediction={
        "type": "content",
        "content": code
    },
    stream=True
)

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

Solucionando problemas

401/403: se você usar Microsoft Entra ID, confirme se sua identidade tem acesso ao recurso Azure OpenAI. Se você usar get_bearer_token_provider, solicite um token para https://ai.azure.com/.default.
404: confirme se base_url usa o nome do seu recurso do OpenAI do Azure e model usa o nome da sua implantação.
400: remova os parâmetros opcionais e os recursos listados em recursos sem suporte e tente novamente.

Comentários

Esta página foi útil?

Last updated on 2026-05-05