اولین درخواست به درگاه

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

1. نشانی پایه درگاه
2. توکن دسترسی گدارAI
3. شناسه مدل

با همین سه مقدار می‌توانید یک درخواست سازگار با OpenAI را به‌جای ارسال مستقیم به ارائه‌دهنده، از مسیر گدارAI عبور دهید.

پیش‌نیازها

• یک حساب ارائه‌دهنده فعال یا مدل مجازی آماده داشته باشید.
• توکن دسترسی ساخته باشید؛ برای تست انسانی PAT و برای سرویس‌ها VAT.
• شناسه مدل مجاز را از فضای کاری برداشته باشید.
• نقطه پایانی مناسب نوع مدل را انتخاب کرده باشید؛ برای متن، معمولاً Chat Completions شروع خوبی است.

۱. نشانی پایه درگاه را بردارید

نشانی پایه همان آدرسی است که SDK یا کلاینت شما درخواست‌ها را به آن می‌فرستد. در SDK رسمی OpenAI، مقدار base_url معمولاً باید به مسیر نسخه API ختم شود:

https://YOUR_WORKSPACE.godarai.ir/v1

این مقدار را از محیط یا میز تست فضای کاری خودتان بردارید. نشانی را حدس نزنید؛ تفاوت دامنه، مسیر /v1 یا محیط توسعه و عملیاتی می‌تواند باعث خطای اتصال شود.

۲. توکن دسترسی را آماده کنید

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

روش پیشنهادی:

Authorization: Bearer YOUR_GODARAI_TOKEN

برای انتخاب نوع توکن:

نوع	کاربرد مناسب
PAT	تست انسانی، توسعه محلی و ابزارهای شخصی
VAT	اپلیکیشن، سرویس پشت‌صحنه، پردازش زمان‌بندی‌شده و محیط عملیاتی

اگر هنوز درباره نوع توکن مطمئن نیستید، احراز هویت در گدارAI را بخوانید.

۳. شناسه مدل را انتخاب کنید

شناسه مدل همان مقداری است که در فیلد model می‌فرستید. این مقدار ممکن است:

• شناسه یک مدل فعال در حساب ارائه‌دهنده باشد؛ مثل openai:default:gpt-4o-mini
• شناسه فنی یک مدل مجازی باشد؛ مثل support-chat

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

۴. درخواست را بفرستید

ابتدا متغیرهای محیطی را تنظیم کنید:

export GODARAI_BASE_URL="https://YOUR_WORKSPACE.godarai.ir"
export GODARAI_TOKEN="YOUR_GODARAI_TOKEN"
export GODARAI_MODEL="YOUR_MODEL_ID"

سپس درخواست یکسان را با روش دلخواه خود بفرستید:

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": "YOUR_MODEL_ID",
  "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": "YOUR_MODEL_ID",
  "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": "YOUR_MODEL_ID",
  "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": "YOUR_MODEL_ID",
    messages=[
        {
          "role": "user",
          "content": "سلام، یک پاسخ کوتاه بده."
        }
      ]

)

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": "YOUR_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "سلام، یک پاسخ کوتاه بده."
    }
  ]
});

console.log(response);

نتیجه مورد انتظار: متن پاسخ مدل چاپ می‌شود و درخواست در «لاگ درخواست‌ها» یا «ردیابی درخواست‌ها» قابل بررسی است.

بررسی نتیجه

بعد از ارسال درخواست:

1. اگر پاسخ موفق دریافت کردید، مقدار model و محتوای پاسخ را بررسی کنید.
2. در «لاگ درخواست‌ها»، وضعیت درخواست، مدل، خطا یا هزینه را ببینید.
3. در «ردیابی درخواست‌ها»، مسیر اجرای درخواست و مقصد انتخاب‌شده را بررسی کنید.
4. اگر از مدل مجازی استفاده کرده‌اید، ببینید آیا مسیر جایگزین یا تلاش دوباره رخ داده است یا نه.

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

خطاهای رایج

خطای 401

توکن ارسال نشده، نادرست است، منقضی شده یا باطل شده است. مقدار Authorization را بررسی کنید و مطمئن شوید توکن را بدون فاصله اضافی فرستاده‌اید.

خطای 403

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

خطای مربوط به model

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

خطای سازگاری نقطه پایانی و مدل

مدل باید با نقطه پایانی سازگار باشد. برای نمونه، مدل امبدینگ را با Chat Completions و مدل چت را با Embeddings صدا نزنید.

پاسخ برنمی‌گردد یا دیر برمی‌گردد

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

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

• برای اولین تست، درخواست را کوتاه و ساده نگه دارید.
• نشانی پایه، توکن و شناسه مدل را داخل کد ثابت ننویسید؛ از تنظیمات یا متغیر محیطی استفاده کنید.
• برای محیط عملیاتی از VAT استفاده کنید تا هویت سرویس از حساب شخصی جدا بماند.
• نتیجه اولین درخواست را در گزارش رخداد یا رد درخواست بررسی کنید، نه فقط در خروجی SDK.

گام بعدی

• برای توضیح دقیق‌تر توکن‌ها، احراز هویت در گدارAI را بخوانید.
• برای پایدار کردن شناسه مدل، مدل مجازی بسازید.
• برای انتخاب API مناسب، Chat Completions را ببینید.

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

آیا باید کلید OpenAI یا Anthropic را در درخواست بفرستم؟

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

آیا می‌توانم از همان کد OpenAI استفاده کنم؟

در بسیاری از مسیرهای سازگار با OpenAI، بله. معمولاً base_url، توکن و مقدار model را تغییر می‌دهید. اگر از قابلیت اختصاصی یک ارائه‌دهنده استفاده می‌کنید، مسیر را جداگانه در محیط خودتان تست کنید.

از کجا بفهمم درخواست واقعاً از گدارAI عبور کرده است؟

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