پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

کش کردن پرامپت (Prompt Caching)

با استفاده از کش کردن پرامپت، تاخیر و هزینه را کاهش دهید.

فهرست مطالب

نمای کلی
ساختاردهی پرامپت‌ها برای کش شدن
نحوه عملکرد
هزینه نوشتن کش و Breakpoint در GPT-5.6
مسیریابی و ماندگاری کش پرامپت
الگوهای Responses و Chat Completions
الزامات
اندازه‌گیری عملکرد کش
چه چیزهایی می‌توانند کش شوند
بهترین شیوه‌ها
عیب‌یابی Cache Miss
کش کردن زمینه Gemini
سوالات متداول
منابع مرتبط

نمای کلی

پرامپت‌های مدل اغلب حاوی محتوای تکراری مانند پرامپت‌های سیستمی و دستورالعمل‌های رایج هستند. ارائه‌دهندگان مدل‌های زیربنایی (مانند OpenAI) ممکن است درخواست‌های API را به سرورهایی هدایت کنند که اخیرا همان پرامپت را پردازش کرده‌اند، که این امر باعث می‌شود پردازش پرامپت نسبت به پردازش از ابتدا، به طور بالقوه ارزان‌تر و سریع‌تر باشد. OpenAI کش کردن پرامپت را یک بهینه‌سازی خودکار معرفی می‌کند که در ترافیک واجد شرایط می‌تواند latency را تا ۸۰٪ و هزینه توکن ورودی را تا ۹۰٪ کاهش دهد؛ هنگام استفاده از AvalAI این اعداد را وابسته به provider/model بدانید و فیلدهای واقعی usage همان route را بررسی کنید. نوشتن کش برای مدل‌های OpenAI پیش از خانواده GPT-5.6 هزینه جداگانه ندارد. نوشتن کش در GPT-5.6 با نرخ ۱.۲۵ برابر ورودی عادی محاسبه می‌شود.

توجه: در دسترس بودن و تخفیف‌های خاص به ارائه دهنده مدل زیربنایی و مدل خاص مورد استفاده بستگی دارد. لطفا برای جزئیات دقیق به مستندات ارائه دهنده مدل مراجعه کنید.

در AvalAI، کش کردن پرامپت می‌تواند برای مدل‌های سازگار با OpenAI که رفتار کش سمت ارائه‌دهنده را expose می‌کنند اعمال شود؛ از جمله gpt-5.6-sol، gpt-5.6-terra، gpt-5.6-luna، gpt-5.5، gpt-5.4، gpt-5.4-pro، gpt-5.2، gpt-5.1، gpt-5-mini، gpt-4.1، gpt-4o، o3 و o4-mini. در دسترس بودن، کنترل‌های request، رفتار ماندگاری و تخفیف همچنان به provider و route بستگی دارد؛ فیلدهای usage پاسخ همان درخواستی را بررسی کنید که واقعا ارسال می‌کنید.

این راهنما نحوه عملکرد کلی کش کردن پرامپت را شرح می‌دهد تا بتوانید پرامپت‌های خود را برای تاخیر و هزینه بالقوه کمتر بهینه‌سازی کنید.

ساختاردهی پرامپت‌ها برای کش شدن

Cache hit (موفقیت در یافتن کش) معمولا فقط برای تطابق دقیق پیشوند (prefix) در یک پرامپت امکان‌پذیر است. برای به حداکثر رساندن مزایای بالقوه کش، محتوای ثابت مانند دستورالعمل‌ها و مثال‌ها را در ابتدای پرامپت خود قرار دهید و محتوای متغیر مانند اطلاعات خاص کاربر را در انتها قرار دهید. این اصل همچنین در مورد تصاویر و ابزارها صدق می‌کند، که معمولا باید بین درخواست‌ها یکسان باشند تا پیشوند مطابقت داشته باشد.

Prompt Caching visualization (منبع تصویر: OpenAI)

نحوه عملکرد

کش کردن ممکن است به طور خودکار توسط ارائه‌دهنده مدل برای پرامپت‌هایی که از طول توکن مشخصی فراتر می‌روند فعال شود (برای OpenAI، ۱۰۲۴ توکن یا بیشتر). هنگامی که از طریق AvalAI به چنین مدلی درخواست API ارسال می‌کنید:

