Chat Completions

Chat Completions مسیر اصلی گدارAI برای ساخت پاسخ متنی، چت چندپیامی، فراخوانی ابزار و خروجی ساختاریافته است. این API با قرارداد سازگار با OpenAI کار می‌کند؛ یعنی بسیاری از SDKها و نمونه‌کدهای رایج را می‌توانید با تغییر base_url و توکن، از مسیر گدارAI اجرا کنید.

POST /v1/chat/completions

این API چه مسئله‌ای را حل می‌کند؟

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

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

چه زمانی انتخاب خوبی است؟

از Chat Completions استفاده کنید وقتی می‌خواهید:

• پاسخ متنی یا گفت‌وگویی تولید کنید.
• تاریخچه پیام‌ها را با messages نگه دارید.
• ورودی چندرسانه‌ای را همراه متن بفرستید، اگر مدل از آن پشتیبانی کند.
• ابزارها را با tools و tool_choice فعال کنید.
• خروجی JSON یا JSON Schema قابل پردازش بگیرید.
• پاسخ را به‌صورت جریانی در رابط کاربری نمایش دهید.

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

شروع سریع

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",
  "messages": [
    {
      "role": "user",
      "content": "سلام، گدارAI را در دو جمله معرفی کن."
    }
  ]
},
    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",
  "messages": [
    {
      "role": "user",
      "content": "سلام، گدارAI را در دو جمله معرفی کن."
    }
  ]
}),
});

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",
  "messages": [
    {
      "role": "user",
      "content": "سلام، گدارAI را در دو جمله معرفی کن."
    }
  ]
}'

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": "سلام، گدارAI را در دو جمله معرفی کن."
        }
      ]

)

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": "سلام، گدارAI را در دو جمله معرفی کن."
    }
  ]
});

console.log(response);

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

ساختار پایه درخواست

حداقل درخواست معمولاً شامل این دو فیلد است:

{
  "model": "openai:default:gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "تفاوت حافظه نهان و سقف نرخ را ساده توضیح بده."
    }
  ]
}

messages نباید خالی باشد. هر پیام یک role دارد و مقدارهای رایج آن system، user، assistant و tool هستند. پیام سیستمی برای تعیین رفتار کلی مدل خوب است، اما داده پویا و حساس را بهتر است در پیام کاربر یا نتیجه ابزار با کنترل دقیق‌تر وارد کنید.

پارامترهای رایج

پارامتر	کاربرد
temperature	میزان تنوع پاسخ را کنترل می‌کند. برای پاسخ‌های دقیق‌تر مقدار پایین‌تر انتخاب کنید.
top_p	روش دیگری برای کنترل تنوع است. معمولاً لازم نیست هم‌زمان با temperature زیاد تغییر کند.
max_tokens	سقف توکن خروجی را تعیین می‌کند. مقدار باید حداقل 1 باشد.
stream	اگر true باشد، پاسخ به‌صورت جریانی برمی‌گردد.
tools و tool_choice	برای فراخوانی ابزار و ساخت جریان‌های عامل‌محور استفاده می‌شود.
response_format	برای خروجی JSON یا ساختاریافته کاربرد دارد.

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

قابلیت‌های مرتبط

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

پاسخ جریانی

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

خطاهای رایج

• messages array must not be empty: آرایه پیام‌ها خالی است.
• max_tokens must be at least 1: سقف خروجی نامعتبر است.
• Model access denied or unsupported for chat completions: مدل انتخابی در دسترسی فعلی مجاز نیست یا با این API سازگار نیست.
• خطاهای ورودی چندرسانه‌ای: معمولاً مدل یا ارائه‌دهنده انتخابی آن نوع رسانه را پشتیبانی نمی‌کند.

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

جمع‌بندی

Chat Completions پایه بیشتر اتصال‌های متنی در گدارAI است. اگر این مسیر را درست بسازید، قابلیت‌های پیشرفته‌تر مثل ابزارها، خروجی ساختاریافته، ورودی چندرسانه‌ای، حافظه نهان و استدلال هم روی همان پایه قابل فهم و قابل کنترل می‌شوند.