SSD Nodes Learn Hosting plans →
راهنماها Matt Connorتوسط Matt Connor · به‌روزرسانی شده 2026-10-23

محاسبه نقطه سر‌به‌سر Claude prompt caching

هزینهٔ cache write پنج‌دقیقه‌ای 1.25x و cache read معمولی 0.1x است؛ ببینید prefix در استفادهٔ دوم جبران می‌شود و محاسبه را با API بررسی کنید.

هزینهٔ prompt caching پیش از آن‌که باعث صرفه‌جویی شود

prompt caching به Claude اجازه می‌دهد بخش ابتدایی prompt شما را دوباره استفاده کند و مجبور نباشد آن را در هر فراخوانی از ابتدا بخواند. کل تصمیم به دو ضریب نسبت به قیمت پایهٔ input مدل بستگی دارد. در October 2026، هزینهٔ cache write برای lifetime پنج‌دقیقه‌ای برابر با 1.25x قیمت پایهٔ input است و برای lifetime یک‌ساعته به 2x می‌رسد؛ این نرخ‌ها در همهٔ مدل‌ها یکسان‌اند. هزینهٔ cache read در بیشتر مدل‌ها 0.1x است، اما ضریب read دیگر در همه‌جا یکسان نیست. این ضریب در Claude Fable 5.1 و Claude Mythos 5.1 برابر با 0.025x است؛ این مدل‌ها در September 1, 2026 با همین نرخ عرضه شدند. این ضریب در Claude Opus 5.5 و Claude Sonnet 5.5 برابر با 0.05x است و نرخ Sonnet 5.5 در October 7, 2026 از 0.1x به این مقدار کاهش یافت. ارقام محاسبه‌شدهٔ زیر از read استاندارد 0.1x استفاده می‌کنند. readهای ارزان‌تر، نقطهٔ سر‌به‌سر را کمی به نفع شما جابه‌جا می‌کنند و بخش بعدی مقدار این تغییر را نشان می‌دهد.

این معامله یعنی اکنون هزینهٔ اضافی بپردازید تا بعداً تخفیف بگیرید. برای ذخیرهٔ یک prefix، یک‌بار هزینهٔ بیشتری پرداخت می‌کنید. هر درخواست بعدی که دقیقاً با همان byteها شروع شود، برای آن بخش یک‌دهم قیمت عادی input را می‌پردازد؛ در مدل‌های بالا این هزینه کمتر است. اگر یک prefix در طول lifetime خود هرگز دوباره استفاده نشود، 25 درصد هزینهٔ اضافی را بدون هیچ صرفه‌جویی پرداخت کرده‌اید.

نقطهٔ سربه‌سر، در یک خط جبر

B را هزینهٔ پایهٔ ورودی prefix در نظر بگیرید؛ یعنی هزینه‌ای که اگر prefix را بدون cache ارسال می‌کردید، پرداخت می‌شد. بدون cache، هزینهٔ N درخواست برابر با N برابر B است. با cache پنج‌دقیقه‌ای، درخواست اول prefix را با هزینهٔ 1.25B می‌نویسد و N منهای 1 درخواست دیگر آن را با هزینهٔ 0.1B می‌خوانند. با برابر قرار دادن دو حالت، به 0.9N = 1.15 می‌رسیم؛ بنابراین N = 1.28 است. درخواست دوم از همان ابتدا از حالت بدون cache ارزان‌تر است.

همین محاسبه را برای cache یک‌ساعته، با نوشتن 2 برابر، تکرار کنید. نتیجه 0.9N = 1.9 و بنابراین N = 2.11 است. cache طولانی‌مدت پیش از رسیدن به نقطهٔ سربه‌سر به دو خواندن نیاز دارد؛ به همین دلیل گزینهٔ پیش‌فرض نیست.

