احراز هویت در گدارAI

برای ارسال درخواست به مدل‌ها، اپلیکیشن شما باید توکن دسترسی گدارAI را بفرستد. کلید خام ارائه‌دهنده‌هایی مثل OpenAI، Anthropic یا Azure را در درخواست‌های محصول خودتان به گدارAI ارسال نکنید.

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

پیش‌نیازها

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

روش پیشنهادی ارسال توکن

توکن را در سرآیند Authorization با الگوی Bearer بفرستید:

Authorization: Bearer YOUR_GODARAI_TOKEN

گدارAI برای سازگاری با بعضی کلاینت‌ها، سرآیندهای api-key و x-api-key را هم می‌پذیرد. مگر اینکه ابزار شما محدودیت خاصی داشته باشد، Authorization را روش پیش‌فرض نگه دارید.

انتخاب نوع توکن

گدارAI دو نوع توکن اصلی برای مصرف مدل‌ها دارد:

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

توکن دسترسی شخصی (PAT)

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

به خاطر داشته باشید که PAT به دسترسی‌های همان کاربر وابسته است. داشتن PAT به‌تنهایی دسترسی به همه مدل‌ها را ایجاد نمی‌کند.

کلید دسترسی مجازی (VAT)

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

برای VAT معمولاً این شرایط لازم است:

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

برای ساخت و مدیریت آن، مدیریت کاربران مجازی و VAT را بخوانید.

تفاوت احراز هویت و دسترسی

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

بنابراین ممکن است:

• توکن معتبر باشد، اما به مدل خاصی دسترسی نداشته باشد.
• کاربر به یک حساب ارائه‌دهنده دسترسی داشته باشد، اما مدل موردنظر برای او فعال نشده باشد.
• VAT معتبر باشد، اما محدوده تیمی آن شامل مدل انتخاب‌شده نباشد.

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

بررسی دسترسی مؤثر پیش از ارسال درخواست

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

1. در پنل مدیریت، بخش «اتصال‌دهنده‌های LLM» را باز کنید.
2. روی منوی کارت حساب ارائه‌دهنده موردنظر بزنید و «تست دسترسی‌های مجاز» را انتخاب کنید.
3. نوع توکن را انتخاب کنید: pat برای توکن دسترسی شخصی یا vat برای کلید دسترسی مجازی.
4. کاربر یا تیم را جست‌وجو و انتخاب کنید.
5. «اجرای تست دسترسی» را بزنید.

نتیجه مورد انتظار: گدار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": "سلام"
    }
  ]
},
    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);

اگر خطای 401 نگرفتید، توکن از نظر احراز هویت پذیرفته شده است. اگر خطای 403 گرفتید، هویت شناخته شده اما دسترسی کافی ندارد.

چرا کلید خام ارائه‌دهنده را نفرستیم؟

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

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

نگهداری امن توکن

• توکن را داخل کد یا مخزن کد قرار ندهید.
• توکن را از متغیر محیطی یا سامانه مدیریت رازها بخوانید.
• برای هر سرویس مهم، VAT جدا بسازید تا چرخش، ابطال و ممیزی مستقل باشد.
• اگر توکن افشا شد، آن را فوراً باطل کنید و توکن تازه بسازید.
• زمان انقضا را متناسب با ریسک و چرخه استقرار محصول تعیین کنید.

رفع خطاهای رایج

خطای 401 Unauthorized

نشانه: گدارAI توکن را نمی‌پذیرد.

علت‌های رایج:

• سرآیند Authorization ارسال نشده است.
• مقدار توکن اشتباه یا ناقص است.
• توکن منقضی یا باطل شده است.

راه‌حل: مقدار سرآیند را بررسی کنید، فاصله اضافی را حذف کنید و در صورت نیاز توکن تازه بسازید.

خطای 403 Forbidden

نشانه: توکن شناخته شده، اما درخواست اجازه اجرا ندارد.

علت‌های رایج:

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

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

گام بعدی

• برای ساخت توکن، توکن‌های دسترسی در گدارAI را بخوانید.
• برای ارسال درخواست، اولین درخواست به درگاه را دنبال کنید.
• برای هویت سرویس، مدیریت کاربران مجازی و VAT را ببینید.

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

آیا PAT را می‌توان در محیط عملیاتی استفاده کرد؟

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

آیا هر توکن معتبر به همه مدل‌ها دسترسی دارد؟

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

اگر SDK من api-key می‌فرستد چه کنم؟

گدارAI سرآیندهای api-key و x-api-key را نیز می‌پذیرد. با این حال، اگر انتخاب با شماست، از Authorization: Bearer ... استفاده کنید.