Промпт кэштеу

Ол қалай жұмыс істейді

• Префикс, реттілігі бойынша — Промпт ретімен оқылады: жүйелік промпт, құрал анықтамалары, содан кейін хабарламалар. Кэш осы тізбектің басынан бастап, алғашқы айырмашылық токеніне дейін сәйкес келеді.
• Не hit (сәйкестік) деп есептеледі — Промпты жақындағы сұраныспен бірдей мазмұннан бастайтын сұраныс — әдетте жаңа хабарламалары қосылған бір сөйлесудің алдыңғы кезегі. Сәйкес келетін префикс кэштелген кіріс болып табылады; одан кейінгінің бәрі қарапайым кіріс болып саналады.
• Дерексіздік (Гранулярлық) — Кэш промптты 1,568 токендік блоктармен сақтайды, сондықтан шамамен 1,500 токеннен қысқа промпт кэштелмейді. Жауаптағы кэштелген сан — кіріс санының промптың кэштелген үлесіне көбейтіндісі, төмен қарай дөңгелектенген. Ол міндетті түрде блок өлшемінің еселігі емес.
• Hit болмағанда — Басы кэште жоқ сұрау әдеттегі кіріс бағасымен есептеледі. Кэштелген промпттар үшін өмір сүру мерзімі жарияланбайды және hit кепілдендірілмейді: сұраудың кэштен нені алғанын көру үшін usage оқыңыз.
• Қосқыш жоқ — Сұрау қосылмайды, ал кэштеуді өшіретін өріс жоқ.
• Қай модельдер — Әрбір хостингтік open-weight id. GET /v1/models олар үшін capabilities.prompt_caching: true және pricing.cached_input_per_million_usd мәндерін көрсетеді. Shannon модельдері бір тұрақты тариф бойынша есептеледі.

Жауаптан кэш hit-ін көру

Бірдей ұзын system prompt-пен басталатын екі сұрау жіберіп, әрқайсысының usage мәнін басып шығарыңыз. Бірінші сан — сұраудың кірісі, екіншісі — оның кэштен оқылған бөлігі.

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")

handbook = open("handbook.txt").read()  # a long text that stays the same


def ask(question):
    response = client.chat.completions.create(
        model="Kimi-K3-3BIT-REAP",
        messages=[
            {"role": "system", "content": handbook},
            {"role": "user", "content": question},
        ],
    )
    usage = response.usage
    print(usage.prompt_tokens, usage.prompt_tokens_details.cached_tokens)


ask("What is the refund policy?")
ask("Who approves travel?")  # same start: read the second number

import { readFileSync } from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });

const handbook = readFileSync("handbook.txt", "utf8"); // a long text that stays the same

async function ask(question) {
  const response = await client.chat.completions.create({
    model: "Kimi-K3-3BIT-REAP",
    messages: [
      { role: "system", content: handbook },
      { role: "user", content: question },
    ],
  });
  const usage = response.usage;
  console.log(usage.prompt_tokens, usage.prompt_tokens_details.cached_tokens);
}

await ask("What is the refund policy?");
await ask("Who approves travel?"); // same start: read the second number

# handbook.txt is a long text that stays the same. jq builds the JSON body from it
# and prints the usage object of the reply. Run it twice with different questions.
jq -Rs '{
    model: "Kimi-K3-3BIT-REAP",
    messages: [
      {role: "system", content: .},
      {role: "user", content: "What is the refund policy?"}
    ]
  }' handbook.txt \
  | curl -s https://api.shannon-ai.com/v1/chat/completions \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d @- \
  | jq .usage

Бағалау

Кэштелген кіріс токендері модельдің кіріс тарифінің 25% бойынша есептеледі, 1M үшін $0.001-ге дейін дөңгеленген. Кэшке жазу үшін қосымша төлем жасалмайды, ал шығыс әдеттегідей есептеледі. Әрбір id-нің кэш тарифі «Модельдер және бағалау» кестесінде көрсетілген. Модельдер және бағалар

Шақырудың кірісі (кіріс − кэштелген) × кіріс бағасы + кэштелген × кэштелген баға түрінде есептеледі. Кэштелген сан кіріс санынан ешқашан үлкен болмайды.

Usage журналы әр шақырудың кэштелген кірісін көрсетеді. Оның есептелген токендері мен құнына кэштелген баға қазірдің өзінде кіреді. Keys & usage

Қолдану алаңдары

{
  "usage": {
    "prompt_tokens": 20000,
    "completion_tokens": 812,
    "total_tokens": 20812,
    "prompt_tokens_details": {
      "cached_tokens": 18000
    },
    "completion_tokens_details": {
      "reasoning_tokens": 604
    }
  }
}

{
  "usage": {
    "input_tokens": 20000,
    "input_tokens_details": {
      "cached_tokens": 18000
    },
    "output_tokens": 812,
    "output_tokens_details": {
      "reasoning_tokens": 604
    },
    "total_tokens": 20812
  }
}

{
  "usage": {
    "input_tokens": 2000,
    "cache_read_input_tokens": 18000,
    "cache_creation_input_tokens": 0,
    "output_tokens": 812
  }
}

Стрим жауап соңғы usage-інде сол өрістерді алып жүреді. Оны сұрау қажет емес:

Кэш hit-лерін көбейту жолдары

• Сұраныстар арасында жүйелік промпт пен құрал анықтамаларын байт-бай тұрақты сақтаңыз. Уақыт белгілері немесе сұраныс ID-лері сияқты әр сұранысқа тән мәндерді жүйелік промптқа емес, соңғы хабарламаның соңына қойыңыз.
• Тарихқа тек мәлімет қосыңыз (append). Алдыңғы кезеңдерді өңдеу, қиып тастау немесе жинақтау префиксті өзгертеді, нәтижесінде алғашқы өзгерістен кейінгінің бәрі қарапайым кіріс ретінде есептеледі.
• Сұраныстар арасында құралдардың, хабарламалардың немесе мазмұн блоктарының ретін өзгертпеңіз және JSON (құрал схемалары, аргументтері мен нәтижелері) деректерін әрқашан бірдей тәсілмен сериялизациялаңыз.
• Бір сөйлесу үшін бір модель id-інде қалыңыз, ал жалғасатын шақыруды алдыңғысынан кейін көп кешіктірмей жіберіңіз.

API сөйлесудің басын мына жағдайларда тұрақты ұстайды:

• Сөйлесудің кейінірек жіберілген system немесе developer хабарламасы өз орнында қалады. Ол промптың басын өзгертпейді, сондықтан оның алдындағы кезеңдер кэштелген күйде қалады.
• Алдыңғы assistant кезеңдеріндегі құрал шақыруларының аргументтері мәні бойынша салыстырылады. Сол JSON-ның кілт реті мен бос орындары маңызды емес.
• Үш endpoint сөйлесуді бірдей оқиды. Басқа endpoint-те жалғастырылған сөйлесу мазмұны бірдей болса, ортақ префиксін сақтайды.

Сұрау алаңдары

prompt_cache_key (Chat Completions және Responses) және Messages контент-блоктарындағы cache_control қабылданады, сондықтан қолданыстағы клиенттік код өзгеріссіз жұмыс істейді. Екеуі де міндетті емес: кэштеу автоматты түрде жүзеге асырылады және оларсыз да бірдей жұмыс істейді.

Токендерді есептеу

Екі тегін endpoint, POST /v1/tokenize және POST /v1/messages/count_tokens, hosted open-weight модельдер үшін мәтіннің немесе бүкіл сұраудың токендерін жібермес бұрын есептейді. Олардың өз беті бар: Токендерді санау