Asosiy kontentga o‘tish
AI qo‘llanmalari

Noldan Adaptive-RAG elektron tijorat mijozlarga xizmat ko‘rsatish tizimini yaratish: moslashuvchan qidiruv, intentni aniqlash va buyurtma vositalari amaliyoti

Ushbu qo‘llanma sizga Adaptive-RAG elektron tijorat mijozlarga xizmat ko‘rsatish tizimini lokal muhitda ishga tushirish, dinamik qidiruv, ko‘p bosqichli dalillarni to‘ldirish, ishonchlilikni tekshirish, Jev va DeepSeek yordamida intentni aniqlashni tushunish hamda siyosat bo‘yicha savol-javob, buyurtmani tekshirish, operator tasdig‘i, test va baholash, Docker orqali joylashtirish imkoniyatlarini sinab ko‘rishga yordam beradi.

Taxminan 40 daqiqalik o‘qish
Adaptive-RAG elektron tijorat mijozlar xizmatini noldan yaratish

Loyiha haqida

Adaptive-RAG elektron tijorat mijozlarga xizmat ko‘rsatish tizimi ko‘p shartli siyosat bo‘yicha maslahatlar uchun mo‘ljallangan intellektual mijozlarga xizmat ko‘rsatish loyihasidir. U yetarli dalil bo‘lmasligi, javoblarning asoslanmaganligi va murakkab savollarni bir martalik qidiruvda to‘liq topib bo‘lmasligi kabi muammolarni hal qilishga qaratilgan. Backend FastAPI va LangGraph asosida ishlaydi, frontend esa React’dan foydalanadi. Tizim foydalanuvchi niyati va savol murakkabligiga qarab to‘g‘ridan-to‘g‘ri javob berish, bilimlarni qidirish, qo‘shimcha qidiruv, vositani ishga tushirish, inson tasdig‘i yoki javob berishni rad etish yo‘llaridan birini dinamik ravishda tanlaydi.

Loyiha mahalliy namoyish, Adaptive RAG ish jarayonini o‘rganish va muhandislik tekshiruvlari uchun mos. U siyosat manbalariga havola berish, namoyish buyurtmalarini qidirish, tasdiqlash kutilayotgan amallar, sessiya xotirasi va SSE javoblarini qo‘llab-quvvatlaydi, ammo buyurtma va logistika ma’lumotlari haqiqiy biznes ma’lumotlari emas.

Joriy API mijoz yuborgan user_id qiymatini bevosita qabul qiladi va uning haqiqiyligini hali tekshirmaydi. Ishonchli autentifikatsiya, TLS va kirishni boshqarish ulanmagan bo‘lsa, loyihani to‘g‘ridan-to‘g‘ri ommaviy tarmoqqa joylashtirmang.

Tizim so‘rovni qanday qayta ishlaydi

Foydalanuvchi Web sahifa yoki HTTP API orqali savol yuborgach, so‘rov ketma-ket kirish himoyasi, niyatni aniqlash va murakkablik bo‘yicha yo‘naltirish bosqichlaridan o‘tadi. Shundan so‘ng tizim mos qayta ishlash tarmog‘ini tanlaydi va javob yaratish, sodiqlikni tekshirish, sessiya xotirasini yangilash hamda havolalarni qaytarish jarayonlarini yakunlaydi.

Foydalanuvchi → Web / HTTP API → Kirish himoyasi
             → Niyatni aniqlash → Murakkablik bo‘yicha yo‘naltirish
               ├─ To‘g‘ridan-to‘g‘ri javob
               ├─ Qidiruv → Qayta saralash → Zarur bo‘lsa qo‘shimcha qidiruv
               ├─ Rejalashtirish → Vosita bajarilishi / Inson tasdig‘i
               └─ Javob berishni rad etish
             → Yaratish va sodiqlikni tekshirish → Sessiya xotirasi → Javob va havolalar

Niyatni aniqlashda standart DeepSeek’dan foydalanish yoki TypeSafe Jev’ga o‘tish mumkin. E’tibor bering, Jev faqat niyatni tasniflash tugunini almashtiradi; murakkablikni aniqlash, so‘rovni qayta yozish, vazifani rejalashtirish, javob yaratish, sodiqlikni tekshirish va xotira xulosasi kabi boshqa LLM tugunlari DeepSeek tomonidan boshqariladi.

