v1/chat/completions/

v1/chat/completions/

مدل‌های تولید متن قابل دسترس از طریق Gilas API توانایی درک زبان طبیعی و کدنویسی را دارند. این مدل‌ها به ورودی‌های خود با خروجی‌های متنی که بسیار شبیه به جواب‌های انسانی هستند پاسخ می‌دهند. ورودی‌های این مدل‌ها همچنین به عنوان “prompt” شناخته می‌شوند. طراحی یک پرامپت اساساً چگونگی “برنامه‌ریزی” یک مدل زبانی بزرگ است.

شما می‌توانید با استفاده از این مدل‌ها برنامه‌هایی بسازید که توانایی انجام کارهای زیر را دارند:

  • پیش‌نویس اسناد
  • نوشتن کد کامپیوتری
  • پاسخ به سوالات درباره پایگاه داده‌های متنی
  • تحلیل متون
  • ارائه رابط زبان طبیعی
  • تعلیم علوم مختلف به زبان انسانی
  • ترجمه زبان‌های مختلف
  • شبیه‌سازی شخصیت‌ها برای بازی‌های کامپیوتری

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

Chat Completions API #

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

ساخت حساب کاربری #

ابتدا، یک حساب کاربری جدید ایجاد کنید یا اگر صاحب حساب کاربری هستید وارد پنل کاربری خود شوید. سپس، به صفحه کلید API بروید و با کلیک روی دکمه “ساخت کلید API” یک کلید جدید برای دسترسی به Gilas API بسازید. مطمئن شوید که این کلید را در جای امنی ذخیره کرده و آن را با کسی به اشتراک نگذارید.

ارسال درخواست #

نمونه‌ای از فواخوانی APIی چت را در زیر مشاهده کنید:

 1curl https://api.gilas.io/v1/chat/completions  \
 2-H "Content-Type: application/json" \
 3-H "Authorization: Bearer $GILAS_API_KEY" \
 4-d '{
 5    "model": "gpt-4o-mini",
 6    "messages": [
 7      {
 8        "role": "system",
 9        "content": "You are a helpful assistant."
10      },
11      {
12        "role": "user",
13        "content": "چه تیمی برنده رقابت‌های سری جهانی ۲۰۲۰ شد؟"
14      },
15      {
16        "role": "assistant",
17        "content": "تیم لس آنجلس دوجرز برنده رقابت‌های سری جهانی ۲۰۲۰ شد."
18      },
19      {
20        "role": "user",
21        "content": "بازی در کجا برگذار شده بود؟"
22      }
23    ]
24  }'

 1package main
 2
 3import (
 4	"bytes"
 5	"encoding/json"
 6	"fmt"
 7	"io/ioutil"
 8	"net/http"
 9	"os"
10)
11
12func main() {
13	url := "https://api.gilas.io/v1/chat/completions"
14	payload := map[string]interface{}{
15		"model": "gpt-4o-mini",
16		"messages": []map[string]string{
17			{
18				"role":    "system",
19				"content": "You are a helpful assistant.",
20			},
21			{
22        "role": "user",
23        "content": "چه تیمی برنده رقابت‌های سری جهانی ۲۰۲۰ شد؟"
24      },
25      {
26        "role": "assistant",
27        "content": "تیم لس آنجلس دوجرز برنده رقابت‌های سری جهانی ۲۰۲۰ شد."
28      },
29      {
30        "role": "user",
31        "content": "بازی در کجا برگذار شده بود؟"
32      },
33		},
34	}
35
36	jsonPayload, _ := json.Marshal(payload)
37	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonPayload))
38	req.Header.Set("Content-Type", "application/json")
39	req.Header.Set("Authorization", "Bearer "+os.Getenv("GILAS_API_KEY"))
40
41	client := &http.Client{}
42	resp, _ := client.Do(req)
43	defer resp.Body.Close()
44
45	body, _ := ioutil.ReadAll(resp.Body)
46	fmt.Println(string(body))
47}

 1const axios = require('axios');
 2
 3async function makeRequest() {
 4    const url = 'https://api.gilas.io/v1/chat/completions';
 5    const payload = {
 6        model: 'gpt-4o-mini',
 7        "messages": [
 8            {
 9                "role": "system",
10                "content": "You are a helpful assistant."
11            },
12            {
13              "role": "user",
14              "content": "چه تیمی برنده رقابت‌های سری جهانی ۲۰۲۰ شد؟"
15            },
16            {
17              "role": "assistant",
18              "content": "تیم لس آنجلس دوجرز برنده رقابت‌های سری جهانی ۲۰۲۰ شد."
19            },
20            {
21              "role": "user",
22              "content": "بازی در کجا برگذار شده بود؟"
23            }
24        ]
25    };
26
27    try {
28        const response = await axios.post(url, payload, {
29            headers: {
30                'Content-Type': 'application/json',
31                'Authorization': `Bearer ${process.env.GILAS_API_KEY}`
32            }
33        });
34        console.log(response.data);
35    } catch (error) {
36        console.error('Error making the request:', error);
37    }
38}
39
40makeRequest();

 1import requests
 2import os
 3
 4def make_request():
 5    url = 'https://api.gilas.io/v1/chat/completions'
 6    headers = {
 7        'Content-Type': 'application/json',
 8        'Authorization': f'Bearer {os.getenv("GILAS_API_KEY")}'
 9    }