مسیریابی کش (Cache Routing): ارائه‌دهنده درخواست را بر اساس hash پیشوند پرامپت مسیریابی می‌کند. OpenAI مستند می‌کند که این hash معمولا از ۲۵۶ توکن اول شروع می‌شود، هرچند طول دقیق می‌تواند بر اساس مدل فرق کند. وقتی پشتیبانی شود، prompt_cache_key با hash پیشوند ترکیب می‌شود تا locality کش برای ترافیک تکراری بهتر شود.
جستجوی کش (Cache Lookup): ارائه‌دهنده بررسی می‌کند که آیا بخش اولیه (پیشوند) پرامپت شما روی ماشین انتخاب‌شده در کش وجود دارد یا خیر.
Cache Hit: اگر پیشوند منطبقی پیدا شود، ارائه‌دهنده پیشوند کش‌شده را reuse می‌کند. این کار می‌تواند تاخیر را کم کند و هزینه توکن‌های ورودی کش‌شده را کاهش دهد.
Cache Miss: اگر پیشوند منطبقی یافت نشود، ارائه‌دهنده کل پرامپت را پردازش می‌کند و ممکن است پیشوند را برای درخواست‌های آینده کش کند.

پیشوندهای کش‌شده معمولا برای دوره‌ای از عدم فعالیت فعال باقی می‌مانند، اما این زمان به ارائه‌دهنده و سیاست ماندگاری بستگی دارد. کش in-memory در OpenAI معمولا پس از ۵ تا ۱۰ دقیقه عدم فعالیت منقضی می‌شود و سقف آن حدود یک ساعت است؛ routeهای AvalAI وقتی ارائه‌دهنده زیربنایی OpenAI نباشد می‌توانند رفتار متفاوتی داشته باشند.

هزینه نوشتن کش و Breakpoint در GPT-5.6

GPT-5.6 مدل هزینه و کنترل کش را تغییر می‌دهد. OpenAI توکن‌های نوشته‌شده در کش را با نرخ ۱.۲۵ برابر ورودی عادی محاسبه می‌کند، تعداد توکن‌های نوشته‌شده را در cache_write_tokens و تعداد توکن‌های خوانده‌شده را در cached_tokens گزارش می‌دهد. کش ضمنی همچنان پیش‌فرض است، اما برنامه می‌تواند بعد از محتوای ثابت prompt یک breakpoint صریح قرار دهد.

OpenAI برای GPT-5.6 و خانواده‌های بعدی این کنترل‌ها را تعریف می‌کند:

prompt_cache_options.mode: "implicit" breakpoint خودکار روی آخرین پیام را نگه می‌دارد و breakpointهای صریح را نیز استفاده می‌کند.
prompt_cache_options.mode: "explicit" breakpoint خودکار را غیرفعال می‌کند. اگر marker صریحی وجود نداشته باشد، request از prompt cache نمی‌خواند و چیزی در آن نمی‌نویسد.
prompt_cache_options.ttl: "30m" حداقل عمر کش را تعیین می‌کند. در حال حاضر 30m تنها مقدار پشتیبانی‌شده و مقدار پیش‌فرض است.
prompt_cache_breakpoint: {"mode": "explicit"} انتهای دقیق یک prefix قابل استفاده مجدد را روی content block پشتیبانی‌شده مشخص می‌کند.

کاتالوگ مدل AvalAI قابلیت prompt caching و قیمت نوشتن کش را برای routeهای GPT-5.6 تایید می‌کند، اما pass-through فیلدهای جدید breakpoint می‌تواند به route وابسته باشد. پیش از اتکا در production، route انتخابی را آزمایش کنید. اگر prompt_cache_options یا prompt_cache_breakpoint خطای 400 invalid_request_error داد، این فیلدها را حذف کنید و تا زمان اعلام پشتیبانی صریح همان route از کش خودکار استفاده کنید.

شکل زیر برای Responses فقط از breakpointهای صریح استفاده می‌کند. محتوای ثابت پیش از marker باید دست‌کم ۱۰۲۴ توکن داشته باشد:

json

{
  "model": "gpt-5.6-luna",
  "prompt_cache_key": "tenant-acme-support-policy-v3",
  "prompt_cache_options": {
    "mode": "explicit",
    "ttl": "30m"
  },
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "Long, stable support policy and examples...",
          "prompt_cache_breakpoint": {
            "mode": "explicit"
          }
        }
      ]
    },
    {
      "role": "user",
      "content": "Draft a reply for the current ticket."
    }
  ]
}

شکل معادل Chat Completions، marker را روی یک content block پشتیبانی‌شده می‌گذارد:

json

{
  "model": "gpt-5.6-luna",
  "prompt_cache_key": "tenant-acme-support-policy-v3",
  "prompt_cache_options": {
    "mode": "explicit",
    "ttl": "30m"
  },
  "messages": [
    {
      "role": "system",
      "content": [
        {
          "type": "text",
          "text": "Long, stable support policy and examples...",
          "prompt_cache_breakpoint": {
            "mode": "explicit"
          }
        }
      ]
    },
    {
      "role": "user",
      "content": "Draft a reply for the current ticket."
    }
  ]
}

