متغیرها و رندر پرامپت

متغیرها کمک می‌کنند یک پرامپت ثابت را برای چند کاربر، سفارش، پروژه یا وضعیت مختلف استفاده کنید. در رجیستری پرامپت، متغیرها با قالب {{variable_name}} داخل پیام‌ها نوشته می‌شوند و هنگام اجرا از prompt_variables مقدار می‌گیرند.

قالب متغیر

متغیر باید داخل دو آکولاد نوشته شود:

{{customer_name}}
{{issue}}
{{order_id}}

نام متغیر باید با حرف انگلیسی یا _ شروع شود و بعد از آن می‌تواند حرف انگلیسی، عدد یا _ داشته باشد.

نمونه معتبر:

{{customer_name}}
{{order_id}}
{{_internal_note}}

نمونه نامناسب:

{{customer-name}}
{{123_order}}
{{نام_مشتری}}

نکته

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

متغیرها چگونه تشخیص داده می‌شوند؟

رجیستری پرامپت متن پیام راهنما و قالب گفتگو را بررسی می‌کند و متغیرهایی مثل {{customer_name}} را در بخش «متغیرهای ورودی» نشان می‌دهد.

برای هر متغیر می‌توانید مقدار تستی وارد کنید تا در «تست آزمایشی» جایگذاری شود. در اجرای واقعی، اپلیکیشن شما مقدارها را در prompt_variables می‌فرستد.

نمونه رندر

قالب پرامپت:

سلام {{customer_name}}،
درباره سفارش {{order_id}} این پاسخ را آماده کن:
{{issue}}

مقدارهای زمان اجرا:

{
  "customer_name": "سارا",
  "order_id": "ORD-10293",
  "issue": "سفارش هنوز ارسال نشده است."
}

متن رندرشده:

سلام سارا،
درباره سفارش ORD-10293 این پاسخ را آماده کن:
سفارش هنوز ارسال نشده است.

ارسال مقدارها در اجرای نسخه

وقتی نسخه ذخیره‌شده را از مسیر درگاه اجرا می‌کنید، مقدارها را در prompt_variables بفرستید:

{
  "model": "openai:default:gpt-4o-mini",
  "prompt_version_fqn": "chat_prompt:acme/support_reply:3",
  "prompt_variables": {
    "customer_name": "سارا",
    "issue": "سفارش هنوز ارسال نشده است."
  },
  "messages": []
}

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

هشدار

مقدار متغیرها می‌تواند داده شخصی یا محرمانه داشته باشد. برای مسیرهای حساس، گاردریل‌های ورودی مثل PII پایه یا تشخیص Secret را در طراحی اجرا لحاظ کنید.

افزودن پیام هنگام اجرا

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

نمونه:

{
  "model": "openai:default:gpt-4o-mini",
  "prompt_version_fqn": "chat_prompt:acme/support_reply:3",
  "prompt_variables": {
    "customer_name": "سارا",
    "issue": "تاخیر در ارسال"
  },
  "messages": [
    {
      "role": "user",
      "content": "پاسخ را در دو جمله بنویس."
    }
  ]
}

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

رندر بدون اجرای مدل

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

POST /api/v1/prompt-versions/{versionID}/render

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

خطاهای رایج

نشانه	علت	راه‌حل
missing prompt variable	یک یا چند متغیر مقدار نگرفته است.	همه نام‌های متغیر را در prompt_variables بفرستید.
متغیر در UI تشخیص داده نمی‌شود	قالب متغیر معتبر نیست.	از قالب {{variable_name}} استفاده کنید.
مقدار اشتباه جایگذاری می‌شود	نام متغیر در پرامپت و درخواست یکی نیست.	نام‌ها را دقیق و با حروف کوچک/بزرگ یکسان بررسی کنید.

گام بعدی

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