Cache de prompts

O armazenamento em cache de prompts reduz a latência global e o custo das solicitações com prompts mais longos que tenham conteúdo idêntico no início. Neste contexto, "prompt" refere-se ao input que envia ao modelo como parte das suas finalizações de chat ou pedidos de criação de resposta. Em vez de reprocessar repetidamente os mesmos tokens de entrada, o serviço mantém um cache temporário dos cálculos processados dos tokens de entrada para melhorar o desempenho global. O armazenamento em cache por prompt não tem impacto no conteúdo de saída retornado na resposta do modelo, exceto por uma redução na latência e no custo.

Para modelos suportados, as leituras de cache são faturadas com desconto no preço dos tokens de entrada para os tipos de implementação padrão e até 100% de desconto nos tokens de entrada para tipos de implementação provisionados. O preço do prompt cache é igual para ambas as políticas de retenção.

Importante

Modelos anteriores à família GPT-5.6 não cobram extra para escrever na cache. Nos modelos GPT-5.6 e nas famílias de modelos posteriores, as escritas de cache podem incorrer em encargos além das leituras de cache descontadas. Para manter os custos previsíveis, estrutura os teus prompts de forma a que o conteúdo reutilizado se mantenha idêntico entre pedidos, o que favorece as leituras em cache em detrimento das escritas em cache. Para as taxas atuais, consulte a página de preços do Azure OpenAI.

Melhore as taxas de acerto do cache com uma chave de cache de prompt

Nos modelos GPT-5.6 e nas famílias de modelos posteriores, define o prompt_cache_key parâmetro e reutiliza a mesma chave para pedidos que partilham prefixos longos e comuns de prompt. Este parâmetro melhora a correspondência de cache para pedidos relacionados. Não precisas de uma versão específica da API para usar prompt_cache_key. Para novas integrações, use a API v1.

Se os pedidos para o mesmo prefixo e prompt_cache_key combinação excederem aproximadamente 15 pedidos por minuto, alguns pedidos podem não entrar na cache. Para cargas de trabalho de maior volume, distribua os pedidos entre múltiplas chaves, mantendo um mapeamento estável entre cada chave e os seus prefixos de prompt partilhados.

Configurar pontos de interrupção de prompt cache

Nos modelos GPT-5.6 e nas famílias de modelos posteriores, utiliza-se pontos de interrupção de cache explícitos para marcar o fim de um prefixo de prompt reutilizável. Tanto a API Responses como a API Chat Completions suportam pontos de interrupção. O Azure OpenAI usa as mesmas estruturas de pedidos das APIs OpenAI, mas definidas model para o nome de implementação do modelo Azure. O conteúdo após o ponto de interrupção pode mudar sem invalidar o prefixo em cache.

As implementações padrão pay-as-you-go suportam pontos de interrupção de cache por prompt. As implementações gerenciadas por débito provisionado (PTU-M) não suportam pontos de interrupção de cache por prompt.

Defina a política de cache de todo o pedido usando prompt_cache_options.mode:

Mode Comportamento
implicit O padrão. O Azure OpenAI coloca um ponto de interrupção na mensagem mais recente e também utiliza quaisquer pontos de interrupção explícitos que forneças.
explicit O Azure OpenAI utiliza apenas pontos de interrupção explícitos para leituras e escritas de cache. Se o pedido não contiver pontos de interrupção explícitos, não utiliza cache de prompt nem incorre em cargas de escrita na cache.

Defina prompt_cache_options.ttl para 30m configurar a vida útil mínima da cache para todos os pontos de interrupção do pedido. O 30m valor é o valor padrão e o único suportado. Esta definição não seleciona a política de retenção em memória ou alargada.

Adicione prompt_cache_breakpoint: { "mode": "explicit" } a um bloco de conteúdo de prompt suportado. O ponto de interrupção inclui o bloco e todo o conteúdo do prompt anterior no prefixo reutilizável.

  • A API Respostas suporta pontos de interrupção em input_text, input_image, e input_file blocos.
  • A API Chat Completions suporta pontos de interrupção em text, image_url, input_audio, e file blocos.

Limites de pontos de rutura

  • Cada pedido pode criar até quatro novas escritas em cache.
  • No implicit modo, o ponto de interrupção na mensagem mais recente usa um slot de escrita, pelo que o pedido pode escrever até aos três pontos de interrupção explícitos mais recentes.
  • No explicit modo, o pedido pode escrever até aos quatro pontos de interrupção explícitos mais recentes.
  • Os pontos de interrupção das conversas anteriores são apenas de leitura. Podem corresponder à cache, mas o pedido não os volta a escrever.
  • Para leituras de cache, o Azure OpenAI considera até os últimos 50 pontos de interrupção na conversa.

Nos exemplos seguintes, o prefixo renderizado através do ponto de interrupção explícito deve conter pelo menos 1.024 tokens para ser cacheável.

O seguinte pedido da API de Respostas utiliza o modo predefinido implicit e adiciona um ponto de interrupção explícito após um ficheiro de referência estável:

