راهنماها

اتصال SaaS چندمشتری

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

بخش‌های این سناریو چطور به هم وصل‌اند

01مشتری واردشده
02پیدا کردن پروژهٔ مشتری
03API key همان پروژه
04نتیجه برای مشتری

یک مثال واقعی

دفتر را در نظر بگیرید؛ یک نرم‌افزار حسابداری آنلاین که هزاران کسب‌وکار کوچک از آن استفاده می‌کنند. دفتر می‌خواهد دستیاری به نام از دفترت بپرس اضافه کند تا صاحب کسب‌وکار بپرسد «سه ماه گذشته بیشترین پرداخت ما به کدام تأمین‌کننده بوده؟» و پاسخ را از گزارش‌های خودش بگیرد.

شرط غیرقابل مذاکره: یک نانوایی هرگز نباید ارقام یک فروشگاه کاشی را ببیند. دفتر این را با دادن یک پروژهٔ مهوش مستقل — با API key و vector store اسناد خودش — به هر کسب‌وکار مشتری حل می‌کند. بک‌اند دفتر پیش از هر فراخوانی تشخیص می‌دهد کاربر واردشده به کدام پروژه تعلق دارد.

آنچه دفتر به دست می‌آورد

جداسازی در دو لایه. دفتر مشتری را بررسی می‌کند و مهوش هر چیزی خارج از پروژهٔ همان مشتری را رد می‌کند.
مصرف به تفکیک مشتری برای طراحی پلن‌های قیمت‌گذاری یا سقف مصرف منصفانه.
خروج امن مشتری. revoke کردن کلید مشتری و حذف داده‌های پروژه‌اش، او را به‌طور کامل خارج می‌کند.
محدودیت برای هر مشتری، تا یک مشتری بسیار فعال بقیه را کند نکند.

با یک مشتری ببینید

مرحله	چه اتفاقی می‌افتد	در این مثال
۱. ثبت‌نام	کسب‌وکار تازه‌ای به دفتر می‌پیوندد و یک job آماده‌سازی پروژه و API key مهوش آن را می‌سازد.	نانوایی رز ← پروژهٔ مستقل و کلیدی که در secret manager دفتر ذخیره می‌شود.
۲. داده	گزارش‌های ماهانهٔ کسب‌وکار در vector store خودش ایندکس می‌شوند.	فقط فایل‌های نانوایی رز در آن vector store هستند.
۳. پرسش	صاحب کسب‌وکار از دستیار می‌پرسد.	«سه ماه گذشته بیشترین پرداخت ما به کدام تأمین‌کننده بوده است؟»
۴. هدایت	دفتر کاربر واردشده را به مشتری نگاشت و کلید همان مشتری را بارگذاری می‌کند.	نشست ← مشتری ۴۸۱۲ ← کلید نانوایی رز.
۵. پاسخ	مهوش فقط در vector store نانوایی رز جست‌وجو می‌کند و پاسخ می‌دهد.	دادهٔ مشتریان دیگر حتی با داشتن شناسه هم در دسترس نیست.

دفتر نگاشت را در پایگاه دادهٔ خودش نگه می‌دارد و در هر request از آن استفاده می‌کند:

-- Your database, not Mahvash
customer_id | name          | mahvash_project | credential_ref              | vector_store
------------+---------------+-----------------+-----------------------------+----------------
4812        | Rose Bakery   | <project-uuid-a> | secret://mahvash/cust-4812  | vs_<store-a>
4813        | Tehran Tiles  | <project-uuid-b> | secret://mahvash/cust-4813  | vs_<store-b>

حتی اگر به اشتباه شناسهٔ vector store مشتری دیگری به این کد برسد، مهوش پاسخ 404 می‌دهد؛ چون آن vector store در پروژهٔ این کلید وجود ندارد.

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

وصل کردن هر مشتری به یک پروژه

مشتریان شما در SaaS خودتان احراز هویت می‌شوند و مهوش آن‌ها را نمی‌شناسد. این دو را با یک جدول ارتباط صریح در پایگاه دادهٔ خودتان به هم وصل کنید:

شناسهٔ مشتری در سیستم شما ← شناسهٔ پروژه در مهوش؛
شناسهٔ مشتری در سیستم شما ← محل نگهداری API key همان پروژه در سامانهٔ مدیریت secretها.

وقتی هر مشتری پروژهٔ خودش را دارد، responseها، فایل‌ها و vector storeهای هر مشتری علاوه بر بررسی‌های شما، توسط خود مهوش هم از بقیه جدا می‌مانند.