Asosiy imkoniyatlar

  • Moslashuvchan yo‘naltirish: biznes niyati va savol murakkabligini birlashtirib, to‘g‘ridan-to‘g‘ri javob, bir bosqichli qidiruv, ko‘p bosqichli qidiruv, vositani ishga tushirish yoki rad etish yo‘lini tanlaydi.
  • Gibrid qidiruv: BM25 va zich vektorli qaytarishni birlashtiradi, natijalarni RRF yordamida qo‘shadi va Cross-Encoder orqali qayta saralashni yoqish imkonini beradi.
  • Dalillarni kuchaytirish: so‘rovni qayta yozish, dalil yetarli bo‘lmaganda qo‘shimcha qidiruv, javob sodiqligini tekshirish va o‘z-o‘zini tuzatishni qo‘llab-quvvatlaydi.
  • Ikki xil niyat backend’i: standart holatda DeepSeek’dan foydalanadi, shuningdek Jev’ning strukturaviy choice interfeysi orqali oldindan belgilangan 14 turdagi biznes niyatini aniqlashi mumkin.
  • Hujjatlarni qayta ishlash: Markdown’ni bevosita qo‘llab-quvvatlaydi; ixtiyoriy bog‘liqliklar va tizim vositalari o‘rnatilgach, PDF, Office va OCR hujjatlarini tahlil qila oladi.
  • Strukturaviy bo‘laklash: oddiy matn uchun standart holatda 500 belgilik oyna va 60 belgilik ustma-ust tushishdan foydalanadi; aniqlangan jadvallar alohida bo‘laklarga ajratiladi hamda sarlavha, bo‘lim va manba kabi metama’lumotlar saqlanadi.
  • Biznes vositalari: buyurtmalar bo‘yicha namoyish vositalarini taqdim etadi, ruxsatlarni tekshirish, zaxira yo‘l, inson tasdig‘i va idempotentlik mexanizmlarini o‘z ichiga oladi, shuningdek MCP vositalariga ulanishi mumkin.
  • Muhandislik imkoniyatlari: sessiya xotirasini siqish, strukturaviy jurnallar, Prometheus ko‘rsatkichlari, holat tekshiruvi va avtomatlashtirilgan testlarni o‘z ichiga oladi.

Ishlash muhitini tayyorlash

Asosiy talablar

  • Python 3.11 yoki undan yuqori versiya.
  • Web frontend’ni ishga tushirish uchun Node.js 20.19+ yoki 22.12+ hamda npm kerak.
  • Standart mahalliy rejim SQLite va xotiradagi qidiruv komponentlaridan foydalanadi; Docker’ni oldindan ishga tushirish talab etilmaydi.

Windows PowerShell’da o‘rnatish bosqichlari

Repository’ni klonlab, loyiha ildiz katalogiga kirgach, virtual muhit yarating, ishlab chiqish bog‘liqliklarini o‘rnating, konfiguratsiya faylidan nusxa oling va namoyish ma’lumotlarini yarating:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
Copy-Item .env.example .env
.\.venv\Scripts\python.exe -m scripts.seed_demo

Agar loyiha ildiz katalogida .env allaqachon mavjud bo‘lsa, asl faylni saqlang va nusxalash buyrug‘ini o‘tkazib yuboring. Keyin FastAPI’ni ishga tushiring:

.\.venv\Scripts\python.exe -m uvicorn app.asgi:app --reload --host 127.0.0.1 --port 8000

macOS va Linux

macOS yoki Linux’da virtual muhit yaratib, uni faollashtiring va tegishli o‘rnatish buyruqlarini bajaring:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
python -m scripts.seed_demo
python -m uvicorn app.asgi:app --reload --host 127.0.0.1 --port 8000

Modellar va mahalliy xizmatlarni sozlash

