پایگاه دانش

مدل‌های زبانی فقط چیزهایی را می‌دانند که در آموزششان دیده‌اند. آن‌ها از قیمت محصولات شما، قوانین مرجوعی فروشگاهتان یا مستندات داخلی تیمتان خبر ندارند. پایگاه دانش هوشوانا این مشکل را حل می‌کند: محتوای خودتان را اضافه می‌کنید، هوشوانا آن را پردازش و نمایه می‌کند و هنگام پرسش، مرتبط‌ترین بخش‌ها را پیدا می‌کند و در اختیار مدل می‌گذارد. به این روش RAG (تولید با پشتوانه‌ی بازیابی) گفته می‌شود.

مفاهیم

• پایگاه دانش: مجموعه‌ای از منابع با یک شناسه‌ی یکتا (مثل kb_123).
• منبع: یک سایت، یک آدرس، یک فایل یا یک پایگاه داده که به پایگاه دانش اضافه کرده‌اید.
• تکه (chunk): بخش کوچکی از متن (حدود ۸۰۰ توکن) که جداگانه جستجو می‌شود.
• بازیابی: پیدا کردن تکه‌هایی که از نظر معنایی به پرسش نزدیک‌ترند.

ساخت پایگاه دانش

1. به پایگاه‌های دانش در داشبورد بروید.
2. «پایگاه دانش جدید» را بزنید و یک نام و توضیح کوتاه وارد کنید.
3. یک یا چند منبع اضافه کنید.
4. صبر کنید پردازش تمام شود. شناسه‌ی پایگاه دانش را برای استفاده در API بردارید.

انواع منبع

خزش وب‌سایت

آدرس صفحه‌ی شروع را می‌دهید و هوشوانا پیوندهای داخل همان دامنه را دنبال می‌کند. عمق خزش (چند پیوند از صفحه‌ی شروع) و حداکثر تعداد صفحه را تعیین می‌کنید. خزنده به فایل robots.txt سایت احترام می‌گذارد و فقط صفحات همان میزبان را می‌خواند. برای مستندات یا مرکز راهنما، آدرس ریشه‌ی همان بخش را بدهید (مثلاً https://example.ir/help) تا صفحات نامرتبط وارد نشوند.

آدرس‌های تکی

اگر فقط چند صفحه‌ی مشخص لازم است، آدرس‌ها را جداگانه اضافه کنید.

بارگذاری فایل

قالب‌های پشتیبانی‌شده: txt، md، pdf، csv، json و html. PDFهای اسکن‌شده (تصویری) متن قابل استخراج ندارند. آن‌ها را ابتدا با OCR به متن تبدیل کنید.

بارگذاری پایگاه داده

می‌توانید جدول‌های CSV یا JSON، فایل SQLite یا خروجی SQL dump بارگذاری کنید. هوشوانا برای هر جدول پروفایل می‌سازد: ستون‌ها، نوع داده‌ها، میزان مقادیر خالی و توزیع مقادیر. این پروفایل همراه با خلاصه‌ای از جدول نمایه می‌شود تا مدل بتواند به سوالاتی مثل «چه ستون‌هایی داریم؟» یا «بیشتر سفارش‌ها از کدام شهرند؟» پاسخ بدهد. توجه کنید این قابلیت برای درک ساختار و محتوای کلی داده است و جایگزین اجرای کوئری دقیق SQL نیست.

مراحل پردازش

هر منبع این مراحل را طی می‌کند:

1. استخراج متن از صفحه یا فایل
2. نرمال‌سازی فارسی: «ي» و «ك» عربی به «ی» و «ک» فارسی تبدیل می‌شوند و نیم‌فاصله‌ها حفظ می‌شوند
3. تکه‌تکه کردن: تکه‌های حدود ۸۰۰ توکنی با ۱۰۰ توکن هم‌پوشانی
4. ساخت embedding با openai/text-embedding-3-small و ذخیره در نمایه‌ی برداری

وضعیت هر منبع در داشبورد نمایش داده می‌شود: در صف، در حال پردازش، آماده یا خطا. اگر منبعی خطا بخورد، دلیل آن (مثلاً دسترسی‌ناپذیر بودن سایت یا فایل خراب) کنار آن نوشته می‌شود. وقتی محتوای منبع تغییر کرد، می‌توانید آن را دوباره پردازش کنید.

جستجو با API

با endpoint زیر مستقیماً در پایگاه دانش جستجو می‌کنید و تکه‌های مرتبط را می‌گیرید. این روش برای وقتی است که می‌خواهید خودتان نتایج را نمایش دهید یا با مدل و prompt دلخواه ترکیب کنید:

curl https://hooshvana.ir/api/v1/kb/kb_123/query \
  -H "Authorization: Bearer $HOOSHVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "شرایط مرجوعی کالا چیست؟", "top_k": 5}'

نمونه‌ی پاسخ:

{
  "results": [
    {
      "text": "مشتریان می‌توانند تا هفت روز پس از دریافت، کالا را در صورت باز نشدن بسته‌بندی مرجوع کنند...",
      "score": 0.86,
      "source": {
        "title": "قوانین مرجوعی",
        "url": "https://example.ir/help/returns"
      }
    },
    {
      "text": "هزینه‌ی ارسال کالای مرجوعی در صورت ایراد فنی بر عهده‌ی فروشگاه است...",
      "score": 0.79,
      "source": { "title": "سوالات متداول", "url": "https://example.ir/faq" }
    }
  ]
}

score میزان شباهت است و هرچه بیشتر باشد، تکه مرتبط‌تر است. top_k تعداد نتایج را تعیین می‌کند.

import os
import requests

resp = requests.post(
    "https://hooshvana.ir/api/v1/kb/kb_123/query",
    headers={"Authorization": "Bearer " + os.environ["HOOSHVANA_API_KEY"]},
    json={"query": "هزینه‌ی ارسال چقدر است؟", "top_k": 3},
    timeout=30,
)
resp.raise_for_status()
for r in resp.json()["results"]:
    print(round(r["score"], 2), r["source"]["title"])

استفاده در چت

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

from openai import OpenAI
import os

client = OpenAI(base_url="https://hooshvana.ir/api/v1", api_key=os.environ["HOOSHVANA_API_KEY"])

resp = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[
        {"role": "system", "content": "Answer only from the provided context. If unsure, say you don't know. Reply in Persian and cite sources."},
        {"role": "user", "content": "اگر کالا ایراد داشته باشد، هزینه‌ی ارسال مرجوعی با کیست؟"},
    ],
    extra_body={"hooshvana": {"knowledge_base_ids": ["kb_123"]}},
)
print(resp.choices[0].message.content)