10    payload = {
11        'model': 'gpt-4o-mini',
12        "messages": [
13            {
14                "role": "system",
15                "content": "You are a helpful assistant."
16            },
17            {
18              "role": "user",
19              "content": "چه تیمی برنده رقابت‌های سری جهانی ۲۰۲۰ شد؟"
20            },
21            {
22              "role": "assistant",
23              "content": "تیم لس آنجلس دوجرز برنده رقابت‌های سری جهانی ۲۰۲۰ شد."
24            },
25            {
26              "role": "user",
27              "content": "بازی در کجا برگذار شده بود؟"
28            }
29        ]
30    }
31
32    response = requests.post(url, json=payload, headers=headers)
33    return response.json()
34
35if __name__ == "__main__":
36    result = make_request()
37    print(result)

ورودی اصلی در این فراخوان API پارامتر Messages است. Messages باید یک آرایه از شیء پیام باشند، جایی که هر شیء شامل role (با مقادیر “system”، “user” یا “assistant”) و content است. چت ها می‌توانند به عنوان یک پیام کوتاه یا چندین نوبت پشت سر هم قرار بگیرند.

به طور معمول، یک گفتگو با یک پیام سیستمی (role=system) شروع می‌شود، سپس پیام‌های کاربر (role=user) و دستیار (role=assistant) به تناوب دنبال می‌شوند. پیام سیستمی به تنظیم رفتار assistant کمک می‌کند. به عنوان مثال، می‌توانید شخصیت assistant را تغییر دهید یا دستورالعمل‌های خاصی را در مورد چگونگی رفتار آن در طول گفتگو ارائه دهید. با این حال توجه داشته باشید که پیام سیستمی اختیاری است.

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

زمانی که دستورالعمل‌ها یا درخواست‌های کاربر به پیام‌های قبلی ارجاع می‌دهند قرار دادن تاریخچه مکالمه در لیست Messages مهم است. در مثال بالا، سوال نهایی کاربر در مورد “?Where was is played“ تنها در کانتکست پیام‌های قبلی در مورد جام جهانی 2020 معنی دارد. از آنجا که مدل‌ها stateless هستند و درخواست‌های قبلی را ذخیره نمی‌کنند، تمام اطلاعات مربوطه باید به عنوان بخشی از تاریخچه گفتگو در هر درخواست فراهم شود. اگر طول Messages از لحاظ تعداد توکن از تعداد توکن مجازی که در کانتکست مدل می‌تواند قرار بگیرد بیشتر شود، باید پیام‌ها را به شکلی کوتاه کنید. برای اینکار می‌توانید پیام‌ها را ابتدا خلاصه کرده و سپس در لیست Messages نگه‌داری کنید. برای خلاصه‌سازی پیام‌ها می‌توانید یک درخواست جدا به مدل ارسال کنید و از آن بخواهید که متن (پیام) دریافت شده را خلاصه کرده و به شما برگرداند.

