کش پاسخ در گدارAI

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

این قابلیت برای درخواست‌های POST /v1/chat/completions و POST /v1/responses کاربرد دارد و روی هر درخواست با سرآیند x-godarai-cache-config فعال می‌شود. اگر درخواست از حافظه نهان پاسخ داده شود، گدارAI همان پاسخ ذخیره‌شده را برمی‌گرداند و وضعیت آن را در سرآیندهای پاسخ و گزارش رخدادها نشان می‌دهد.

اطلاع

کش پاسخ گدارAI با حافظه نهان پرامپت سمت ارائه‌دهنده مدل یکی نیست. حافظه نهان پرامپت معمولاً بخشی از پردازش ورودی را در ارائه‌دهنده سبک‌تر می‌کند؛ اما کش پاسخ در گدارAI می‌تواند کل فراخوانی به ارائه‌دهنده مدل را حذف کند.

چه زمانی از کش پاسخ استفاده کنیم؟

کش پاسخ زمانی بیشترین اثر را دارد که درخواست‌ها الگوی تکراری دارند و پاسخ قدیمی هنوز برای کاربر معتبر است؛ برای نمونه:

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

هشدار

برای داده‌های لحظه‌ای، قیمت‌های زنده، وضعیت سفارش، موجودی انبار یا هر پاسخی که سریع منقضی می‌شود، کش را فقط با ttl کوتاه و namespace دقیق فعال کنید.

حالت‌های کش

گدارAI دو حالت اصلی برای کش پاسخ دارد:

حالت	رفتار	مناسب برای
`simple`	فقط وقتی پاسخ از کش برمی‌گردد که داده درخواست و پارامترهای مؤثر دقیقاً یکسان باشند.	مسیرهای حساس به دقت، پرامپت‌های ثابت، پاسخ‌های کاملاً قابل پیش‌بینی
`smart`	ابتدا تطبیق دقیق بررسی می‌شود؛ اگر پاسخی پیدا نشود، متن آخرین پیام کاربر به‌صورت معنایی مقایسه می‌شود.	پرسش‌های پرتکرار که کاربران با عبارت‌های متفاوت می‌پرسند

در کش هوشمند، آستانه شباهت با similarity_threshold تنظیم می‌شود. مقدار پیش‌فرض 0.9 نقطه شروع خوبی است: نه بیش از حد سخت‌گیرانه است و نه خیلی آزاد.

نکته

برای شروع، کش را روی یک مسیر کم‌ریسک با حالت simple فعال کنید، نرخ پاسخ از کش را ببینید و بعد برای پرسش‌های پرتکرار سراغ smart بروید.

فعال‌سازی کش در درخواست

برای فعال‌کردن کش، سرآیند x-godarai-cache-config را به درخواست اضافه کنید.

نمونه‌های زیر از Chat Completions استفاده می‌کنند. در Responses API همین سرآیند را همراه POST /v1/responses بفرستید و متن کاربر را در input قرار دهید. نمونه کامل را در راهنمای Responses API ببینید.

نمونه کش ساده

Python
NodeJS
REST API
OpenAI Python SDK
OpenAI NodeJS SDK

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
        "x-godarai-cache-config": "{\"type\":\"simple\",\"ttl\":600,\"namespace\":\"support\"}",
    },
    json={
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "شرایط لغو اشتراک چیست؟"
    }
  ]
},
    timeout=60,
)

response.raise_for_status()
print(response.json())

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
    "x-godarai-cache-config": "{\"type\":\"simple\",\"ttl\":600,\"namespace\":\"support\"}",
  },
  body: JSON.stringify({
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "شرایط لغو اشتراک چیست؟"
    }
  ]
}),
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --header "x-godarai-cache-config: {\"type\":\"simple\",\"ttl\":600,\"namespace\":\"support\"}" \
  --data '{
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "شرایط لغو اشتراک چیست؟"
    }
  ]
}'

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GODARAI_TOKEN",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

response = client.chat.completions.create(
    "model": "openai:default:gpt-4o-mini",
    messages=[
        {
          "role": "user",
          "content": "شرایط لغو اشتراک چیست؟"
        }
      ],
    extra_headers={
        "x-godarai-cache-config": "{\"type\":\"simple\",\"ttl\":600,\"namespace\":\"support\"}",
    }
)

