Context caching pe disc în API-ul DeepSeek în DeepSeek (V4 & R1): explicație și exemple

Context Caching on Disk este activ implicit pentru toți utilizatorii și nu cere modificări de cod. Fiecare cerere construiește un cache pe disc; dacă o cerere ulterioară începe cu un prefix deja salvat, partea comună se citește din cache și se numără ca „cache hit”. Diferența de preț este mare: la deepseek-flash, în orele de vârf, 1M tokeni de intrare costă $0,006 din cache și $0,30 în afara lui (vezi modele și prețuri).

Din cauza mecanismului Sliding Window Attention, fiecare prefix salvat este o unitate completă, iar o cerere are cache hit doar dacă se potrivește integral cu o unitate. Unitățile se creează la sfârșitul intrării utilizatorului și la sfârșitul ieșirii modelului, când sistemul detectează un prefix comun mai multor cereri și, la intrări sau ieșiri lungi, la intervale fixe de tokeni. Exemplul din documentație: după A + B, cererea A + B + C are hit pe A + B; după A + B, cererea A + C nu are hit, dar sistemul salvează A, iar o a treia cerere A + D va avea hit.

Cache-ul funcționează pe principiul best-effort, fără garanția unei rate de 100%. Construirea lui durează câteva secunde, iar un cache nefolosit se șterge automat, de obicei în câteva ore până la câteva zile. Cache-ul privește doar prefixul intrării; ieșirea se generează din nou. Cu user_id poți izola cache-ul KV între utilizatorii aplicației tale.

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
`usage.prompt_cache_hit_tokens`	Tokenii de intrare găsiți în cache.
`usage.prompt_cache_miss_tokens`	Tokenii de intrare care nu au fost în cache; `prompt_tokens` = hit + miss.
`usage.prompt_tokens_details.cached_tokens`	Același număr ca `prompt_cache_hit_tokens`, în câmpul compatibil OpenAI.
`user_id`	Izolează cache-ul KV, programarea și verificarea conținutului pe utilizator; șir `[a-zA-Z0-9-_]+` de cel mult 512 caractere, fără date personale.
`Prețuri cache hit (vârf / în afara vârfului)`	`deepseek-flash`: $0,006 / $0,003; `deepseek-v4-pro`: $0,044 / $0,022, pe 1M tokeni.
`cache_control (format Anthropic)`	Ignorat: cache-ul DeepSeek este automat.

Exemple practice și scenarii reale

Exemplul 1: Întrebări repetate despre același document

Ca în exemplul oficial: primele două cereri nu au hit; după ele, sistemul salvează prefixul comun (mesajul de sistem + raportul), iar a treia cerere are hit.

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"], base_url="https://api.deepseek.com")
raport = open("raport_financiar.txt", encoding="utf-8").read()
SISTEM = "Ești un analist de rapoarte financiare."

for intrebare in ["Rezumă informațiile cheie.",
                  "Analizează profitabilitatea.",
                  "Care este raportul dintre venituri și cheltuieli?"]:
    r = client.chat.completions.create(
        model="deepseek-flash",
        messages=[
            {"role": "system", "content": SISTEM},
            {"role": "user", "content": raport + "\n\n" + intrebare},   # partea fixă întâi
        ],
    )
    u = r.usage
    print(intrebare, "hit:", u.prompt_cache_hit_tokens, "miss:", u.prompt_cache_miss_tokens)

Exemplul 2: Conversație cu mai multe ture

Cererea a doua reia exact prima cerere ca prefix, deci se potrivește cu unitatea salvată la sfârșitul ei.

messages = [
    {"role": "system", "content": "Ești un asistent util."},
    {"role": "user", "content": "Care este capitala Franței?"},
]
r1 = client.chat.completions.create(model="deepseek-flash", messages=messages)

messages.append({"role": "assistant", "content": r1.choices[0].message.content})
messages.append({"role": "user", "content": "Dar a Italiei?"})
r2 = client.chat.completions.create(model="deepseek-flash", messages=messages)
print(r2.usage.prompt_cache_hit_tokens)

Exemplul 3: Cache separat pentru fiecare client al aplicației

r = client.chat.completions.create(
    model="deepseek-flash",
    messages=messages,
    extra_body={"user_id": "client-4821"},   # fără nume, e-mail sau alte date personale
)

Greșeli frecvente și capcane

Pui la începutul promptului date care se schimbă (ora curentă, ID-ul cererii). Prefixul diferă la fiecare cerere și nu mai există hit; mută-le la final.
Te aștepți la hit pe o parte dintr-un prefix salvat. Unitățile se potrivesc doar integral; prefixul comun se salvează abia după ce sistemul îl detectează în mai multe cereri.
Adaugi cache_control în formatul Anthropic ca să forțezi cache-ul. DeepSeek îl ignoră.

`Context caching pe disc în API-ul DeepSeek` în DeepSeek (V4 & R1)