برای آگاهی از طول کانتکست هر مدل لطفا مستندات مربوط به مدل‌های قابل دسترس را مطالعه کنید.

Chat Completions response format #

 نمونه از فرمت پاسخ Chat Completions API در زیر آمده است:

 1{
 2  "choices": [
 3    {
 4      "finish_reason": "stop",
 5      "index": 0,
 6      "message": {
 7        "content": "The 2020 World Series was played in Texas at Globe Life Field in Arlington.",
 8        "role": "assistant"
 9      },
10      "logprobs": null
11    }
12  ],
13  "created": 1677664795,
14  "id": "chatcmpl-7QyqpwdfhqwajicIEznoc6Q47XAyW",
15  "model": "gpt-4o-mini",
16  "object": "chat.completion",
17  "usage": {
18    "completion_tokens": 17,
19    "prompt_tokens": 57,
20    "total_tokens": 74
21  }
22}

 پاسخ assistant در مسیر choices[0].message.content قرار دارد.

هر پاسخ شامل یک finish_reason خواهد بود. مقادیر ممکن برای finish_reason عبارت‌اند از:

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

  • length: خروجی مدل به دلیل پارامتر max_tokens یا محدودیت تعداد توکن ناقص است.

  • function_call: مدل تصمیم به فراخوانی یک تابع گرفته است. (برای آگاهی بیشتر از نحوه فراخوانی توابع برنامه توسط مدل٬ پست فراخوانی توابع توسط مدل را مطالعه کنید.)

  • content_filter: محتوا به دلیل مغایرت با قوانین OpenAI یا پلتفرم گیلاس توسط فیلترهای محتوا حذف شده است.

  • null: پاسخ API هنوز در حال تولید یا ناقص است.

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

تولید خروجی با فرمت JSON #

یک روش رایج برای استفاده از Chat Completions این است که مدل را به گونه‌ای پرامپت کنید که همیشه یک شیء JSON را برگرداند. این روش مخصوصا برای زمانی که قصد دارید از خروجی مدل در داخل برنامه‌های خود استفاده کنید بسیار کاربردی است. در نظر داشته باشید که ممکن از در بعضی حالات خروجی JSON تولید شده معتبر نباشد. برای همین همیشه خروجی را قبل از استفاده اعتبارسنجی کنید.

برای جلوگیری از این خطاها و بهبود عملکرد مدل، هنگام فراخوانی gpt-4-turbo، می‌توانید پارامتر response_format را به {"type": "json_object"} تنظیم کنید تا حالت JSON فعال شود. وقتی حالت JSON فعال است، مدل فقط به تولید رشته‌هایی محدود می‌شود که به شیء JSON معتبر تجزیه شوند.

نکات مهم:

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

  • شیء JSON برگردانده شده ممکن است به دلیل بزرگ بودن طول خروجی و تمام شدن تعداد توکن‌هایی که می‌شود در خروجی تولید کرد ناقص بماند. برای مطمین شدن ازینکه خروجی تولید شده کامل است حتما ابتدا مقدار پارامتر finish_reason را بررسی کنید.

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

 1curl https://api.gilas.io/v1/chat/completions \
 2  -H "Content-Type: application/json" \
 3  -H "Authorization: Bearer $GILAS_API_KEY" \
 4  -d '{
 5    "model": "gpt-4o-mini",
 6    "response_format": { "type": "json_object" },
 7    "messages": [
 8      {
 9        "role": "system",
10        "content": "You are a helpful assistant designed to output JSON."
11      },
12      {
13        "role": "user",
14        "content": "چه تیمی برنده رقابت‌های سری جهانی ۲۰۲۰ شد؟"
15      }
16    ]
17  }'

خروجی تولید شده به فرمت JSON:

1"content": "{\"winner\": \"تیم لس آنجلس دوجرز\"}"`

استریم کردن خروجی #

به طور پیش فرض، هنگامی که شما از Gilas API درخواست تولید متن می کنید، کل متن تولید شده در یک رسپانس به کلاینت برگردانده می شود. اگر قصد تولید خروجی‌های طولانی را دارید٬ تولید متن می تواند چندین ثانیه طول بکشد. برای دریافت سریعتر پاسخ ها٬ می توانید متن را در حالی که تولید می شود stream کنید. در این صورت پاسخ های ناتمام را به صورت استریم از سمت سرور دریافت خواهید کرد.

برای استریم کردن متن ها، هنگام فراخوانی v1/chat/completions مقدار پارامتر stream=true را تنظیم کنید. این درخواست یک شیء برمی گرداند که پاسخ را به عنوان data-only server-sent events برگشت می دهد.

توجه داشته باشید که استفاده از stream=true باعث می شود که مدیریت محتوای متن دشوارتر شود، زیرا کار ارزیابی تکه های جزئی متن ممکن است دشوارتر باشند. مخصوصا زمانی که قصد تولید خروجی JSON را دارید توصیه می‌شود از حالت استریم استفاده نکنید.

یکی دیگر از معایب پاسخ های استریم این است که پاسخ دیگر شامل فیلد usage نیست که به شما بگوید چند توکن مصرف شده است. برای حل این مشکل٬ پس از دریافت و ترکیب همه پاسخ ها، می توانید تعداد توکن‌های مصرف شده را با استفاده از tiktoken محاسبه کنید.

خروجی تولید شده به صورت استریم شامل قطعه‌هایی (chunk) از جواب هستند:

1{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}
2{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":"Hello"},"logprobs":null,"finish_reason":null}]}
3....
4{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]}

مدیریت توکن‌ها #

مدل‌های زبانی متن‌ها را در قطعاتی به نام tokenها می‌خوانند و می‌نویسند. در زبان انگلیسی، یک token می‌تواند به کوتاهی یک حرف یا به درازای یک کلمه (مثلا a یا apple) باشد و در برخی زبان‌ها، tokenها می‌توانند حتی کوتاه‌تر از یک حرف یا طولانی‌تر از یک کلمه باشند.

برای مثال، رشته "Gilas API is great!" به شش token تقسیم می‌شود: ["Gil", "as", "API", " is", " great", "!"].

تعداد کل tokenها در یک فراخوانی API تاثیر می‌گذارد بر:

  • هزینه‌ی فراخوانی API٬ چرا که تولید و مصرف هر token هزینه دارد.
  • مدت زمان فراخوانی API ، چرا که نوشتن tokenهای بیشتر زمان بیشتری می‌برد.
  • عملکرد فراخوانی API، چرا که تعداد کل tokenها باید کمتر از حداکثر طول کانتکست مدل باشد.

هزینه استفاده از APIهای تولید متن بر اساس تعداد توکن‌های تولید شده و مصرف شده محاسبه می‌شود. برای آگاهی بیشتر از هزینه‌ی استفاده از هر مدل مستندات مربوط به هزینه‌ها را مطالعه کنید.

همچنین خواندن پست شمردن تعداد توکن‌ها با ‌tiktoken را برای درک بهتر توکن‌ها و نحوه شمردن و محاسبه هزینه توصیه می‌کنیم.

فراخوانی توابع #

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

مدلهای gpt-3.5-turbbo و gpt-4-turbo قابلیت تصمیم گیری برای فراخوانی توابع داخل برنامه را بر اساس درخواست یوزر دارند.

در یک فراخوانی API، می‌توانید توابعی را توصیف کنید و به مدل اجازه دهید تا به طور هوشمندانه تصمیم بگیرد که یک شیء JSON شامل آرگومان‌هایی برای فراخوانی یک یا چند تابع را خروجی دهد. Chat Completions API تابعی را فراخوانی نمی‌کند؛ به جای آن، مدل JSONای تولید می‌کند که می‌توانید از آن برای فراخوانی تابع در کد خود استفاده کنید.

مدل‌های جدید (gpt-4o-mini و gpt-4-turbo) آموزش دیده‌اند که هم تشخیص دهند چه زمانی باید تابعی فراخوانی شود (بسته به ورودی) و هم پاسخی به فرم JSON بدهند که برای فراخوانی توابع ضروری است. این توانایی، خطرات بالقوه‌ای نیز دارد. ما توصیه می‌کنیم که قبل از انجام هر گونه عملیاتی از طرف کاربران (فرستادن ایمیل، ارسال پست در اینترنت، خرید و غیره)، ورودی های کاربر را اعتبارسنجی کنید.

کاربردهای متداول #

فراخوانی تابع به شما امکان می‌دهد داده‌های ساختاریافته قابل اعتمادتری از مدل دریافت کنید. به عنوان مثال، می‌توانید:

  • دستیارهایی ایجاد کنید که با فراخوانی APIهای خارجی به سؤالات پاسخ دهند.

  • زبان طبیعی را به فراخوانی‌های API تبدیل کنید مثلاً “چه کسانی مشتریان اصلی من هستند؟” را به get_customers(min_revenue: int, created_before: string, limit: int) تبدیل کرده و API داخلی خود را فراخوانی کنید.

… و خیلی چیزهای دیگر!

توالی مراحل برای فراخوانی تابع به شرح زیر است:

  • مدل را با پرسش کاربر و مجموعه‌ای از توابع تعریف شده در پارامتر functions فراخوانی کنید.
  • مدل ممکن است تصمیم بگیرد یک یا چند تابع را فراخوانی کند؛ در این صورت، محتوا یک شیء JSON خواهد بود که مطابق با schema تعریف شده شما است (توجه: مدل ممکن است در تولید پارامترها اشتباه کند).
  • رشته را در کد خود به JSON تبدیل کرده و اگر آرگومان‌هایی وجود دارد، تابع خود را با آن‌ها فراخوانی کنید.
  • مدل را دوباره با اضافه کردن پاسخ تابع به عنوان پیام جدید فراخوانی کنید و اجازه دهید مدل نتایج را به کاربر خلاصه کند.

رفتار فراخوانی تابع #

مقدار پیش‌فرض برای متغیر tool_choice هنگام فراخوانی اندپویت v1/chat/completions/ معادل auto است. ازین طریق این اجازه را به مدل می‌دهیم تا تصمیم بگیرد آیا توابعی را فراخوانی کند و در صورت مثبت بودن پاسخ، کدام توابع را فراخوانی کند.

ما سه روش برای سفارشی‌سازی رفتار پیش‌فرض بسته به مورد استفاده شما ارائه می‌دهیم:

  • برای مجبور کردن مدل به فراخوانی یک یا چند تابع، می‌توانید tool_choice: required را تنظیم کنید. ازین طریق مدل باید همیشه تابع یا توابعی را که باید فراخوانی شوند انتخاب می‌کند.
  • برای مجبور کردن مدل به فراخوانی تنها یک تابع خاص، می‌توانید tool_choice: {"type": "function", "function": {"name": "my_function"}} را تنظیم کنید.
  • برای غیرفعال کردن فراخوانی تابع و مجبور کردن مدل به تولید تنها یک پیام متنی برای کاربر، می‌توانید tool_choice: none را تنظیم کنید.

برای مشاهده یک مثال کامل از نحوه‌ی فراخوانی توابع می‌توانید پست فراخوانی توابع توسط مدل را مطالعه کنید.

اطلاعات تکمیلی #

در نظر داشته باشید که Gilas APIs از لحاظ فنی و نحوه کارکرد و قابلیت‌ها کاملا شبیه API ارایه دهنده های دیگر مانند OpenAI یا Mistral هستند. به همین منظور پیشنهاد میکنیم که برای آگاهی از نحوه‌ی کارکرد API ها به مستندات زیر مراجعه کنید.

v1/fim/completions/ ◀︎