Yakha Futhi Usebenzise Isizindalwazi Solwazi Samafayela Sasekhaya nge-FastAPI, SQLite, ne-MCP

Uhlolojikelele

Isigaba 1 se-Knowledge Base siyisisekelo solwazi samafayela esisebenzayo esincane, esakhiwe nge-FastAPI, SQLite, kanye nokugcinwa kwamafayela kusistimu yendawo. Sisekela ukuphathwa kwemibhalo okuqinisekisiwe, amafolda ahlelekile, ukubuka kuqala okugcinwa esipheqululini sendawo, imethadatha namathegi, amathuluzi omlawuli, ulwazi lokucwaninga, kanye nokufinyelela kokufunda kuphela kwama-ejenti e-AI nge-Model Context Protocol, noma i-MCP.

Lesi sigaba senziwe saba lula ngamabomu. Asidingi i-Docker, i-PostgreSQL, i-MinIO, i-LibreOffice, i-ONLYOFFICE, noma enye isevisi yesizindalwazi esebenzayo. I-PostgreSQL nokugcinwa kwezinto kugcinelwe ukuthuthela esigabeni esizayo.

Lokho okunikezwa yiphrojekthi

• Abasebenzisi abadalwe umlawuli, ukungena ngemvume, nokuqinisekiswa kwe-JWT.
• Izisekelo zolwazi zomphakathi ezinamafolda ahlelekile nokuzulazula kwe-breadcrumb.
• Ukufakwa kuhlu kwemibhalo okuqondene nefolda, ukulayishwa kwefayela elilodwa, nokulayishwa kwamaqoqo.
• Ukusekelwa kwamafayela e-PDF, umbhalo, i-Markdown, i-HTML, izithombe, i-PowerPoint, i-Word, ne-Excel.
• Imethadatha yemibhalo, amathegi, ulwazi lomnikazi nolomlayishi.
• Ukubuka kuqala nokulanda ifayela lokuqala.
• Ukufunda ngaphakathi kohlelo kwemibhalo ye-text, Markdown, PDF, DOCX, XLSX, PPTX, kanye nezithombe.
• Ukukhishwa kombhalo okusemandleni akhona kwamafayela amadala e-DOC, XLS, ne-PPT.
• Ukuhlelwa kwemibhalo ngumnikazi kuphela, ukususwa okuthambile, ukubuyiselwa, ukuqanjwa kabusha kwamafolda, nokususwa kwamafolda angenalutho.
• Umgqomo wokuphinda usebenzise wemibhalo esusiwe.
• Ukukopishwa kwemibhalo namafolda phakathi kwezindawo ezahlukene, okuhlanganisa amakhophi amafolda aphindaphindayo nokuphindwa kokugcinwa ngokomzimba.
• Ukuphathwa kwabasebenzisi, amalogi ocwaningo, namalogi okubizwa kwe-MCP okwenziwa umlawuli kuphela.
• I-REST API yokufunda kuphela, imibhalo ye-OpenAPI ekhiqiziwe, nokuhlanganiswa kwe-MCP.

Indlela okusebenza ngayo ukugcinwa

Uhlelo lwakha amafayela esikhathi sokusebenza ngaphansi kwe-backend/data/. Isizindalwazi se-SQLite sigcinwa njenge-backend/data/knowledge_base.db, kanti amafayela alayishiwe namafayela e-Markdown akhiqiziwe abekwa ngaphansi kwe-backend/data/storage/.

Ukugcinwa kwasendaweni kuhlanganisa ukuvikelwa ekudluleni kwezindlela zamafayela. Ukucushwa okukhona kwe-Docker Compose kuhloselwe ukuthuthela kamuva ku-PostgreSQL nasekugcinweni kwezinto, futhi akudingeki kulesi sigaba.

Faka i-backend

1. Dala ifayela lendawo

Vula i-PowerShell, ungene enkombeni ye-backend yendawo yokugcina ikhodi, bese ukopisha ithempulethi yendawo esempandeni uye ku-backend/.env.

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

Izilungiselelo zokusebenza zichazwa nge-.env.example, backend/app/core/config.py, kanye namafayela okulawula e-PowerShell angaphansi kwe-scripts/.

2. Dala indawo ebonakalayo ye-Python

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

Sebenzisa le miyalo usuka enkombeni ye-backend. Ukwenza indawo ebonakalayo isebenze kugcina amaphakheji ephrojekthi ehlukene nokufakwa kwakho kwe-Python komhlaba wonke.

3. Qalisa i-SQLite

python -m app.db.init_db

Lo myalo uqalisa noma udala kabusha amathebula e-SQLite adingekayo. Njengoba ukudala kabusha amathebula kungathinta idatha ekhona, sebenzisa lokhu ngokuqapha ngemva kokuba usuqale ukugcina imibhalo.

