ການ Cache Prompt

ຫຼັກການເຮັດວຽກ

• Prefix, ຕາມລຳດັບ — Prompt ຈະຖືກອ່ານຕາມລຳດັບ: system prompt, tool definitions, ຈາກນັ້ນຈຶ່ງເປັນຂໍ້ຄວາມ. Cache ຈະກົງກັນນັບຈາກຈຸດເລີ່ມຕົ້ນຂອງລຳດັບນັ້ນ ຈົນຮອດ token ທຳອິດທີ່ມີການປ່ຽນແປງ.
• ສິ່ງທີ່ນັບວ່າເປັນ hit — Request ທີ່ prompt ເລີ່ມຕົ້ນດ້ວຍເນື້ອຫາທີ່ຄືກັນກັບ request ຫຼ້າສຸດ — ໂດຍທົ່ວໄປແມ່ນການສົນທະນາຮອບກ່ອນໜ້ານັ້ນ ທີ່ມີຂໍ້ຄວາມໃໝ່ຖືກເພີ່ມເຂົ້າໄປ. Prefix ທີ່ກົງກັນແມ່ນ cached input; ສ່ວນທີ່ເຫຼືອຫຼັງຈາກນັ້ນແມ່ນ regular input.
• ລະດັບຄວາມລະອຽດ — cache ເກັບ prompt ເປັນ block ລະ 1,568 tokens, ດັ່ງນັ້ນ prompt ທີ່ສັ້ນກວ່າປະມານ 1,500 tokens ຈະບໍ່ຖືກ cache. ຈຳນວນ cached ໃນຄຳຕອບແມ່ນຈຳນວນ input ຂອງທ່ານຄູນດ້ວຍສ່ວນທີ່ຖືກ cache ຂອງ prompt, ປັດລົງ. ມັນບໍ່ຈຳເປັນຕ້ອງເປັນຈຳນວນເທົ່າຂອງຂະໜາດ block.
• ເມື່ອບໍ່ມີ hit — ຄຳຮ້ອງຂໍທີ່ສ່ວນເລີ່ມຕົ້ນບໍ່ຢູ່ໃນ cache ຖືກຄິດເງິນຕາມອັດຕາ input ປົກກະຕິ. ບໍ່ມີການປະກາດອາຍຸຂອງ prompt ທີ່ຖືກ cache ແລະ ບໍ່ຮັບປະກັນ hit: ອ່ານ usage ເພື່ອເບິ່ງວ່າຄຳຮ້ອງຂໍໃຊ້ຫຍັງຈາກ cache.
• ບໍ່ມີສະວິດ — ຄຳຮ້ອງຂໍບໍ່ຕ້ອງເລືອກເຂົ້າ, ແລະ ບໍ່ມີຟີວໃດປິດ caching.
• Model ທີ່ຮອງຮັບ — ທຸກ hosted open-weight id. GET /v1/models ຈະລາຍງານ capabilities.prompt_caching: true ແລະ pricing.cached_input_per_million_usd ສໍາລັບ model ເຫຼົ່ານັ້ນ. Shannon models ຈະຄິດໄລ່ໃນອັດຕາຄົງທີ່.

ເບິ່ງ cache hit ໃນຄຳຕອບ

ສົ່ງສອງຄຳຮ້ອງຂໍທີ່ເລີ່ມດ້ວຍ system prompt ຍາວອັນດຽວກັນ ແລະ ພິມ usage ຂອງແຕ່ລະອັນ. ເລກທຳອິດແມ່ນ input ຂອງຄຳຮ້ອງຂໍ, ເລກທີສອງແມ່ນສ່ວນທີ່ອ່ານຈາກ cache.

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

ລາຄາ

Cached input tokens ຈະຖືກຄິດໄລ່ 25% ຂອງອັດຕາ input ຂອງ model, ປັດເປັນ $0.001 ຕໍ່ 1M. ການຂຽນລົງ cache ບໍ່ມີຄ່າໃຊ້ຈ່າຍເພີ່ມເຕີມ, ແລະ output ຈະຖືກຄິດໄລ່ຕາມປົກກະຕິ. ອັດຕາ cached ຂອງແຕ່ລະ id ຢູ່ໃນຕາຕະລາງ Models & pricing. Model ແລະ ລາຄາ

input ຂອງການເອີ້ນຄັ້ງໜຶ່ງຖືກຄິດເງິນເປັນ (input − cached) × ອັດຕາ input + cached × ອັດຕາ cached. ຈຳນວນ cached ບໍ່ເຄີຍໃຫຍ່ກວ່າຈຳນວນ input.