با ارزان‌تر شدن خواندن‌ها، این خط جابه‌جا می‌شود، اما نه به‌طور چشمگیر. در خواندن 0.05x، cache پنج‌دقیقه‌ای رابطهٔ 0.95N = 1.2 را می‌دهد؛ بنابراین N = 1.26 است. در 0.025x نیز رابطهٔ 0.975N = 1.225 به دست می‌آید که باز هم N = 1.26 است. برای cache یک‌ساعته، این مقدار به‌ترتیب به N = 2.05 و N = 2.03 کاهش می‌یابد. نتیجهٔ عملی در همهٔ مدل‌ها یکسان است: cache پنج‌دقیقه‌ای از درخواست دوم مقرون‌به‌صرفه می‌شود و cache یک‌ساعته از درخواست سوم.

نمودار زیر هزینهٔ این وضعیت را برای prefix دارای 20,000 token در Claude Opus 5 محاسبه می‌کند. نرخ پایهٔ ورودی آن تا October 2026 برابر با $5 به‌ازای هر million token است و از August تغییری نکرده است. Opus 5 اکنون یک مدل legacy است، اما همچنان در دسترس قرار دارد. مدل جانشین آن، Claude Opus 5.5، نرخ $4 به‌ازای هر million را با read برابر با 0.05x اعلام می‌کند؛ بنابراین هزینهٔ نوشتن همان prefix در آنجا $0.10 و هزینهٔ خواندن $0.004 است. برای مدلی با نرخ $3 به‌ازای هر million و read استاندارد 0.1x، همهٔ ارقام را در 0.6 ضرب کنید. شکل منحنی تغییر نمی‌کند.

نمودارCost of N requests sharing a 20,000 token prefix (Claude Opus 5, August 2026 prices)
داده‌های پشت این نمودار
[
  {
    "requests": 1,
    "uncached_usd": "0.10",
    "cached_5m_usd": "0.125",
    "cached_1h_usd": "0.20"
  },
  {
    "requests": 2,
    "uncached_usd": "0.20",
    "cached_5m_usd": "0.135",
    "cached_1h_usd": "0.21"
  },
  {
    "requests": 3,
    "uncached_usd": "0.30",
    "cached_5m_usd": "0.145",
    "cached_1h_usd": "0.22"
  },
  {
    "requests": 5,
    "uncached_usd": "0.50",
    "cached_5m_usd": "0.165",
    "cached_1h_usd": "0.24"
  },
  {
    "requests": 10,
    "uncached_usd": "1.00",
    "cached_5m_usd": "0.215",
    "cached_1h_usd": "0.29"
  },
  {
    "requests": 20,
    "uncached_usd": "2.00",
    "cached_5m_usd": "0.315",
    "cached_1h_usd": "0.39"
  }
]

یک درخواست به‌تنهایی، بدون cache $0.10 و با cache $0.125 هزینه دارد؛ بنابراین cache کردن promptی که فقط یک بار استفاده می‌شود، زیان خالص است. در درخواست دوم، هزینهٔ cache پنج‌دقیقه‌ای $0.135 است، در حالی که هزینهٔ حالت بدون cache $0.20 است. cache یک‌ساعته در این نقطه همچنان هزینهٔ بیشتری دارد: $0.21 در برابر همان $0.20. این cache فقط در درخواست سوم از حالت بدون cache ارزان‌تر می‌شود: $0.22 در برابر $0.30. در 20 درخواست، فاصله به $2.00 در برابر $0.315 می‌رسد.

cache hit ورودی را نیز refresh می‌کند؛ به همین دلیل جدول قیمت منتشرشده این ستون را cache hits and refreshes می‌نامد. بنابراین یک endpoint پرترافیک می‌تواند entry پنج‌دقیقه‌ای را با هزینه‌های read به‌طور نامحدود زنده نگه دارد. عمر یک‌ساعته فقط زمانی هزینهٔ 2x نوشتن را توجیه می‌کند که ترافیک شما واقعاً فاصله‌های طولانی داشته باشد.