4. Qalisa i-FastAPI

uvicorn app.main:app --reload

Iseva yokuthuthukisa izobe isitholakala ku-http://127.0.0.1:8000. Inketho ye---reload ilayisha kabusha uhlelo ngokuzenzakalelayo lapho amafayela omthombo eshintsha.

5. Vula imibhalo ye-API

Vakashela ku-http://127.0.0.1:8000/docs ukuze uhlole futhi uzame ama-endpoint e-OpenAPI akhiqiziwe.

Qinisekisa ukufakwa

Ukuhlola kudinga ukuthi inkomba ye-backend ibe ku-PYTHONPATH. Ku-Windows Command Prompt, sebenzisa:

set PYTHONPATH=.
python -m pytest

Ku-PowerShell, sebenzisa:

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

Indawo yokugcina ikhodi iphinde inikeze ngamafayela okulawula e-PowerShell ahlukene angaphansi kwe-scripts/ okuqalisa, ukuqala kabusha, ukumisa, nokubheka isimo samasevisi.

Qinisekisa nge-REST API

Abasebenzisi badalwa umlawuli. Uma usune-akhawunti, thumela igama layo lomsebenzisi nephasiwedi ku-endpoint yokungena. Impendulo iqukethe ithokheni edingekayo ezicelweni eziqinisekisiwe.

$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

Kopisha ithokheni yokufinyelela ebuyisiwe bese uyisebenzisa njengemininingwane ye-Bearer. Izimvume zethokheni zilandela ubuwena nendima yomsebenzisi oqinisekisiwe.

Layisha umbhalo

I-endpoint yokulayisha yamukela idatha yefomu ye-multipart. Nikeza nge-ID yesisekelo solwazi, amathegi ozikhethela wona, ifayela, kanye nethokheni ye-Bearer:

$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"

Iphrojekthi isekela kokubili ukulayishwa ngakunye nokulayishwa kwamaqoqo. Amafayela okuqala alayishiwe ahlala ekugcinweni kwasendaweni, kanti okuqukethwe okusekelwayo kungavulwa kumfundi ongaphakathi kohlelo.

Dala futhi usebenzise amafolda

Dala ifolda ngokuthumela i-ID yesisekelo solwazi negama layo ku-endpoint yamafolda:

$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

Ukuze ulayishe kufolda ethile, engeza i-folder_id efomini lokulayisha le-multipart. Isixhumi esibonakalayo sewebhu siyengeza ngokuzenzakalelayo lapho kukhethwa ifolda.

Isikhethi sesisekelo solwazi siqala ngokuzenzakalela ku-全部, okusho ukuthi “konke.” Lokhu kubuka kubonisa amadokhumenti nez folda eziyizimpande kuzo zonke izisekelo zolwazi zomphakathi. Lapho udala ifolda, khetha isisekelo solwazi okuyiwa kuso ebhokisini lengxoxo. Ukulayisha okwenziwa ekubukeni kwazo zonke izisekelo zolwazi kusebenzisa isisekelo solwazi sokuqala esitholakalayo ngaphandle kokuthi kukhethwe ifolda.

Qonda ukubuka kuqala kwasendaweni yesiphequluli

I-frontend ilanda amafayela nge-API egunyaziwe, iwagcine enkumbulweni yesiphequluli, bese iwabonisa endaweni. Isebenzisa i-vue3-office-preview kuma-DOCX, PPTX, XLS, nama-XLSX, i-@vue3-office/vue-pdf kuma-PDF, kanye ne-@deot/docs-markdown kuma-Markdown. Ukuboniswa kwe-PPTX kusebenzisa i-pptx-renderer efakiwe.

Le ndlela ayidingi i-LibreOffice, i-ONLYOFFICE, i-Docker, noma i-Python SDK yokubuka kuqala amadokhumenti. Ifayela lokuqala lihlala kwisitoreji sasendaweni. Ukukhishwa kwe-Markdown nokucutshungulwa kokubuyela emuva kwamafayela amadala e-.doc, .xls, ne-.ppt kusalokhu kuwumthwalo we-backend.

Xhuma i-ejenti ye-AI nge-MCP

Indawo yokugcina ikhodi ihlanganisa isevisi ye-MCP ehlukile efundwayo kuphela. Yabelana ngesizindalwazi se-SQLite sohlelo lwe-FastAPI, isitoreji sasendaweni, imfihlo ye-JWT, nesifundi samadokhumenti. Amathuluzi eSigaba 1 atholakalayo yilawa:

• list_knowledge_bases
• list_documents
• search_knowledge
• get_document
• get_document_metadata

Inqubo ye-MCP ayikwazi ukulayisha, ukuhambisa, ukususa, noma ukuphatha amafolda. Ukufinyelela kwayo kumadokhumenti kukhawulelwe kulokho umsebenzisi ohlobene nayo avunyelwe ukukufunda.