Loyiha ildiz katalogidagi .env faylini oching. Quyidagi sozlamalarni avvalo tekshirish tavsiya etiladi:

  • DEEPSEEK_API_KEY: DeepSeek ish jarayoni va standart niyat tasnifini yoqadi. Haqiqiy API chaqiruvlari haq olishi mumkin.
  • INTENT_BACKEND: standart deepseek yoki ixtiyoriy jev qiymatiga o‘rnatilishi mumkin.
  • JEV_API_KEY: Jev niyat tasnifini yoqishda kerak bo‘ladi.
  • JEV_MODEL: loyihaning joriy standart qiymati jev-1.13.0.
  • DATABASE_URL: standart holatda sqlite+aiosqlite:///./data/local/app.db ishlatiladi.
  • KNOWLEDGE_DIR: standart qiymati knowledge; undagi bilim hujjatlari ishga tushirish vaqtida bazaga kiritiladi.
  • LOCAL_EMBEDDING_ENABLED: mahalliy semantik vektor funksiyasini boshqaradi.
  • CROSS_ENCODER_ENABLED: mahalliy qayta saralash funksiyasini boshqaradi.
  • REDIS_URL va QDRANT_URL: ixtiyoriy tashqi kesh va vektor xizmatlarini sozlaydi.

DeepSeek kaliti sozlanmasa ham, tizim oflayn namoyish mantig‘idan foydalanishi mumkin, biroq uning javob sifati haqiqiy model rejimidan farq qiladi. O‘zgaruvchilarning to‘liq ro‘yxatini konfiguratsiya ma’lumotnomasi va namunaviy muhit fayli orqali ko‘rish mumkin.

React chat interfeysini ishga tushirish

Backend jarayonini ishlayotgan holatda qoldirib, boshqa terminalda frontend katalogiga kiring:

cd frontend
npm ci
npm run dev

http://127.0.0.1:5173 manziliga kirsangiz, chat sahifasi ochiladi. Ishlab chiqish serveri /api so‘rovlarini mahalliy 8000-portga yo‘naltiradi.

Frontend manba havolalari, mahalliy sessiyalar ro‘yxati va amalni tasdiqlash kartalarini qo‘llab-quvvatlaydi. Backend javob tekshirilgach, mazmunni SSE orqali bo‘laklarga ajratib yuboradi. npm run build orqali frontend/dist yaratilsa, FastAPI ushbu katalogni aniqlab, frontend sahifasini ildiz yo‘ldan taqdim etadi.

Asosiy foydalanish: qaytarish va almashtirish siyosati bo‘yicha maslahat

Avval xizmat holatini tekshiring:

Quyida PowerShell yordamida bir nechta siyosat shartlarini o‘z ichiga olgan savolni chat interfeysiga yuboramiz:

$payload = @{
    message = "定制马克杯过了七天，但是有质量问题，可以退吗？"
    user_id = "u_demo"
} | ConvertTo-Json

Invoke-RestMethod `
    -Uri "http://127.0.0.1:8000/api/v1/chat" `
    -Method Post `
    -ContentType "application/json; charset=utf-8" `
    -Body ([System.Text.Encoding]::UTF8.GetBytes($payload))

Tizim avval qaytarish va almashtirishga oid niyatni aniqlaydi, so‘ng savol murakkabligiga qarab siyosat hujjatlarini qidirish kerak yoki kerak emasligini belgilaydi. Dastlabki dalil yetarli bo‘lmasa, ish jarayoni so‘rovni qayta yozib, qo‘shimcha qidiruvni bajarishi mumkin; javob yaratilgach, uning qidirilgan dalillarga sodiqligi ham tekshiriladi va mavjud manba havolalari qaytariladi.

HTTP API’dan tashqari, backend ishlayotgan paytda quyidagi buyruq orqali terminal mijozidan ham foydalanish mumkin:

python -m app.cli

Asosiy foydalanish: namoyish buyurtmalarini qidirish va boshqarish

scripts.seed_demo namoyish buyurtmalarini aniq yaratadi. API ishga tushirilganda bu ma’lumotlar avtomatik yozilmaydi, shuning uchun birinchi ishga tushirishda ma’lumotlarni boshlang‘ich holatga keltirishni o‘tkazib yubormang. Namoyish foydalanuvchisi u_demo, mavjud buyurtmalar:

  • ORD10001: jo‘natilgan, mahsulot shovqinni kamaytiruvchi quloqchin.
  • ORD10002: qabul qilib olingan, mahsulot maxsus tayyorlangan krujka.
  • ORD10003: to‘langan, ammo hali jo‘natilmagan, mahsulot futbolka.

