راهنماها

ساخت محصول با مهوش

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

مهوش چه کاری انجام می‌دهد

مهوش میان اپلیکیشن شما و ارائه‌دهندگان مدل‌های هوش مصنوعی قرار می‌گیرد. شما یک request با قالبی آشنا به https://api.mahvashai.ir می‌فرستید و مهوش بقیهٔ کار را انجام می‌دهد: تشخیص می‌دهد چه کسی و از طرف کدام پروژه درخواست داده، request را بررسی می‌کند، مسیری را انتخاب می‌کند که واقعاً از پس آن برمی‌آید، آن را اجرا می‌کند و پاسخی یکدست برمی‌گرداند. هر فراخوانی با شناسه، میزان مصرف و هزینهٔ مشخص ثبت می‌شود و متعلق به سازمان شماست.

یعنی می‌توانید با همان قالب OpenAI که احتمالاً با آن آشنا هستید کار کنید و بخش‌های دشوار را به مهوش بسپارید:

یک API برای مدل‌های مختلف. کافی است مدلی مثل auto یا یکی از شناسه‌های GET /v1/models را بخواهید؛ انتخاب مسیر مناسب با مهوش است.
فضای کاری با جداسازی واقعی. با سازمان، پروژه، تیم و API keyهای محدودشده، هر مشتری، محصول یا محیط از بقیه جدا می‌ماند.
کارهای ماندگار و قابل پیگیری. هر response شناسهٔ ثابت دارد، می‌تواند در پس‌زمینه اجرا شود، قابل بازیابی و لغو است و تکرار امن request را پشتیبانی می‌کند.
فایل و بازیابی اسناد. سند را یک بار آپلود کنید، آن را در یک vector store ایندکس کنید و پاسخ همراه با ارجاع بگیرید.
ابزارهای مدیریت‌شده. اگر پروژه اجازه دهد، مهوش قابلیت‌هایی مثل جست‌وجوی وب، ساخت تصویر یا خواندن سند و تصویر را در اختیار مدلی قرار می‌دهد که خودش آن‌ها را ندارد.

چه چیزهایی می‌توانید بسازید

نام endpointهای هوش مصنوعی همان نام‌های OpenAI است؛ پس بیشتر نمونه‌کدها و SDKهای موجود بدون تغییر قابل استفاده‌اند. بخش‌های اصلی عبارت‌اند از:

متن و استدلال: POST /v1/responses (پیشنهاد ما برای پروژه‌های تازه) و POST /v1/chat/completions برای یکپارچه‌سازی‌های گفت‌وگومحور.
Embedding: POST /v1/embeddings برای جست‌وجوی معنایی، دسته‌بندی و پیدا کردن موارد تکراری.
تصویر: POST /v1/images/generations و POST /v1/images/edits.
صوت: POST /v1/audio/transcriptions برای تبدیل گفتار به متن و POST /v1/audio/speech برای تبدیل متن به گفتار.
ایمنی محتوا: POST /v1/moderations برای بررسی محتوای کاربر پیش از پردازش.
اسناد: /v1/files، /v1/vector_stores و ابزار file_search برای پرسش‌وپاسخ روی فایل‌های خودتان.
پردازش انبوه: /v1/batches برای اجرای هزاران request در پس‌زمینه از روی یک فایل JSONL.

علاوه بر این‌ها، مهوش زیر مسیر /api/v1 APIهایی برای مدیریت فضای کاری دارد: سازمان، پروژه، API key، اعضا، تیم‌ها، promptها، منابع داده و webhookها.

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

دو بخش اصلی API

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

بخش	کاربرد	credential	body پاسخ
`/v1/*`	کارهای هوش مصنوعی: response، چت، embedding، تصویر، صوت، فایل، vector store و batch	API key پروژه (یا JWT کاربر)	خود شیء، با قالب OpenAI
`/api/v1/tenancy/*`	سازمان، پروژه، اعضا، تیم‌ها، grantها، کلیدها، promptها و منابع داده	JWT کاربر	داخل ساختار `{ "status": ..., "data": ... }`
`/api/v1/chat/*`	assetهای قابل استفادهٔ مجدد، آپلود چندبخشی، webhookها و دیگر قابلیت‌های مکمل مهوش	طبق توضیح هر endpoint	داخل ساختار `{ "status": ..., "data": ... }`