هر request می‌تواند حداکثر چهار cache write جدید بسازد. در حالت implicit، breakpoint خودکار آخرین پیام یک slot را مصرف می‌کند و حداکثر سه write صریح جدید باقی می‌ماند؛ حالت explicit می‌تواند چهار breakpoint صریح آخر را بنویسد. OpenAI در حال حاضر حداکثر ۵۰ breakpoint آخر را برای read بررسی می‌کند و بلندترین prefix منطبق را به کار می‌برد. Responses از marker روی input_text، input_image و input_file پشتیبانی می‌کند؛ Chat Completions از text، image_url، input_audio، file و refusal. مدل‌های قدیمی‌تر کنترل‌های جدید را رد می‌کنند و باید همان کش خودکار موجود را ادامه دهند.

مسیریابی و ماندگاری کش پرامپت

برای ترافیک تکراری سازگار با OpenAI از طریق AvalAI، پیشوند را ثابت نگه دارید و در صورت پشتیبانی، برای workload، tenant یا پیکربندی assistant از prompt_cache_key ثابت استفاده کنید. کلیدی انتخاب نکنید که حجم زیادی از ترافیک را در یک bucket جمع کند: مستندات OpenAI توضیح می‌دهد که اگر ترکیب یک پیشوند و cache key از حدود ۱۵ درخواست در دقیقه بیشتر شود، بخشی از درخواست‌ها ممکن است به ماشین‌های دیگر overflow شوند و اثر کش کمتر شود.

با prompt_cache_key مثل یک برچسب مسیریابی رفتار کنید، نه داده کاربر. bucketهای opaque مانند support-policy-v3، tenant-acme-chat-v2 یا invoice-extractor-schema-v1 را ترجیح دهید. ایمیل، شماره تلفن، شناسه کاربر، شناسه ticket، کلید API یا secret خام را در key قرار ندهید؛ شناسه‌های مخصوص هر درخواست را نزدیک انتهای prompt بگذارید تا پیشوند مشترک را خراب نکنند.

کنترل retention بر اساس نسل مدل فرق می‌کند. برای GPT-5.6 و خانواده‌های بعدی از prompt_cache_options.ttl استفاده کنید؛ prompt_cache_retention برای این مدل‌ها deprecated است. برای مدل‌های پیش از GPT-5.6، prompt_cache_retention در صورت پشتیبانی همان سیاست حداکثر ماندگاری است. مثال gpt-5.5 زیر عمدا یک نمونه legacy برای retention است.

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model="gpt-5.5",
    instructions="You are the BrightCart support assistant. Follow the fixed policy below...",
    input="Draft a two-sentence reply for ticket ORDER-8831.",
    prompt_cache_key="brightcart-support-policy-v1",
    prompt_cache_retention="24h",
)

cached = response.usage.input_tokens_details.cached_tokens
print(f"cached prompt tokens: {cached}")
print(response.output_text)

از prompt_cache_retention="24h" فقط برای مدل‌ها و ارائه‌دهندگانی استفاده کنید که ماندگاری extended را پشتیبانی می‌کنند. OpenAI برای بسیاری از مدل‌های قابل cache ماندگاری کوتاه in-memory را مستند می‌کند (معمولا ۵ تا ۱۰ دقیقه عدم فعالیت، با سقف حدود یک ساعت) و برای مدل‌های پشتیبانی‌شده ماندگاری extended تا ۲۴ ساعت را ارائه می‌دهد. OpenAI همچنین مستند می‌کند که قیمت‌گذاری prompt cache برای ماندگاری in-memory و extended یکسان است؛ در AvalAI همچنان قیمت و فیلدهای usage همان route/model انتخابی را بررسی کنید. اگر provider یا مدل این پارامتر را از طریق AvalAI expose نمی‌کند، آن را حذف کنید و به کش خودکار in-memory تکیه کنید.

ماندگاری extended همچنان یک ویژگی performance است، نه state برنامه. OpenAI مستند می‌کند که extended caching ممکن است key/value tensorهای مشتق‌شده از محتوای مشتری را در storage محلی GPU نگه دارد، نه پاسخ نهایی؛ بیشتر استفاده‌ها پس از ۱ تا ۲ ساعت منقضی می‌شوند و سقف ماندگاری ۲۴ ساعت است. رفتار دقیق حریم خصوصی، residency و retention هنگام استفاده از AvalAI همچنان به provider و route وابسته است.

OpenAI در حال حاضر ماندگاری extended prompt cache را برای این خانواده مدل‌ها فهرست می‌کند: gpt-5.5، gpt-5.5-pro، gpt-5.4، gpt-5.2، gpt-5.1-codex-max، gpt-5.1، gpt-5.1-codex، gpt-5.1-codex-mini، gpt-5.1-chat-latest، gpt-5، gpt-5-codex و gpt-4.1. این را یک فهرست قابلیت upstream بدانید، نه تضمین AvalAI؛ پشتیبانی AvalAI به route، حساب و alias دقیق مدلی که فراخوانی می‌کنید وابسته است.

