استخدام التخزين المؤقت لمطالبات Claude مع cache_control: تكاليف كاش 5 دقائق مقابل ساعة واحدة

في التخزين المؤقت لمطالبات Claude رقم جميل واحد وفخ سهل الوقوع فيه: قراءات الكاش تكلف 0.1× من الإدخال العادي، لكن كتابات الكاش تكلف أكثر من الإدخال العادي. توثق Anthropic حاليًا أن كتابات كاش 5 دقائق تكلف 1.25× من سعر الإدخال، وكتابات ساعة واحدة تكلف 2×، وأن إصابات الكاش تكلف 0.1× عبر نماذج Claude النشطة (توثيق Anthropic للتخزين المؤقت للمطالبات).

هذا يجعل الكاش ميزة تسعير، لا مجرد ميزة لتقليل زمن الاستجابة. إذا كان تطبيقك يعيد استخدام مطالبة نظام طويلة، أو مخطط أدوات، أو حزمة أمثلة، أو مجموعة سياسات، أو مستندات مسترجعة، أو حالة محادثة متعددة الأدوار، فعليك قياس كتابات الكاش وقراءاته بالطريقة نفسها التي تقيس بها رموز الإخراج.

هناك تفصيلة مهمة حتى اليوم، 14 يونيو 2026: أطلقت Anthropic نموذج Claude Fable 5 في 9 يونيو، ثم نشرت تحديثًا في 12 يونيو تقول فيه إن الوصول إلى Fable 5 وMythos 5 عُلّق مؤقتًا بينما يعملون على استعادته (Anthropic). كما تعرض OneHop النموذج anthropic/claude-fable-5، مع دعم كاش المطالبات، لكنها تضع عليه حاليًا علامة غير متاح مؤقتًا في صفحة النموذج (OneHop). ابنِ التكامل الآن، واجعل معرف النموذج قابلًا للتهيئة، ثم فعّله عندما يعود الوصول.

حسابات الكاش التي يحتاجها المطورون فعلًا

يخزن كاش المطالبات في Anthropic بادئات المطالبة. يجب أن يكون الجزء القابل لإعادة الاستخدام مطابقًا: الأدوات، ومحتوى النظام، والرسائل تُؤخذ بهذا الترتيب، ويطبَّق الكاش حتى الكتلة الموسومة بـ cache_control (توثيق Anthropic للتخزين المؤقت للمطالبات).

نموذج التسعير المفيد بسيط. لنفترض أن البادئة القابلة لإعادة الاستخدام لديك هي 100,000 رمز إدخال.

بالنسبة إلى Claude Fable 5، تذكر Anthropic في منشور الإطلاق سعر 10 دولارات لكل مليون رمز إدخال و50 دولارًا لكل مليون رمز إخراج، وتعرض وثائق كاش المطالبات أسعار كاش Fable 5 كالتالي: 12.50 دولار/مليون لكتابات 5 دقائق، و20 دولار/مليون لكتابات ساعة واحدة، و1 دولار/مليون لإصابات الكاش (Anthropic, توثيق كاش المطالبات).

باستخدام أسعار Anthropic المعلنة، تكلف بادئة الـ100 ألف رمز هذه:

• إدخال عادي: $1.00
• كتابة 5 دقائق: $1.25
• كتابة ساعة واحدة: $2.00
• قراءة كاش: $0.10

لذلك إذا استُخدمت بادئة الـ100 ألف رمز نفسها مرتين داخل مدة الصلاحية، فسيكلف كاش 5 دقائق $1.25 + $0.10 = $1.35، مقابل $2.00 بلا كاش. أما كاش الساعة الواحدة فيكلف $2.10 لاستخدامين، لذا يخسر عند طلبين لكنه يربح عندما يكون لديك طلب ثالث أو عندما تتجنب إعادة كتابة باردة بعد توقف أطول.

هذه هي القاعدة التي أستخدمها في الإنتاج: اجعل 5 دقائق الخيار الافتراضي للحلقات الساخنة؛ واستخدم ساعة واحدة عندما يتوقف البشر، أو تنتظر الوكلاء الأدوات، أو تُستأنف سير العمل بعد عدة دقائق.

طريقتان لتفعيل الكاش

توثق Anthropic الآن نهجين. الطريق الأسرع هو الكاش التلقائي: أضف حقل cache_control على المستوى الأعلى وسيدفع Claude نقطة الفصل إلى الأمام مع نمو المحادثة. الطريق الأكثر تحكمًا هو نقاط الفصل الصريحة: ضع cache_control على آخر كتلة محتوى في البادئة المستقرة (توثيق Anthropic للتخزين المؤقت للمطالبات).

الكاش التلقائي ممتاز لسجل المحادثة وحالة الوكيل:

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ONEHOP_API_KEY"],
    base_url=os.getenv("ANTHROPIC_BASE_URL", "https://api.onehop.ai/v1"),
)

