FastAPI, SQLite va MCP yordamida mahalliy fayllar bilim bazasini yaratish va undan foydalanish

Umumiy ko‘rinish

Knowledge Base 1-bosqichi FastAPI, SQLite va mahalliy fayl tizimi xotirasi asosida yaratilgan, amalda foydalanish uchun yetarli bo‘lgan minimal fayl bilim bazasidir. U autentifikatsiya qilingan hujjatlarni boshqarish, ichma-ich papkalar, brauzerda mahalliy ko‘rish, metama’lumotlar va teglar, administrator vositalari, audit ma’lumotlari hamda Model Context Protocol yoki MCP orqali AI agentlari uchun faqat o‘qish huquqidagi kirishni qo‘llab-quvvatlaydi.

Bu bosqich ataylab yengil tuzilgan. Unda Docker, PostgreSQL, MinIO, LibreOffice, ONLYOFFICE yoki ishlayotgan boshqa ma’lumotlar bazasi xizmati talab qilinmaydi. PostgreSQL va obyekt xotirasi keyingi migratsiya uchun qoldirilgan.

Loyiha nimalarni taqdim etadi

• Administrator tomonidan yaratiladigan foydalanuvchilar, tizimga kirish va JWT autentifikatsiyasi.
• Ichma-ich papkalar va navigatsiya yo‘li mavjud ochiq bilim bazalari.
• Papka doirasida hujjatlar ro‘yxati, bitta faylni yuklash va ommaviy yuklash.
• PDF, matn, Markdown, HTML, rasmlar, PowerPoint, Word va Excel fayllarini qo‘llab-quvvatlash.
• Hujjat metama’lumotlari, teglar, egasi va yuklovchisi haqidagi ma’lumotlar.
• Asl faylni ko‘rish va yuklab olish.
• Matn, Markdown, PDF, DOCX, XLSX, PPTX va rasmlarni ilova ichida o‘qish.
• Eski DOC, XLS va PPT fayllari uchun imkon qadar matn ajratib olish.
• Faqat egasi uchun hujjatni tahrirlash, yumshoq o‘chirish, tiklash, papka nomini o‘zgartirish va bo‘sh papkani o‘chirish.
• O‘chirilgan hujjatlar uchun qayta ishlash qutisi.
• Doiralararo hujjat va papxalarni nusxalash, jumladan papkalarni rekursiv nusxalash va jismoniy xotira nusxasini yaratish.
• Faqat administrator uchun foydalanuvchilarni boshqarish, audit jurnallari va MCP chaqiruv jurnallari.
• Faqat o‘qish huquqidagi REST API, yaratilgan OpenAPI hujjatlari va MCP integratsiyasi.

Xotira qanday ishlaydi

Ilova ish vaqtiga oid fayllarni backend/data/ ichida yaratadi. SQLite ma’lumotlar bazasi backend/data/knowledge_base.db sifatida saqlanadi, yuklangan fayllar va yaratilgan Markdown fayllari esa backend/data/storage/ ichiga joylashtiriladi.

Mahalliy xotira yo‘l bo‘ylab kataloglardan tashqariga chiqishni himoyalashni o‘z ichiga oladi. Mavjud Docker Compose konfiguratsiyasi keyingi PostgreSQL va obyekt xotirasiga migratsiya uchun mo‘ljallangan bo‘lib, bu bosqichda kerak emas.

Backendni o‘rnatish

1. Muhit faylini yarating

PowerShell dasturini oching, repositoryning backend katalogiga kiring va asosiy muhit shablonini backend/.env fayliga nusxalang.

cd backend
Copy-Item ..\.env.example .env

Operatsion sozlamalar .env.example, backend/app/core/config.py va scripts/ ichidagi PowerShell boshqaruv fayllari orqali belgilanadi.

2. Python virtual muhitini yarating

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Bu buyruqlarni backend katalogidan ishga tushiring. Virtual muhitni faollashtirish loyiha paketlarini global Python o‘rnatmangizdan alohida saqlaydi.

3. SQLite-ni ishga tushiring

python -m app.db.init_db

Bu buyruq kerakli SQLite jadvallarini ishga tushiradi yoki qayta yaratadi. Jadvallarni qayta yaratish mavjud ma’lumotlarga ta’sir qilishi mumkinligi sababli, hujjatlarni saqlashni boshlaganingizdan keyin bu amalni ehtiyotkorlik bilan bajaring.

4. FastAPI-ni ishga tushiring

uvicorn app.main:app --reload

Shundan so‘ng ishlab chiqish serveri http://127.0.0.1:8000 manzilida mavjud bo‘ladi. --reload parametri manba fayllari o‘zgarganda ilovani avtomatik ravishda qayta yuklaydi.

5. API hujjatlarini oching

Yaratilgan OpenAPI endpointlarini ko‘rish va sinab ko‘rish uchun http://127.0.0.1:8000/docs manziliga kiring.

O‘rnatishni tekshiring

Testlar uchun backend katalogi PYTHONPATHda bo‘lishi kerak. Windows Command Prompt dasturida quyidagilarni bajaring:

set PYTHONPATH=.
python -m pytest

PowerShell dasturida esa quyidagilardan foydalaning:

$env:PYTHONPATH = "."
python -m pytest

Repository shuningdek xizmatni ishga tushirish, qayta ishga tushirish, to‘xtatish va holatini tekshirish uchun scripts/ katalogida alohida PowerShell boshqaruv fayllarini taqdim etadi.

REST API orqali autentifikatsiyadan o‘ting

Foydalanuvchilar administrator tomonidan yaratiladi. Hisobingiz mavjud bo‘lgach, uning foydalanuvchi nomi va parolini tizimga kirish endpointiga yuboring. Javobda autentifikatsiya qilingan so‘rovlar uchun kerak bo‘ladigan token mavjud.

$body = @{
  username = "demo"
  password = "password-123"
} | ConvertTo-Json

$response = Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:8000/api/v1/auth/login `
  -ContentType "application/json" `
  -Body $body

$response

Qaytarilgan kirish tokenidan nusxa oling va undan Bearer hisob ma’lumoti sifatida foydalaning. Token ruxsatlari autentifikatsiyadan o‘tgan foydalanuvchining shaxsi va roliga bog‘liq.

Hujjat yuklang

Yuklash endpointi multipart forma ma’lumotlarini qabul qiladi. Bilim bazasi ID raqami, ixtiyoriy teglar, fayl va Bearer tokenini yuboring:

$token = "<access_token>"
$knowledgeBaseId = 1

curl.exe `
  -X POST `
  "http://127.0.0.1:8000/api/v1/documents/upload" `
  -H "Authorization: Bearer $token" `
  -F "knowledge_base_id=$knowledgeBaseId" `
  -F "tags=制度,测试" `
  -F "file=@D:\path\to\guide.txt"

Loyiha alohida va ommaviy yuklashlarni qo‘llab-quvvatlaydi. Yuklangan asl fayllar mahalliy xotirada saqlanadi, qo‘llab-quvvatlanadigan tarkib esa ilova ichidagi o‘quvchi orqali ochilishi mumkin.

Papkalarni yarating va ulardan foydalaning

Papka yaratish uchun uning bilim bazasi ID raqami va nomini papka endpointiga yuboring:

$body = @{
  knowledge_base_id = 1
  name = "实验方案"
} | ConvertTo-Json

Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:8000/api/v1/folders `
  -Headers @{ Authorization = "Bearer $token" } `
  -ContentType "application/json" `
  -Body $body

Muayyan papkaga yuklash uchun multipart yuklash formasiga folder_idni qo‘shing. Veb-interfeys papka tanlanganda uni avtomatik qo‘shadi.

Bilim bazasi selektori sukut bo‘yicha 全部 qiymatiga ega bo‘lib, “barchasi” degan ma’noni anglatadi. Bu ko‘rinish barcha ochiq bilim bazalaridagi ildiz hujjatlar va papkalarni ko‘rsatadi. Papka yaratishda muloqot oynasida uning manzil bilim bazasini tanlang. Barcha bilim bazalari ko‘rinishidan yuklangan fayl, agar papka tanlanmagan bo‘lsa, mavjud bilim bazalarining birinchisidan foydalanadi.

Brauzerda lokal ko‘rib chiqish qanday ishlashini tushuning

Frontend fayllarni autentifikatsiyadan o‘tgan API orqali oladi, ularni brauzer xotirasida saqlaydi va lokal ravishda ko‘rsatadi. DOCX, PPTX, XLS va XLSX uchun vue3-office-preview, PDF uchun @vue3-office/vue-pdf, Markdown uchun esa @deot/docs-markdown ishlatiladi. PPTX ko‘rsatilishi birga kiritilgan pptx-renderer orqali amalga oshiriladi.

Bu yo‘l LibreOffice, ONLYOFFICE, Docker yoki Python hujjatlarni ko‘rib chiqish SDKʼsini talab qilmaydi. Asl fayl lokal xotirada qoladi. Markdownʼni ajratib olish hamda eski .doc, .xls va .ppt fayllari uchun zaxira ishlov berish backend zimmasida qoladi.

MCP orqali AI agentini ulang

Repository alohida, faqat o‘qish uchun mo‘ljallangan MCP xizmatini o‘z ichiga oladi. U FastAPI ilovasining SQLite ma’lumotlar bazasi, lokal xotirasi, JWT siri va hujjat o‘quvchisi bilan birgalikda ishlaydi. 1-bosqichda mavjud vositalar:

• list_knowledge_bases
• list_documents
• search_knowledge
• get_document
• get_document_metadata

MCP jarayoni fayl yuklay, ko‘chira, o‘chira yoki papkalarni boshqara olmaydi. Unga hujjatlardan foydalanish faqat tegishli foydalanuvchi o‘qishga ruxsat berilgan doira bilan cheklangan.

MCP bog‘liqliklarini o‘rnating

backend katalogidan alohida MCP virtual muhitini yarating:

cd backend
python -m venv .mcp-venv
.\.mcp-venv\Scripts\python.exe -m pip install -r requirements-mcp.txt

MCPʼni standart kiritish va chiqarish orqali ishga tushiring

MCP jarayonini API bilan bir xil ma’lumotlar bazasi va xotira sozlamalari bilan sozlang. Kirish tokenini KB_MCP_TOKEN ga joylang, so‘ng serverni ishga tushiring:

$env:PYTHONPATH = "."
$env:KB_MCP_TOKEN = "<access_token>"
.\.mcp-venv\Scripts\python.exe -m app.mcp_server

Lokal stdio mijozlari uchun KB_MCP_TOKEN ni qoldirib ketish mumkin. Bunday holatda agent foydalanuvchi nomi va paroli bilan authenticate vositasini bir marta chaqirishi kerak. Natijada hosil bo‘ladigan qisqa muddatli sessiya faqat MCP jarayoni xotirasida mavjud bo‘ladi.

stdio MCP xizmatiga oddiy print() chaqiruvlarini qo‘shmang. Standart chiqish protokol xabarlarini uzatadi, shuning uchun diagnostika ma’lumotlari standart xatoga yozilishi kerak.

MCP smoke testini ishga tushiring

$env:PYTHONPATH = "."
.\.mcp-venv\Scripts\python.exe scripts\mcp_stdio_smoke.py

MCPʼni Streamable HTTP orqali taqdim eting

Xuddi shu MCP modulini ishga tushirishdan oldin transport, tinglash manzili, port, yo‘l va holatsiz rejimni sozlang:

$env:PYTHONPATH = "."
$env:MCP_TRANSPORT = "streamable-http"
$env:MCP_HOST = "0.0.0.0"
$env:MCP_PORT = "8020"
$env:MCP_PATH = "/mcp"
$env:MCP_STATELESS_HTTP = "true"
.\.mcp-venv\Scripts\python.exe -m app.mcp_server

HTTPS reverse proxy sozlangandan so‘ng ochiq endpoint https://your-domain/mcp bo‘lishi mumkin. Masofaviy mijozlar Authorization: Bearer <access_token> sarlavhasini yuborishi va API ulanishidagi kabi himoyalangan Bearer ma’lumotlaridan foydalanishi kerak.

/mcp-token.html brauzer sahifasi parolni o‘qimasdan yoki saqlamasdan, tizimga kirgan hisob uchun MCP tokenini so‘rashi mumkin. Administratorlar foydalanuvchi holati, rollari, parollari va har bir foydalanuvchi uchun MCP tokenining amal qilish siyosatini, jumladan doimiy uzoq muddatli tokenlarni, boshqarish uchun /admin.html dan foydalanishi mumkin.

Ilg‘or ekspluatatsiya maslahatlari

• API va MCP sozlamalarini mos holda saqlang. Har ikkala xizmat bir xil SQLite ma’lumotlar bazasi va xotira yo‘llariga yo‘naltirilishi hamda bir xil JWT siridan foydalanishi kerak.
• Eng kam imtiyozli identifikatsiyalardan foydalaning. MCP agenti token foydalanuvchisiga o‘qish mumkin bo‘lgan hujjatlar doirasini meros qilib oladi.
• Bearer tokenlarini himoya qiling. API yoki MCP ma’lumotlarini versiyalarni boshqarish tizimiga, jurnallarga yoki oddiy konsol chiqishiga joylashtirmang.
• stdio protokolini saqlang. MCP diagnostikasini standart chiqish o‘rniga standart xatoga yuboring.
• Masofaviy ulanishlarda HTTPSʼdan foydalaning. Streamable HTTP endpointini lokal mashinadan tashqariga ochishdan oldin uni HTTPS reverse proxy ortiga joylashtiring.
• 1-bosqich chegaralarini yodda tuting. Docker Compose, PostgreSQL va obyekt xotirasi hozirgi ishga tushirish talablari emas, balki migratsiya maqsadlaridir.
• Egalik cheklovlarini tekshiring. Hujjatlarni tahrirlash, yumshoq o‘chirish, tiklash, papka nomini o‘zgartirish va bo‘sh papkani o‘chirish faqat egasi bajarishi mumkin bo‘lgan amallardir.
• Yaratilgan API hujjatlaridan foydalaning. /docs sahifasi bu yerda keltirilgan misollardan tashqari mavjud so‘rov maydonlari va javoblarini tekshirishning eng bevosita usulidir.

Xulosa

Knowledge Base 1-bosqichi autentifikatsiyadan o‘tgan fayllarni tartibga solish, ko‘rib chiqish, olish va agentlardan foydalanish uchun amaliy lokal asosni taqdim etadi. Faqat Python, SQLite va lokal xotira yordamida xizmatni ishga tushirish, tuzilgan hujjatlar to‘plamlarini yuklash, papkalar va metama’lumotlarni boshqarish hamda faqat o‘qish uchun mo‘ljallangan bilim vositalarini lokal stdio yoki masofaviy Streamable HTTP MCP transporti orqali xavfsiz taqdim etish mumkin.