رفتن به محتوا
Mahvash/مستندات API
English

راهنماها

ساخت پرسش‌وپاسخ اسناد

یک مسیر کامل از ابتدا تا انتها: آماده کردن پروژه، آپلود سند، ایندکس کردن، اتصال به پروژه، پرسیدن سؤال، خواندن ارجاع‌ها و پاک‌سازی.

چه چیزی می‌سازید

در پایان این راهنما، سرور شما می‌تواند به پرسشی مثل «کارمند تازه‌وارد چند روز مرخصی دارد؟» از روی آیین‌نامه‌های خودتان پاسخ دهد و نشان دهد پاسخ از کدام فایل آمده است. روند کار این است:

  1. ۱با JWT کاربر یک پروژه و یک API key پروژه آماده می‌کنید (فقط یک بار).
  2. ۲سرور شما اسناد را آپلود می‌کند و در یک vector store ایندکس می‌کند.
  3. ۳برای هر پرسش، سرور شما با API key پروژه Responses را صدا می‌زند و مهوش بخش‌های مرتبط را پیدا می‌کند و با ارجاع پاسخ می‌دهد.

در هر مرحله، پیوند عملیات دقیق API و یک request و پاسخ نمونه آمده است.

۱. آماده کردن پروژه

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

کلید را در سامانهٔ مدیریت secretها نگه دارید. همهٔ مراحل بعدی با همین کلید انجام می‌شود و هرچه با آن ساخته شود، به همین پروژه تعلق دارد.

ساخت پروژه ↗صدور API key برای پروژه ↗
curl -X POST 'https://api.mahvashai.ir/api/v1/tenancy/projects' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Research",
  "slug": "research"
}'
{
  "status": 201,
  "data": {
    "id": "<project-uuid>",
    "organization": "<organization-uuid>",
    "name": "Research",
    "slug": "research"
  }
}

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

۲. آپلود فایل منبع

هر سند را با POST /v1/files و به‌صورت multipart/form-data آپلود کنید و شناسهٔ file-... برگشتی را در پایگاه دادهٔ خودتان کنار رکورد همان سند ذخیره کنید.

  • برای اسنادی که می‌خواهید در آن‌ها جست‌وجو شود، purpose=user_data بفرستید.
  • برای فایل‌های بزرگ از آپلود چندبخشی استفاده کنید؛ نتیجه همان نوع شیء فایل است.
  • فایل را به‌صورت base64 داخل JSON نفرستید.
آپلود فایل (مسیر اصلی /v1) ↗
curl -X POST 'https://api.mahvashai.ir/v1/files' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -F 'file=@./your-file'
{
  "id": "<id>",
  "object": "file",
  "bytes": 0,
  "created_at": 1750000000,
  "expires_at": null,
  "filename": "example",
  "purpose": "user_data",
  "status": "processed",
  "status_details": null
}

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

۳. ایندکس کردن

در همان پروژه یک vector store بسازید و فایل را به آن اضافه کنید. با این کار ایندکس شدن شروع می‌شود؛ وضعیت فایل در vector store را آن‌قدر بخوانید تا status آن completed شود.

  • failed یعنی سند قابل پردازش نبوده است. last_error را بررسی کنید، سند را اصلاح کنید و دوباره امتحان کنید.
  • هر vector store می‌تواند فایل‌های زیادی داشته باشد. اسنادی را که باید با هم جست‌وجو شوند در یک vector store بگذارید و اگر کاربران مختلف اجازهٔ خواندن اسناد متفاوتی دارند، vector storeهای جداگانه بسازید.

مهم:vector storeی که هیچ فایل ایندکس‌شده‌ای ندارد، نمی‌تواند به پرسش‌ها پاسخ دهد. تا ایندکس شدن تمام نشده، این قابلیت را برای کاربران فعال نکنید.

ساخت vector store ↗افزودن فایل به vector store ↗دریافت وضعیت یک فایل در vector store ↗
curl -X POST 'https://api.mahvashai.ir/v1/vector_stores' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Product manuals"
}'
{
  "id": "<id>",
  "object": "vector_store",
  "created_at": 1750000000,
  "name": "example",
  "usage_bytes": 0,
  "file_counts": {
    "in_progress": 0,
    "completed": 0,
    "cancelled": 0,
    "failed": 0,
    "total": 0
  },
  "status": "completed",
  "expires_after": null,
  "expires_at": null,
  "metadata": {},
  "retrieval_placement": "<value>",
  "effective_retrieval_placement": null
}

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

