Cache de prompts

O cache de prompts permite reduzir a latência geral da solicitação e o custo de prompts mais longos que têm conteúdo idêntico no início do prompt. "Prompt" neste contexto está se referindo à entrada que você envia para o modelo como parte de suas conclusões de chat ou solicitações de criação de resposta. Em vez de reprocessar os mesmos tokens de entrada repetidamente, o serviço é capaz de manter um cache temporário de cálculos de token de entrada processados para melhorar o desempenho geral. O armazenamento em cache de prompts não afeta o conteúdo de saída retornado na resposta do modelo, exceto pela redução na latência e no custo.

Para modelos com suporte, os tokens armazenados em cache são cobrados com desconto no preço do token de entrada para tipos de implantação Standard e até 100% desconto em tokens de entrada para tipos de implantação provisionados. O preço do cache de prompt é o mesmo para ambas as políticas de retenção.

Retenção de cache de prompt

O cache de prompts pode usar políticas de retenção em memória ou políticas de retenção estendidas. Quando disponível, o Cache de Prompt Estendido visa manter o cache por mais tempo, de modo que as solicitações subsequentes sejam mais propensas a corresponder ao 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 Conversa.

Retenção de cache de prompt na memória

Os caches normalmente são limpos dentro de 5 a 10 minutos de inatividade e sempre são removidos dentro de uma hora do último uso do cache. Os caches de prompt não são compartilhados entre assinaturas da Azure.

Suporta-se a retenção de cache de solicitação na memória com todos os modelos Azure OpenAI GPT-4 ou mais recentes. Essa aplicação é destinada a modelos que oferecem completude de chat, conclusão, respostas ou operações em tempo real. Para modelos que não têm essas operações, esse recurso não está disponível.

Retenção estendida de cache de prompt

A retenção estendida de cache de prompt mantém os prefixos armazenados em cache ativos por mais tempo, até um máximo de 24 horas. O cache de prompt estendido funciona descarregando os tensores de chave/valor para o armazenamento local de GPU quando a memória estiver cheia, aumentando significativamente a capacidade de armazenamento disponível para cache.

A retenção estendida de cache de prompt 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 por solicitação

Para gpt-5.4 modelos e modelos mais antigos, se você 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 tem suporte.

{
  "model": "gpt-5.4",
  "input": "Your prompt goes here...",
  "prompt_cache_retention": "24h"
}

Introdução

Para aproveitar o cache de prompts, uma solicitação deve atender aos dois requisitos:

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

As solicitações são roteadas com base em um hash do prefixo inicial de um prompt. O hash normalmente usa os primeiros 256 tokens, embora o comprimento exato varie dependendo do modelo.

Quando uma correspondência é encontrada entre as computações de token em um prompt e o conteúdo atual do cache de prompt, ela é conhecida como um acerto de cache. Os acertos de cache exibirão como cached_tokens sob prompt_tokens_details na resposta de completamento 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, os acertos de cache ocorrerão a cada 128 tokens adicionais idênticos.

Uma única diferença de caractere nos primeiros 1.024 tokens resultará em uma perda de cache caracterizada por um cached_tokens valor de 0. O cache de prompt é habilitado por padrão sem nenhuma configuração adicional necessária para modelos com suporte.

Se você fornecer o parâmetro prompt_cache_key, ele será combinado com o hash do prefixo, permitindo que você influencie o roteamento e melhore as taxas de acerto do cache. Isso é especialmente benéfico quando muitas solicitações compartilham prefixos longos e comuns. Se as solicitações para a combinação de prefixo e prompt_cache_key excederem uma determinada taxa (aproximadamente 15 solicitações por minuto), algumas poderão transbordar e serem roteadas para máquinas adicionais, reduzindo a eficácia do cache.

Perguntas frequentes

O que é armazenado em cache?

O suporte a recursos de modelos da série o1 varia de acordo com o modelo. Para obter mais informações, consulte nosso guia de modelos de raciocínio dedicados.

Há suporte para o cache de prompt para:

Para melhorar a probabilidade de acessos ao cache, você deve estruturar suas solicitações de modo que o conteúdo repetitivo ocorra no início do array de mensagens.

Posso desabilitar o cache de prompts?

O cache de prompt é habilitado por padrão para todos os modelos com suporte. Não há suporte para desativação do cache de prompts.

O cache de prompts é compatível com a residência de dados?

O cache de prompt na memória é compatível com todas as Regiões de Residência de Dados. O cache de prompt estendido armazena temporariamente dados em máquinas GPU e só será mantido na região ao usar os tipos de implantação Padrão Regional ou Provisionados Regionais.