مدیریت فایل و کرال در پایگاه دانش
مقدمه
در این مستند، APIهای مربوط به فایل و کرال در پایگاه دانش توضیح داده شده است.
هر پایگاه دانش باید یکی از این دو حالت را داشته باشد:
- فقط ** فایل**
- یا فقط ** کرال**
آدرس پایه تمامی سرویسها:
http://app.houshyar24.ir/api/v1/b2b/
بخش اول: مدیریت فایلها
1. ایجاد (آپلود) فایل در پایگاه دانش
مسیر سرویس
POST /knowledge-bases/{knowledge_base_id}/files/
هدرها(Headers)
| نام | مقدار | توضیحات |
|---|---|---|
Authorization | Token api-token | توکن احراز هویت |
Content-Type | multipart/form-data | نوع محتوای درخواست |
فیلدهای فرم
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| file | فایل | بله | فایل مورد نظر |
| name | رشته | بله | نام فایل |
| file_type | رشته | بله | نوع فایل (مثال: sops_&_docs) |
برای ارسال فایل، مقدار file_type="sops_&_docs" قرار دهید.
نمونه فراخوانی
curl --location 'http://app.houshyar24.ir/api/v1/b2b/knowledge-bases/100/files/' --header 'Authorization: Token <your-token>' --form 'file=@"/path/to/file.png"' --form 'name="my-file"' --form 'file_type="sops_&_docs"'
پاسخ موفق (201)
{
"id": 40,
"uuid": "4ee4026a-6356-428e-a7d8-888a2d279dc8",
"name": "my-file",
"file_type": "sops_&_docs",
"extension": "png",
"size": 30340,
"words_count": 0,
"status": "embedding",
"created_at": "2025-12-13T20:06:41.456740+03:30"
}
وضعیت فایل (status)
| وضعیت | توضیح |
|---|---|
| pending | در صف پردازش |
| embedding | در حال امبد |
| completed | پردازش کامل شده |
| failed | خطا در پردازش |
2. دریافت لیست فایلهای پایگاه دانش
GET /knowledge-bases/{knowledge_base_id}/files/
نمونه فراخوانی
curl --location 'http://app.houshyar24.ir/api/v1/b2b/knowledge-bases/100/files/' --header 'Authorization: Token <your-token>'
پاسخ موفق (200)
[
{
"id": 40,
"name": "my-file",
"extension": "png",
"size": 30340,
"status": "embedding",
"created_at": "2025-12-13T20:06:41.456740+03:30"
}
]
3. حذف فایل
DELETE /knowledge-bases/{knowledge_base_id}/files/{file_id}/
بخش دوم: کرال (Crawl)
4. شروع کرال
این سرویس برای شروع فرآیند کرال یک وبسایت در یک پایگاه دانش مشخص استفاده میشود. پس از فراخوانی این API، سیستم به صورت غیرهمزمان عملیات کرال را آغاز کرده و وضعیت آن از طریق فیلد crawl_status قابل پیگیری خواهد بود.
مسیر سرویس
POST /knowledge-bases/{knowledge_base_id}/crawls/
هدرها(Headers)
| نام | مقدار | توضیحات |
|---|---|---|
Authorization | Token api-token | توکن احراز هویت |
Content-Type | multipart/form-data | نوع محتوای درخواست |
بدنه درخواست (Request Body)
| نام | نوع | اجباری | توضیح |
|---|---|---|---|
| url | string | بله | آدرس وبسایتی که باید کرال شود |
نمونه بدنه درخواست
{
"url": "https://houshyar24.ir/"
}
نمونه فراخوانی
curl --location 'https://app.houshyar24.ir/api/v1/b2b/knowledge-bases/100/crawls/' \
--header 'Authorization: Token <your-token>' \
--header 'Content-Type: application/json' \
--data '{"url": "https://houshyar24.ir/"}'
پاسخ موفق (201)
{
"id": 50,
"url": "https://houshyar24.ir/",
"crawl_status": "crawling",
"created_at": "2025-12-13T20:12:16.704768+03:30"
}
وضعیتهای کرال (crawl_status)
| وضعیت | توضیح |
|---|---|
| pending | در صف |
| crawling | در حال کرال |
| crawled | کرال اولیه انجام شده |
| downloading | در حال دانلود |
| completed | کامل |
| failed | خطا |
5. دریافت سایتمپ کرال(Sitemap)
این سرویس برای دریافت لیست صفحات شناساییشده در فرآیند کرال استفاده میشود. خروجی این API معمولاً شامل URLهای استخراجشده از وبسایت است که میتوان از آنها برای انتخاب صفحات جهت دانلود و پردازش استفاده کرد.
مسیر سرویس
GET /api/v1/b2b/knowledge-bases/{knowledge_base_id}/crawls/{crawl_id}/sitemap/
پارامترهای مسیر (Path Parameters)
| نام | نوع | توضیحات |
|---|---|---|
knowledge_base_id | integer | شناسه پایگاه دانش (Knowldge-base) |
crawl_id | integer | شناسه کرال (Crawl) |
هدرها (Headers)
| نام | مقدار | توضیحات |
|---|---|---|
Authorization | Token api-token | توکن احراز هویت |
نمونه فراخوانی
curl --location 'https://app.houshyar24.ir/api/v1/b2b/knowledge-bases/100/' \
--header 'Authorization: Token <your-token>'
پاسخ موفق (200)
{
"houshyar24.ir": {
"__self__": {
"url": "https://houshyar24.ir"
},
"about-us": {
"__self__": {
"url": "https://houshyar24.ir/about-us"
}
},
"ai-agents": {
"__self__": {
"url": "https://houshyar24.ir/ai-agents"
}
}
}
}
6. دانلود و پردازش صفحات انتخابی
این سرویس برای شروع فرآیند دانلود و پردازش صفحات کرالشده استفاده میشود. پس از فراخوانی، عملیات به صورت غیرهمزمان انجام شده و پردازش محتوا در پسزمینه آغاز میشود.
مسیر سرویس
POST /knowledge-bases/{knowledge_base_id}/crawls/{crawl_id}/download/
پارامترهای مسیر (Path Parameters)
| نام | نوع | توضیحات |
|---|---|---|
knowledge_base_id | integer | شناسه پایگاه دانش (Knowldge-base) |
crawl_id | integer | شناسه کرال (Crawl) |
هدرها (Headers)
| نام | مقدار | توضیحات |
|---|---|---|
Authorization | Token api-token | توکن احراز هویت |
پاسخ موفق (200)
"Download started"
ℹ️ این پاسخ به معنی شروع فرآیند دانلود است و پایان پردازش را تضمین نمیکند.
7. دریافت لیست SubCrawlها
این سرویس برای دریافت لیست SubCrawlهای مربوط به یک کرال مشخص استفاده میشود. هر SubCrawl معمولاً نمایانگر یک صفحه یا بخش مشخص از وبسایت است.
مسیر سرویس
GET /knowledge-bases/{knowledge_base_id}/crawls/{crawl_id}/subcrawls/
پارامترهای مسیر (Path Parameters)
| نام | نوع | توضیحات |
|---|---|---|
knowledge_base_id | integer | شناسه پایگاه دانش (Knowldge-base) |
crawl_id | integer | شناسه کرال (Crawl) |
هدرها (Headers)
| نام | مقدار | توضیحات |
|---|---|---|
Authorization | Token api-token | توکن احراز هویت |
بخش سوم: سگمنتها
8. دریافت سگمنتهای فایل
این سرویس برای دریافت سگمنتهای استخراجشده از یک فایل پردازششده در پایگاه دانش استفاده میشود.
مسیر سرویس
GET /knowledge-bases/{knowledge_base_id}/file/{file_id}/segments/?page=1&limit=16
پارامترهای مسیر (Path Parameters)
| نام | نوع | توضیحات |
|---|---|---|
knowledge_base_id | integer | شناسه پایگاه دانش (Knowldge-base) |
file_id | integer | شناسه فایل |
هدرها (Headers)
| نام | مقدار | توضیحات |
|---|---|---|
Authorization | Token api-token | توکن احراز هویت |
پاسخ موفق (200)