message = client.messages.create(
    model=os.getenv("CLAUDE_MODEL", "anthropic/claude-fable-5"),
    max_tokens=700,
    cache_control={"type": "ephemeral"},
    system="You are a senior backend engineer. Be concise and specific.",
    messages=[
        {"role": "user", "content": "My app uses FastAPI, Postgres, and Redis."},
        {"role": "assistant", "content": "Got it. What do you want to change?"},
        {"role": "user", "content": "Design a cache key strategy for user dashboards."},
    ],
)

print(message.content[0].text)
print(message.usage.model_dump())

هذا هو مسار التحويل إلى OneHop: أبقِ طلبك بأسلوب Anthropic كما هو، واجعل base URL قابلًا للتهيئة، ووجّهه إلى https://api.onehop.ai/v1. تعرض صفحة النموذج لدى OneHop أيضًا anthropic/claude-fable-5 كمعرف النموذج، وتقول إن المستخدمين الجدد يحصلون على رصيد مجاني قدره 10 دولارات من دون بطاقة (OneHop). إذا أردت الطريق المختصر، افتح Claude Fable 5 على OneHop وابدأ بـ10 دولارات مجانًا.

الكاش الصريح أفضل عندما تكون البادئة مستقرة لكن رسالة المستخدم تتغير في كل طلب. ضع نقطة الفصل قبل الجزء المتغير:

from anthropic import Anthropic
import os

client = Anthropic(
    api_key=os.environ["ONEHOP_API_KEY"],
    base_url="https://api.onehop.ai/v1",
)