پیش از تنظیم این پارامتر، این چک‌لیست retention را اجرا کنید:

برای مدل‌های پیش از GPT-5.6 مانند gpt-5.5 که extended caching را از طریق AvalAI expose می‌کنند، فقط وقتی AvalAI پارامتر را عبور می‌دهد از prompt_cache_retention="24h" استفاده کنید. این پشتیبانی را برای GPT-5.6 یا خانواده‌های بعدی فرض نکنید؛ آن مدل‌ها به‌جای آن از prompt_cache_options.ttl استفاده می‌کنند.
برای مدل‌های قدیمی‌تر OpenAI که هم in_memory و هم 24h را پشتیبانی می‌کنند، بر اساس نیازمندی retention داده خودتان آگاهانه انتخاب کنید و به defaultها تکیه نکنید، چون defaultها هنگام فعال بودن Zero Data Retention می‌توانند متفاوت باشند.
برای Zero Data Retention، residency یا workloadهای regulated، تا وقتی route و policy دقیق provider را تأیید نکرده‌اید، حذف پارامترهای retention را ترجیح دهید.
هیچ‌وقت prompt caching را جایگزین ذخیره state مکالمه یا رکوردهای کسب‌وکار در دیتابیس برنامه خودتان نکنید.

الگوهای Responses و Chat Completions

برای اپلیکیشن‌های جدید AvalAI، API پاسخ‌ها (Responses API) را ترجیح دهید، چون با workflowهای stateful، چندوجهی و ابزارمحور هماهنگ‌تر است. برای اپلیکیشن‌های موجود v1/chat/completions، اگر migration پرریسک است همان route را نگه دارید؛ همان اصول caching وقتی اعمال می‌شود که prefix طولانی سیستم/developer، schema ابزارها، ترتیب تصاویر و schema خروجی ساختاریافته ثابت بمانند.

هنگام مهاجرت یک workload کش‌شده از Chat Completions به v1/responses، prefix ثابت را حفظ کنید و فقط شکل endpoint را تغییر دهید:

دستورالعمل‌های سیستمی طولانی و مشترک را در instructions یا اولین آیتم ثابت input قرار دهید.
متن پویا کاربر، snippetهای retrieval، timestampها و request IDها را نزدیک انتها نگه دارید.
برای همان assistant، tenant، policy یا schema از همان bucket در prompt_cache_key استفاده کنید.
برای Responses مقدار usage.input_tokens_details.cached_tokens و برای Chat Completions مقدار usage.prompt_tokens_details.cached_tokens را بررسی کنید؛ cache hit نشانه بهینه‌سازی است، نه نشانه correctness.

python

# Responses API — گزینه پیشنهادی برای کارهای جدید AvalAI
response = client.responses.create(
    model="gpt-5.5",
    instructions="You are the BrightCart support assistant. Follow the fixed policy below...",
    input="Draft a two-sentence reply for ticket ORDER-8831.",
    prompt_cache_key="brightcart-support-policy-v1",
    prompt_cache_retention="24h",
)
print(response.usage.input_tokens_details.cached_tokens)

python

# Chat Completions API — برای اپلیکیشن‌های موجود نگه دارید
chat_response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {
            "role": "system",
            "content": "You are the BrightCart support assistant. Follow the fixed policy below...",
        },
        {
            "role": "user",
            "content": "Draft a two-sentence reply for ticket ORDER-8831.",
        },
    ],
    prompt_cache_key="brightcart-support-policy-v1",
    prompt_cache_retention="24h",
)
print(chat_response.usage.prompt_tokens_details.cached_tokens)

الزامات

در دسترس بودن و رفتار کش به ارائه‌دهنده مدل بستگی دارد. برای OpenAI، پرامپت باید حداقل ۱۰۲۴ توکن (1024 tokens) داشته باشد تا توکن‌های کش‌شده بتوانند غیرصفر شوند. درخواست‌های زیر این آستانه نیز وقتی جزئیات usage برگردد فیلد cache دارند، اما cached_tokens صفر خواهد بود.

برخی از پاسخ‌های API شامل جزئیاتی درباره توکن‌های کش‌شده در آبجکت usage هستند:

json

