مدیریت کاربران مجازی و VAT

کاربر مجازی هویت غیرانسانی سرویس شما در گدارAI است. وقتی اپلیکیشن، سرویس پشت‌صحنه، پردازش‌گر یا کار زمان‌بندی‌شده باید به درگاه وصل شود، بهتر است برای آن کاربر مجازی بسازید و یک کلید دسترسی مجازی (VAT) صادر کنید.

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

اطلاع

در بعضی بخش‌های فنی ممکن است نام virtual_account را ببینید. در مستندات کاربرمحور گدارAI، منظور همان «کاربر مجازی و VAT» است.

چه زمانی کاربر مجازی بسازیم؟

برای هر کاری که انسان پشت آن نیست:

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

هشدار

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

ساخت کاربر مجازی

1. در پنل، بخش «کاربران مجازی» را باز کنید.
2. گزینه «ایجاد کاربر مجازی» را انتخاب کنید.
3. در «شناسه فنی»، نامی پایدار و قابل فهم وارد کنید؛ مثل order-support-api.
4. در «نام نمایشی»، نام خوانا بنویسید؛ مثل «سرویس پشتیبانی سفارش».
5. تیم مربوط را انتخاب کنید.
6. در صورت نیاز، واحد سازمانی را مشخص کنید.
7. کاربر مجازی را ایجاد کنید.

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

نکته

برای هر سرویس مهم یک کاربر مجازی جدا بسازید. نام‌هایی مثل support-api-prod، payment-assistant-prod و catalog-sync-dev بعداً در لاگ‌ها و گزارش مصرف بسیار کمک‌کننده‌اند.

صدور VAT

بعد از ساخت کاربر مجازی:

1. همان کاربر مجازی را انتخاب کنید.
2. در بخش «توکن‌های دسترسی مجازی (VAT)»، گزینه «ایجاد VAT» را بزنید.
3. در «نام توکن»، نامی روشن بنویسید؛ مثل support-api-main.
4. اگر لازم است، «زمان انقضا» را وارد کنید؛ مثل 30d یا 720h.
5. اگر می‌خواهید دسترسی مدل محدودتر شود، «مدل‌های مجاز» را انتخاب کنید.
6. VAT را ایجاد کنید و مقدار خام را همان لحظه در محل امن ذخیره کنید.

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

استفاده از VAT در کد

در اپلیکیشن، VAT را مثل توکن درگاه استفاده کنید:

Python

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_VAT",
        "Content-Type": "application/json",
    },
    json={
  "model": "support-assistant",
  "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_VAT",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "support-assistant",
  "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_VAT" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "support-assistant",
  "messages": [
    {
      "role": "user",
      "content": "برای سفارش A-1024 یک پاسخ کوتاه و محترمانه آماده کن."
    }
  ]
}'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GODARAI_VAT",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

response = client.chat.completions.create(
    "model": "support-assistant",
    messages=[
        {
          "role": "user",
          "content": "برای سفارش A-1024 یک پاسخ کوتاه و محترمانه آماده کن."
        }
      ]

)

print(response)

OpenAI NodeJS SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_GODARAI_VAT",
  baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const response = await client.chat.completions.create({
  "model": "support-assistant",
  "messages": [
    {
      "role": "user",
      "content": "برای سفارش A-1024 یک پاسخ کوتاه و محترمانه آماده کن."
    }
  ]
});

console.log(response);

وضعیت کاربر مجازی

کاربر مجازی می‌تواند فعال یا غیرفعال باشد. وقتی آن را غیرفعال می‌کنید:

• صدور توکن جدید برای آن متوقف می‌شود.
• توکن‌های متصل به آن هویت نباید برای دسترسی معتبر بمانند.
• سرویس‌هایی که به آن هویت وابسته‌اند باید بررسی شوند.

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

ابطال و چرخش VAT

عملیات	کاربرد
ابطال	قطع دسترسی همان توکن
چرخش	تولید مقدار محرمانه تازه برای ادامه کار سرویس

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

برای سرویس‌های محیط عملیاتی، روال پیشنهادی:

1. VAT را بچرخانید.
2. مقدار تازه را در مخزن اسرار یا تنظیمات امن سرویس ذخیره کنید.
3. سرویس را دوباره بارگذاری کنید.
4. در لاگ درخواست‌ها درخواست‌های موفق را بررسی کنید.
5. مطمئن شوید مقدار قدیمی دیگر استفاده نمی‌شود.

حذف کاربر مجازی

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

• VATهای فعال را ابطال کنید.
• مطمئن شوید هیچ سرویس فعالی از آن استفاده نمی‌کند.
• در لاگ‌ها آخرین استفاده را بررسی کنید.
• شناسه فنی کاربر مجازی را برای تأیید حذف وارد کنید.

هشدار

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

یک مثال عملی

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

مورد	مقدار پیشنهادی
تیم	support-prod
کاربر مجازی	ticket-summary-api
VAT	ticket-summary-main
مدل مجاز	support-assistant
زمان انقضا	90d

اگر بعداً این سرویس به مشکل امنیتی برخورد، فقط VAT همان سرویس را ابطال یا بچرخانید. PAT کاربران پشتیبانی و سرویس‌های دیگر دست‌نخورده می‌مانند.

خطاهای رایج

قبل از صدور VAT پیام «محدوده تیم الزامی است» می‌بینم

کاربر مجازی را به یک تیم وصل کنید. VAT باید محدوده مالکیت و دسترسی مشخص داشته باشد.

مدل انتخابی برای VAT پذیرفته نمی‌شود

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

مقدار خام VAT را گم کرده‌ام

قابل بازیابی نیست. توکن را بچرخانید یا VAT جدید صادر کنید.

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

آیا یک VAT برای همه سرویس‌ها کافی است؟

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

آیا هر کاربر مجازی باید فقط یک VAT داشته باشد؟

نه. می‌توانید برای یک کاربر مجازی چند VAT با زمان انقضا یا محدوده متفاوت داشته باشید، اما تعداد زیاد توکن‌ها را با نام‌گذاری و چرخش منظم مدیریت کنید.

VAT به تیم وصل است یا به کاربر مجازی؟

VAT به کاربر مجازی صادر می‌شود و محدوده تیمی از همان هویت سرویس می‌آید. بنابراین کاربر مجازی باید تیم روشن داشته باشد.