سازمان‌ها و پروژه‌ها

مهوش هرچه می‌سازید را در یک ساختار دوسطحی نگه می‌دارد:

• سازمان مرز اصلی جداسازی است. اعضایی با نقش مشخص، یک کیف پول که هزینهٔ همهٔ کارها را می‌پردازد، و محدودیت‌های مصرف و بودجه دارد. هیچ سازمانی از وجود سازمان‌های دیگر خبر ندارد.
• پروژه فضای کاری داخل سازمان است. هر response، گفت‌وگو، فایل، asset، vector store، prompt، منبع داده، webhook و API key دقیقاً به یک پروژه تعلق دارد.

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

Organization "Acme"                    tenant, members, wallet, limits
├─ Members   Sara (ADMIN), Ali (MEMBER), Nadia (VIEWER)
├─ Teams     Support, Marketing
├─ Project "default"      open to every member         requests with no selector land here
├─ Project "support"      open to every member         support copilot: keys, files, prompts
└─ Project "campaigns"    restricted: Marketing team   only granted teams can reach it

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

پروژه ابزار اصلی شما برای جداسازی داخل یک سازمان است. هرچه داخل یک پروژه باشد، این موارد را مشترک دارد:

• داده: فایل، vector store یا response یک پروژه از پروژهٔ دیگر دیده نمی‌شود. اگر شناسه‌ای متعلق به پروژهٔ دیگر بفرستید، پاسخ 404 می‌گیرید؛ درست مثل شناسه‌ای که هرگز وجود نداشته است.
• credential: هر API key فقط به یک پروژه دسترسی دارد.
• تنظیمات: دستورالعمل‌های پیش‌فرض، promptها، منابع داده برای بازیابی، تنظیمات ابزارهای مدیریت‌شده و محل پیش‌فرض نگهداری ایندکس‌ها.
• محدودیت و بودجه: سقف تعداد request، تعداد کارهای همزمان و سقف هزینهٔ ماهانه را می‌توان برای هر پروژه جداگانه تعیین کرد.

روش‌های رایج برای تقسیم کار بین پروژه‌ها:

• یک پروژه برای هر قابلیت محصول؛ مثلاً دستیار پشتیبانی و ابزار جست‌وجوی داخلی، داده و prompt متفاوتی دارند؛
• یک پروژه برای هر محیط؛ staging و production هیچ‌وقت کلید یا سند مشترک ندارند؛
• یک پروژه برای هر مشتری، وقتی یک SaaS چندمشتری می‌سازید. سناریوی اتصال SaaS چندمشتری را ببینید.

مهوش اول سازمان و بعد پروژه را مشخص می‌کند؛ آن هم پیش از اینکه هیچ داده‌ای را بخواند یا کاری را شروع کند. دو header اختیاری این انتخاب را تعیین می‌کنند:

این انتخاب همیشه به همین ترتیب انجام می‌شود:

چند نکتهٔ مهم:

• X-Mahvash-Organization فقط از میان سازمان‌هایی انتخاب می‌کند که شما عضو فعال آن‌ها هستید. با آن نمی‌توان به سازمانی رسید که عضوش نیستید.
• X-Mahvash-Project دامنهٔ request را محدودتر می‌کند؛ هرگز دسترسی بیشتری نمی‌دهد.
• اگر سازمان یا پروژهٔ ناشناخته‌ای بفرستید، پاسخ 404 می‌گیرید و request بی‌صدا به حالت پیش‌فرض برنمی‌گردد. کلاینتی که فکر می‌کند برای یک شرکت کار می‌کند، نباید بی‌خبر در شرکت دیگری کار کند.
• اگر endpointی فیلد project را در body بپذیرد، مقدار آن باید با header یکی باشد.
• ادامهٔ گفت‌وگو با previous_response_id یا chat_id همیشه در پروژه‌ای انجام می‌شود که صاحب آن گفت‌وگوست.

# A person working in the "support" project of the "acme" organization
curl https://api.mahvashai.ir/v1/responses \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "X-Mahvash-Organization: acme" \
  -H "X-Mahvash-Project: support" \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "input": "Summarize today\u0027s open tickets."}'

# A project API key already knows its organization and project
curl https://api.mahvashai.ir/v1/responses \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "input": "Summarize today\u0027s open tickets."}'

هر عضو یک نقش در سازمان دارد. نقش‌ها به این ترتیب از کم به زیاد هستند: VIEWER < MEMBER < ADMIN < OWNER.

هیچ‌کس نمی‌تواند نقشی بالاتر از نقش خودش به دیگران بدهد و هر سازمان همیشه دست‌کم یک مالک (owner) دارد.

پروژه‌های عمومی و محدود

به‌طور پیش‌فرض، هر پروژه برای همهٔ اعضای فعال سازمان و با همان نقش سازمانی‌شان باز است. در سازمان‌هایی که از پروژهٔ محدود (restricted) استفاده می‌کنند، چنین پروژه‌ای فقط برای مالکان، مدیران و تیم‌ها یا اعضایی باز است که در یک grant نامشان آمده باشد:

# Create a team, then give it access to one restricted project
curl -X POST https://api.mahvashai.ir/api/v1/tenancy/teams \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "X-Mahvash-Organization: acme" \
  -H "Content-Type: application/json" \
  -d '{"name": "Marketing"}'

curl -X POST https://api.mahvashai.ir/api/v1/tenancy/projects/<project-uuid>/grants \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "X-Mahvash-Organization: acme" \
  -H "Content-Type: application/json" \
  -d '{"team": "<team-uuid>", "role": "MEMBER"}'

دو نکته که به‌راحتی اشتباه برداشت می‌شوند:

• grant فقط تعیین می‌کند به کجا دسترسی دارید، نه اینکه آنجا چه کاری می‌توانید بکنید. نقش نهایی، پایین‌ترینِ نقش سازمانی و نقش grant است؛ پس VIEWERی که grant با نقش MEMBER دارد، همچنان فقط می‌تواند بخواند.
• پروژه‌ای که به آن دسترسی ندارید، طوری رفتار می‌کند که انگار وجود ندارد. پاسخ آن 404 است، نه 403؛ تا از روی فهرست‌ها یا شناسه‌ها نتوان فهمید تیم‌های دیگر چه دارند.

برای سازمان، هر پروژه و حتی هر API key می‌توانید سقف تعداد request در دقیقه (requests_per_minute) و سقف کارهای همزمان (max_active_runs) تعیین کنید؛ برای سازمان و پروژه هم می‌توانید بودجهٔ ماهانه و آستانهٔ هشدار بگذارید:

curl -X PATCH https://api.mahvashai.ir/api/v1/tenancy/organizations/settings \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "X-Mahvash-Organization: acme" \
  -H "Content-Type: application/json" \
  -d '{"requests_per_minute": 120, "max_active_runs": 4, "monthly_budget_usd": "500.00", "budget_alert_percent": 80}'

• سخت‌گیرانه‌ترین محدودیت اعمال می‌شود. پروژه نمی‌تواند محدودیت سازمان را بالا ببرد و کلید هم نمی‌تواند محدودیت پروژه را. ساده‌ترین راه برای کنترل کلیدی که به یک شریک تجاری می‌دهید، گذاشتن محدودیت کوچک روی همان کلید است.
• مقدار null یعنی «از سطح بالاتر پیروی کن»، نه «بدون محدودیت».
• اگر از سقف تعداد request عبور کنید، پاسخ 429 همراه با Retry-After می‌گیرید؛ اگر از سقف کارهای همزمان عبور کنید، کار تازه همان ابتدا پذیرفته نمی‌شود.
• monthly_budget_usd سقفی قطعی برای هر ماه میلادی به وقت UTC است و کاری که از آن عبور کند پذیرفته نمی‌شود. budget_alert_percent فقط هشدار می‌دهد و جلوی هیچ کاری را نمی‌گیرد.

فضای کاری را با endpointهای /api/v1/tenancy و JWT کاربر مدیریت می‌کنید؛ هرگز با API key پروژه. با X-Mahvash-Organization مشخص کنید کدام سازمان را مدیریت می‌کنید. یک اسکریپت راه‌اندازی معمولی این مراحل را دارد:

1. ۱با GET /api/v1/tenancy/organizations سازمان‌هایی را که عضوشان هستید ببینید و با GET /api/v1/tenancy/organization بررسی کنید request به کدام سازمان و پروژه می‌رسد.
2. ۲با POST /api/v1/tenancy/projects پروژه بسازید.
3. ۳در صورت نیاز پروژه را تنظیم کنید: promptها، منابع داده و ابزارهای مدیریت‌شده.
4. ۴API key پروژه را صادر کنید و در سامانهٔ مدیریت secretها نگه دارید.
5. ۵کلید را به سرویسی بدهید که قرار است requestهای هوش مصنوعی را بفرستد.

curl https://api.mahvashai.ir/api/v1/tenancy/organizations \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

# Which organization, project and role did this request resolve to?
curl https://api.mahvashai.ir/api/v1/tenancy/organization \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "X-Mahvash-Organization: acme"

curl -X POST https://api.mahvashai.ir/api/v1/tenancy/projects \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "X-Mahvash-Organization: acme" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support assistant", "slug": "support", "description": "Ticket drafting"}'

ساخت پروژه، صدور کلید و مدیریت grantها و webhookها به نقش ADMIN نیاز دارد. پروژهٔ پیش‌فرض قابل بایگانی یا حذف نیست، چون requestهایی که پروژه‌ای مشخص نمی‌کنند به آن می‌رسند. حذف هر پروژهٔ دیگر در واقع آن را بایگانی می‌کند و سوابقش برای حسابداری باقی می‌ماند.

صفحه‌های مرتبط در مرجع API: سازمان‌ها، پروژه‌ها، API credentialها، اعضا، تیم‌ها و grantهای دسترسی.