ورودی فایل و بازیابی اطلاعات

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

• assetها (/api/v1/chat/assets) فایل‌های قابل استفادهٔ مجدد پروژه هستند که با یک UUID شناخته می‌شوند. آن‌ها را با asset_ids به request می‌دهید.
• فایل‌ها (/v1/files) همان اشیای فایل OpenAI (file-...) هستند و برای سازگاری با SDK، batch و vector store به کار می‌روند. /api/v1/chat/files همین فایل‌ها را در قالب پاسخ مخصوص مهوش ارائه می‌دهد.
• آپلود چندبخشی (/api/v1/chat/uploads) یک فایل بزرگ را به بخش‌های شماره‌دار و قابل تکرار تقسیم می‌کند.
• vector storeها (/v1/vector_stores) فایل‌ها را ایندکس می‌کنند تا file_search بتواند بخش‌های مرتبط را پیدا کند.
• منابع دادهٔ پروژه یک vector store ایندکس‌شده را به بخشی از جست‌وجوی پروژه تبدیل می‌کنند.

وقتی کاربر برای یک پرسش سند یا تصویری پیوست می‌کند، مدل باید خود فایل را بخواند، نه اینکه در آن جست‌وجو کند. فایل را یک بار به‌عنوان asset آپلود کنید و با UUID به آن اشاره کنید:

# Upload once. Keep the returned asset UUID in your own records.
curl https://api.mahvashai.ir/api/v1/chat/assets/upload \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -F "file=@./contract.pdf"

# Reuse it in any supported request of the same project
curl https://api.mahvashai.ir/v1/responses \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "input": "List the termination clauses.", "asset_ids": ["<asset-uuid>"]}'

• asset باید آماده باشد و به همان پروژهٔ request تعلق داشته باشد.
• هر request تعداد محدودی asset می‌پذیرد (به‌طور پیش‌فرض حداکثر ۱۰ فایل با مجموع حجم ۵۰ مگابایت). موارد تکراری حذف می‌شوند و ترتیب بقیه حفظ می‌شود.
• اگر مدل انتخاب‌شده نتواند نوعی از فایل را بخواند و ابزارهای مدیریت‌شدهٔ پروژه فعال باشند، مهوش می‌تواند اول متن سند را استخراج یا تصویر را توصیف کند. سندهای اسکن‌شده‌ای که لایهٔ متنی ندارند پذیرفته نمی‌شوند.

/v1/files از Files API در OpenAI پیروی می‌کند؛ بنابراین متدهایی مثل files.create در SDK بدون تغییر کار می‌کنند. هر فایل یک purpose دارد: user_data (پیش‌فرض) برای ورودی‌های عمومی، batch برای فایل ورودی batch، و مقدارهای دیگر OpenAI مثل assistants یا vision.

with open("handbook.pdf", "rb") as handle:
    uploaded = mahvash.files.create(file=handle, purpose="user_data")

print(uploaded.id)  # file-<uuid>

store = mahvash.vector_stores.create(name="Employee handbook")
mahvash.vector_stores.files.create(vector_store_id=store.id, file_id=uploaded.id)

اطلاعات فایل (GET /v1/files/{id}) و محتوای آن (GET /v1/files/{id}/content) از هم جدا هستند: endpoint محتوا خود بایت‌های فایل را با نوع MIME ذخیره‌شده برمی‌گرداند، نه JSON.

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

# 1. Open a session for the whole file
curl https://api.mahvashai.ir/api/v1/chat/uploads \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "archive.pdf", "bytes": 10485760, "mime_type": "application/pdf", "purpose": "user_data"}'

# 2. Send numbered parts; each may be retried independently
curl -X PUT https://api.mahvashai.ir/api/v1/chat/uploads/upload-<uuid>/parts/1 \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "X-Part-SHA256: <lowercase-sha256-of-part-1>" \
  -F "data=@./archive.part1"

curl -X PUT https://api.mahvashai.ir/api/v1/chat/uploads/upload-<uuid>/parts/2 \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "X-Part-SHA256: <lowercase-sha256-of-part-2>" \
  -F "data=@./archive.part2"

# 3. Complete: parts 1..part_count must add up to the declared bytes
curl https://api.mahvashai.ir/api/v1/chat/uploads/upload-<uuid>/complete \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"part_count": 2}'

• شمارهٔ بخش‌ها از 1 شروع می‌شود، ترتیب ارسال مهم نیست و تا پیش از تکمیل می‌توانید هر بخش را دوباره بفرستید یا جایگزین کنید. hash از نوع SHA-256 هر بخش را در X-Part-SHA256 بفرستید تا خراب شدن داده تشخیص داده شود.
• هنگام تکمیل، بخش‌های 1..part_count باید پشت سر هم باشند و مجموع حجمشان دقیقاً برابر bytes اعلام‌شده باشد. نتیجه یک شیء فایل معمولی است.
• هر جلسهٔ آپلود به‌طور پیش‌فرض پس از حدود یک ساعت منقضی می‌شود. جلسه‌هایی را که نیمه‌کاره رها می‌کنید، لغو کنید.