print(response)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_GODARAI_TOKEN",
  baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const response = await client.chat.completions.create({
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "شرایط لغو اشتراک چیست؟"
    }
  ]
}, {
  headers: {
    "x-godarai-cache-config": "{\"type\":\"simple\",\"ttl\":600,\"namespace\":\"support\"}",
  },
});

console.log(response);

نمونه کش هوشمند

Python
NodeJS
REST API
OpenAI Python SDK
OpenAI NodeJS SDK

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
        "x-godarai-cache-config": "{\"type\":\"smart\",\"ttl\":900,\"similarity_threshold\":0.9,\"namespace\":\"helpdesk\"}",
    },
    json={
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "چطور رمز عبورم را بازیابی کنم؟"
    }
  ]
},
    timeout=60,
)

response.raise_for_status()
print(response.json())

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
    "x-godarai-cache-config": "{\"type\":\"smart\",\"ttl\":900,\"similarity_threshold\":0.9,\"namespace\":\"helpdesk\"}",
  },
  body: JSON.stringify({
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "چطور رمز عبورم را بازیابی کنم؟"
    }
  ]
}),
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --header "x-godarai-cache-config: {\"type\":\"smart\",\"ttl\":900,\"similarity_threshold\":0.9,\"namespace\":\"helpdesk\"}" \
  --data '{
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "چطور رمز عبورم را بازیابی کنم؟"
    }
  ]
}'

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GODARAI_TOKEN",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

response = client.chat.completions.create(
    "model": "openai:default:gpt-4o-mini",
    messages=[
        {
          "role": "user",
          "content": "چطور رمز عبورم را بازیابی کنم؟"
        }
      ],
    extra_headers={
        "x-godarai-cache-config": "{\"type\":\"smart\",\"ttl\":900,\"similarity_threshold\":0.9,\"namespace\":\"helpdesk\"}",
    }
)

print(response)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_GODARAI_TOKEN",
  baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const response = await client.chat.completions.create({
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "چطور رمز عبورم را بازیابی کنم؟"
    }
  ]
}, {
  headers: {
    "x-godarai-cache-config": "{\"type\":\"smart\",\"ttl\":900,\"similarity_threshold\":0.9,\"namespace\":\"helpdesk\"}",
  },
});

console.log(response);

پارامترهای `x-godarai-cache-config`

فیلد	الزامی	توضیح
`type`	بله	یکی از `simple` یا `smart`.
`ttl`	خیر	مدت نگهداری پاسخ در کش، بر حسب ثانیه.
`namespace`	خیر	فضای نام برای جداکردن کش بین محصول، محیط، پروژه یا جریان کاری.
`similarity_threshold`	برای `smart`	آستانه شباهت معنایی. معمولاً بین `0.8` تا `1.0` تنظیم می‌شود.

راهنمای انتخاب آستانه شباهت

مقدار	رفتار	پیشنهاد
`0.95` تا `1.0`	بسیار سخت‌گیرانه	وقتی پاسخ اشتباه هزینه زیادی دارد.
`0.88` تا `0.94`	متعادل	بیشتر چت‌بات‌ها و پرسش‌های پرتکرار.
`0.80` تا `0.87`	آزادتر	مسیرهای کم‌ریسک که پوشش بیشتر مهم‌تر است.

چرا `namespace` مهم است؟

اگر یک توکن یا یک مدل مجازی در چند بخش محصول استفاده می‌شود، namespace کمک می‌کند پاسخ‌های کش‌شده با هم قاطی نشوند. برای نمونه، می‌توانید برای هر بخش نام جدا داشته باشید:

support
helpdesk
mobile-app
customer-onboarding
tenant-123

اگر namespace مشخص نشود، گدارAI از مقدار پیش‌فرض استفاده می‌کند. برای مسیرهای حساس، بهتر است خودتان فضای نام مشخص و پایدار تعریف کنید.

چه درخواست‌هایی از حافظه نهان عبور می‌کنند؟

گدارAI درخواست‌های زیر را در هر دو حالت simple و smart با وضعیت bypass به مسیر عادی ارائه‌دهنده می‌فرستد:

درخواست‌های جریانی با stream: true
درخواست‌های Responses API با background: true
درخواست‌های Responses API که conversation یا previous_response_id دارند