{
  "usage": {
    "prompt_tokens": 2006,
    "completion_tokens": 300,
    "total_tokens": 2306,
    "prompt_tokens_details": {
      "cached_tokens": 1920,
      "cache_write_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

در این مثال، 1920 توکن prompt از cache خوانده شده و هیچ توکنی در cache نوشته نشده است. برای GPT-5.6 و خانواده‌های بعدی، وقتی route انتخابی این فیلد را expose کند، cache_write_tokens تعداد توکن‌های نوشته‌شده را نشان می‌دهد.

برای فراخوانی‌های Responses API، همین مفهوم زیر usage.input_tokens_details.cached_tokens دیده می‌شود. برای Chat Completions مقدار usage.prompt_tokens_details.cached_tokens را در پاسخ chat بررسی کنید. APIهای native provider مانند Gemini ممکن است نام‌های متفاوتی داشته باشند.

اندازه‌گیری عملکرد کش

Prompt caching را یک بهینه‌سازی قابل مشاهده بدانید. پیش و پس از بازچینی promptها، metricهای سبک اضافه کنید:

text

cache_hit_ratio = cached_tokens / input_or_prompt_tokens
uncached_tokens = input_or_prompt_tokens - cached_tokens

این فیلدها را بر اساس route، مدل، prompt_cache_key و نسخه پایدار prompt ثبت کنید:

توکن‌های ورودی/prompt، cached_tokens، در صورت بازگشت cache_write_tokens، توکن‌های خروجی، توکن‌های کل، latency p50/p95 و تعداد درخواست.
نسبت cache hit برای درخواست دوم و درخواست‌های بعدی در workload تکراری؛ درخواست اول معمولا warm-up miss است.
نرخ خطا یا fallback وقتی route انتخابی prompt_cache_retention را به‌دلیل پشتیبانی نکردن از extended retention رد می‌کند.

برای ترافیک GPT-5.6 هزینه read و write را جداگانه محاسبه کنید. cache write فقط وقتی به‌صرفه است که readهای تخفیف‌دار بعدی هزینه بیشتر write را جبران کنند. به جای اینکه هر مقدار غیرصفر را صرفه‌جویی بدانید، cache_write_tokens درخواست‌های warm-up را با cached_tokens درخواست‌های بعدی مقایسه کنید.

از این metricها برای تصمیم درباره split یا rotate کردن bucketهای cache استفاده کنید. یک prompt_cache_key مشترک می‌تواند locality را برای prefixهای مشترک بهتر کند، اما اگر یک key ترافیک بسیار متنوع یا زیاد را مخلوط کند، routing ارائه‌دهنده ممکن است overflow شود و hit rate افت کند. بررسی correctness را جدا نگه دارید: توکن‌های cacheشده می‌توانند هزینه و latency را کم کنند، اما کل prompt همچنان می‌تواند در rate limit حساب شود و پاسخ هر بار تازه تولید می‌شود.

چه چیزهایی می‌توانند کش شوند

اجزای زیر از یک درخواست اغلب می‌توانند به پیشوند پرامپت قابل کش کمک کنند:

پیام‌ها: آرایه کامل پیام‌ها (سیستم، کاربر، دستیار).
تصاویر: تصاویر موجود در پیام‌های کاربر به صورت URL، داده base64 یا فایل آپلودشده. ترتیب تصاویر و پارامتر detail را یکسان نگه دارید.
استفاده از ابزار: آرایه پیام‌ها/input و لیست tools موجود؛ schemaهای بزرگ ابزار می‌توانند به پیشوند قابل کش کمک کنند.
خروجی‌های ساختاریافته: schema خروجی ساختاریافته وقتی ثابت باشد می‌تواند بخشی از پیشوند قابل کش باشد.

بهترین شیوه‌ها

پرامپت‌ها را با محتوای ثابت در ابتدا و محتوای پویا در انتها ساختاردهی کنید.
جزئیات usage پاسخ API را برای cached_tokens، latency و cache-hit rate مانیتور کنید.
برای پیشوندهای تکراری از prompt_cache_key ثابت استفاده کنید، اما granularity را طوری انتخاب کنید که زیر محدودیت‌های مسیریابی provider بماند.
تعریف ابزارها، ترتیب تصاویر، schema خروجی ساختاریافته و متن policy طولانی را بین درخواست‌ها ثابت نگه دارید.
timestampها، user IDها، snippetهای بازیابی‌شده و facts مخصوص هر درخواست را نزدیک انتها بگذارید تا پیشوند مشترک را خراب نکنند.
کش را یک بهینه‌سازی بدانید، نه ویژگی correctness؛ برنامه شما باید حتی در cache miss هم درست کار کند.

عیب‌یابی Cache Miss

اگر cached_tokens برای ترافیکی که باید تکراری باشد همچنان 0 می‌ماند، قبل از تغییر مدل این موارد را بررسی کنید:

نشانه	علت محتمل	راه‌حل
پرامپت‌های کوتاه هرگز cache نمی‌شوند	درخواست زیر حداقل طول cacheable ارائه‌دهنده است	instruction، schema یا context مرجع ثابت را ترکیب کنید تا prefix تکراری به اندازه کافی بلند شود.
پرامپت‌های طولانی بعد از هر درخواست miss می‌شوند	مقدارهای پویا خیلی زود در prompt آمده‌اند	متن مخصوص کاربر، timestamp، snippetهای retrieval و request ID را بعد از prefix ثابت قرار دهید.
درخواست‌های tool-heavy به شکل غیرمنتظره miss می‌شوند	schema یا ترتیب ابزارها تغییر کرده است	نام ابزار، description، schema و ترتیب ابزارها را بین درخواست‌ها ثابت نگه دارید.
درخواست‌های تصویری miss می‌شوند	ترتیب تصویر، URL/bytes base64 یا مقدار `detail` تغییر کرده است	برای prefix مشترک از همان representation تصویر و همان مقدار `detail` استفاده کنید.
hit rate زیر بار افت می‌کند	یک `prompt_cache_key` ترافیک خیلی زیادی را در یک bucket جمع کرده است	کلیدها را بر اساس assistant، tenant یا workload جدا کنید تا هر ترکیب prefix/key در محدوده منطقی بماند.
فقط یک provider miss می‌دهد	route/model انتخابی جزئیات caching را از طریق AvalAI expose نمی‌کند	صفحه provider را بررسی کنید، پارامترهای retention پشتیبانی‌نشده را حذف کنید و به رفتار عادی درخواست تکیه کنید.

کش کردن زمینه Gemini

مدل‌های Gemini مکانیزم کش زمینه مخصوص خود را با دو نوع متمایز دارند: کش ضمنی (Implicit Caching) و کش صریح (Explicit Caching).

کش ضمنی در مقابل کش صریح

ویژگی	کش ضمنی	کش صریح
فعال‌سازی	خودکار	دستی (کنترل توسط توسعه‌دهنده)
صرفه‌جویی در هزینه	تضمین نشده	تضمین شده
تنظیمات مورد نیاز	هیچ	ایجاد/مدیریت محتوای کش شده
کنترل TTL	خیر	بله (قابل تنظیم)
پشتیبانی AvalAI	⚠️ ممکن اما تضمین نشده	❌ در حال حاضر پشتیبانی نمی‌شود

وضعیت پشتیبانی AvalAI

مهم

از آنجایی که AvalAI یک تجمیع‌کننده API است، درخواست‌های مختلف API ممکن است به زیرساخت‌های متفاوتی ارسال شوند. ما تلاش می‌کنیم درخواست‌های کاربران یکتا را به همان زیرساخت هدایت کنیم، اما این تضمین نشده است. بنابراین، مزایای کش ضمنی را نمی‌توان در AvalAI تضمین کرد.

نوع کش	وضعیت	توضیحات
کش ضمنی	⚠️ ممکن	درخواست‌ها ممکن است به زیرساخت‌های مختلف هدایت شوند
کش صریح	❌ پشتیبانی نمی‌شود	ممکن است در به‌روزرسانی‌های آینده اضافه شود

جزئیات کش ضمنی

کش ضمنی به طور پیش‌فرض در مدل‌های Gemini فعال است. هنگامی که درخواست شما به کش برخورد کند، Google به طور خودکار صرفه‌جویی در هزینه را اعمال می‌کند.

حداقل الزامات توکن برای Gemini

مدل	حداقل تعداد توکن
Gemini 3 Flash Preview	۱،۰۲۴ توکن
Gemini 3 Pro Preview	۴،۰۹۶ توکن
Gemini 2.5 Flash	۱،۰۲۴ توکن
Gemini 2.5 Pro	۴،۰۹۶ توکن

نکاتی برای افزایش احتمال Cache Hit

محتوای بزرگ و ثابت را در ابتدای پرامپت قرار دهید
- دستورالعمل‌های سیستمی
- اسناد مرجع
- مثال‌های Few-shot
درخواست‌های مشابه را در فاصله زمانی کوتاه ارسال کنید
- درخواست‌هایی با همان پیشوند که نزدیک به هم ارسال می‌شوند احتمال cache hit بالاتری دارند
محتوای پویا را در انتها نگه دارید
- اطلاعات خاص کاربر
- پرسش‌های متغیر
- برچسب‌های زمانی و شناسه‌های یکتا

بررسی Cache Hit در پاسخ‌های Gemini

هنگام استفاده از API بومی Gemini، می‌توانید cache hitها را در پاسخ بررسی کنید:

Python

python

import os
from google import genai

client = genai.Client(
    api_key=os.environ["AVALAI_API_KEY"],
    http_options={"base_url": "https://api.avalai.ir"},
)

response = client.models.generate_content(
    model="gemini-2.5-flash", contents="پرامپت شما با زمینه قابل توجه..."
)

# بررسی متادیتای استفاده برای اطلاعات کش
if hasattr(response, "usage_metadata"):
    usage = response.usage_metadata
    print(f"توکن‌های پرامپت: {usage.prompt_token_count}")
    print(f"توکن‌های کش شده: {getattr(usage, 'cached_content_token_count', 0)}")
    print(f"توکن‌های خروجی: {usage.candidates_token_count}")

JavaScript

javascript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
  apiKey: process.env.AVALAI_API_KEY,
  httpOptions: { baseUrl: "https://api.avalai.ir" }
});

const response = await client.models.generateContent({
  model: "gemini-2.5-flash",
  contents: "پرامپت شما با زمینه قابل توجه..."
});

// بررسی متادیتای استفاده برای اطلاعات کش
if (response.usageMetadata) {
  console.log(`توکن‌های پرامپت: ${response.usageMetadata.promptTokenCount}`);
  console.log(`توکن‌های کش شده: ${response.usageMetadata.cachedContentTokenCount || 0}`);
  console.log(`توکن‌های خروجی: ${response.usageMetadata.candidatesTokenCount}`);
}

cURL

bash

curl -X POST "https://api.avalai.ir/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "پرامپت شما با زمینه قابل توجه..."}]
    }]
  }'