هزینهٔ نرخ hit پایین

در ترافیک واقعی، همهٔ درخواست‌ها hit نمی‌شوند. اگر درخواستی cache را از دست بدهد اما همچنان breakpoint داشته باشد، هزینهٔ آن مانند write محاسبه می‌شود. بنابراین مدل‌سازی دقیق باید هزینه را تابعی از نرخ hit در نظر بگیرد. نمودار زیر این وضعیت را برای 1,000 درخواست نشان می‌دهد که هرکدام prefix یکسانی با 20,000 token دارند.

نمودارCost of 1,000 requests by cache hit rate, 20,000 token prefix
داده‌های پشت این نمودار
[
  {
    "hit_rate_percent": 0,
    "cost_5m_usd": "125.00",
    "cost_1h_usd": "200.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 25,
    "cost_5m_usd": "96.25",
    "cost_1h_usd": "152.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 50,
    "cost_5m_usd": "67.50",
    "cost_1h_usd": "105.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 75,
    "cost_5m_usd": "38.75",
    "cost_1h_usd": "57.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 90,
    "cost_5m_usd": "21.50",
    "cost_1h_usd": "29.00",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 95,
    "cost_5m_usd": "15.75",
    "cost_1h_usd": "19.50",
    "uncached_usd": "100.00"
  },
  {
    "hit_rate_percent": 99,
    "cost_5m_usd": "11.15",
    "cost_1h_usd": "11.90",
    "uncached_usd": "100.00"
  }
]

در نرخ hit برابر با 0 درصد، به‌جای $125.00 باید $100.00 بپردازید و cache یک‌ساعته این هزینه را دو برابر می‌کند و به $200.00 می‌رساند. با حل معادلهٔ 1.25 منهای 1.15h برابر با 1، مشخص می‌شود که cache پنج‌دقیقه‌ای از نرخ hit حدود 22 درصد شروع به کاهش هزینه می‌کند؛ به همین دلیل نرخ 25 درصد نیز مقدار $96.25 را نشان می‌دهد. همین محاسبه برای write با ضریب 2، آستانهٔ حدود 53 درصد را برای cache یک‌ساعته نشان می‌دهد. بنابراین نرخ hit برابر با 50 درصد همچنان هزینهٔ $105.00 دارد که از خط بدون cache بیشتر است. در نرخ 90 درصد، این دو مقدار به‌ترتیب به $21.50 و $29.00 می‌رسند. در نرخ 99 درصد، cache کوتاه‌مدت به $11.15 می‌رسد که به کف هزینه، یعنی یک‌دهم قیمت بدون cache، نزدیک است.

در مدلی با read برابر با 0.05x، آستانه‌ها به حدود 21 درصد برای cache پنج‌دقیقه‌ای و 51 درصد برای cache یک‌ساعته کاهش می‌یابند. با read برابر با 0.025x، این آستانه‌ها به حدود 20 و 51 درصد می‌رسند. با کاهش قیمت read، کف هزینه نیز کاهش می‌یابد و به یک‌بیستم یا یک‌چهلم هزینهٔ بدون cache می‌رسد.

نرخ hit عددی است که باید برای آن instrumentation انجام دهید، زیرا پس از ثابت‌شدن اندازهٔ prefix تنها ورودی‌ای است که می‌توانید کنترل کنید.

کدام prefixها ارزش breakpoint دارند

هر درخواست می‌تواند حداکثر چهار cache breakpoint داشته باشد؛ بنابراین پرسش این است که کدام blockها شایستهٔ داشتن آن هستند. گزینه‌های مناسب، blockهایی هستند که در درخواست‌های مختلف از نظر byte کاملاً یکسان‌اند و آن‌قدر بزرگ هستند که تفاوت ایجاد کنند. نمودار زیر هزینهٔ چهار شکل رایج را برای 1,000 درخواست، با hit rate برابر 90 percent در cache پنج‌دقیقه‌ای، محاسبه می‌کند.

