Panduan Cache Konteks OpenAI

Untuk model GPT-5.6 dan yang lebih baru yang mendukung fitur ini, atur prompt_cache_options.ttl dalam permintaan Responses API untuk memilih masa cache minimum 30 menit atau 12 jam. Contoh menggunakan gpt-6.1-terra.

Cache 12 jam hanya didukung oleh /v1/responses, bukan /v1/chat/completions. TTL menentukan masa minimum, bukan batas waktu penghapusan atau jaminan bahwa setiap permintaan menggunakan cache.

Atur kunci API

export API_KEY="YOUR_API_KEY"

Teks panjang dalam contoh adalah teks pengganti. Ganti dengan konten yang ingin digunakan kembali. Prefiks yang akan disimpan harus berisi minimal 1.024 token; teks pengganti pendek ini saja tidak memicu penulisan cache.

Menggunakan cache 30 menit

Atur prompt_cache_options.ttl ke "30m". Jika ttl dihilangkan, nilainya juga 30 menit. Jika mode dihilangkan, cache implisit digunakan dan layanan hulu memilih titik batas cache secara otomatis.

curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "30m"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)... Summarize the key points."
        }
      ]
    }
  ]
}'

Menggunakan cache 12 jam

Ubah kolom yang sama menjadi "12h" dan pertahankan struktur permintaan lainnya:

curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "12h"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)... Summarize the key points."
        }
      ]
    }
  ]
}'

Menggunakan prefiks tetap untuk pertanyaan berbeda

Untuk menggunakan kembali dokumen panjang sambil mengubah hanya pertanyaan terakhir, atur mode ke "explicit" dan tambahkan prompt_cache_breakpoint pada blok input_text di akhir konten tetap. Contoh ini menggunakan 12 jam; untuk 30 menit, ubah TTL permintaan menjadi "30m".

Mengatur mode: "explicit" tanpa titik batas menonaktifkan pembacaan dan penulisan cache. Titik batas di bawah tidak memiliki TTL tersendiri, sehingga mewarisi prompt_cache_options.ttl dari permintaan.

curl "https://api.apimart.ai/v1/responses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-6.1-terra",
  "prompt_cache_options": {
    "ttl": "12h",
    "mode": "explicit"
  },
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Long reference material to reuse (at least 1024 tokens)...",
          "prompt_cache_breakpoint": {
            "mode": "explicit"
          }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Summarize the three main points in the reference material."
        }
      ]
    }
  ]
}'

Kirim model, prefiks tetap, dan titik batas yang sama pada permintaan berikutnya. Ubah hanya pesan pengguna terakhir. Pertahankan konten, urutan, dan pengaturan yang memengaruhi konteks. Anda tidak perlu membuat atau mengirim ID cache.

Memeriksa penggunaan cache

Periksa usage.input_tokens_details dalam respons:

cached_tokens: Token yang dibaca dari cache dalam permintaan ini. Nilai di atas 0 menunjukkan pembacaan cache.
cache_write_tokens: Total token yang ditulis ke cache dalam permintaan ini.
cache_write_tokens_details.ttl_30m_tokens: Token yang ditulis dengan TTL 30 menit dalam permintaan ini.
cache_write_tokens_details.ttl_12h_tokens: Token yang ditulis dengan TTL 12 jam dalam permintaan ini.

Setelah penulisan pertama, kirim permintaan lagi dengan prefiks tetap yang sama dan periksa cached_tokens. Nilainya bisa 0 jika prefiks terlalu pendek, konten berubah, atau cache tidak cocok.

Contoh cache usage dan penghitungan token

Cuplikan respons ini hanya menampilkan usage untuk model OpenAI yang mendukung cache, dengan penulisan pada kedua TTL. Nilai aktual mengikuti respons.

{
  "usage": {
    "input_tokens": 12000,
    "input_tokens_details": {
      "cached_tokens": 4000,
      "cache_write_tokens": 7000,
      "cache_write_tokens_details": {
        "ttl_30m_tokens": 5000,
        "ttl_12h_tokens": 2000
      }
    },
    "output_tokens": 1000,
    "total_tokens": 13000
  }
}

Token masukan biasa:

input_tokens - input_tokens_details.cached_tokens - input_tokens_details.cache_write_tokens

cache_write_tokens = ttl_30m_tokens + ttl_12h_tokens
total_tokens = input_tokens + output_tokens

Pembacaan dan penulisan cache sudah termasuk dalam input_tokens. Kedua hitungan TTL adalah bagian dari cache_write_tokens: jangan menjumlahkan kembali total dan rinciannya, atau menambahkan pembacaan dan penulisan cache ke total masukan. Di sini, masukan biasa adalah 12000 - 4000 - 7000 = 1000, penulisan adalah 5000 + 2000 = 7000, dan total token adalah 12000 + 1000 = 13000. Lihat panduan resmi cache prompt OpenAI untuk perilaku cache.

Ikhtisar

Model

Seri Teks

Seri Gambar

Seri Video

Seri Audio

Seri Moderasi

Manajemen Unggahan

Manajemen Tugas

Manajemen Akun

Panduan Cache Konteks OpenAI

Atur kunci API

Menggunakan cache 30 menit

Menggunakan cache 12 jam

Menggunakan prefiks tetap untuk pertanyaan berbeda

Memeriksa penggunaan cache

Contoh cache usage dan penghitungan token

​Atur kunci API

​Menggunakan cache 30 menit

​Menggunakan cache 12 jam

​Menggunakan prefiks tetap untuk pertanyaan berbeda

​Memeriksa penggunaan cache

​Contoh cache usage dan penghitungan token

Atur kunci API

Menggunakan cache 30 menit

Menggunakan cache 12 jam

Menggunakan prefiks tetap untuk pertanyaan berbeda

Memeriksa penggunaan cache

Contoh cache usage dan penghitungan token