QwenCloudBRASIL
Início›Biblioteca›Documentação
Tradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗

Melhores práticas de cache explícito

O cache explícito garante acessos determinísticos ao cache para conteúdo de entrada idêntico, adicionando marcadores de cache às suas solicitações, reduzindo significativamente o custo e a latência.

Este tópico descreve como usar o cache explícito e suas práticas recomendadas.

Quando usar cache explícito

Agente e ferramentas de codificação

Os seguintes agentes e ferramentas de codificação se conectam a QwenCloud através do protocolo Antrópico e suporta nativamente cache explícito. Configure-os seguindo a respectiva documentação e eles aproveitarão automaticamente o cache explícito para otimizar o gerenciamento de contexto.

Claude Code

Claude Code v2.x e posterior inclui automaticamente `cache_control` marcadores em solicitações (sistema, ambiente e mensagem do usuário mais recente). Nenhuma configuração adicional é necessária após conectar-se ao QwenCloudEndpoint compatível com Antrópico.

**Configuração**

Criar ou editar `~/.claude/settings.json` (Janelas: `C:\Users\<username>\.claude\settings.json`) com as configurações de plano apropriadas. Como alternativa, conecte-se por meio de variáveis de ambiente:

```bash
export ANTHROPIC_BASE_URL="https://maas.qwencloudapi.com/apps/anthropic"
export ANTHROPIC_AUTH_TOKEN="${DASHSCOPE_API_KEY}"
export ANTHROPIC_MODEL="qwen3.8-max"
claude
```

Defina o endpoint do protocolo Antrópico:

- Plano de Token (Equipe): `https://token-plan.maas.qwencloudapi.com/apps/anthropic`
- Pague conforme o uso: `https://maas.qwencloudapi.com/apps/anthropic`

Para obter detalhes, consulte [Código Claude](/developer-guides/clients-and-developer-tools/claude-code).

**Opcional: melhore a taxa de acertos entre sessões**

Por padrão, o Claude Code inclui informações dinâmicas no prompt do sistema (diretório atual, data, status do git), o que pode reduzir as taxas de acertos do cache entre sessões. Adicione o seguinte sinalizador na inicialização para mover seções dinâmicas para mensagens do usuário:

```bash
claude --exclude-dynamic-system-prompt-sections
```

Open Code

Quando o OpenCode se conecta a QwenCloudEndpoint compatível com Antrópico via `@ai-sdk/anthropic`, ele injeta automaticamente `cache_control` na mensagem do sistema e na mensagem não pertencente ao sistema mais recente.

**Instalação**

```bash
npm install -g opencode-ai
```

**Configuração**

Crie o arquivo de configuração `~/.config/opencode/opencode.json` (Janelas: `C:\Users\<username>\.config\opencode\opencode.json`):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "bailian": {
      "npm": "@ai-sdk/anthropic",
      "name": "Alibaba Cloud Model Studio",
      "options": {
        "baseURL": "https://maas.qwencloudapi.com/apps/anthropic/v1",
        "apiKey": "{env:DASHSCOPE_API_KEY}"
      },
      "models": {
        "qwen3.8-max": { "name": "qwen3.8-max" }
      }
    }
  }
}
```



  O `baseURL` deve terminar com `/v1`.



```bash
export DASHSCOPE_API_KEY=sk-xxxxx
opencode run -m "bailian/qwen3.8-max" "..."
```

Outros URLs base do plano:

- Plano de Token (Equipe): `https://token-plan.maas.qwencloudapi.com/apps/anthropic/v1`

Para obter detalhes, consulte [OpenCode](/developer-guides/clients-and-developer-tools/opencode).

OpenClaw

Ao usar o endpoint compatível com Anthropic, o OpenClaw injeta automaticamente `cache_control` marcadores no prompt do sistema e a mensagem do usuário mais recente. Nenhuma configuração adicional é necessária, desde que o URL base do provedor aponte para `/apps/anthropic`, o cache explícito é ativado automaticamente.