Masalan, chat sahifasiga 取消订单 ORD10003 kiriting. Tasdiqlashni talab qiladigan amal bajarilganda tizim pending_action qaytarishi mumkin. Tasdiqlash so‘rovida javobdagi session_id albatta yuborilishi, pending_action.action_id esa confirm_action_id ichiga joylashtirilishi kerak. Web sahifasi bu jarayonni yakunlashga yordam beradigan tasdiqlash kartasidan foydalanadi.

Tasdiqlash kutilayotgan amallar standart holatda server jarayoni ichida 15 daqiqa saqlanadi. Xizmat qayta ishga tushirilsa yoki so‘rov boshqa jarayonga o‘tsa, amalni qaytadan boshlash talab qilinishi mumkin. Maydonlar va interfeys formatlari uchun API ma’lumotnomasiga murojaat qiling.

Kengaytirilgan sozlama: Jev niyatni aniqlashni yoqish

Niyat tasniflash tugunini TypeSafe Jev’ga o‘tkazish uchun mahalliy .env fayliga quyidagi sozlamalarni qo‘shing yoki o‘zgartiring:

INTENT_BACKEND=jev
JEV_API_KEY=your_jev_api_key
JEV_ENDPOINT=https://api.typesafe.ai/v1/systemone
JEV_MODEL=jev-1.13.0
JEV_TIMEOUT_SECONDS=10
JEV_MAX_RETRIES=2
JEV_INTENT_APPLY_OVERLAY=true

DEEPSEEK_API_KEY=your_deepseek_api_key

Saqlagach, backend’ni qayta ishga tushiring. Jev HTTP interfeysi orqali ulanadi va maxsus SDK o‘rnatishni talab qilmaydi. Qaytarilgan natija Pydantic yordamida tekshiriladi, so‘ng yagona tasnif natijasiga aylantiriladi.

Jev kaliti mavjud bo‘lmasa, so‘rov muvaffaqiyatsiz tugasa yoki javob noto‘g‘ri bo‘lsa, tizim avvalgi IntentClassifier’ga qaytadi. Qaytish zanjirida avval sozlangan DeepSeek ishlatiladi; oflayn rejimda yoki model chaqiruvi muvaffaqiyatsiz bo‘lganda esa qoidalar asosidagi tasnifdan foydalanish davom ettiriladi. Qayta urinish mumkin bo‘lgan xatolar eksponensial kechikish bilan qayta ishlanadi va joriy amalga oshirishda JEV_MAX_RETRIES maksimal urinishlar sonini bildiradi.

JEV_INTENT_APPLY_OVERLAY Jev muvaffaqiyatli tasniflagandan keyingi qoidaviy tuzatishni boshqaradi va standart holatda yoqilgan. Ushbu parametr qaytish tasniflagichining o‘z qoplama qatlamini boshqarmaydi. Standart niyat tasnifiga qaytish uchun INTENT_BACKEND qiymatini yana deepseek ga o‘zgartirish kifoya.

Kengaytirilgan sozlamalar: qidiruv va hujjatlarni tahlil qilishni kuchaytirish

Mahalliy vektor va qayta saralash bog‘liqliklarini o‘rnatish

.\.venv\Scripts\python.exe -m pip install -e ".[rerank]"

rerank bog‘liqliklari mahalliy zich vektor modeli va Cross-Encoder uchun ishlatiladi. Standart vektor modeli BAAI/bge-small-zh-v1.5, standart qayta saralash modeli esa BAAI/bge-reranker-base. Birinchi yuklashda model og‘irliklari yuklab olinishi mumkin; model mavjud bo‘lmaganda tizim zaxira rejimiga o‘tadi, shuning uchun natija to‘liq model sozlamalariga teng bo‘lmaydi.

Kengaytirilgan hujjatlarni tahlil qilish bog‘liqliklarini o‘rnatish

.\.venv\Scripts\python.exe -m pip install -e ".[docs]"