بازیابی اسناد برای وقتی است که مجموعهٔ اسناد آن‌قدر بزرگ است که نمی‌شود همه را در هر request فرستاد. این کار سه مرحلهٔ جدا دارد که بهتر است با هم اشتباه نشوند:

1. ۱فایل را آپلود کنید. حالا فایل ذخیره شده، ولی هنوز قابل جست‌وجو نیست.
2. ۲فایل را با اضافه کردن به یک vector store ایندکس کنید. مهوش متن را استخراج می‌کند، آن را به قطعه‌های کوچک‌تر تقسیم می‌کند و ایندکس قابل جست‌وجو می‌سازد. وضعیت فایل در vector store از in_progress به completed (یا failed) تغییر می‌کند.
3. ۳در آن جست‌وجو کنید. ابزار file_search در یک request به Responses مرتبط‌ترین قطعه‌ها را پیدا می‌کند و به مدل می‌دهد و مدل با ارجاع به منبع پاسخ می‌دهد.

# Create a store in the project that will query it
curl https://api.mahvashai.ir/v1/vector_stores \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support policies"}'

# Attach an uploaded file; indexing starts now
curl https://api.mahvashai.ir/v1/vector_stores/vs_<uuid>/files \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "file-<uuid>"}'

# Poll until "status" is "completed" (or handle "failed")
curl https://api.mahvashai.ir/v1/vector_stores/vs_<uuid>/files/file-<uuid> \
  -H "Authorization: Bearer $MAHVASH_API_KEY"

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

برای اینکه یک request در اسناد شما جست‌وجو کند، دو راه دارید.

`file_search` صریح

vector storeها را در خود request نام ببرید. این روش کنترل دقیق به شما می‌دهد؛ مثلاً می‌توانید vector store را بر اساس دسترسی کاربر خودتان انتخاب کنید:

{
  "model": "auto",
  "input": "How many vacation days do new employees get?",
  "tools": [
    { "type": "file_search", "vector_store_ids": ["vs_<uuid>"], "max_num_results": 8 }
  ],
  "include": ["file_search_call.results"]
}

با include: ["file_search_call.results"] قطعه‌های پیداشده هم در پاسخ برمی‌گردند که برای نمایش منبع یا بررسی کیفیت جست‌وجو مفید است.

منابع دادهٔ پروژه

یک vector store آماده را به‌عنوان منبع داده به پروژه متصل کنید. اگر auto-search پروژه فعال باشد، هر requestی که خودش ابزاری تعیین نکرده باشد، خودکار در منابع دادهٔ پروژه جست‌وجو می‌کند. متصل کردن منبع داده چیزی آپلود یا ایندکس نمی‌کند؛ فقط یک vector store موجود را به جست‌وجوی پروژه اضافه می‌کند.

پاسخ‌ها با annotationهای file_citation به منبع ارجاع می‌دهند که شناسهٔ file-... فایل در مهوش را دارند. این شناسه‌ها را به رکوردهای سند خودتان وصل کنید تا بتوانید پیوند منبع را نمایش دهید.

راهنمای ساخت پرسش‌وپاسخ اسناد همهٔ این مراحل را به ترتیب کنار هم گذاشته است.

• محدودهٔ پروژه. هر فایل، asset و vector store به یک پروژه تعلق دارد. شناسه‌ای که به جای دیگری تعلق دارد یا به آن دسترسی ندارید، پاسخ 404 می‌گیرد. file_search فقط vector storeهای متعلق به سازمان شما را می‌پذیرد.
• محل نگهداری. فیلد retrieval_placement در هر vector store تعیین می‌کند ایندکس کجا نگه داشته شود: local اسناد را در ایندکس خود مهوش نگه می‌دارد و hosted آن‌ها را از طریق حساب یک ارائه‌دهنده ایندکس می‌کند. مقدار پیش‌فرض در عمل local است و هر پروژه می‌تواند برای vector storeهای تازه پیش‌فرض دیگری تعیین کند.
• حذف کردن صریح است. جدا کردن منبع داده، جست‌وجوی پروژه را متوقف می‌کند؛ برداشتن فایل از vector store ایندکس آن را پاک می‌کند اما خود فایل را نه؛ و حذف فایل یک درخواست جداگانه است. پاک‌سازی را بر اساس سیاست نگهداری داده‌های خودتان برنامه‌ریزی کنید.
• محافظت از دانلودها با شماست. محتوایی را که از مهوش دانلود می‌کنید، فقط پس از بررسی دسترسی در اپلیکیشن خودتان به کاربران نشان دهید.