**Instalação**

```bash
npm install -g openclaw
# or
curl -fsSL https://openclaw.ai/install.sh | bash
```

**Configuração**

Edite o arquivo de configuração `~/.openclaw/openclaw.json`. Definir `"api"` para `"anthropic-messages"` e defina o URL base:

- Plano de Token (Equipe): `https://token-plan.maas.qwencloudapi.com/apps/anthropic/v1`
- Pague conforme o uso: `https://maas.qwencloudapi.com/apps/anthropic/v1`

Para obter detalhes, consulte [OpenClaw](/developer-guides/clients-and-developer-tools/openclaw).

**Opcional: limite de cache personalizado**

Se o prompt do sistema contiver conteúdo de modelo estável e conteúdo dinâmico (carimbos de data e hora, CWD, etc.), insira `<!-- OPENCLAW_CACHE_BOUNDARY -->` entre eles. OpenClaw será aplicado `cache_control` apenas para o prefixo estável antes do limite, melhorando as taxas de acerto entre sessões:

```plaintext
You are a Python engineer following these conventions:
- type hints required
- docstrings in Google format
<!-- OPENCLAW_CACHE_BOUNDARY -->
Current time: 2026-05-25 18:42
Working directory: /Users/.../project
```

Sem esse limite, o OpenClaw se aplica `cache_control` para todo o prompt do sistema usando sua estratégia integrada, ainda se beneficiando do cache explícito.

Hermes

Configurar usando o `hermes config set` comando. Defina o URL base:

- Plano de Token (Equipe): `https://token-plan.maas.qwencloudapi.com/apps/anthropic/v1`
- Pague conforme o uso: `https://maas.qwencloudapi.com/apps/anthropic/v1`

Para obter detalhes, consulte [Agente Hermes](/developer-guides/clients-and-developer-tools/hermes-agent).

Integração de API

Pontos-chave

Início rápido

O exemplo a seguir demonstra o fluxo de trabalho básico: a primeira solicitação cria um cache e a segunda solicitação o atinge.

OpenAI compatible

```python
from openai import OpenAI
import os
client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://maas.qwencloudapi.com/compatible-mode/v1",
)
# Long text to cache (must exceed 1024 tokens)
long_text_content = "<Your Long Text Here>" * 400
def get_completion(user_input):
  messages = [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": long_text_content,
          # Cache marker: content from the start of messages to this point will be cached
          "cache_control": {"type": "ephemeral"},
        }
      ],
    },
    {"role": "user", "content": user_input},
  ]
  completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=messages,
    extra_body={"enable_thinking": False},
  )
  return completion
# First request: creates cache
first = get_completion("Summarize the key points of this document")
print(f"Cache created: {first.usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"Cache hit: {first.usage.prompt_tokens_details.cached_tokens}")
# Second request: same system content, different question — hits cache
second = get_completion("What precautions are mentioned in the document?")
print(f"Cache created: {second.usage.prompt_tokens_details.cache_creation_input_tokens}")
print(f"Cache hit: {second.usage.prompt_tokens_details.cached_tokens}")
```

Anthropic compatible

```python
import anthropic
import os
client = anthropic.Anthropic(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://maas.qwencloudapi.com/apps/anthropic",
)
# Long text to cache (must exceed 1024 tokens)
long_text_content = "<Your Long Text Here>" * 400
def get_completion(user_input):
  response = client.messages.create(
    model="qwen3.8-max",
    max_tokens=1024,
    system=[
      {
        "type": "text",
        "text": long_text_content,
        # Cache marker
        "cache_control": {"type": "ephemeral"},
      }
    ],
    messages=[
      {"role": "user", "content": user_input},
    ],
  )
  return response
# First request: creates cache
first = get_completion("Summarize the key points of this document")
print(f"Cache created: {first.usage.cache_creation_input_tokens}")
print(f"Cache hit: {first.usage.cache_read_input_tokens}")
# Second request: hits cache
second = get_completion("What precautions are mentioned in the document?")
print(f"Cache created: {second.usage.cache_creation_input_tokens}")
print(f"Cache hit: {second.usage.cache_read_input_tokens}")
```