docs bog‘liqliklari Unstructured hujjatlarni tahlil qilish uchun ishlatiladi. PDF, OCR va Office fayllarini qayta ishlashda Poppler, Tesseract va xitoy tili paketlari, shuningdek LibreOffice ham o‘rnatilishi kerak bo‘lishi mumkin. Batafsil talablar Tahlil qilish va qidiruv qo‘llanmasida keltirilgan.

Bilim bo‘laklari IDʼsi hujjat yo‘li va bo‘lak tartib raqami asosida hosil qilinadi. Yo‘l va bo‘lish natijasi o‘zgarmasa, qayta indekslashda ID bir xil qolishi mumkin; fayl ko‘chirilgach, mazmun tahrirlangach yoki bo‘laklash strategiyasi o‘zgargach, tarixiy havolalar ayni mazmunga yo‘naltirilishi kafolatlanmaydi.

To‘liq xizmatni Docker yordamida ishga tushirish

API, PostgreSQL, Redis, Qdrant va yig‘ilgan Web frontendini bir vaqtda ishga tushirmoqchi bo‘lsangiz, avval mahalliy .env faylini tayyorlang, so‘ng quyidagini bajaring:

docker compose up --build

Ishga tushgach, http://127.0.0.1:8000 manziliga kiring. Composeʼdagi ma’lumotlar bazasi paroli va port xaritalari faqat mahalliy namoyish uchun mo‘ljallangan. Internetga joylashtirishdan oldin namoyish parollarini almashtirish, ma’lumotlar bazasi va kesh portlarini cheklash, ishonchli autentifikatsiya hamda TLSʼni yoqish, shuningdek ishonchli saqlash va ekspluatatsiya rejasini ishlab chiqish shart.

Testlar, statik tekshiruv va baholash

Backend testlari va sifat tekshiruvlarini loyiha ildiz katalogida bajaring:

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check app eval tests
.\.venv\Scripts\python.exe -m mypy
.\.venv\Scripts\python.exe -m eval.runner --task retrieval

Frontend testlari va yig‘ish buyruqlari frontend katalogida bajarilishi kerak:

npm test
npm run build

Test sozlamalari mahalliy model kalitlarini ajratadi va test ma’lumotlar bazasidan foydalanadi. Haqiqiy model baholashini alohida ishga tushirishdan oldin model va tarmoq sozlamalarini tekshiring, chunki tashqi modellarga murojaat qilish xarajat keltirishi mumkin.

Jev va DeepSeek maqsad tasnifini taqqoslash

Ikki model uchun mahalliy kalitlarni sozlagach, bir xil namunalar va bir xil qoplama shartlarida taqqoslashni ishga tushirishingiz mumkin:

.\.venv\Scripts\python.exe -m eval.compare_intent --backend both --limit 10 --no-overlay --output data/local/intent-comparison.json

Hisobotda aniqlik, P50 va P95 kechikishlari, zaxira rejimiga o‘tishlar soni hamda qoidalar qoplamasi soni keltiriladi. --no-overlay ikkala tasniflagichdagi qoidaviy tuzatishni o‘chiradi va modelning o‘z tasniflash natijalarini kuzatishni osonlashtiradi; bu parametr olib tashlansa, qoplama qo‘shilgandan keyingi natijalarni taqqoslash mumkin.

Joriy maqsadlar ma’lumotlar to‘plami ishlab chiqish to‘plamidir, aniqlik zaxira rejimidagi namunalarni ham o‘z ichiga oladi va uni Jev mustaqil modelining umumlashtirish qobiliyati sifatida to‘g‘ridan-to‘g‘ri talqin qilib bo‘lmaydi. Avvalgi baholashlar joriy versiya qayta tekshirilganini anglatmaydi va haqiqiy biznes natijalarining kafolati hisoblanmaydi.

