التخزين المؤقت للموجّهات وتحسين التكلفة

متقدّم

إذا كان كثير من طلباتك يتشارك جزءًا كبيرًا غير متغير — موجّه نظام طويل، أو مستند ضخم، أو كتالوج أدوات — فإن التخزين المؤقت للموجّهات يتيح لـ API إعادة استخدام البادئة المعالَجة بدلاً من إعادة قراءتها في كل استدعاء. وهذا يخفض كلًا من التكلفة وزمن الاستجابة على الجزء المخزّن مؤقتًا.

What you'll learn

النموذج الذهني: نقطة فاصل للتخزين المؤقت بعد بادئة ثابتة، يُعاد استخدامها عبر الاستدعاءات
كيفية تعليم نقطة الفاصل في Python وTypeScript باستخدام cache_control
الثابت الوحيد الذي يصنع نجاحها أو يكسرها — يجب أن تكون البادئة مطابقة بايتًا ببايت
كيفية قراءة حقول الاستخدام للتأكد من أنك تحصل فعلًا على إصابات للمخزن المؤقت
أين يؤتي التخزين المؤقت ثماره أكثر، وكيفية إقرانه بالمعالجة الدُّفعية واختيار الحجم المناسب

كيف يعمل (النموذج الذهني)

تضع نقطة فاصل للتخزين المؤقت بعد البادئة الثابتة. في الاستدعاء الأول تُعالَج وتُخزَّن مؤقتًا؛ والاستدعاءات اللاحقة التي تتشارك البادئة نفسها تمامًا تصيب المخزن المؤقت وتدفع مقابلها أقل بكثير.

مفردات التخزين المؤقت

اضغط Enter أو مفتاح المسافة لقلب البطاقة. استخدم مفتاحي السهمين الأيسر والأيمن للتنقل بين البطاقات.تم إظهار المصطلح.

1 / 4

ضع نقطة الفاصل (انسخ والصق)

أضف cache_control إلى آخر كتلة ثابتة — هنا، موجّه نظام كبير. يأتي دور المستخدم بعدها ويتغير بحرية؛ وكل شيء حتى الكتلة المعلَّمة وبما فيها يُخزَّن مؤقتًا.

Guided walkthrough1 of 4

اعثر على الجزء الكبير غير المتغير — موجّه نظام طويل، أو مستند ضخم، أو كتالوج أدوات يُعاد استخدامه عبر طلبات كثيرة.

Python
TypeScript

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LARGE_STABLE_PROMPT,  # long, unchanging — the cached prefix
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "Summarize the key points."}],  # varies per call
)

print(message.usage.cache_read_input_tokens)  # > 0 means you got a hit

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  system: [
    {
      type: "text",
      text: LARGE_STABLE_PROMPT, // long, unchanging — the cached prefix
      cache_control: { type: "ephemeral" },
    },
  ],
  messages: [{ role: "user", content: "Summarize the key points." }], // varies per call
});

console.log(message.usage.cache_read_input_tokens); // > 0 means you got a hit

يدفع الاستدعاء الأول علاوة كتابة صغيرة لملء المخزن المؤقت؛ وكل استدعاء لاحق بالبادئة نفسها يقرأها مرة أخرى بجزء بسيط من سعر الإدخال. يجب أن تكون البادئة طويلة بما يكفي لتكون مؤهلة — بضعة آلاف من الرموز، وذلك يعتمد على النموذج — وإلا فلن تُخزَّن مؤقتًا بصمت.

الثابت الذي يصنع نجاحها أو يكسرها

:::warning التخزين المؤقت دقيق على مستوى البادئة تتطلب إصابة المخزن المؤقت أن تكون البادئة المخزّنة مطابقة بايتًا ببايت. أكثر الأخطاء شيوعًا: مُبطِل صامت قرب أعلى الموجّه — طابع زمني، أو اسم مستخدم متغير، أو قائمة أدوات أُعيد ترتيبها — يغيّر البادئة ويُسقط معدل إصاباتك إلى صفر بهدوء. :::

ضع كل ما هو ثابت أولًا، وكل ما هو متغير أخيرًا، وأبقِ البادئة ثابتة فعلًا.

تحقق من أنها تعمل فعلًا

لا تفترض — اقرأها من حقل usage في الاستجابة:

cache_creation_input_tokens — الرموز المكتوبة إلى المخزن المؤقت في هذا الاستدعاء (الطلب الأول).
cache_read_input_tokens — الرموز المخدومة من المخزن المؤقت (التوفير).
input_tokens — الباقي غير المخزّن، ويُحاسَب عليه بالسعر الكامل.

إذا بقي cache_read_input_tokens عند الصفر عبر طلبات متكررة يُفترض أن تتشارك بادئة، فإن مُبطِلًا صامتًا يعمل — قارن بايتات الموجّه المُصاغ بين استدعاءين للعثور عليه.

أين يؤتي ثماره أكثر

موجّهات النظام الطويلة المُعاد استخدامها عبر المستخدمين.
RAG / الإجابة على الأسئلة من المستندات حيث يُستعلَم عن النص المصدري نفسه مرارًا.
الوكلاء الذين لديهم كتالوج أدوات وتعليمات ثابتة عبر أدوار كثيرة.

اقرن التخزين المؤقت مع المعالجة الدُّفعية لأحمال العمل غير المتصلة، ومع اختيار الحجم المناسب للنموذج (اختيار نموذج) لأكبر توفير مجمّع — انظر التكلفة وزمن الاستجابة.

اختبر نفسك

0/3

ماذا تتطلب إصابة المخزن المؤقت من البادئة المخزّنة؟
أي حقل من حقول الاستخدام يخبرك بأن الرموز خُدمت من المخزن المؤقت (توفيرك)؟
أين ينبغي أن يوضع المحتوى المتغير لكل استدعاء بالنسبة لنقطة فاصل التخزين المؤقت؟

Key takeaways

ضع نقطة فاصل للتخزين المؤقت بعد البادئة الثابتة؛ الاستدعاء الأول يكتبها، والاستدعاءات اللاحقة تقرأها بثمن زهيد.
تحتاج إصابة المخزن المؤقت إلى بادئة مطابقة بايتًا ببايت — أبقِ المحتوى الثابت أولًا والمحتوى المتغير أخيرًا.
المُبطِلات الصامتة قرب أعلى الموجّه (الطوابع الزمنية، الأسماء، الأدوات المُعاد ترتيبها) تُسقط معدل الإصابات إلى صفر بهدوء.
تحقق عبر الاستخدام: cache_read_input_tokens أكبر من الصفر يعني إصابة؛ والصفر عبر الطلبات المتكررة يعني أن هناك مُبطِلًا يعمل.
يؤتي التخزين المؤقت ثماره أكثر مع موجّهات النظام المُعاد استخدامها، وRAG، والوكلاء؛ اقرنه بالمعالجة الدُّفعية واختيار الحجم المناسب للنموذج.

كيف يعمل (النموذج الذهني)​

ضع نقطة الفاصل (انسخ والصق)​

الثابت الذي يصنع نجاحها أو يكسرها​

تحقق من أنها تعمل فعلًا​

أين يؤتي ثماره أكثر​