اجرای نسخه از درگاه

پس از ذخیره نسخه پرامپت، می‌توانید آن نسخه را با prompt_version_fqn از مسیر Chat Completions اجرا کنید. در این حالت، گدارAI نسخه را پیدا می‌کند، متغیرها را جایگذاری می‌کند، پیام‌های اختیاری درخواست را اضافه می‌کند و سپس درخواست را به مدل مسیریابی می‌کند.

پیش‌نیازها

• FQN نسخه را از رجیستری پرامپت کپی کرده باشید.
• توکن معتبر گدارAI داشته باشید.
• مدل نسخه، یا مدلی که در درخواست می‌فرستید، برای توکن شما مجاز باشد.

قالب FQN

FQN نسخه معمولاً این شکل را دارد:

chat_prompt:{tenant_slug}/{prompt_name}:{version}

نمونه:

chat_prompt:acme/support_reply:3

اطلاع

FQN به نسخه مشخص اشاره می‌کند، نه فقط نام پرامپت. اگر نسخه جدید بسازید، FQN نسخه قبلی تغییر نمی‌کند.

اجرای نسخه از کد

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:gpt-4o-mini",
  "prompt_version_fqn": "chat_prompt:acme/support_reply:3",
  "prompt_variables": {
    "customer_name": "سارا",
    "issue": "سفارش هنوز ارسال نشده است."
  },
  "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",
  },
  body: JSON.stringify({
  "model": "openai:default:gpt-4o-mini",
  "prompt_version_fqn": "chat_prompt:acme/support_reply:3",
  "prompt_variables": {
    "customer_name": "سارا",
    "issue": "سفارش هنوز ارسال نشده است."
  },
  "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" \
  --data '{
  "model": "openai:default:gpt-4o-mini",
  "prompt_version_fqn": "chat_prompt:acme/support_reply:3",
  "prompt_variables": {
    "customer_name": "سارا",
    "issue": "سفارش هنوز ارسال نشده است."
  },
  "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_body={
      "prompt_version_fqn": "chat_prompt:acme/support_reply:3",
      "prompt_variables": {
          "customer_name": "سارا",
          "issue": "سفارش هنوز ارسال نشده است.",
      },
  },
)

print(response.choices[0].message.content)

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: "پاسخ را کوتاه و قابل اقدام بنویس.",
    },
  ],
},
{
  body: {
    prompt_version_fqn: "chat_prompt:acme/support_reply:3",
    prompt_variables: {
      customer_name: "سارا",
      issue: "سفارش هنوز ارسال نشده است.",
    },
  },
},
);

console.log(response.choices[0].message.content);

در این مثال:

• پیام‌های ذخیره‌شده در نسخه support_reply رندر می‌شوند.
• مقدارهای customer_name و issue جایگذاری می‌شوند.
• پیام داخل messages بعد از پیام‌های نسخه اضافه می‌شود.
• مدل ارسالی در درخواست برای همین اجرا استفاده می‌شود.

نکته

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

در SDKهای OpenAI-compatible، فیلدهای اختصاصی گدارAI در بدنه درخواست به همان مسیر سازگار با OpenAI ارسال می‌شوند.

مدل و پیام‌ها چگونه ترکیب می‌شوند؟

در زمان اجرا:

1. گدارAI نسخه را با FQN پیدا می‌کند.
2. متغیرها را در پیام‌های نسخه جایگذاری می‌کند.
3. اگر درخواست messages داشته باشد، آن پیام‌ها به انتهای پیام‌های نسخه اضافه می‌شوند.
4. اگر درخواست model داشته باشد، همان مدل برای اجرا استفاده می‌شود؛ در غیر این صورت مدل ذخیره‌شده در نسخه مبنا قرار می‌گیرد.
5. نتیجه در گزارش رخدادها با متادیتای پرامپت قابل پیگیری است.

مشاهده‌پذیری

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

فیلد	توضیح
prompt_id	شناسه پرامپت.
prompt_version_id	شناسه نسخه اجراشده.
prompt_fqn	FQN نسخه.
prompt_version	شماره نسخه.

این داده‌ها کمک می‌کنند بعداً بفهمید کدام نسخه در کدام درخواست، با چه هزینه و چه نتیجه‌ای اجرا شده است.

اجرای هم‌زمان با تنظیمات دیگر

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

• برای کش پاسخ، سرآیند x-godarai-cache-config را بفرستید.
• برای گاردریل‌ها، سرآیند x-godarai-guardrails را بفرستید.
• برای خروجی ساخت‌یافته، response_format را در بدنه درخواست بگذارید.
• برای کنترل هزینه و مصرف، قوانین بودجه و محدودسازی نرخ همچنان در مسیر درگاه اعمال می‌شوند.

هشدار

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

گام بعدی

• برای تنظیم کش، گاردریل و خروجی ساخت‌یافته، تنظیمات پیشرفته نسخه را بخوانید.
• برای خطاهای رایج اجرا، عیب‌یابی رجیستری پرامپت را ببینید.