Resultado esperado:

Cache created: 2005
Cache hit: 0
Cache created: 0
Cache hit: 2005

A primeira solicitação cria um bloco de cache. A segunda solicitação atinge o cache porque o conteúdo do prompt do sistema é idêntico. Os tokens armazenados em cache são cobrados apenas 10% do preço de entrada padrão.

Verifique o status do cache

Verifique o usage campo na resposta para confirmar o comportamento do cache:

Melhores práticas por cenário

Conversas multivoltas

Características:

Prática recomendada: adicione um cache_control marcador para a última mensagem em cada solicitação. Cada turno atinge o cache criado pelo turno anterior (o histórico de conversas), enquanto cria um novo cache que inclui o turno atual para a próxima rodada.

Exemplo:

from openai import OpenAI
import os
client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://maas.qwencloudapi.com/compatible-mode/v1",
)
# System prompt: product manual (must exceed 1024 tokens)
product_manual = """You are the support assistant for "BaiLian SmartHome" smart home controller. Here is the complete product manual:
## Product Overview
BaiLian SmartHome is a whole-home smart controller supporting voice control, scene automation, and energy management...
## Installation Guide
1. Install at a central location with good WiFi coverage...
2. Connect the power adapter (5V/2A)...
## FAQ
Q: Cannot connect to WiFi? A: Make sure your router supports 2.4GHz...
""" * 80  # Repeat to exceed 1024 tokens
messages = [{"role": "system", "content": product_manual}]
def chat(user_input):
  # Key: add cache_control to the last user message
  messages.append({
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": user_input,
        "cache_control": {"type": "ephemeral"},
      }
    ],
  })
  completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=messages,
    extra_body={"enable_thinking": False},
  )
  assistant_msg = completion.choices[0].message.content
  messages.append({"role": "assistant", "content": assistant_msg})
  usage = completion.usage
  created = usage.prompt_tokens_details.cache_creation_input_tokens
  cached = usage.prompt_tokens_details.cached_tokens
  print(f"  [Cache] Created: {created} tokens, Hit: {cached} tokens")
  return assistant_msg
# Simulate multi-turn conversation
print("User: What voice assistants does BaiLian SmartHome support?")
print(f"Agent: {chat('What voice assistants does BaiLian SmartHome support?')[:80]}...\n")
print("User: What if I cannot connect to WiFi?")
print(f"Agent: {chat('What if I cannot connect to WiFi?')[:80]}...\n")
print("User: How many devices can it control simultaneously?")
print(f"Agent: {chat('How many devices can it control simultaneously?')[:80]}...")

A partir do segundo turno, cada solicitação atinge o cache do turno anterior (o histórico da conversa), enquanto cria um novo cache que inclui o turno atual. Quanto mais voltas na conversa, maior será a economia.

Agente de produção (múltiplos marcadores de cache)

Características:

Prática recomendada: use vários marcadores de cache (até quatro) para fixar conteúdo em diferentes níveis de estabilidade. Cada marcador deve estar em uma mensagem separada (função diferente) para servir como um ponto de interrupção independente:

Exemplo: Este exemplo simula uma arquitetura típica de Agente com três marcadores de cache fixando a persona e as ferramentas do sistema (marcador 1), base de conhecimento (marcador 2) e histórico de conversas (marcador 3). Observe que a base de conhecimento é colocada em uma mensagem do usuário para garantir que ela tenha seu próprio ponto de interrupção de cache independente — diversas mensagens do sistema são mescladas internamente e não podem servir como pontos de interrupção separados:

from openai import OpenAI
import os
client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://maas.qwencloudapi.com/compatible-mode/v1",
)
# Layer 1: System persona (rarely changes)
system_persona = """You are the senior AI support agent for "Model Studio Electronics". Your guidelines:
1. Answer questions based on the knowledge base
2. For information not in the knowledge base, say "Let me transfer you to a human agent"
3. Maintain a professional and friendly tone
4. If the user is unhappy, apologize first then resolve the issue
Below is your complete service specification and script guide:
""" + "Detailed service specification..." * 200  # Ensure > 1024 tokens
# Layer 2: Tools/skills definitions (changes occasionally, e.g. when new features launch)
tools_description = """### Available Tools
- search_product(query): Search product information
- check_inventory(sku, color): Check stock status
- create_ticket(type, description): Create a support ticket
- transfer_to_human(reason): Transfer to a human agent
### Tool Usage Rules
1. When user asks about product details, use search_product first
2. When user asks about stock/shipping, use check_inventory
3. When user requests return/exchange, use create_ticket
4. When a tool returns an error, apologize and transfer_to_human
""" + "Detailed tool usage examples..." * 150  # Ensure > 1024 tokens
# Layer 3: Project knowledge base (semi-stable, changes when user switches products)
knowledge_base_product_a = """### Current product: Model Studio Pro Max Wireless Earbuds
- SKU: BL-PM-2024
- Price: $89
- Colors: Night Black / Nebula White / Ice Blue
- Battery: 8 hours (ANC on), 12 hours (ANC off)
- Water resistance: IPX5
- Warranty: 1 year, 7-day no-questions-asked return
- Stock: Night Black (in stock) / Nebula White (low) / Ice Blue (out of stock)
""" * 50  # Ensure > 1024 tokens
def ask_agent(user_question, history=None):
  if history is None:
    history = []
  messages = [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": system_persona + "\n\n" + tools_description,
          "cache_control": {"type": "ephemeral"},  # Marker 1: system persona + tools
        }
      ],
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": f"Here is the knowledge base for the current product:\n{knowledge_base_product_a}",
          "cache_control": {"type": "ephemeral"},  # Marker 2: knowledge base
        }
      ],
    },
    {"role": "assistant", "content": "Got it. I have the product details ready. How can I help you?"},
  ]
  messages.extend(history)
  # Add current question with marker 3
  messages.append({
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": user_question,
        "cache_control": {"type": "ephemeral"},  # Marker 3: conversation history
      }
    ],
  })
  completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=messages,
    extra_body={"enable_thinking": False},
  )
  usage = completion.usage
  print(f"  Created: {usage.prompt_tokens_details.cache_creation_input_tokens}, "
        f"Hit: {usage.prompt_tokens_details.cached_tokens}")
  return completion.choices[0].message.content
# First request
print("Q1: Is the Ice Blue color available?")
a1 = ask_agent("Is the Ice Blue color available?")
print(f"A1: {a1}\n")
# Second request: same product (persona + tools + knowledge base all hit)
history = [
  {"role": "user", "content": "Is the Ice Blue color available?"},
  {"role": "assistant", "content": a1},
]
print("Q2: When will it be back in stock?")
a2 = ask_agent("When will it be back in stock?", history)
print(f"A2: {a2}")

Como funciona o cache de vários marcadores:

Processamento em lote (conclusão de tarefa)

Características:

Prática recomendada: adicione o cache_control marcador apenas no prompt do sistema. Todas as solicitações subsequentes chegam ao cache, desde que o prompt do sistema permaneça inalterado.

Chamada de função com definições de ferramentas em cache

Características:

Prática recomendada: A tools o conteúdo do parâmetro faz parte do prompt do sistema para armazenamento em cache. Certifique-se de que as definições de ferramentas sejam exatamente idênticas em todas as solicitações (mesma ordem, mesma ordem de campo, mesma estrutura) e adicione um cache_control marcador para o conteúdo da mensagem.

Chaves para maximizar os acessos ao cache de chamadas de função:

Notas importantes

Modelos suportados

Para obter a lista de modelos que suportam cache explícito, consulte Cache de contexto.