response = client.messages.create(
    model="anthropic/claude-fable-5",
    max_tokens=500,
    system=[
        {
            "type": "text",
            "text": open("system_prompt.md").read(),
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        {"role": "user", "content": "Review this migration plan for race conditions."}
    ],
)

print(response.usage.model_dump())

نسخة TypeScript مع مدة صلاحية ساعة واحدة

استخدم كاش الساعة الواحدة عندما يمتلك التطبيق سياقًا ثابتًا مكلفًا وفواصل خمول واقعية. فكّر في: وكلاء مراجعة الكود الذين ينتظرون CI، أو مساعدين لدعم العملاء حيث يتوقف البشر، أو جلسات بحث قانوني، أو تحليل بيانات متعدد الخطوات تستغرق فيه الأدوات عدة دقائق.

تعرض وثائق Anthropic مدة الساعة الواحدة كـ {"type":"ephemeral","ttl":"1h"} وتوضح أن الكاش التلقائي يستخدم 5 دقائق افتراضيًا (توثيق Anthropic للتخزين المؤقت للمطالبات).

import Anthropic from "@anthropic-ai/sdk";
import fs from "node:fs";

const client = new Anthropic({
  apiKey: process.env.ONEHOP_API_KEY!,
  baseURL: process.env.ANTHROPIC_BASE_URL ?? "https://api.onehop.ai/v1",
});

const policyPack = fs.readFileSync("policy-pack.md", "utf8");

const msg = await client.messages.create({
  model: process.env.CLAUDE_MODEL ?? "anthropic/claude-fable-5",
  max_tokens: 800,
  system: [
    {
      type: "text",
      text: policyPack,
      cache_control: { type: "ephemeral", ttl: "1h" },
    },
  ],
  messages: [
    {
      role: "user",
      content: "Apply the policy pack to this refund request: customer used 3 of 10 seats.",
    },
  ],
});

console.log(msg.content);
console.log(msg.usage);

النقطة المهمة مملة: لا تدفن النموذج وbase URL في عمق الكود. أبقهما في متغيرات البيئة. إتاحة Fable 5 تتحرك اليوم؛ يجب أن يكون تكاملك قادرًا على الرجوع إلى نموذج Claude نشط آخر من دون تعديل منطق الأعمال.

ما الذي تراقبه في الاستخدام

يبقى كاش المطالبات غير مرئي إلى أن تفحص حقول الاستخدام. تقول Anthropic إن التحقق من الكاش يكون عبر حقول مثل cache_creation_input_tokens وcache_read_input_tokens؛ إذا كان كلاهما صفرًا، فهذا يعني أن المطالبة لم تُخزَّن في الكاش، وغالبًا لأنها لم تبلغ الحد الأدنى للطول القابل للتخزين في النموذج (توثيق Anthropic للتخزين المؤقت للمطالبات).

سجّل هذه لكل طلب:

const usage = msg.usage;

console.log({
  input: usage.input_tokens,
  output: usage.output_tokens,
  cacheCreate: usage.cache_creation_input_tokens,
  cacheRead: usage.cache_read_input_tokens,
});

بالنسبة إلى كائنات الاستخدام الأحدث، تعرض وثائق Anthropic أيضًا تقسيم إنشاء الكاش إلى حاويات خاصة بمدة الصلاحية مثل ephemeral_5m_input_tokens وephemeral_1h_input_tokens. التقط كائن الاستخدام كاملًا في البداية. طبّعه لاحقًا بعد أن تعرف بالضبط أي بوابة وأي إصدار SDK تستخدم.

لوحات المراقبة الجيدة تجيب عن أربعة أسئلة:

1. كم عدد الرموز التي تُكتب إلى الكاش؟
2. كم عدد الرموز التي تُقرأ من الكاش؟
3. ما نسبة قراءة/كتابة الكاش حسب المسار؟
4. أي مطالبات تنشئ كتابات باردة كبيرة بعد فترات خمول؟

إذا كان cache_creation_input_tokens مرتفعًا بينما يبقى cache_read_input_tokens قريبًا من الصفر، فمن المحتمل أن نقطة الفصل لديك تقع بعد محتوى متغير. انقلها إلى موضع أبكر.

5 دقائق أم ساعة واحدة: اختر بحسب سلوك المستخدم

استخدم كاش 5 دقائق لحلقات الطلبات الضيقة. وكيل برمجة يستدعي الأدوات كل 20 ثانية، أو تطبيق محادثة يرسل فيه المستخدمون متابعات بسرعة، أو دفعة من مهام تصنيف متشابهة — كل هذه يجب أن تبدأ من هنا. علاوة الكتابة لا تتجاوز 1.25×، وكل قراءة تجدد عمر الكاش مجانًا بحسب وثائق Anthropic (توثيق Anthropic للتخزين المؤقت للمطالبات).

استخدم كاش الساعة الواحدة عندما يُحتمل إعادة استخدام البادئة المكلفة بعد أكثر من خمس دقائق. سير العمل الذي يتضمن إنسانًا في الحلقة هو الحالة الكلاسيكية. وينطبق ذلك أيضًا على الوكلاء طويلي التشغيل حيث يرسل النموذج عملًا إلى أنظمة خارجية، أو ينتظر متصفحًا، أو يستطلع CI، أو يتوقف بانتظار الموافقة.

لا تخزن المطالبات الصغيرة في الكاش. توثق Anthropic الحد الأدنى لأطوال المطالبات القابلة للتخزين حسب النموذج والمنصة؛ بالنسبة إلى Fable 5، الحد الأدنى في Claude API مذكور كـ512 رمزًا، بينما لدى Bedrock حدود مختلفة لبعض النماذج (توثيق Anthropic للتخزين المؤقت للمطالبات). قد تُعالَج المطالبات الأقصر ببساطة من دون كاش.

قائمة تحقق عملية:

• ضع المحتوى المستقر أولًا: الأدوات، مطالبات النظام، الأمثلة، المستندات المرجعية.
• أبقِ البيانات المتغيرة بعد البادئة المخزنة: الطوابع الزمنية، معرفات الطلب، نص المستخدم.
• ابدأ بالكاش التلقائي للمحادثات.
• انتقل إلى نقاط الفصل الصريحة عندما تتغير اللاحقة في كل استدعاء.
• استخدم مدة صلاحية ساعة واحدة فقط عندما تبرر فواصل الخمول كتابة 2×.
• سجّل حقول الاستخدام قبل إعلان النصر.

وصّله عبر OneHop، ثم قِس

أنظف تكامل هو تغيير endpoint في سطر واحد مع اختيار النموذج عبر البيئة:

export ONEHOP_API_KEY="..."
export ANTHROPIC_BASE_URL="https://api.onehop.ai/v1"
export CLAUDE_MODEL="anthropic/claude-fable-5"

ثم أبقِ كود Anthropic Messages كما هو وأضف cache_control.

تعلن صفحة Fable 5 لدى OneHop حاليًا عن تسعير أقل من القائمة الرسمية، ورصيد بداية قدره 10 دولارات بلا بطاقة، ومسار Anthropic Messages للنموذج (OneHop). وبما أن الوصول إلى Fable 5 معلّق مؤقتًا حسب تحديث Anthropic في 12 يونيو، اجعل الرجوع إلى نموذج بديل جزءًا من خطة الإطلاق، لا فكرة لاحقة.

العائد بسيط. إذا كان تطبيقك يعيد استخدام بادئات كبيرة، فإن القراءات المخزنة بسعر 0.1× تحوّل هندسة المطالبات إلى هندسة تكلفة. ابدأ بكاش 5 دقائق. انقل بعض سير العمل المختارة إلى كاش ساعة واحدة عندما تُظهر السجلات إعادة كتابات باردة بعد التوقفات. وإذا أردت الطريق المختصر إلى Claude Fable 5 عندما تعود الإتاحة، جرّب Claude Fable 5 على OneHop وابدأ بـ10 دولارات مجانًا.