نمودارCost per 1,000 requests at a 90% hit rate, by cached prefix (Claude Opus 5)
داده‌های پشت این نمودار
[
  {
    "label": "System prompt",
    "prefix_size_tokens": "2,000",
    "uncached_usd": "10.00",
    "cached_usd": "2.15",
    "saved_usd": "7.85"
  },
  {
    "label": "System plus tools",
    "prefix_size_tokens": "8,000",
    "uncached_usd": "40.00",
    "cached_usd": "8.60",
    "saved_usd": "31.40"
  },
  {
    "label": "Policy document",
    "prefix_size_tokens": "25,000",
    "uncached_usd": "125.00",
    "cached_usd": "26.88",
    "saved_usd": "98.12"
  },
  {
    "label": "Codebase context",
    "prefix_size_tokens": "120,000",
    "uncached_usd": "600.00",
    "cached_usd": "129.00",
    "saved_usd": "471.00"
  }
]

یک system prompt ساده با token برابر 2,000، در مقایسه با هزینهٔ uncached برابر $10.00، در هر 1,000 درخواست $7.85 صرفه‌جویی ایجاد می‌کند. در مقیاس بالا مبلغ قابل‌توجهی است، اما دلیل جذابیت caching نیست. با افزودن تعریف‌های ابزار، به 8,000 token و $31.40 صرفه‌جویی می‌رسید. یک سند policy با 25,000 token که هر درخواست دربارهٔ آن سؤال می‌پرسد، $98.12 صرفه‌جویی ایجاد می‌کند. ردیف آخر همان چیزی است که معماری را تغییر می‌دهد: 120,000 token از context مربوط به codebase یا transcript، در حالت uncached $600.00 و در حالت cached $129.00 هزینه دارد؛ یعنی $471.00 صرفه‌جویی.

صرفه‌جویی با اندازهٔ prefix و hit rate افزایش می‌یابد و به عامل دیگری وابسته نیست. این موضوع نشان می‌دهد که اصلاً چه محتوایی ارزش قرار گرفتن در prompt را دارد: هزینهٔ واقعی یک میلیون token از Claude برای هر چیزی که بیش از یک بار ارسال کنید، به یک‌دهم قیمت اسمی یا حتی کمتر می‌رسد؛ مدل‌هایی که read ارزان‌تری دارند، هزینهٔ پایین‌تری نیز خواهند داشت.

نمای آن در صورت‌حساب ماهانه

نمودار زیر از پیشوند توکن 8,000 که در بالا ذکر شد، به همراه یک system prompt و تعاریف ابزار، با نرخ موفقیت (hit rate) 90 درصد استفاده کرده و آن را به حجم درخواست‌های ماهانه تعمیم می‌دهد.

نمودارMonthly input cost, 8,000 token cached prefix at a 90% hit rate
داده‌های پشت این نمودار
[
  {
    "label": "10k requests",
    "uncached_usd": "400.00",
    "cached_usd": "86.00",
    "saved_usd": "314.00"
  },
  {
    "label": "100k requests",
    "uncached_usd": "4,000.00",
    "cached_usd": "860.00",
    "saved_usd": "3,140.00"
  },
  {
    "label": "1M requests",
    "uncached_usd": "40,000.00",
    "cached_usd": "8,600.00",
    "saved_usd": "31,400.00"
  }
]

در حجم 10,000 درخواست در ماه، میزان صرفه‌جویی برابر با $314.00 است که تفاوت میان $400.00 و $86.00 محسوب می‌شود. در 100,000 درخواست، این رقم $3,140.00 است. در حجم یک میلیون درخواست، صورت‌حساب ورودی بدون کش برابر با $40,000.00 است و استفاده از کش، $31,400.00 از آن را کاهش می‌دهد. این ارقام فقط مربوط به توکن‌های ورودی هستند. توکن‌های خروجی به‌صورت جداگانه قیمت‌گذاری می‌شوند و کشینگ تأثیری بر آن‌ها ندارد؛ پیش از آنکه به کسی وعده کاهش 90 درصدی صورت‌حساب را بدهید، به یاد داشتن این نکته ضروری است. کشینگ در کنار سایر روش‌های معمول در کنترل هزینه‌های یک ایجنت هوش مصنوعی روی VPS قرار می‌گیرد.