{
  "model": "<your-gpt-5.6-deployment-name>",
  "prompt_cache_key": "tenant:contoso:product-manual-v2",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_file",
          "file_id": "<product-manual-file-id>",
          "prompt_cache_breakpoint": { "mode": "explicit" }
        },
        {
          "type": "input_text",
          "text": "Summarize the troubleshooting procedures."
        }
      ]
    }
  ]
}

O seguinte pedido de API de Chat Completions utiliza explicit o modo e marca o fim de uma mensagem de sistema reutilizável:

{
  "model": "<your-gpt-5.6-deployment-name>",
  "prompt_cache_key": "tenant:contoso:support-policy-v2",
  "prompt_cache_options": { "mode": "explicit", "ttl": "30m" },
  "messages": [
    {
      "role": "system",
      "content": [{
        "type": "text",
        "text": "<at least 1,024 tokens of reusable instructions>",
        "prompt_cache_breakpoint": { "mode": "explicit" }
      }]
    },
    {
      "role": "user",
      "content": "<variable user input>"
    }
  ]
}

Note

Modelos anteriores à família GPT-5.6 não suportam prompt_cache_options nem prompt_cache_breakpoint. Pedidos que incluem estes parâmetros devolvem um 400 erro. Continue a usar cache automática de prompts com estes modelos.

Retenção de cache por prompt

A cache de prompts tem dois controlos com semântica diferente:

  • Nos modelos GPT-5.6 e nas famílias de modelos posteriores, prompt_cache_options.ttl define uma vida útil mínima da cache. Não seleciona uma política de armazenamento nem um período máximo de retenção.
  • Para modelos anteriores, prompt_cache_retention seleciona uma política de retenção máxima. Nos modelos GPT-5.6 e nas famílias de modelos posteriores, este campo não se aplica e está obsoleto.

Nos modelos GPT-5.6 e nas famílias de modelos posteriores, utiliza-se prompt_cache_options.ttl para definir a vida útil mínima de todos os pontos de interrupção escritos pelo pedido. O único valor suportado é 30m, que também é o padrão. Um prefixo em cache permanece elegível para reutilização durante pelo menos 30 minutos, mas o serviço pode mantê-lo por mais tempo.

Para modelos anteriores à família GPT-5.6, defina prompt_cache_retention o seu pedido de Respostas ou Conclusão de Chat. O armazenamento em cache de prompts pode usar quer políticas de retenção na memória quer políticas de retenção estendida. Quando disponível, o armazenamento em cache alargado de prompts visa manter o cache durante mais tempo, para que os pedidos subsequentes tenham maior probabilidade de coincidir com o cache. A tarifação prompt cache é a mesma para ambas as apólices.

Retenção do cache de prompts em memória

O sistema normalmente limpa caches entre 5 a 10 minutos após a inatividade e remove-as sempre dentro de uma hora após a última utilização da cache. O sistema não partilha caches de prompt entre subscrições do Azure.

Todos os modelos GPT-4o ou posteriores do Azure OpenAI suportam a retenção da cache de prompts na memória. Aplica-se a modelos que têm completação de chat, conclusão, respostas ou operações de tempo real. Para modelos que não têm estas operações, esta funcionalidade não está disponível.

Retenção estendida de cache de comandos

A retenção prolongada do cache de prompts mantém os prefixos armazenados ativos por mais tempo, até um máximo de 24 horas. O armazenamento em cache alargado de prompts funciona descarregando os tensores de chave/valor para o armazenamento local da GPU quando a memória está cheia, o que aumenta significativamente a capacidade de armazenamento disponível para o armazenamento em cache.

A retenção estendida de prompt cache está disponível para os seguintes modelos:

  • gpt-5.5
  • gpt-5.4
  • gpt-5.3-codex
  • gpt-5.2
  • gpt-5.1-codex-max
  • gpt-5.1
  • gpt-5.1-codex
  • gpt-5.1-codex-mini
  • gpt-5.1-chat
  • gpt-5
  • gpt-5-codex
  • gpt-4.1

Configurar sob pedido

Para gpt-5.4 e modelos mais antigos, se não especificar uma política de retenção, o padrão é in_memory. Os valores permitidos são in_memory e 24h. Para gpt-5.5, a retenção estendida está ativada por defeito.

{
  "model": "<your-gpt-5.4-deployment-name>",
  "input": "Your prompt goes here...",
  "prompt_cache_retention": "24h"
}

Como começar

Para tirar partido do prompt cache, um pedido deve cumprir ambos os requisitos:

  • Um mínimo de 1.024 tokens em comprimento.
  • Os primeiros 1.024 tokens no prompt devem ser idênticos.

Quando se encontra uma correspondência entre os cálculos de tokens num prompt e o conteúdo atual da cache do prompt, é referido como cache hit. As ocorrências na cache aparecem como cached_tokens em prompt_tokens_details na resposta de conclusões de chat.

