حافظه نهان و استدلال

در Chat Completions دو قابلیت می‌توانند تجربه و هزینه را جدی تغییر دهند:

• حافظه نهان برای پاسخ‌های تکراری یا مشابه.
• استدلال برای مدل‌هایی که مسائل چندمرحله‌ای را بهتر حل می‌کنند.

این دو قابلیت مفیدند، اما باید آگاهانه فعال شوند. هر دو روی زمان پاسخ، مصرف توکن، هزینه و عیب‌یابی اثر می‌گذارند.

دو نوع حافظه نهان را جدا کنید

وقتی درباره caching حرف می‌زنیم، دو مفهوم متفاوت داریم:

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

این دو را یکی فرض نکنید. تنظیم، اثر هزینه و محدودیت‌هایشان متفاوت است.

فعال‌کردن حافظه نهان پاسخ

برای تنظیم حافظه نهان در هر درخواست، از سرآیند x-godarai-cache-config استفاده کنید.

نمونه simple:

Python

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())

NodeJS

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);

REST API

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": "چطور رمز عبورم را بازیابی کنم؟"
    }
  ]
}'

OpenAI Python SDK

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)

OpenAI NodeJS SDK

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);

نمونه smart:

Python

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\":600,\"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())

NodeJS

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\":600,\"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);

REST API

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\":600,\"similarity_threshold\":0.9,\"namespace\":\"helpdesk\"}" \
  --data '{
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "روش بازیابی گذرواژه چیست؟"
    }
  ]
}'

OpenAI Python SDK

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\":600,\"similarity_threshold\":0.9,\"namespace\":\"helpdesk\"}",
    }
)

print(response)

OpenAI NodeJS SDK

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\":600,\"similarity_threshold\":0.9,\"namespace\":\"helpdesk\"}",
  },
});

console.log(response);

انتخاب بین simple و smart

حالت	مناسب برای	نکته
simple	درخواست‌های تقریباً یکسان	قابل پیش‌بینی‌تر و سخت‌گیرانه‌تر است.
smart	پرسش‌های مشابه با بیان متفاوت	به آستانه شباهت و کیفیت متن وابسته است.

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

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

درخواست‌هایی از این جنس معمولاً برای حافظه نهان پاسخ مناسب نیستند یا از آن عبور می‌کنند:

• stream: true
• درخواست دارای tools
• درخواست دارای tool_choice
• ورودی چندرسانه‌ای
• آخرین پیام غیرمتنی یا غیرکاربر
• داده‌هایی که باید همیشه تازه و لحظه‌ای باشند

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

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

برای تحلیل رفتار حافظه نهان، این سرآیندها را در سرویس خود ثبت کنید:

سرآیند	معنی
x-godarai-cache-status	وضعیت‌هایی مثل hit، miss، bypass یا error.
x-godarai-cached-trace-id	شناسه رد درخواست اصلی، وقتی پاسخ از حافظه نهان آمده باشد.
x-godarai-cache-similarity-score	امتیاز شباهت در حالت smart.

این داده‌ها برای اعتماد به حافظه نهان ضروری‌اند. فقط سریع‌تر شدن پاسخ کافی نیست؛ باید بدانید چرا سریع‌تر شده است.

استدلال چیست؟

بعضی مدل‌ها برای مسائل پیچیده می‌توانند زمان و توکن بیشتری صرف تحلیل کنند. در قراردادهای رایج، این رفتار با پارامترهایی مثل reasoning_effort یا فیلدهای خروجی مثل reasoning_content دیده می‌شود.

از استدلال استفاده کنید برای:

• تحلیل چندمرحله‌ای.
• برنامه‌ریزی.
• استخراج پیچیده.
• تصمیم‌گیری با چند شرط.
• عامل‌هایی که ابزار صدا می‌زنند.

برای پرسش‌های ساده، استدلال عمیق معمولاً فقط هزینه و زمان پاسخ را بالا می‌برد.

نمونه reasoning_effort

Python

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
    },
    json={
  "model": "openai:default:o4-mini",
  "messages": [
    {
      "role": "user",
      "content": "برای کاهش هزینه پاسخ‌های پرتکرار، یک برنامه سه‌مرحله‌ای پیشنهاد بده."
    }
  ],
  "reasoning_effort": "medium",
  "max_tokens": 1200
},
    timeout=60,
)

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

NodeJS

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "openai:default:o4-mini",
  "messages": [
    {
      "role": "user",
      "content": "برای کاهش هزینه پاسخ‌های پرتکرار، یک برنامه سه‌مرحله‌ای پیشنهاد بده."
    }
  ],
  "reasoning_effort": "medium",
  "max_tokens": 1200
}),
});

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

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

REST API

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "openai:default:o4-mini",
  "messages": [
    {
      "role": "user",
      "content": "برای کاهش هزینه پاسخ‌های پرتکرار، یک برنامه سه‌مرحله‌ای پیشنهاد بده."
    }
  ],
  "reasoning_effort": "medium",
  "max_tokens": 1200
}'

OpenAI Python SDK

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:o4-mini",
    messages=[
        {
          "role": "user",
          "content": "برای کاهش هزینه پاسخ‌های پرتکرار، یک برنامه سه‌مرحله‌ای پیشنهاد بده."
        }
      ],
    reasoning_effort="medium",
    max_tokens=1200

)

print(response)

OpenAI NodeJS SDK

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:o4-mini",
  "messages": [
    {
      "role": "user",
      "content": "برای کاهش هزینه پاسخ‌های پرتکرار، یک برنامه سه‌مرحله‌ای پیشنهاد بده."
    }
  ],
  "reasoning_effort": "medium",
  "max_tokens": 1200
});

console.log(response);

مقدارهای رایج reasoning_effort به مدل و ارائه‌دهنده وابسته‌اند؛ مثل low، medium و high. همیشه با مقدار کمتر شروع کنید و فقط وقتی کیفیت بهتر می‌شود مقدار را بالا ببرید.

حافظه نهان و استدلال با هم

این دو قابلیت مستقل‌اند، اما در عمل روی هم اثر می‌گذارند:

• استدلال می‌تواند مصرف توکن و زمان پاسخ را افزایش دهد.
• حافظه نهان می‌تواند درخواست‌های تکراری مناسب را کم‌هزینه‌تر کند.
• اگر ابزار، پاسخ جریانی یا ورودی چندرسانه‌ای وارد شود، رفتار حافظه نهان تغییر می‌کند.

برای ارزیابی، این سناریوها را جداگانه بسنجید:

• متن ساده بدون ابزار و بدون پاسخ جریانی.
• متن ساده با استدلال.
• استدلال همراه ابزار.
• ورودی چندرسانه‌ای همراه استدلال.

مصرف و هزینه

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

برای محیط عملیاتی، بهتر است این سنجه‌ها را پایش کنید:

• نرخ hit و miss.
• زمان پاسخ قبل و بعد از فعال‌سازی حافظه نهان.
• مصرف توکن در مدل‌های استدلالی.
• خطاهای ناشی از ناسازگاری مدل با پارامترهای استدلال.

جمع‌بندی

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