# پاسخ شامل usage_metadata با تعداد توکن‌های کش شده خواهد بود

کش صریح (پشتیبانی نمی‌شود)

کش صریح به شما امکان می‌دهد محتوا را به صورت دستی کش کنید و در درخواست‌های بعدی با استفاده از cachedContent به آن ارجاع دهید. این روش صرفه‌جویی در هزینه را تضمین می‌کند اما نیاز به تنظیمات اضافی دارد.

توجه

endpointهای کش صریح (/cachedContents) در حال حاضر در AvalAI پشتیبانی نمی‌شوند. ممکن است در به‌روزرسانی‌های آینده پشتیبانی اضافه شود.

چرا کش صریح پشتیبانی نمی‌شود

به عنوان یک تجمیع‌کننده API، AvalAI درخواست‌ها را در چندین زیرساخت برای اطمینان و عملکرد توزیع می‌کند. کش صریح نیاز دارد به:

ذخیره‌سازی پایدار متصل به زیرساخت خاص
هدایت ثابت همه درخواست‌های مرتبط به همان سرورها
مدیریت مستقیم چرخه حیات کش

این الزامات با معماری توزیع شده AvalAI در تضاد هستند.

موارد استفاده مناسب برای کش کردن

کش کردن زمینه به ویژه برای موارد زیر مفید است:

چت‌بات‌ها با دستورالعمل‌های سیستمی گسترده - تعریف شخصیت بزرگ، پایگاه دانش شرکت
برنامه‌های تحلیل اسناد - پرسش‌های تکراری از همان اسناد
ابزارهای تحلیل کد - تحلیل مخزن، رفع اشکال در کدبیس‌های مشابه
تحلیل ویدیو/صوت - سوالات متعدد درباره همان فایل رسانه‌ای

سوالات متداول (بر اساس پیاده‌سازی OpenAI)

حریم خصوصی داده‌ها برای کش‌ها چگونه حفظ می‌شود؟ کش‌های پرامپت معمولا بین سازمان‌ها به اشتراک گذاشته نمی‌شوند. فقط اعضای همان سازمان می‌توانند از کش‌های پرامپت‌های یکسان ارسال شده توسط آن سازمان بهره‌مند شوند. AvalAI به عنوان یک پروکسی عمل می‌کند، بنابراین مزایای کش به نحوه مدیریت درخواست‌ها توسط ارائه دهنده زیربنایی از زیرساخت AvalAI یا به طور بالقوه سازمان خاص شما (در صورت استفاده از ویژگی‌های قابل اعمال ارائه دهنده) بستگی دارد.
آیا کش کردن پرامپت بر پاسخ نهایی تاثیر می‌گذارد؟ خیر. کش کردن پرامپت نباید بر تولید توکن‌های خروجی یا پاسخ نهایی تاثیر بگذارد. فقط پردازش پرامپت به طور بالقوه بهینه می‌شود؛ پاسخ هر بار بر اساس پرامپت کامل (که ممکن است بخشی از آن کش شده باشد) دوباره محاسبه می‌شود.
آیا راهی برای پاک کردن دستی کش وجود دارد؟ پاک کردن دستی کش معمولا در دسترس نیست. کش‌ها معمولا پس از دوره‌های عدم فعالیت به طور خودکار پاک می‌شوند.
آیا هزینه اضافی برای کش کردن پرامپت وجود دارد؟ نوشتن cache برای مدل‌های OpenAI پیش از GPT-5.6 هزینه جداگانه ندارد. در GPT-5.6 و خانواده‌های بعدی، cache write با نرخ ۱.۲۵ برابر ورودی عادی محاسبه می‌شود و readهای بعدی از نرخ تخفیف‌دار ورودی کش‌شده استفاده می‌کنند. پیش از ادعای صرفه‌جویی خالص، هم cache_write_tokens و هم cached_tokens را بررسی کنید.
آیا پرامپت‌های کش شده به محدودیت‌های نرخ TPM کمک می‌کنند؟ بله، توکن‌های کامل پرامپت (کش شده + غیر کش شده) معمولا در محدودیت‌های نرخ مانند توکن در دقیقه (TPM) محاسبه می‌شوند. کش کردن بر هزینه و تاخیر تاثیر می‌گذارد، نه محاسبه محدودیت نرخ.
آیا تخفیف برای کش کردن پرامپت در همه جا در دسترس است؟ در دسترس بودن به ارائه دهنده و سطوح خدمات خاص بستگی دارد (به عنوان مثال، OpenAI آن را در APIهای استاندارد و Scale Tier ارائه می‌دهد، اما نه در Batch API).
آیا کش کردن پرامپت با درخواست‌های Zero Data Retention (ZDR) کار می‌کند؟ رفتار ارائه‌دهنده به مدل و حالت نگه‌داری cache وابسته است. OpenAI نگه‌داری cache در حافظه و extended را جداگانه مستند می‌کند؛ در AvalAI پیش از وعده دادن تضمین شبیه ZDR، route انتخابی را تأیید کنید.
آیا کش کردن پرامپت روی data residency اثر دارد؟ residency را وابسته به provider و route بدانید. OpenAI مستند می‌کند که in-memory caching داده prompt را روی disk ذخیره نمی‌کند و extended caching هنگام استفاده از regional inference باید در همان region بماند. در AvalAI پیش از تعهد residency به مشتری، route، region و رفتار retention ارائه‌دهنده انتخابی را بررسی کنید.
آیا prompt_cache_key باید کاربران فردی را شناسایی کند؟ معمولا نه. از bucketهای پایدار و opaque برای workload، tenant، assistant، policy یا schema استفاده کنید و شناسه‌های شخصی خام را بیرون از cache key نگه دارید. هر وقت policy طولانی‌مدت، schema ابزار یا prefix prompt تغییر کرد، key را rotate کنید.
آیا می‌توانم برای correctness یا continuity به prompt cache تکیه کنم؟ خیر. Cache hit فقط پردازش prompt تکراری را بهینه می‌کند. جایگزین ارسال context کامل موردنیاز نیست، state مکالمه برنامه شما را نگه نمی‌دارد و توکن‌های prompt کش‌شده همچنان می‌توانند در محدودیت TPM حساب شوند.