۴. اتصال vector store به پروژه (اختیاری)

برای استفاده از vector store دو راه دارید:

  • جست‌وجوی صریح: نام vector store را در ابزار file_search هر request بیاورید (مرحلهٔ ۵). این روش برای وقتی مناسب است که کاربران مختلف باید در vector storeهای متفاوت جست‌وجو کنند.
  • منبع دادهٔ پروژه: vector store را به پروژه متصل کنید. اگر auto-search پروژه فعال باشد، هر requestی که ابزار خودش را تعیین نکرده باشد، خودکار در منابع دادهٔ پروژه جست‌وجو می‌کند. این روش برای وقتی مناسب است که همهٔ کاربران پروژه اجازهٔ جست‌وجو در یک دانش مشترک را دارند.

اتصال منبع داده با اضافه کردن فایل به vector store فرق دارد؛ چیزی آپلود یا ایندکس نمی‌کند. هر request همچنان می‌تواند با tools: [] یا tool_choice: "none" این جست‌وجو را غیرفعال کند.

اتصال vector store به‌عنوان منبع دادهٔ پروژه ↗
curl -X POST 'https://api.mahvashai.ir/api/v1/tenancy/projects/<project_id>/data-sources' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "vector_store_id": "3f5a8c4e-6b8d-4a4f-9d2c-1f0a2b3c4d5e"
}'
{
  "status": 201,
  "data": {
    "id": "<data-source-uuid>",
    "vector_store_id": "<store-uuid>",
    "position": 0,
    "added_by": "<user-id>"
  }
}

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

۵. پرسیدن و بررسی پاسخ

با API key پروژه یک request به Responses بفرستید. request و پاسخ نمونهٔ پایان این مرحله از ابزار file_search به‌صورت صریح استفاده می‌کنند.

پاسخ یک آیتم file_search_call دارد و بعد از آن message دستیار می‌آید. ارجاع‌ها به‌صورت annotation روی output_text می‌آیند، نه به‌صورت متن داخل پاسخ:

  • annotationهای file_citation مقدار file_id و filename فایلی را که آن بخش از آن آمده مشخص می‌کنند.
  • file_id را به رکورد سند خودتان وصل کنید و پیوندی به نمایشگر اسناد خودتان نشان دهید که با کنترل دسترسی خودتان محافظت می‌شود.
  • اگر پاسخی هیچ ارجاعی ندارد، آن را پاسخ بدون منبع نشان دهید، نه پاسخ مستند.
ساخت response ↗
curl https://api.mahvashai.ir/v1/responses \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-question-id>" \
  -d '{
    "model": "auto",
    "input": "What does the uploaded policy say about retention?",
    "tools": [{"type": "file_search", "vector_store_ids": ["vs_<store-uuid>"]}]
  }'
{
  "id": "resp_example",
  "object": "response",
  "status": "completed",
  "output": [
    {"type": "file_search_call", "status": "completed"},
    {"type": "message", "role": "assistant", "content": [{
      "type": "output_text",
      "text": "The policy retains records for the stated period.",
      "annotations": [{"type": "file_citation", "file_id": "file-<uuid>", "filename": "policy.pdf"}]
    }]}
  ]
}

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

۶. مدیریت چرخهٔ عمر اسناد

اسناد تغییر می‌کنند؛ پس برای خارج کردنشان از سیستم هم به اندازهٔ وارد کردنشان برنامه داشته باشید:

  • جایگزینی سند: نسخهٔ تازه را آپلود و به vector store اضافه کنید، صبر کنید تا completed شود و بعد فایل قدیمی را از vector store بردارید.
  • توقف جست‌وجو در کل پروژه: منبع داده را از پروژه جدا کنید. responseهای قبلی ارجاع‌هایشان را حفظ می‌کنند.
  • حذف محتوا: برداشتن فایل از vector store ایندکس آن را پاک می‌کند اما خود فایل باقی می‌ماند؛ فایل را جداگانه حذف کنید و وقتی vector store خالی شد، آن را هم حذف کنید.
جدا کردن منبع داده از پروژه ↗برداشتن فایل از vector store ↗حذف فایل (مسیر اصلی /v1) ↗
curl -X DELETE 'https://api.mahvashai.ir/api/v1/tenancy/projects/<project_id>/data-sources/<vector_store_id>' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"
نمونه‌های پیاده‌سازی →