Cache de prompts

A cache de prompts permite-lhe reduzir a latência e o custo total dos pedidos para prompts mais longos que tenham conteúdo idêntico no início do prompt. "Prompt" neste contexto refere-se à entrada 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 consegue manter uma cache temporária de cálculos de tokens de entrada processados 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, os tokens em cache são faturados com desconto no preço dos tokens de entrada para 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.

Retenção de cache por prompt

Prompt Caching pode usar políticas de retenção em memória ou estendidas. Quando disponível, o Extended Prompt Caching visa manter a cache por mais tempo, para que os pedidos subsequentes tenham maior probabilidade de corresponder à cache.

Para configurar a política de retenção de cache de prompt, defina o parâmetro prompt_cache_retention na API de Respostas ou Conclusões de Chat.

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

As caches são normalmente limpas dentro de 5-10 minutos após a inatividade e são sempre removidas dentro de uma hora após a última utilização da cache. As caches de prompts não são partilhadas entre subscrições do Azure.

A retenção de cache de prompt em memória é suportada em todos os modelos Azure OpenAI GPT-4 ou mais recentes. 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 Prompt Cache Estendido funciona descarregando os tensores chave/valor para armazenamento local da GPU quando a memória está cheia, aumentando significativamente a capacidade de armazenamento disponível para cache.

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

• gpt-5.4
• gpt-5.3-codex
• gpt-5.2
• gp5-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 todos os modelos mais recentes, o padrão é 24h e in_memory não é suportado.

{
  "model": "gpt-5.4",
  "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.

Os pedidos são encaminhados com base num hash do prefixo inicial de um prompt. O hash normalmente utiliza os primeiros 256 tokens, embora o comprimento exato varie consoante o modelo.

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. Os acessos ao cache aparecerão como cached_tokens sob prompt_tokens_details na resposta de conclusão do chat.

{
  "created": 1729227448,
  "model": "o1-2024-12-17",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": "fp_50cdd5dc04",
  "usage": {
    "completion_tokens": 1518,
    "prompt_tokens": 1566,
    "total_tokens": 3084,
    "completion_tokens_details": {
      "audio_tokens": null,
      "reasoning_tokens": 576
    },
    "prompt_tokens_details": {
      "audio_tokens": null,
      "cached_tokens": 1408
    }
  }
}

Após os primeiros 1.024 tokens, ocorrerão ocorrências de acessos ao cache para cada 128 tokens idênticos adicionais.

Uma diferença de um carácter nos primeiros 1.024 tokens resultará numa falha de cache caracterizada por um cached_tokens valor de 0. O cache de prompts está ativado por padrão, sem precisar de configuração adicional para modelos suportados.

Se você fornecer o parâmetro prompt_cache_key, ele será combinado com o prefixo hash, permitindo que você influencie o encaminhamento e melhore as taxas de acerto de cache. Isto é especialmente benéfico quando muitos pedidos partilham prefixos longos e comuns. Se os pedidos para o mesmo prefixo e prompt_cache_key combinação excederem uma certa taxa (aproximadamente 15 pedidos por minuto), alguns podem transbordar e ser encaminhados para máquinas adicionais, reduzindo a eficácia do cache.

Perguntas frequentes

O que está armazenado em cache?

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

O cache por prompts é suportado para:

Para aumentar a probabilidade de ocorrerem acessos à cache, deve estruturar os seus pedidos de forma a que o conteúdo repetitivo ocorra no início do array de mensagens.

Posso desativar a cache do prompt?

O cache de prompts está ativado por padrão para todos os modelos suportados. Não há suporte de opt-out para cache de prompts.

O Prompt Caching funciona com Data Residency?

A cache de prompts em memória é compatível com todas as regiões de residência de dados. A cache de prompt estendida armazena temporariamente dados em máquinas GPU e só será mantida na mesma região ao utilizar os tipos de implementação Regional Standard ou Regional Provisioned.