Faka okuncikile kwe-MCP

Dala indawo ebonakalayo ezinikele ye-MCP usuka ku-backend:

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

Qalisa i-MCP nge-input ne-output ejwayelekile

Hlela inqubo ye-MCP isebenzise izilungiselelo ezifanayo zesizindalwazi nesitoreji njenge-API. Faka ithokheni yokungena ngemvume ku-KB_MCP_TOKEN, bese uqala iseva:

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

Kumaklayenti endawo e-stdio, i-KB_MCP_TOKEN ingashiywa ingafakwanga. Kuleso simo, i-ejenti kufanele ibize ithuluzi le-authenticate kanye nemininingwane yegama lomsebenzisi nephasiwedi yomsebenzisi. Iseshini yesikhashana evelayo iba khona kuphela enkumbulweni yenqubo ye-MCP.

Ungangezi amakholi ajwayelekile e-print() kusevisi ye-stdio MCP. I-standard output iphethe imiyalezo yephrothokholi, ngakho ukuxilonga kufanele kubhalelwe ku-standard error.

Qalisa ukuhlolwa kwe-MCP smoke

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

Veza i-MCP nge-Streamable HTTP

Setha ezokuthutha, ikheli lokulalela, imbobo, indlela, nemodi engenasimo ngaphambi kokuqala le moduli efanayo ye-MCP:

$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

Ngemva kokulungisa i-reverse proxy ye-HTTPS, i-endpoint yomphakathi ingaba yi-https://your-domain/mcp. Amaklayenti akude kufanele athumele i-Authorization: Bearer <access_token> futhi kufanele asebenzise imininingwane efanayo evikelwe ye-Bearer esetshenziswa ukuxhuma ku-API.

Ikhasi lesiphequluli elithi /mcp-token.html lingacela i-MCP Token ye-akhawunti engene ngemvume ngaphandle kokufunda noma ukugcina iphasiwedi yayo. Abaphathi bangasebenzisa i-/admin.html ukuphatha isimo sabasebenzisi, izindima, amaphasiwedi, nezinqubomgomo zokuphelelwa isikhathi zama-MCP Token zomsebenzisi ngamunye, kuhlanganise nama-Token ahlala isikhathi eside.

Amathiphu okusebenza athuthukile

• Gcina izilungiselelo ze-API ne-MCP zihambisana. Zombili lezi zinsizakalo kufanele zikhombe kusizindalwazi esifanayo se-SQLite nezindlela zesitoreji ezifanayo futhi zisebenzise imfihlo efanayo ye-JWT.
• Sebenzisa ubunikazi obunamalungelo amancane. I-ejenti ye-MCP izuza ububanzi bokufunda amadokhumenti bomsebenzisi wethokheni yayo.
• Vikela ama-Bearer token. Ungafaki imininingwane ye-API noma ye-MCP ekulawuleni ikhodi, kumalogi, noma kokuphumayo kwekhonsoli okujwayelekile.
• Gcina iphrothokholi ye-stdio. Thumela ukuxilonga kwe-MCP ku-standard error esikhundleni se-standard output.
• Sebenzisa i-HTTPS ukude. Beka i-Streamable HTTP endpoint ngemuva kwe-reverse proxy ye-HTTPS ngaphambi kokuyiveza ngaphandle komshini wendawo.
• Khumbula imingcele yeSigaba 1. I-Docker Compose, i-PostgreSQL, nesitoreji sezinto kuyizinhloso zokuthuthela kwenye ingqalasizinda, hhayi izidingo zesikhathi samanje sokusebenza.
• Buyekeza imikhawulo yobunikazi. Ukuhlela amadokhumenti, ukuwasusa kancane, ukuwabuyisela, ukuqamba kabusha amafolda, nokususa amafolda angenalutho yimisebenzi yomnikazi kuphela.
• Sebenzisa imibhalo ye-API ekhiqiziwe. Ikhasi le-/docs liyindlela eqondile kakhulu yokuhlola izinkambu zezicelo nezimpendulo ezitholakalayo ngaphezu kwezibonelo eziboniswe lapha.

Isiphetho

ISisekelo Solwazi Sesigaba 1 sihlinzeka ngesisekelo esisebenzayo sendawo sokuhlela amafayela ngokugunyaziwe, ukuwabuka kuqala, ukuwathola, nokufinyelela kwama-ejenti. Nge-Python, i-SQLite, nesitoreji sasendaweni kuphela, ungakwazi ukuqalisa isevisi, ulayishe amaqoqo amadokhumenti ahlelekile, uphathe amafolda nemethadatha, futhi uveze ngokuphepha amathuluzi olwazi afundwayo kuphela nge-stdio yasendaweni noma ezokuthutha ze-Streamable HTTP MCP ezikude.