پرش به مطلب اصلی
جستجو

سرآیندهای درخواست

در بیشتر درخواست‌ها فقط به دو سرآیند نیاز دارید: Authorization و Content-Type. سرآیندهای دیگر زمانی لازم می‌شوند که بخواهید رفتارهایی مثل رد درخواست، حافظه نهان یا گاردریل را از سمت کلاینت کنترل کنید.

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

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

سرآیندلازم است؟کاربرد
Authorizationبلهاحراز هویت با توکن گدارAI
Content-Typeبرای بدنه JSON بلهاعلام نوع بدنه درخواست

نمونه:

Authorization: Bearer YOUR_GODARAI_TOKEN
Content-Type: application/json

گدارAI برای سازگاری، api-key و x-api-key را هم می‌پذیرد، اما روش پیشنهادی مستندات Authorization است.

سرآیندهای عمومی گدارAI​

سرآیندجهتکاربرد
x-godarai-trace-idدرخواستارسال شناسه رد درخواست از سمت سیستم شما
x-godarai-tenantدرخواستراهنمای فضای کاری در مسیرهایی که به آن نیاز دارند
x-godarai-cache-configدرخواستتنظیم رفتار حافظه نهان برای همان درخواست
x-godarai-guardrailsدرخواستانتخاب گاردریل‌های ورودی یا خروجی
x-godarai-guardrails-scopeدرخواستتعیین محدوده اجرای گاردریل‌های ورودی
x-godarai-cost-usdپاسخهزینه دلاری ثبت‌شده برای درخواست، در صورت محاسبه
x-godarai-cost-irrپاسخهزینه ریالی ثبت‌شده برای درخواست، در صورت محاسبه
x-godarai-cache-statusپاسخوضعیت حافظه نهان
x-godarai-cached-trace-idپاسخشناسه درخواست منبع در پاسخ‌های برگرفته از حافظه نهان
x-godarai-cache-similarity-scoreپاسخامتیاز شباهت در حافظه نهان هوشمند، در صورت استفاده

Authorization​

همه درخواست‌های مدل باید با توکن گدارAI احراز هویت شوند:

Authorization: Bearer YOUR_GODARAI_TOKEN

اگر این سرآیند ارسال نشود یا توکن معتبر نباشد، معمولاً خطای 401 دریافت می‌کنید.

x-godarai-trace-id​

اگر در سامانه خودتان شناسه درخواست دارید و می‌خواهید همان شناسه در گدارAI هم قابل جست‌وجو باشد، آن را با این سرآیند بفرستید:

x-godarai-trace-id: order-7421-chat-1

اگر این سرآیند را نفرستید، گدارAI برای درخواست شناسه تولید می‌کند. در بعضی مسیرها، x-trace-id نیز به‌عنوان نام جایگزین شناخته می‌شود.

x-godarai-tenant​

این سرآیند راهنمای فضای کاری است:

x-godarai-tenant: acme

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

x-godarai-cache-config​

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

x-godarai-cache-config: {"type":"simple","ttl":600,"namespace":"production"}

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

x-godarai-guardrails​

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

نمونه JSON:

x-godarai-guardrails: {"llm_input_guardrails":["guardrails/pii-redaction"]}

نمونه فهرست ساده برای گاردریل‌های ورودی:

x-godarai-guardrails: guardrails/pii-redaction, guardrails/secrets-detection

برای جزئیات بیشتر، گاردریل‌ها را بخوانید.

x-godarai-guardrails-scope​

این سرآیند محدوده اجرای گاردریل‌های ورودی را مشخص می‌کند:

x-godarai-guardrails-scope: last

مقدارهای معتبر:

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

اگر گاردریل خروجی لازم دارید، آن را داخل x-godarai-guardrails و با کلید llm_output_guardrails مشخص کنید.

سرآیندهای پاسخ برای حافظه نهان​

اگر از حافظه نهان استفاده می‌کنید، این سرآیندهای پاسخ برای عیب‌یابی مفیدند:

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

این مقدارها را می‌توانید در گزارش‌های سمت کلاینت خود ذخیره کنید تا رفتار حافظه نهان قابل بررسی بماند.

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

در بعضی پاسخ‌ها، گدارAI هزینه را در سرآیندهای زیر برمی‌گرداند:

  • x-godarai-cost-usd
  • x-godarai-cost-irr

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

توصیه‌های عملی​

  • درخواست اول را فقط با Authorization و Content-Type بفرستید.
  • برای هم‌بستگی با سامانه‌های خودتان، x-godarai-trace-id را اضافه کنید.
  • x-godarai-tenant را فقط وقتی بفرستید که معماری فضای کاری شما به آن نیاز دارد.
  • سرآیندهای حافظه نهان و گاردریل را بعد از روشن شدن سیاست محصول اضافه کنید.
  • سرآیندهای پاسخ هزینه و حافظه نهان را در لاگ کلاینت ثبت کنید، اگر برای پشتیبانی یا عیب‌یابی لازم‌اند.

گام بعدی​

پرسش‌های پرتکرار​

آیا x-godarai-tenant امنیت درخواست را تعیین می‌کند؟​

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

آیا باید همیشه x-godarai-trace-id بفرستم؟​

نه. اگر سامانه شما شناسه درخواست خودش را دارد و می‌خواهید آن را در گدارAI هم دنبال کنید، این سرآیند مفید است. در غیر این صورت، گدارAI شناسه تولید می‌کند.

آیا می‌توانم از x-api-key به‌جای Authorization استفاده کنم؟​

بله، پذیرفته می‌شود. با این حال، برای مستندات و نمونه‌های جدید، Authorization: Bearer ... را روش اصلی نگه دارید.