نحوه اطمینان از عملکرد کش

به طراحی سیستم اعتماد نکنید. بلوک usage در پاسخ دریافتی را بررسی کنید. هر پاسخ API (رابط برنامه‌نویسی کاربردی) پیام‌ها، تعداد توکن‌های کش‌شده‌ای که نوشته، توکن‌های کش‌شده‌ای که خوانده و توکن‌های جدیدی که مجبور به پردازش آن‌ها بوده است را گزارش می‌دهد.

from anthropic import Anthropic

client = Anthropic()

resp = client.messages.create(
    model="claude-opus-5",
    max_tokens=512,
    system=[
        {
            "type": "text",
            "text": POLICY_DOCUMENT,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": question}],
)

u = resp.usage
print("write:", u.cache_creation_input_tokens)
print("read: ", u.cache_read_input_tokens)
print("fresh:", u.input_tokens)

درخواست را دو بار با یک سند واحد و پرسش‌های متفاوت اجرا کنید. فراخوانی اول یک مقدار غیرصفر برای cache_creation_input_tokens و مقدار صفر برای cache_read_input_tokens گزارش می‌دهد. فراخوانی دوم این وضعیت را معکوس می‌کند، زیرا پیشوند (prefix) پیدا شده است. مقدار input_tokens فقط توکن‌های بعد از آخرین breakpoint را می‌شمارد، بنابراین در یک فراخوانی دومِ سالم، این مقدار کوچک است و معمولاً فقط شامل پیام جدید کاربر می‌شود. هر دو فراخوانی مشمول هزینه هستند، زیرا سرویس Claude API هیچ سطح رایگانی ندارد، اگرچه هزینه پیشوند 20,000 توکنی در این جفت فراخوانی حدود چهارده سنت می‌شود.

همین بررسی را از طریق shell و با استفاده از بدنه درخواستی که در request.json ذخیره کرده‌اید، انجام دهید:

curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d @request.json | jq '.usage'

یک فراخوانی دومِ سالم، خروجی مشابه زیر را نمایش می‌دهد:

{
  "input_tokens": 42,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 20143,
  "output_tokens": 187
}

یک خط در خروجی، حقیقت را به شما می‌گوید. اگر مقدار cache_read_input_tokens در فراخوانی‌های متوالی روی 0 باقی بماند، یعنی شما هر بار هزینه 1.25 برابری نوشتن را پرداخت می‌کنید و هیچ بهره‌ای از کش نمی‌برید.

برای طول عمر 1 ساعته، breakpoint دارای یک زمان ماندگاری (TTL) است:

{
  "type": "text",
  "text": "your stable prefix",
  "cache_control": {"type": "ephemeral", "ttl": "1h"}
}

همچنین قابلیت کش خودکار وجود دارد: یک فیلد cache_control در سطح بالای درخواست که پس از آن، API با رشد مکالمه، مدیریت breakpointها را بر عهده می‌گیرد. این قابلیت یکی از چهار جایگاه (slot) breakpoint شما را اشغال می‌کند. از همین‌جا شروع کنید. زمانی که نیاز دارید دقیقاً تعیین کنید مرز کش کجا باشد، به سراغ breakpointهای صریح (explicit) بروید.

قانون ترتیب که نرخ hit را از بین می‌برد

Cache از ابتدای request، یک prefix را byte به byte تطبیق می‌دهد و request با ترتیب ثابتی ساخته می‌شود: ابتدا tools، سپس system و بعد messages. هر تغییر در یک سطح، همان سطح و تمام سطوح بعد از آن را invalid می‌کند. اگر توضیح یک tool را ویرایش کنید، system prompt و کل message history نیز همراه آن invalid می‌شوند؛ حتی اگر آن‌ها را تغییر نداده باشید.

این موضوع یک قانون بدون استثنا دارد: هر چیزی که بین callها تغییر می‌کند باید بعد از هر چیزی قرار بگیرد که تغییر نمی‌کند.

متخلف معمول، timestamp است. وجود خطی مانند Current time: 2026-08-03T14:07:11Z در ابتدای system prompt نرخ hit برابر با 0 درصد را تضمین می‌کند، زیرا prefix hash در هر call متفاوت است و هیچ entry قبلی نمی‌تواند با آن match شود. آن را به user message و به انتهای آن منتقل کنید. session identifier یا per-request nonce نیز به همین شکل مشکل ایجاد می‌کند و راه‌حل آن‌ها نیز همین است. Retrieved documentهایی که در هر request متفاوت‌اند نیز باید بعد از cached block قرار بگیرند؛ در غیر این صورت، تمام tokenهای پایدار را پشت یک boundary متغیر قرار می‌دهند.

مشکل دوم، قرار دادن breakpoint روی blockی است که تغییر می‌کند. cache write در breakpoint انجام می‌شود. بنابراین اگر آن block در هر بار متفاوت باشد، هیچ محتوای پایداری ذخیره نمی‌شود و lookback فقط entryهایی را پیدا می‌کند که requestهای قبلی در breakpointهای متغیر خود نوشته‌اند. cache_control را روی آخرین blockی قرار دهید که محتوای آن در requestها یکسان است.

مشکل سوم، تغییر پارامتری است که آن را بخشی از prompt نمی‌دانستید. هر model، cache متفاوتی دارد. تغییر tool_choice باعث invalid شدن message history می‌شود، هرچند tools و system prompt در cache باقی می‌مانند. افزودن یا حذف یک tool، همه‌چیز را invalid می‌کند.

حداقل طول prefix و no-op بی‌صدا

prefix کوتاه‌تر از حداقل موردنیاز مدل cache نمی‌شود و هیچ پیامی نیز این موضوع را اعلام نمی‌کند. نه خطایی نمایش داده می‌شود و نه هشداری. درخواست با موفقیت انجام می‌شود و مقدار هر دو شمارنده 0 باقی می‌ماند. در October 2026، حداقل‌های منتشرشده به این شرح هستند:

  • 512 توکن در Claude Opus 5 و Claude Fable 5 و همچنین نسخه‌های جدیدتر Opus 5.5، Sonnet 5.5، Fable 5.1 و Haiku 5.5
  • 1,024 توکن در Claude Sonnet 5 و Claude Opus 4.8
  • 4,096 توکن در Claude Haiku 4.5

اگر مقدار هر دو شمارنده در درخواستی که تصور می‌کنید cache شده است 0 باشد، پیش از هر چیز طول prefix را بررسی کنید. به همین دلیل، ارزان‌ترین مدل لزوماً ارزان‌ترین گزینه برای workloadهای مبتنی بر caching نیست. Haiku 4.5 برای فعال‌شدن caching به prefixای نیاز دارد که 8 برابر طولانی‌تر از Opus 5 باشد؛ بنابراین system prompt دارای 2,000 توکن در یکی cache می‌شود و در دیگری بدون هیچ پیامی نادیده گرفته می‌شود.

محل cache کردن Claude Code برای شما و مواردی که نمی‌تواند کمکی به شما بکند

Claude Code پیشوند خودش را cache می‌کند. system prompt و تعریف ابزارها در ابتدای هر request قرار دارند و جابه‌جا نمی‌شوند؛ بنابراین یک‌بار نوشته می‌شوند و در ادامهٔ session از cache خوانده می‌شوند. به همین دلیل، هزینهٔ هر turn در یک session طولانی بسیار کمتر از چیزی است که اندازهٔ context نشان می‌دهد. این موضوع در شمارنده‌هایی که در Claude Code چگونه میزان استفاده از token را گزارش می‌کند توضیح داده شده است.

جایی که cache نمی‌تواند کمکی بکند، ایجاد تغییر در نزدیکی ابتدای context است. سابقهٔ conversation فقط به‌صورت append-only تغییر می‌کند؛ بنابراین turnهای معمولی جدید، پیشوندی را که از قبل cache شده است گسترش می‌دهند. ویرایش فایلی که در ابتدای session خوانده شده است این وضعیت را مختل نمی‌کند، زیرا Claude Code به‌جای بازنویسی محتوای قبلی، یادداشتی دربارهٔ تغییر فایل اضافه می‌کند. چیزی که این وضعیت را مختل می‌کند، تغییر model است، چون هر model cache جداگانهٔ خود را دارد. اتصال یک MCP server که ابزارهای آن در prefix بارگذاری می‌شوند نیز همین اثر را دارد. compact کردن conversation هم همین‌طور است. هرکدام از این موارد باعث می‌شوند turn بعدی prefix را دوباره بنویسد. یک فاصلهٔ طولانی بدون فعالیت نیز همین اثر را دارد، چون entry منقضی می‌شود و turn بعدی باید هزینهٔ یک write کامل را بپردازد. هیچ‌یک از این موارد bug نیست. این‌ها همان قاعدهٔ prefix هستند که دقیقاً مطابق تعریف خود عمل می‌کنند.

اگر در حال نوشتن client خودتان هستید، layout را از همان request نخست اعمال کنید و بعداً آن را اصلاح نکنید: call را همان‌طور بسازید که در ساخت نخستین برنامهٔ Claude API روی یک VPS انجام می‌شود؛ یعنی blockهای پایدار را ابتدا و blockهای متغیر را در انتها قرار دهید.

حالت‌های شکست و آنچه مشاهده خواهید کرد

هر فراخوانی یک write است. مقدار cache_creation_input_tokens در هر درخواست non-zero است، درحالی‌که cache_read_input_tokens روی 0 باقی می‌ماند. چیزی در نقطهٔ breakpoint یا پیش از آن، بین فراخوانی‌ها تغییر می‌کند. 200 نویسهٔ اول prefix مونتاژشده را در دو درخواست پیاپی چاپ کنید و آن‌ها را با چشم مقایسه کنید.

هر دو شمارنده 0 هستند. prefix از حداقل موردنیاز مدل کوتاه‌تر است، یا فیلد cache_control هرگز به API نرسیده است. ابتدا توکن‌های prefix را بشمارید، سپس body واقعی درخواستی را که ارسال کرده‌اید log کنید.

خواندن‌ها کار می‌کنند و سپس متوقف می‌شوند. چند hit پشت‌سرهم رخ می‌دهد، سپس یک write و بعد دوباره hitها. فاصلهٔ بین درخواست‌ها از lifetime بیشتر بوده است. write را بپذیرید، یا پس از بررسی این‌که hit rate از 53 درصد بیشتر است، به TTL برابر با 1 hour منتقل شوید؛ در مدلی که read با ضریب 0.05x یا 0.025x قیمت‌گذاری می‌شود، این آستانه حدود 51 درصد است.

پس از deploy، hit rate کاهش می‌یابد. توضیح یک tool ویرایش شده یا مدل تغییر کرده است. هر دو تغییر، کل prefix را invalidate می‌کنند. پس از هر deploy که prompt را تغییر می‌دهد، انتظار یک دور پرهزینه از writeها را داشته باشید.

پس از فعال‌کردن caching، مبلغ صورتحساب افزایش یافته است. hit rate شما کمتر از نقطهٔ سربه‌سر است. در cache با مدت 5 minute، اگر hit rate حدوداً کمتر از 22 درصد باشد، ارسال prefix بدون cache ارزان‌تر است؛ در cache با مدت 1 hour، این مقدار کمتر از حدود 53 درصد است. در مدل‌هایی با read ارزان‌تر، این آستانه‌ها به‌ترتیب حدود 20 تا 21 درصد و 51 درصد هستند.

FAQ

چند بار باید از یک prompt استفاده شود تا caching از نظر هزینه توجیه‌پذیر شود؟

در cache پنج‌دقیقه‌ای، یک بار کافی است. هزینه write برابر با 1.25 برابر input پایه و هزینه read در بیشتر مدل‌ها برابر با 0.1 برابر است؛ بنابراین هزینه N درخواست بدون cache برابر با N و هزینه N درخواست با cache برابر با 1.25 به‌اضافه 0.1 ضربدر N منهای 1 است. این دو مقدار در N = 1.28 برابر می‌شوند؛ بنابراین درخواست دوم نیز از نظر هزینه به‌صرفه است. در مدل‌هایی که هزینه read برابر با 0.05 یا 0.025 است، نقطه تلاقی N = 1.26 خواهد بود و نتیجه همان است. در cache یک‌ساعته، هزینه write برابر با 2 برابر است و نقطه تلاقی در N = 2.11 قرار دارد؛ این مقدار با readهای ارزان‌تر حدود 2.05 است. بنابراین به دو read نیاز دارد.

چرا cache_read_input_tokens همیشه صفر است؟

ابتدا طول prefix را بررسی کنید: اگر طول آن از حداقل مدل کمتر باشد—512 توکن برای Claude Opus 5 و 4,096 برای Claude Haiku 4.5 در October 2026—caching بدون نمایش خطا رد می‌شود و هر دو شمارنده مقدار 0 را نشان می‌دهند. اگر prefix به‌اندازه کافی طولانی است، به دنبال محتوایی بگردید که بین فراخوانی‌ها تغییر می‌کند و در محل breakpoint یا پیش از آن قرار دارد؛ برای مثال timestamp یا session identifier در system prompt. اگر شمارنده‌ها قبلاً درست کار می‌کردند و سپس متوقف شدند، فاصله بین درخواست‌ها از طول عمر cache بیشتر بوده است.

آیا prompt caching پاسخ‌های Claude را تغییر می‌دهد؟

خیر. cache شکل پردازش‌شده توکن‌هایی را که قبلاً ارسال کرده‌اید ذخیره می‌کند و مدل در هر دو حالت همان prompt را می‌بیند. این قابلیت برای هزینه و latency است و رفتار مدل را تغییر نمی‌دهد. بنابراین می‌توانید آن را برای یک prompt فعال و عملیاتی کنید، بدون آن‌که ارزیابی‌های خود را دوباره اجرا کنید.

آیا باید برای cache یک‌ساعته هزینه پرداخت کنم؟

فقط زمانی که بین درخواست‌های شما فاصله‌هایی بیشتر از 5 دقیقه وجود دارد و hit rate شما همچنان تقریباً از 53 درصد بیشتر می‌ماند؛ این مقدار در مدلی با read ارزان‌تر حدود 51 درصد است. در صورت miss، هزینه write برابر با 2 برابر، چهار برابر write با هزینه 1.25 برابر است. یک write ناموفق در cache یک‌ساعته، کل قیمت پایه input مربوط به prefix را هدر می‌دهد؛ درحالی‌که write ناموفق در cache پنج‌دقیقه‌ای فقط یک‌چهارم آن را هدر می‌دهد. یک ورودی پنج‌دقیقه‌ای با هر hit تازه‌سازی می‌شود؛ بنابراین ترافیک پیوسته آن را با هزینه read فعال نگه می‌دارد، بدون آن‌که هیچ‌گاه هزینه عمر طولانی‌تر را پرداخت کنید.

آیا این مقاله مفید بود؟

#claude#prompt-caching#api#token-costs#optimization