توکن‌های دسترسی در گدارAI

برای ارسال درخواست از محصول خود به گدارAI به توکن دسترسی نیاز دارید. این توکن به گدارAI نشان می‌دهد درخواست از کدام فضای کاری، کدام کاربر یا کدام سرویس آمده و چه مدل‌هایی برای آن مجاز است.

در گدارAI دو نوع توکن اصلی دارید:

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

اطلاع

توکن دسترسی گدارAI جایگزین پخش‌کردن کلید ارائه‌دهنده در چند سرویس است. کلید ارائه‌دهنده در گدارAI مدیریت می‌شود و اپلیکیشن شما با توکن گدارAI به درگاه وصل می‌شود.

چه زمانی PAT بسازید؟

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

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

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

هشدار

در درخواست ساخت PAT از فیلدهای models یا allowed_models استفاده نکنید. این مسیر آن‌ها را نمی‌پذیرد، چون دسترسی مدل باید از تنظیمات مرکزی مدیریت شود.

چه زمانی VAT بسازید؟

VAT برای هویت‌های غیرانسانی است؛ یعنی سرویس‌ها و اپلیکیشن‌هایی که باید مستقل از افراد کار کنند. مثال‌های مناسب:

• سرویس پاسخ‌گویی به مشتریان
• پردازش‌گر صف پیامک یا سفارش
• کار زمان‌بندی‌شده برای خلاصه‌سازی گزارش‌ها
• سامانه داخلی پشتیبانی
• مسیر استقرار و آزمایش خودکار

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

کدام را انتخاب کنم؟

یک قاعده ساده:

• اگر انسان از توکن استفاده می‌کند، PAT.
• اگر اپلیکیشن یا سرویس از توکن استفاده می‌کند، VAT.

اگر مردد هستید، از خودتان بپرسید: «اگر صاحب این توکن از شرکت خارج شود، آیا این سرویس باید از کار بیفتد؟» اگر پاسخ نه است، VAT انتخاب درست‌تری است.

ساخت PAT در پنل

1. وارد پنل گدارAI شوید.
2. از منوی «توکن‌های دسترسی شخصی» گزینه «ایجاد توکن» را انتخاب کنید.
3. در «نام توکن»، نامی روشن بنویسید؛ مثل iman-local-test یا support-report-check.
4. در «زمان انقضا»، بازه‌ای مثل 30d وارد کنید.
5. توکن را ایجاد کنید و مقدار خام را همان لحظه در محل امن ذخیره کنید.

هشدار

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

استفاده از توکن در کد

برای SDKهای سازگار با OpenAI، توکن گدارAI را به‌جای کلید ارائه‌دهنده بگذارید و نشانی پایه درگاه را روی فضای کاری خود تنظیم کنید:

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": "وضعیت سفارش A-1024 را خلاصه کن."
    }
  ]
},
    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": "وضعیت سفارش A-1024 را خلاصه کن."
    }
  ]
}),
});

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": "وضعیت سفارش A-1024 را خلاصه کن."
    }
  ]
}'

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": "وضعیت سفارش A-1024 را خلاصه کن."
        }
      ]

)

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": "وضعیت سفارش A-1024 را خلاصه کن."
    }
  ]
});

console.log(response);

با متغیر محیطی هم می‌توانید همین کار را انجام دهید:

export OPENAI_BASE_URL="https://YOUR_WORKSPACE.godarai.ir/v1"
export OPENAI_API_KEY="YOUR_GODARAI_TOKEN"

بعد از ساخت توکن چه چیزی می‌بینید؟

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

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

ابطال چه زمانی لازم است؟

ابطال یعنی توکن دیگر برای احراز هویت پذیرفته نشود. این کار را انجام دهید وقتی:

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

نکته

برای هر سرویس مهم یک VAT جدا داشته باشید. در این حالت اگر فقط سرویس «گزارش فروش» مشکل داشت، همان توکن را ابطال یا بچرخانید و سرویس‌های دیگر مثل «پشتیبانی سفارش» تحت تأثیر قرار نمی‌گیرند.

خطاهای رایج

درخواست با خطای دسترسی مدل رد می‌شود

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

توکن تازه را نمی‌توانم دوباره ببینم

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

سرویس محیط عملیاتی با خروج یک نفر از تیم از کار افتاده است

احتمالاً سرویس با PAT آن فرد کار می‌کرده است. برای سرویس، کاربر مجازی بسازید و VAT مستقل صادر کنید.

گام بعدی

• برای چرخش امن توکن‌ها، چرخش توکن‌های دسترسی را بخوانید.
• برای سرویس‌ها، مدیریت کاربران مجازی و VAT را دنبال کنید.
• برای فهم نقش دسترسی مرکزی مدل‌ها، مدل مجازی را ببینید.