Context & cache

Workload context dài và agent sống chết ở ba thứ: biết giới hạn, biết mình đang ở đâu so với nó, và hưởng giá cache mà không phải làm gì đặc biệt. Trang này nói cả ba — kèm một cam kết: chúng tôi không bao giờ viết lại hay cắt bớt messages của bạn.

Cửa sổ context

Mỗi model có cửa sổ context cố định tính trên token input CỘNG ngân sách max_tokens — nhà cung cấp đếm cả hai khi quyết request có vừa không, nên prompt còn dưới cửa sổ vẫn có thể bị từ chối nếu max_tokens đẩy tổng vượt trần.

Danh sách sống ở trang models và GET /v1/models. Độ dài output bị chặn riêng bởi max_tokens (mặc định 16.384 mỗi request cho một tổ chức).

Khi request quá lớn

Request quá cỡ fail nhanh với 400 context_length_exceeded — bị từ chối trước khi model chạy, nên không bị tính tiền. Message mang số ước lượng và giới hạn:

# 400 context_length_exceeded
{
  "error": {
    "message": "Estimated 332876 tokens (input + max_tokens) exceeds the model context window of 262144 tokens. Reduce message length or max_tokens.",
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "param": null
  }
}

• Đừng retry y nguyên. Cùng payload thì lần nào cũng bị từ chối y hệt. Rút gọn hội thoại hoặc giảm max_tokens rồi mới gửi lại.
• Cửa kiểm là ước lượng. Ngưỡng từ chối tính từ phép xấp xỉ, không phải chạy tokenizer chính xác — hãy coi các con số là ranh cứng có chút nhiễu, chừa lề thay vì tính sát từng token.

Đếm token trước khi gửi

POST /v1/count_tokens trả ước lượng cho messages của bạn mà không đụng model — miễn phí, không trừ rate limit, không tính tiền:

curl https://api.clfaigateway.dev/v1/count_tokens \
  -H "Authorization: Bearer sk-gw-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k2.6",
    "messages": [{"role": "user", "content": "Summarize this repository..."}]
  }'

# 200
{
  "object": "token_count",
  "model": "kimi-k2.6",
  "estimated": true,
  "method": "chars-per-model",
  "estimated_input_tokens": 1210,
  "context_window": 262144
}

Ước lượng là ceil(tổng ký tự content / 4) — cùng họ xấp xỉ với cửa kiểm của nhà cung cấp, đó là lý do chúng tôi mô phỏng nó thay vì chạy một tokenizer sẽ cãi nhau với người gác cổng. Response dán nhãn "estimated": true, và sai số trung thực đo trên usage thật là:

Header context trên mọi response

Prefix cache tự động

Prompt caching là tự động. Không có field nào để bật, không header nào phải gửi — tiền tố prompt lặp lại được phục vụ từ cache của nhà cung cấp và tính giá cached_input rẻ hơn (xem giá live) bất kể request rơi vào đâu.

• Cache tính theo block 64 token — prompt rất ngắn không cache được; phần lợi bắt đầu từ vài trăm token tiền tố ổn định.
• Tiền tố đã cache còn ấm ít nhất một giờ khi được dùng lại — dư sức phủ phiên chat và vòng lặp agent.
• Giữ tiền tố ổn định từng byte để hưởng giá: system prompt cố định đứng đầu, lịch sử chỉ nối thêm, và đừng đặt timestamp, request id hay giá trị ngẫu nhiên gần đầu hội thoại. Một byte đổi ở đầu prompt là mọi block phía sau mất cache.
• Định nghĩa tools được serialize tất định bởi gateway (thứ tự khóa ổn định), nên cùng một bộ tools không bao giờ vô tình phá cache.

Chúng tôi không bao giờ sửa messages của bạn

Gateway forward messages đúng nguyên văn bạn gửi — không cắt bớt, không tóm tắt, không nén giữa chừng, không bao giờ, kể cả dưới dạng opt-in. Request không vừa thì fail to tiếng bằng lỗi phía trên thay vì bị âm thầm gọt thành một câu hỏi khác. Chiến lược quản lý context (cửa sổ trượt, tóm tắt lượt cũ) thuộc về ứng dụng của bạn, nơi bạn biết cái gì quan trọng; API này bảo đảm model thấy đúng thứ bạn đã gửi.