Nos modelos GPT-5.6 e nas famílias de modelos posteriores, as implementações padrão pay-as-you-go reportam leituras cached_tokens em cache e escritas em cache em cache_write_tokens. O excerto seguinte mostra estes campos numa resposta de Chat Completions. A ordem de propriedade JSON não é significativa e pode variar.

{
  "usage": {
    "prompt_tokens": 1566,
    "completion_tokens": 1518,
    "total_tokens": 3084,
    "prompt_tokens_details": {
      "audio_tokens": null,
      "cached_tokens": 1408,
      "cache_write_tokens": 0
    },
    "completion_tokens_details": {
      "audio_tokens": null,
      "reasoning_tokens": 576
    }
  }
}

No GPT-5.5 e modelos anteriores, as verificações de cache após os primeiros 1.024 tokens ocorrem em incrementos de 128 tokens. Este arredondamento não se aplica aos modelos GPT-5.6 e às famílias de modelos posteriores.

Uma diferença de um carácter nos primeiros 1.024 tokens resulta num erro de cache, que é caracterizado por um cached_tokens valor de 0. O cache de prompts está ativado por defeito para modelos suportados.

Melhores práticas

  • Coloque conteúdo estável ou repetido no início do prompt e conteúdo dinâmico no final. Mantém a conversa, contexto apenas com o anexo.
  • Reutilize um consistente prompt_cache_key para pedidos que partilhem um prefixo. Para cargas de trabalho de alto volume, particione o tráfego entre chaves mantendo um mapeamento estável entre cada chave e os seus prefixos.
  • Nas implementações padrão pay-as-you-go com modelos GPT-5.6 e famílias de modelos posteriores, coloca-se pontos de falha explícitos após o conteúdo estável. Usa explicit o modo quando quiseres que apenas os pontos de interrupção que forneces sejam elegíveis para leituras e escritas em cache.
  • Monitorize as leituras de cache com cached_tokens. Nas implementações padrão pay-as-you-go com modelos GPT-5.6 e famílias de modelos posteriores, monitoriza também as gravações de cache e cache_write_tokens compara o volume de escrita com as leituras de cache posteriores.
  • Mantenha um fluxo constante de pedidos com prefixos idênticos para melhorar a reutilização do cache.

Perguntas frequentes

As respostas seguintes esclarecem o conteúdo de cache suportado, custos, tipos de implementação e residência de dados.

O que está armazenado em cache?

O suporte a funcionalidades para modelos da série O1 varia consoante o modelo. Para mais informações, consulte o guia dedicado aos modelos de raciocínio.

Suporte para cache de prompts:

Cache suportado Descrição
Mensagens O conjunto completo de mensagens: conteúdo do sistema, do desenvolvedor, do utilizador e do assistente
Imagens Imagens incluídas nas mensagens dos utilizadores, tanto como links como dados codificados em base64. O parâmetro de detalhe deve ser definido igual em todos os pedidos.
Utilização de ferramentas Tanto a matriz de mensagens quanto as definições das ferramentas.
Saídas estruturadas O esquema de saída estruturado é acrescentado como prefixo à mensagem do sistema.

Para aumentar a probabilidade de acessos na cache, estrutura os teus pedidos de modo a que o conteúdo repetitivo ocorra no início do array de mensagens.

Posso desativar a cache do prompt?

Em implementações padrão pay-as-you-go com modelos GPT-5.6 e famílias de modelos posteriores, defina prompt_cache_options.mode e explicit não adiciona pontos de interrupção explícitos. O pedido não utiliza cache de prompt nem incorre em cargas de cache-write. Modelos anteriores e implementações PTU-M não suportam esta opção; O cache de prompts mantém-se ativado por defeito.

Devo pagar extra para escrever na cache?

Nos modelos anteriores à família GPT-5.6, não há custo extra para escrever na cache. Nos modelos GPT-5.6 e nas famílias de modelos posteriores, as escritas de cache podem incorrer em encargos além das leituras de cache descontadas. Para ver as taxas atuais, consulte a página de preços do Azure OpenAI.

Os pontos de interrupção de cache de prompt funcionam com PTU-M?

Nos modelos GPT-5.6 e nas famílias de modelos posteriores, as implementações padrão pay-as-you-go suportam pontos de interrupção de cache por prompt e expor cache_write_tokens. As implementações gerenciadas por débito provisionado (PTU-M) continuam a suportar cache por prompt, mas não suportam pontos de interrupção de cache de prompt nem expose cache_write_tokens.

O armazenamento em cache de prompts funciona com a residência dos dados?

A cache de prompts em memória é compatível com todas as regiões de residência de dados. A cache de prompts estendida armazena temporariamente dados em máquinas GPU. Os dados mantêm-se dentro do limite da zona de dados para os tipos de implantação Data Zone Standard e Data Zone Provisioned, e dentro do limite regional para os tipos de implantação Regional Standard e Regional Provisioned.

Conteúdo relacionado

  • Last updated on