مهم:هرگز شناسهٔ پروژه‌ای را که از مرورگر می‌آید، به‌عنوان مجوز نپذیرید. مرورگر (از طریق نشست خود شما) فقط می‌گوید کاربر کیست؛ اینکه به کدام پروژه وصل است را پایگاه دادهٔ شما تعیین می‌کند.

ساخت پروژه برای مشتری تازه

وقتی مشتری تازه‌ای ثبت‌نام می‌کند، یک job راه‌اندازی که با JWT یک مدیر اجرا می‌شود این کارها را انجام می‌دهد:

۱برای مشتری یک پروژه می‌سازد.
۲یک API key پروژه صادر می‌کند (ترجیحاً با scopeهای محدود و سقف requests_per_minute مخصوص همان کلید) و token آن را در سامانهٔ مدیریت secretها ذخیره می‌کند؛ این token فقط یک بار نمایش داده می‌شود.
۳اگر مشتری به مجموعهٔ اسناد خصوصی برای جست‌وجو نیاز دارد، فایل‌ها و vector storeهای خودش را می‌سازد.
۴شناسهٔ پروژه و محل نگهداری کلید را کنار رکورد مشتری ثبت می‌کند.

APIهای این مرحله

POST ساخت پروژه ↗POST صدور API key برای پروژه ↗

فرستادن هر request به پروژهٔ درست

برای هر request کاربر:

۱کاربر را احراز کنید و مشتری مربوط به او را در پایگاه دادهٔ خودتان پیدا کنید.
۲API key پروژهٔ همان مشتری را از سامانهٔ مدیریت secretها بخوانید.
۳/v1/responses را با همان کلید صدا بزنید. کلید به پروژهٔ خودش گره خورده است؛ پس headerی وجود ندارد که بتوان آن را اشتباه فرستاد.

X-Mahvash-Project را از ورودی کاربر نگیرید. کلیدی که به پروژه گره خورده، مقدار متناقض را در هر صورت رد می‌کند و ارتباط مشتری با پروژه فقط باید از سرور شما بیاید.

APIهای این مرحله

POST ساخت response ↗

پیاده‌سازی در سرور

این نمونه شناسهٔ مشتریِ احرازشده را می‌گیرد، تنظیمات پروژهٔ او را از سرور می‌خواند و Responses را صدا می‌زند. مشتری فقط نتیجه را دریافت می‌کند و هیچ API key مهوش یا شناسه‌ای از مشتری دیگر به مرورگر نمی‌رسد.

نمونهٔ پیاده‌سازی

// Resolve the signed-in tenant in your app; never take a key from the browser.
const tenant = await db.tenants.getForSession(session);
const projectKey = await secrets.get(tenant.mahvashCredentialRef);
const response = await fetch("https://api.mahvashai.ir/v1/responses", {
  method: "POST",
  headers: { Authorization: "Bearer " + projectKey, "Content-Type": "application/json" },
  body: JSON.stringify({ model: "auto", input: userMessage })
});
if (!response.ok) throw new Error("Mahvash request failed: " + response.status);
const body = await response.json();
await db.tenantRuns.insert({ tenantId: tenant.id, responseId: body.id });
return body.output;

نمونهٔ خروجی این مرحله

{
  "id": "resp_example",
  "object": "response",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Here is your answer..."
        }
      ]
    }
  ]
}

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

رکوردهای تفکیک‌شده برای هر مشتری

شناسهٔ responseها، فایل‌ها و vector storeهای مهوش را کنار مشتری و پروژهٔ مربوط در پایگاه دادهٔ خودتان ذخیره کنید. از همین اطلاعات برای فیلتر کردن تاریخچه، نمایش ارجاع‌ها و پاک‌سازی هنگام رفتن مشتری استفاده کنید.

مصرف جداگانهٔ هر پروژه هم مبنای روشنی برای محاسبهٔ هزینهٔ هر مشتری است.

APIهای این مرحله

GET دریافت response ↗

وقتی جداسازی به خطر می‌افتد

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

همین الگو برای کسب‌وکارهای دیگر

CRM و ابزارهای فروش — دستیار روی معامله‌ها و یادداشت‌های هر شرکت.
سامانه‌های منابع انسانی — پرسش‌های آیین‌نامه و حقوق برای هر کارفرما.
سامانه‌های آموزش آنلاین — یک دستیار آموزشی برای هر مدرسه با مطالب همان مدرسه.
آژانس‌ها — یک پروژه برای هر مشتری تا مطالب مشتریان هرگز قاطی نشود.
بازارگاه‌ها — دستیار برای هر فروشنده روی کاتالوگ و سفارش‌های خودش.

← همهٔ سناریوهای پیاده‌سازی