منابع مرتبط

این راهنما با اقتباس از OpenAI Cookbook رسمی و مخزن openai/openai-cookbook، با تغییرات endpoint، کلید API، مدل و مرزهای پشتیبانی AvalAI تهیه شده است.

کش کردن پرامپت (Prompt Caching) ​

فهرست مطالب ​

نمای کلی ​

ساختاردهی پرامپت‌ها برای کش شدن ​

نحوه عملکرد ​

هزینه نوشتن کش و Breakpoint در GPT-5.6 ​

مسیریابی و ماندگاری کش پرامپت ​

الگوهای Responses و Chat Completions ​

الزامات ​

اندازه‌گیری عملکرد کش ​

چه چیزهایی می‌توانند کش شوند ​

بهترین شیوه‌ها ​

عیب‌یابی Cache Miss ​

کش کردن زمینه Gemini ​

کش ضمنی در مقابل کش صریح ​

وضعیت پشتیبانی AvalAI ​

جزئیات کش ضمنی ​

حداقل الزامات توکن برای Gemini ​

نکاتی برای افزایش احتمال Cache Hit ​

بررسی Cache Hit در پاسخ‌های Gemini ​

Python ​

JavaScript ​

cURL ​

کش صریح (پشتیبانی نمی‌شود) ​

چرا کش صریح پشتیبانی نمی‌شود ​

موارد استفاده مناسب برای کش کردن ​

سوالات متداول (بر اساس پیاده‌سازی OpenAI) ​

منابع مرتبط ​

کش کردن پرامپت (Prompt Caching)

فهرست مطالب

نمای کلی

ساختاردهی پرامپت‌ها برای کش شدن

نحوه عملکرد

هزینه نوشتن کش و Breakpoint در GPT-5.6

مسیریابی و ماندگاری کش پرامپت

الگوهای Responses و Chat Completions

الزامات

اندازه‌گیری عملکرد کش

چه چیزهایی می‌توانند کش شوند

بهترین شیوه‌ها

عیب‌یابی Cache Miss

کش کردن زمینه Gemini

کش ضمنی در مقابل کش صریح

وضعیت پشتیبانی AvalAI

جزئیات کش ضمنی

حداقل الزامات توکن برای Gemini

نکاتی برای افزایش احتمال Cache Hit

بررسی Cache Hit در پاسخ‌های Gemini

Python

JavaScript

cURL

کش صریح (پشتیبانی نمی‌شود)

چرا کش صریح پشتیبانی نمی‌شود

موارد استفاده مناسب برای کش کردن

سوالات متداول (بر اساس پیاده‌سازی OpenAI)

منابع مرتبط