usage log ລະບຸ cached input ຂອງແຕ່ລະການເອີ້ນ. tokens ທີ່ຖືກຄິດເງິນ ແລະ ຄ່າໃຊ້ຈ່າຍຂອງມັນລວມອັດຕາ cached ແລ້ວ. 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
  }
}

ຄຳຕອບແບບ stream ມີຟີວດຽວກັນໃນ usage ສຸດທ້າຍ. ທ່ານບໍ່ຕ້ອງຂໍມັນ:

ວິທີເພີ່ມ cache hits

• ຮັກສາ system prompt ແລະ tool definitions ໃຫ້ຄົງທີ່ (stable) ລະຫວ່າງການເອີ້ນໃຊ້. ວາງຄ່າທີ່ປ່ຽນແປງໃນແຕ່ລະ call ເຊັ່ນ timestamps ຫຼື request ids ໄວ້ທີ່ຕອນທ້າຍຂອງຂໍ້ຄວາມຫຼ້າສຸດ, ບໍ່ແມ່ນໃນ system prompt.
• ໃຫ້ເພີ່ມຂໍ້ມູນ (append) ຕໍ່ທ້າຍ history ເທົ່ານັ້ນ. ການແກ້ໄຂ, ຕັດ ຫຼື ສະຫຼຸບຂໍ້ຄວາມໃນຮອບກ່ອນໜ້ານັ້ນ ຈະເຮັດໃຫ້ prefix ປ່ຽນແປງ, ແລະ ທຸກຢ່າງຫຼັງຈາກຈຸດທີ່ປ່ຽນແປງຈະຖືກຄິດໄລ່ເປັນ regular input.
• ຢ່າປ່ຽນລຳດັບຂອງ tools, ຂໍ້ຄວາມ ຫຼື content blocks ລະຫວ່າງການເອີ້ນໃຊ້, ແລະ ຈັດຮູບແບບ JSON (tool schemas, tool arguments ແລະ results) ໃຫ້ຄືກັນທຸກຄັ້ງ.
• ໃຊ້ model id ດຽວຕະຫຼອດບົດສົນທະນາ, ແລະ ສົ່ງການເອີ້ນຕໍ່ໄປໃຫ້ໄວຫຼັງຈາກການເອີ້ນກ່ອນໜ້າ.

API ຮັກສາສ່ວນເລີ່ມຕົ້ນຂອງບົດສົນທະນາໃຫ້ຄົງທີ່ໃນກໍລະນີເຫຼົ່ານີ້:

• ຂໍ້ຄວາມ system ຫຼື developer ທີ່ສົ່ງຕອນຫຼັງໃນບົດສົນທະນາຢູ່ບ່ອນເດີມຂອງມັນ. ມັນບໍ່ປ່ຽນສ່ວນເລີ່ມຕົ້ນຂອງ prompt, ດັ່ງນັ້ນ turn ກ່ອນມັນຍັງຖືກ cache.
• arguments ຂອງການເອີ້ນ tool ໃນ assistant turn ກ່ອນໜ້າຖືກປຽບທຽບດ້ວຍຄ່າ. ລຳດັບ key ແລະ ການເວັ້ນວັກຂອງ JSON ນັ້ນບໍ່ສຳຄັນ.
• ທັງສາມ endpoint ອ່ານບົດສົນທະນາແບບດຽວກັນ. ບົດສົນທະນາທີ່ສືບຕໍ່ໃນ endpoint ອື່ນຈະຮັກສາ prefix ຮ່ວມຂອງມັນໄວ້ ເມື່ອເນື້ອຫາຄືກັນ.

ຟິວຂອງຄຳຮ້ອງຂໍ (Request fields)

prompt_cache_key (ສຳລັບ Chat Completions ແລະ Responses) ແລະ cache_control ໃນ content blocks ຂອງ Messages ແມ່ນຖືກຮອງຮັບ, ດັ່ງນັ້ນ code ຂອງ client ເດີມຈຶ່ງເຮັດວຽກໄດ້ໂດຍບໍ່ຕ້ອງປ່ຽນແປງ. ທັງສອງບໍ່ໄດ້ຖືກບັງຄັບ: ການເຮັດ caching ແມ່ນເປັນອັດຕະໂນມັດ ແລະ ເຮັດວຽກໄດ້ຄືກັນໂດຍບໍ່ມີພວກມັນ.

ການນັບ tokens

ສອງ endpoint ທີ່ບໍ່ເສຍຄ່າ, POST /v1/tokenize ແລະ POST /v1/messages/count_tokens, ນັບ tokens ຂອງຂໍ້ຄວາມ ຫຼື ຂອງທັງຄຳຮ້ອງຂໍສຳລັບ hosted open-weight models ກ່ອນທີ່ທ່ານຈະສົ່ງ. ມັນມີໜ້າຂອງຕົນເອງ: ການນັບ token