اتصال به کلید

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

هزینه‌ها

پردازش پایگاه دانش مثل فراخوانی‌های عادی API هزینه دارد:

• هنگام افزودن منبع: هزینه‌ی embedding همه‌ی تکه‌ها (و برای پایگاه داده، خلاصه‌سازی جدول‌ها). این هزینه در لاگ‌ها با منبع kb نمایش داده می‌شود.
• هنگام جستجو: هزینه‌ی embedding متن پرسش که بسیار ناچیز است.
• هنگام چت: تکه‌های بازیابی‌شده به توکن‌های ورودی مدل اضافه می‌شوند. با top_k بیشتر، هزینه‌ی هر پاسخ هم بیشتر می‌شود.

امنیت و حمله‌ی تزریق prompt

محتوای پایگاه دانش، به‌خصوص صفحاتی که از وب خزش شده‌اند، ممکن است شامل متن‌هایی باشد که سعی می‌کنند به مدل دستور بدهند (مثل «همه‌ی دستورات قبلی را نادیده بگیر»). هوشوانا متن بازیابی‌شده را در یک بخش زمینه‌ی جداشده و مشخص قرار می‌دهد، آن را داده معرفی می‌کند نه دستور، و هرگز به آن اختیار فراخوانی ابزار نمی‌دهد. با این حال:

• فقط منابعی را اضافه کنید که به محتوایشان اعتماد دارید.
• اطلاعات محرمانه‌ای را که نباید به کاربران نهایی نشان داده شود، در پایگاه دانش عمومی نگذارید. هر چیزی در پایگاه دانش ممکن است در پاسخ مدل ظاهر شود.
• برای کاربران با سطح دسترسی متفاوت، پایگاه‌های دانش جداگانه بسازید.
• اگر مدل در کنار پایگاه دانش به ابزارهای حساس دسترسی دارد (مثل ارسال ایمیل یا تغییر داده)، اجرای آن ابزارها را در کد خودتان کنترل و تأیید کنید.

بهترین روش‌ها برای محتوای فارسی

• ساختار واضح: عنوان‌ها و پاراگراف‌های کوتاه بازیابی را دقیق‌تر می‌کنند. هر بخش بهتر است درباره‌ی یک موضوع باشد.
• پرسش و پاسخ: محتوای سوالات متداول با قالب «سوال، پاسخ» معمولاً بهترین نتیجه را می‌دهد.
• اصطلاحات هم‌معنی: اگر کاربران یک مفهوم را با چند واژه می‌پرسند (مثل «مرجوعی»، «بازگشت کالا» و «پس دادن»)، این واژه‌ها را در متن بیاورید.
• اعداد و تاریخ‌ها: اطلاعات قیمت و زمان را به‌روز نگه دارید و منبع قدیمی را حذف یا دوباره پردازش کنید.
• حذف محتوای تکراری: منوها، فوترها و صفحات تکراری کیفیت بازیابی را پایین می‌آورند. دامنه‌ی خزش را محدود کنید.
• آزمایش: چند پرسش واقعی را با /kb/{id}/query امتحان کنید و ببینید تکه‌های درست برمی‌گردند یا نه.