در عمل، سرور شما در production معمولاً با API key پروژه با /v1 کار می‌کند؛ اما مدیر سیستم یا اسکریپت راه‌اندازی، برای ساخت پروژه و کلید از /api/v1/tenancy و token کاربرِ واردشده استفاده می‌کند. قالب پاسخ‌ها را در Headerها و ساختار Response به‌تفصیل توضیح داده‌ایم.

مفاهیم کلیدی

چند اصطلاح در سراسر این مستندات تکرار می‌شود:

سازمان: بالاترین سطح جداسازی و محل پرداخت هزینه‌ها. هر حساب با یک سازمان شخصی شروع می‌شود و شرکت‌ها سازمان مشترک می‌سازند.
پروژه: فضای کاری داخل سازمان. runها، فایل‌ها، vector storeها، promptها و API keyها به پروژه تعلق دارند. هر سازمان یک پروژهٔ پیش‌فرض دارد.
API key پروژه: کلیدی محرمانه با پیشوند mk_... برای ارتباط سرور با سرور که فقط به یک سازمان و یک پروژه تعلق دارد.
JWT کاربر: tokenی کوتاه‌عمر که نشان‌دهندهٔ یک کاربرِ واردشده است و برای مدیریت فضای کاری لازم است.
مدل منطقی: شناسهٔ مدلی که درخواست می‌کنید. مهوش در هر request آن را به یک مسیر مشخص نزد ارائه‌دهنده وصل می‌کند.
response یا run: یک request پذیرفته‌شده با شناسهٔ ثابت (resp_...)، وضعیت، خروجی و میزان مصرف.
asset، فایل و vector store: به‌ترتیب فایل‌های قابل استفادهٔ مجدد، فایل‌هایی با قالب OpenAI، و ایندکس‌های قابل جست‌وجو که از فایل‌ها ساخته می‌شوند.

از کجا شروع کنید

بسته به چیزی که می‌سازید، یکی از این مسیرها را دنبال کنید:

۱می‌خواهم در چند دقیقه اولین request را بفرستم: شروع سریع را دنبال کنید.
۲به چند مشتری یا تیم سرویس می‌دهم: احراز هویت و سازمان‌ها و پروژه‌ها را بخوانید و بعد سناریوی اتصال SaaS چندمشتری را ببینید.
۳می‌خواهم از روی اسناد به پرسش‌ها پاسخ بدهم: ورودی فایل و بازیابی اطلاعات و بعد ساخت پرسش‌وپاسخ اسناد را بخوانید.
۴رابط گفت‌وگوی زنده می‌سازم: Stream و رویدادها و بعد سناریوی چت تعاملی پشتیبانی را ببینید.
۵آمادهٔ انتشار در production هستم: Headerها و ساختار Response و چک‌لیست اتصال در محیط اصلی را مرور کنید.

مرجع API همهٔ endpointها را با ورودی‌های مجاز، کدهای وضعیت و نمونه‌ها فهرست کرده است. هر وقت دنبال یک فیلد مشخص بودید سراغ مرجع بروید؛ برای اینکه بفهمید اجزا چطور کنار هم کار می‌کنند، راهنماها را بخوانید.

آدرس API و SDKها

همهٔ requestها به https://api.mahvashai.ir فرستاده می‌شوند. SDKهای رسمی OpenAI هم برای عملیات پشتیبانی‌شدهٔ /v1 کار می‌کنند؛ کافی است آدرس پایه را https://api.mahvashai.ir/v1 بگذارید و API key پروژهٔ مهوش را به آن بدهید:

import OpenAI from "openai";

// Server-side only. The key comes from your secret store or environment.
export const mahvash = new OpenAI({
  apiKey: process.env.MAHVASH_API_KEY,
  baseURL: "https://api.mahvashai.ir/v1",
  timeout: 60_000,
  maxRetries: 0, // Decide retries yourself; see "Errors and retries".
});

مهم:کلاینت SDK را فقط روی سرور بسازید. API keyی که در کد JavaScript مرورگر، بستهٔ اپ موبایل یا یک مخزن عمومی باشد، به‌راحتی کپی می‌شود. اگر بخشی از سایت یا اپ به قابلیت هوش مصنوعی نیاز دارد، request را از بک‌اند خودتان بفرستید.

شروع سریع →