Caching prompt

Cách thức hoạt động

• Tiền tố, theo thứ tự — Prompt được đọc theo thứ tự: system prompt, định nghĩa tool, sau đó là các tin nhắn. Cache sẽ khớp từ đầu chuỗi đó cho đến token đầu tiên có sự khác biệt.
• Thế nào là một hit — Một request có prompt bắt đầu bằng nội dung giống với một request gần đây — thường là lượt hội thoại trước đó với các tin nhắn mới được chèn thêm. Tiền tố khớp nhau là cached input; mọi thứ sau đó là regular input.
• Độ chi tiết — Cache lưu prompt theo các khối 1,568 token, nên prompt ngắn hơn khoảng 1,500 token sẽ không được cache. Số cached trong phản hồi bằng số input của bạn nhân với phần prompt được cache, làm tròn xuống. Nó không nhất thiết là bội số của kích thước khối.
• Khi không có cache hit — Yêu cầu có phần đầu không nằm trong cache sẽ bị tính phí theo giá input thông thường. Không có thời gian lưu nào được công bố cho prompt đã cache và cache hit không được đảm bảo: hãy đọc usage để biết yêu cầu đã lấy được gì từ cache.
• Không có công tắc — Yêu cầu không cần đăng ký tham gia, và không có trường nào tắt được caching.
• Các model áp dụng — Mọi hosted open-weight id. GET /v1/models báo cáo capabilities.prompt_caching: true và pricing.cached_input_per_million_usd cho chúng. Các model Shannon tính một mức giá cố định.

Xem một cache hit trong phản hồi

Gửi hai yêu cầu bắt đầu bằng cùng một system prompt dài và in usage của từng yêu cầu. Số thứ nhất là input của yêu cầu, số thứ hai là phần trong đó được đọc từ 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

Giá cả

Cached input tokens được tính phí 25% mức giá input của model, làm tròn đến $0.001 cho mỗi 1M. Việc ghi vào cache không tốn thêm phí, và output được tính phí như bình thường. Giá cache của mỗi id nằm trong bảng Models & pricing. Model và giá

Đầu vào của một lần gọi được tính phí theo (input − cached) × giá input + cached × giá cached. Số cached không bao giờ lớn hơn số input.

Nhật ký sử dụng liệt kê đầu vào cached của từng lần gọi. Số token bị tính phí và chi phí của nó đã bao gồm giá cached. Keys & usage

Trường sử dụng

{
  "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
  }
}

Phản hồi dạng stream mang các trường giống nhau trong usage cuối. Bạn không cần yêu cầu nó:

Cách tăng tỷ lệ cache hit

• Giữ system prompt và định nghĩa tool ổn định tuyệt đối giữa các lần gọi. Đặt các giá trị thay đổi theo từng lần gọi như timestamp hoặc request id ở cuối tin nhắn mới nhất, thay vì trong system prompt.
• Chỉ chèn thêm vào lịch sử. Việc chỉnh sửa, cắt tỉa hoặc tóm tắt các lượt trước đó sẽ thay đổi tiền tố, và mọi thứ sau thay đổi đầu tiên sẽ bị tính phí là regular input.
• Không thay đổi thứ tự các tool, tin nhắn hoặc khối nội dung giữa các lần gọi, và serialize JSON (tool schemas, tool arguments và results) theo cùng một cách mỗi lần.
• Hãy giữ một model id cho cả cuộc hội thoại, và gửi lần gọi tiếp theo sớm sau lần gọi trước.

API giữ phần đầu của cuộc hội thoại ổn định trong các trường hợp sau:

• Tin nhắn system hoặc developer được gửi muộn hơn trong cuộc hội thoại giữ nguyên vị trí của nó. Nó không làm thay đổi phần đầu của prompt, nên các lượt trước nó vẫn được cache.
• Các đối số của lần gọi tool trong những lượt assistant trước được so sánh theo giá trị. Thứ tự khóa và khoảng trắng của JSON đó không quan trọng.
• Ba endpoint đọc một cuộc hội thoại theo cùng một cách. Cuộc hội thoại được tiếp tục trên endpoint khác vẫn giữ nguyên phần tiền tố chung khi nội dung giống nhau.

Các trường yêu cầu

prompt_cache_key (Chat Completions và Responses) và cache_control trên các khối nội dung Messages được chấp nhận, vì vậy mã nguồn client hiện tại vẫn chạy bình thường. Cả hai đều không bắt buộc: việc caching là tự động và hoạt động tương tự nếu không có chúng.

Đếm tokens

Hai endpoint miễn phí, POST /v1/tokenize và POST /v1/messages/count_tokens, đếm số token của một đoạn văn bản hoặc của cả yêu cầu cho các model open-weight hosted trước khi bạn gửi. Chúng có trang riêng: Đếm token