Amaliy muhandislik tavsiyalari

  1. Avval standart mahalliy rejimda jarayonni tekshiring: SQLite va xotiradagi qidiruv komponentlari asosiy namoyish uchun yetarli, tashqi ma’lumotlar bazasi va vektor xizmatlarini darhol joylashtirish shart emas.
  2. Maqsad modelini ish jarayoni modelidan ajrating: Jevʼga o‘tish boshqa DeepSeek tugunlarini almashtirmaydi. To‘liq onlayn ish jarayonini ishga tushirish uchun baribir DeepSeekʼni sozlash kerak.
  3. Muammolarni sog‘liq interfeyslari orqali aniqlang:/api/v1/health jarayonni tekshirish uchun, /api/v1/ready esa bog‘liqliklar tayyorligini tasdiqlash uchun mosroq.
  4. Bo‘laklash strategiyasini ehtiyotkorlik bilan o‘zgartiring: yo‘l, matn mazmuni yoki bo‘laklash parametrlari o‘zgarishi bo‘lak IDʼsi va tarixiy havolalarga ta’sir qilishi mumkin.
  5. Jarayon ichidagi tasdiqlash holatiga tayanmang: standart kutilayotgan tasdiqlash operatsiyalari atigi 15 daqiqa amal qiladi va qayta ishga tushirish yoki ko‘p jarayonli almashish sabab yo‘qolishi mumkin.
  6. Maxfiy ma’lumotlarni himoyalang: .env, haqiqiy kalitlar, mahalliy ma’lumotlar bazasi, jurnallar, foydalanuvchi yuklagan hujjatlar yoki shaxsiy materiallarni GitHubʼga yubormang.
  7. Tashqi ma’lumot uzatishni tekshiring: tashqi model yoki masofaviy MCPʼdan foydalanishdan oldin so‘rov mazmunida tashqariga yuborilmasligi kerak bo‘lgan foydalanuvchi ma’lumotlari yo‘qligini tasdiqlang.
  8. Bilim bazasini yangilashni rejalashtiring: joriy tizim ishga tushganda barcha ma’lumotlarni to‘liq indekslaydi, to‘liq qo‘shimcha o‘chirish jarayoni hali taqdim etilmagan.

Loyiha kataloglariga qisqacha nazar

  • app/api: HTTP API va SSE.
  • app/agents: LangGraph ijro grafigi va ish jarayoni tugunlari.
  • app/retrieval: tahlil qilish, bo‘laklash, qaytarish, birlashtirish va qayta saralash.
  • app/providers: model va vektor xizmatlari adapterlari.
  • app/tools: biznes vositalari, vositalarni ro‘yxatdan o‘tkazish va ruxsatlarni boshqarish.
  • app/mcp: MCP vositalarini ulash.
  • app/memory: sessiya xotirasi va siqish.
  • app/guardrails: kiritish va javoblarni tekshirish.
  • app/observability: jurnallar va ko‘rsatkichlar.
  • frontend: React va TypeScript asosidagi chat interfeysi.
  • knowledge: siyosatga oid bilim hujjatlari.
  • tests va eval: avtomatlashtirilgan testlar, baholash ma’lumotlari va ishga tushiruvchi modul.

Xulosa

Adaptive-RAG elektron tijorat mijozlarga xizmat ko‘rsatish loyihasi aqlli mijozlarga xizmat ko‘rsatishning nisbatan to‘liq muhandislik zanjirini namoyish etadi: avval maqsad va murakkablik aniqlanadi, so‘ng zaruratga ko‘ra aralash qidiruv, ko‘p bosqichli dalil to‘ldirish, vositalardan foydalanish, inson tasdig‘i va sodiqlik tekshiruvi birlashtiriladi. Avval SQLite, namoyish buyurtmalari va oflayn mantiqdan foydalanib tezda sinab ko‘rishingiz, keyin esa DeepSeek, Jev, mahalliy vektor modeli, Cross-Encoder, kengaytirilgan hujjatlarni tahlil qilish va Docker xizmatlarini bosqichma-bosqich yoqishingiz mumkin.

Haqiqiy biznesga joriy etishdan oldin autentifikatsiya, haqiqiy buyurtmalar tizimi bilan integratsiya, tasdiqlash holatini doimiy saqlash, bilim bazasini bosqichma-bosqich yangilash, kalitlarni boshqarish va ishlab chiqarish darajasidagi tarmoq xavfsizligini to‘ldirish kerak. Loyiha MIT License asosida tarqatiladi; arxitektura va cheklovlar haqidagi qo‘shimcha ma’lumotni Arxitektura va ish jarayoni, Qidiruv dizayni hamda Cheklovlar va yo‘l xaritasidan ko‘rishingiz mumkin.