این درخواست‌ها در ارائه‌دهنده وضعیت می‌سازند یا وضعیت قبلی را ادامه می‌دهند. پاسخ‌دادن از حافظه نهان می‌تواند این رفتار را حذف کند.

در حالت smart، موارد زیر نیز از حافظه نهان عبور می‌کنند:

درخواست‌هایی که tools یا tool_choice دارند
درخواست‌های Chat Completions که آخرین پیام آن‌ها از نقش user نیست
درخواست‌های Responses API که آخرین ورودی آن‌ها پیام کاربر نیست
درخواست‌هایی که آخرین پیام یا ورودی کاربر شامل تصویر، فایل یا محتوای غیرمتنی است

این رفتار کمک می‌کند کش فقط روی درخواست‌هایی اعمال شود که مقایسه معنایی آن‌ها قابل اتکاست.

سرآیندهای پاسخ

گدارAI وضعیت کش را در پاسخ نشان می‌دهد:

سرآیند	توضیح
`x-godarai-cache-status`	وضعیت کش: `hit`، `miss`، `bypass` یا `error`.
`x-godarai-cached-trace-id`	شناسه رخداد پاسخ اصلی، وقتی پاسخ از کش آمده باشد.
`x-godarai-cache-similarity-score`	امتیاز شباهت در کش هوشمند، اگر تطبیق معنایی انجام شده باشد.

برای تحلیل اثر کش، این سرآیندها را کنار گزارش رخدادها و سنجه‌های مدل بررسی کنید.

اثر کش روی هزینه

وقتی وضعیت کش hit باشد:

درخواست به ارائه‌دهنده مدل ارسال نمی‌شود.
هزینه تازه‌ای برای آن فراخوانی ایجاد نمی‌شود.
تأخیر پاسخ معمولاً کمتر می‌شود.
گزارش رخداد همچنان قابل ردیابی است و نشان می‌دهد پاسخ از کش آمده است.

در سنجه‌ها ممکن است مقدارهایی مثل «هزینه بدون کش» و «هزینه برآوردی صرفه‌جویی‌شده» را ببینید. این عددها کمک می‌کنند اثر واقعی کش را در کاهش مصرف بررسی کنید.

عیب‌یابی سریع

وضعیت	علت‌های رایج	چه کار کنید؟
همیشه `miss` می‌بینید	پرامپت، پارامترها یا `namespace` بین درخواست‌ها فرق می‌کند.	یک نمونه درخواست ثابت بسازید و همان را چند بار تکرار کنید.
وضعیت `bypass` است	درخواست جریانی یا وابسته به وضعیت ارائه‌دهنده است؛ یا در حالت `smart` ابزار، محتوای غیرمتنی یا شکل نامناسب پیام دارد.	فیلدهای `stream`، `background`، `conversation` و `previous_response_id` را بررسی کنید. برای محدودیت‌های مخصوص `smart`، در صورت مناسب‌بودن از `simple` استفاده کنید.
کش هوشمند پاسخ برنمی‌گرداند	آستانه شباهت خیلی سخت‌گیرانه است یا متن‌ها واقعاً متفاوت‌اند.	با مقدارهایی مثل `0.9` شروع کنید و براساس داده واقعی تنظیم کنید.
پاسخ قدیمی برمی‌گردد	`ttl` طولانی است یا فضای نام بیش از حد عمومی انتخاب شده است.	`ttl` را کوتاه‌تر کنید و `namespace` دقیق‌تری بگذارید.

جمع‌بندی

کش پاسخ در گدارAI فقط یک ابزار سرعت نیست؛ بخشی از کنترل مصرف است. با انتخاب حالت درست، ttl مناسب، فضای نام دقیق و بررسی سرآیندهای پاسخ، می‌توانید هم هزینه را کاهش دهید و هم رفتار محصول را قابل پیش‌بینی‌تر کنید.

چه زمانی از کش پاسخ استفاده کنیم؟​

حالت‌های کش​

فعال‌سازی کش در درخواست​

نمونه کش ساده​

نمونه کش هوشمند​

پارامترهای x-godarai-cache-config​

راهنمای انتخاب آستانه شباهت​

چرا namespace مهم است؟​

چه درخواست‌هایی از حافظه نهان عبور می‌کنند؟​

سرآیندهای پاسخ​

اثر کش روی هزینه​

عیب‌یابی سریع​

جمع‌بندی​