Jenga na Utumie Msingi wa Maarifa wa Faili za Ndani kwa FastAPI, SQLite na MCP

Muhtasari

Awamu ya 1 ya Knowledge Base ni hifadhidata ya faili ya maarifa inayoweza kutumika kwa kiwango cha chini, iliyojengwa kwa FastAPI, SQLite na hifadhi ya mfumo wa faili wa ndani. Inasaidia usimamizi wa hati ulio na uthibitishaji, folda zilizopangiliwa ndani ya nyingine, violezo vya hakikisho vya ndani ya kivinjari, metadata na lebo, zana za msimamizi, taarifa za ukaguzi, na ufikiaji wa kusoma pekee kwa mawakala wa AI kupitia Model Context Protocol, au MCP.

Awamu hii imeundwa kwa urahisi kimakusudi. Haihitaji Docker, PostgreSQL, MinIO, LibreOffice, ONLYOFFICE, au huduma nyingine ya hifadhidata inayoendesha. PostgreSQL na hifadhi ya vitu vimehifadhiwa kwa ajili ya uhamishaji wa baadaye.

Mradi unatoa nini

• Watumiaji wanaoundwa na msimamizi, kuingia, na uthibitishaji wa JWT.
• Misingi ya maarifa ya umma yenye folda zilizopangiliwa ndani ya nyingine na urambazaji wa breadcrumb.
• Uorodheshaji wa hati kulingana na folda, upakiaji wa faili moja, na upakiaji wa kundi.
• Msaada kwa faili za PDF, maandishi, Markdown, HTML, picha, PowerPoint, Word na Excel.
• Metadata za hati, lebo, taarifa za mmiliki na mpakiaji.
• Hakikisho na upakuaji wa faili asili.
• Kusoma ndani ya programu kwa maandishi, Markdown, PDF, DOCX, XLSX, PPTX na picha.
• Utoaji wa maandishi kwa kiwango kinachowezekana kwa faili za zamani za DOC, XLS na PPT.
• Uhariri wa hati unaoruhusiwa kwa mmiliki pekee, ufutaji laini, urejeshaji, kubadilisha jina la folda, na ufutaji wa folda tupu.
• Kikapu cha kuchakata tena kwa hati zilizofutwa.
• Kunakili hati na folda kati ya maeneo mbalimbali, ikijumuisha kunakili folda kwa kujirudia na kunakili hifadhi halisi.
• Usimamizi wa watumiaji unaoruhusiwa na msimamizi pekee, kumbukumbu za ukaguzi, na kumbukumbu za miito ya MCP.
• API ya REST ya kusoma pekee, nyaraka za OpenAPI zinazozalishwa, na ujumuishaji wa MCP.

Jinsi hifadhi inavyofanya kazi

Programu huunda faili za wakati wa utekelezaji chini ya backend/data/. Hifadhidata ya SQLite huhifadhiwa kama backend/data/knowledge_base.db, huku faili zilizopakiwa na faili za Markdown zinazozalishwa zikiwekwa chini ya backend/data/storage/.

Hifadhi ya ndani ina ulinzi dhidi ya kuvuka njia za faili. Mipangilio iliyopo ya Docker Compose imekusudiwa kwa uhamishaji wa baadaye kwenda PostgreSQL na hifadhi ya vitu, na haihitajiki kwa awamu hii.

Sakinisha backend

1. Unda faili la mazingira

Fungua PowerShell, ingia kwenye folda ya backend ya hazina, kisha nakili kiolezo cha mazingira cha mzizi hadi backend/.env.

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

Mipangilio ya uendeshaji imefafanuliwa kupitia .env.example, backend/app/core/config.py, na faili za udhibiti za PowerShell zilizo chini ya scripts/.

2. Unda mazingira pepe ya Python

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

Tekeleza amri hizi kutoka kwenye folda ya backend. Kuamilisha mazingira pepe hutenganisha vifurushi vya mradi na usakinishaji wako wa jumla wa Python.

3. Anzisha SQLite

python -m app.db.init_db

Amri hii huanzisha au kuunda upya majedwali yanayohitajika ya SQLite. Kwa kuwa kuunda upya majedwali kunaweza kuathiri data iliyopo, itumie kwa uangalifu baada ya kuanza kuhifadhi hati.

4. Anzisha FastAPI

uvicorn app.main:app --reload

Seva ya usanidi itapatikana kwenye http://127.0.0.1:8000. Chaguo la --reload hupakia upya programu kiotomatiki wakati faili za chanzo zinabadilika.

5. Fungua nyaraka za API

Tembelea http://127.0.0.1:8000/docs ili kukagua na kujaribu endpoint za OpenAPI zinazozalishwa.

Thibitisha usakinishaji

Majaribio yanahitaji folda ya backend kwenye PYTHONPATH. Katika Windows Command Prompt, tekeleza:

set PYTHONPATH=.
python -m pytest

Katika PowerShell, tumia:

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

Hazina pia hutoa faili tofauti za udhibiti za PowerShell zilizo chini ya scripts/ kwa ajili ya kuanzisha, kuanzisha upya, kusimamisha na kuangalia hali ya huduma.

Thibitisha utambulisho kwa API ya REST

Watumiaji huundwa na msimamizi. Baada ya kuwa na akaunti, tuma jina lake la mtumiaji na nenosiri kwenye endpoint ya kuingia. Jibu lina tokeni inayohitajika kwa maombi yaliyothibitishwa.

$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

Nakili tokeni ya ufikiaji iliyorejeshwa na uitumie kama kitambulisho cha Bearer. Ruhusa za tokeni hufuata utambulisho na jukumu la mtumiaji aliyethibitishwa.

Pakia hati

Endpoint ya upakiaji hupokea data ya fomu ya multipart. Weka kitambulisho cha msingi wa maarifa, lebo za hiari, faili na tokeni ya 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"

Mradi unaunga mkono upakiaji wa faili moja moja na wa kundi. Faili asili zilizopakiwa hubaki kwenye hifadhi ya ndani, huku maudhui yanayoungwa mkono yakifunguliwa katika kisomaji cha ndani ya programu.

Unda na tumia folda

Unda folda kwa kutuma kitambulisho cha msingi wake wa maarifa na jina kwenye endpoint ya folda:

$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

Ili kupakia kwenye folda maalum, ongeza folder_id kwenye fomu ya multipart ya upakiaji. Kiolesura cha wavuti huongeza kitambulisho hicho kiotomatiki folda inapochaguliwa.

Kiteuzi cha hifadhidata ya maarifa kwa chaguo-msingi huwa 全部, linalomaanisha “yote.” Mwonekano huu huonyesha hati na folda za mizizi katika hifadhidata zote za maarifa za umma. Unapounda folda, chagua hifadhidata yake ya maarifa lengwa katika kisanduku cha mazungumzo. Upakiaji unaofanywa kutoka mwonekano wa hifadhidata zote za maarifa hutumia hifadhidata ya kwanza inayopatikana isipokuwa folda imechaguliwa.

Elewa uhakiki wa ndani wa kivinjari

Kiolesura cha mbele hupata faili kupitia API iliyo na uthibitishaji, huzihifadhi kwenye kumbukumbu ya kivinjari, na kuzionyesha ndani ya kifaa. Hutumia vue3-office-preview kwa DOCX, PPTX, XLS, na XLSX, @vue3-office/vue-pdf kwa PDF, na @deot/docs-markdown kwa Markdown. Uonyeshaji wa PPTX hutumia pptx-renderer iliyojumuishwa.

Njia hii haihitaji LibreOffice, ONLYOFFICE, Docker, au SDK ya Python ya kuhakiki hati. Faili asili hubaki kwenye hifadhi ya ndani. Uchimbaji wa Markdown na uchakataji wa akiba kwa faili za zamani za .doc, .xls, na .ppt hubaki kuwa majukumu ya upande wa nyuma.

Unganisha wakala wa AI kupitia MCP

Hazina inajumuisha huduma tofauti ya MCP ya kusoma pekee. Inashiriki hifadhidata ya SQLite ya programu ya FastAPI, hifadhi ya ndani, siri ya JWT, na msomaji wa hati. Zana zinazopatikana katika Awamu ya 1 ni:

• list_knowledge_bases
• list_documents
• search_knowledge
• get_document
• get_document_metadata

Mchakato wa MCP hauwezi kupakia, kuhamisha, kufuta, au kudhibiti folda. Ufikiaji wake wa hati umewekewa mipaka kulingana na hati ambazo mtumiaji anayehusishwa anaruhusiwa kusoma.

Sakinisha vitegemezi vya MCP

Unda mazingira maalum ya MCP kutoka kwenye saraka ya backend:

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

Endesha MCP kupitia ingizo na pato la kawaida

Sanidi mchakato wa MCP utumie mipangilio ileile ya hifadhidata na hifadhi kama API. Weka tokeni ya kuingia katika KB_MCP_TOKEN, kisha uanzishe seva:

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

Kwa wateja wa ndani wa stdio, KB_MCP_TOKEN inaweza kuachwa. Katika hali hiyo, wakala lazima aitumie zana ya authenticate mara moja pamoja na jina la mtumiaji na nenosiri la mtumiaji. Kikao kifupi kinachopatikana huwepo tu kwenye kumbukumbu ya mchakato wa MCP.

Usiongeze miito ya kawaida ya print() kwenye huduma ya MCP ya stdio. Pato la kawaida hubeba ujumbe wa itifaki, kwa hivyo uchunguzi lazima uandikwe kwenye hitilafu ya kawaida.

Endesha jaribio la MCP la smoke

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

Fanya MCP ipatikane kupitia Streamable HTTP

Weka usafirishaji, anwani ya kusikiliza, porti, njia, na hali isiyo na hali kabla ya kuanzisha moduli ileile ya 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

Baada ya kusanidi proksi ya nyuma ya HTTPS, mwisho wa umma unaweza kuwa https://your-domain/mcp. Wateja wa mbali lazima watume Authorization: Bearer <access_token> na wanapaswa kutumia kitambulisho kilekile cha Bearer kilicholindwa kama muunganisho wa API.

Ukurasa wa kivinjari /mcp-token.html unaweza kuomba Tokeni ya MCP kwa akaunti iliyoingia bila kusoma au kuhifadhi nenosiri lake. Wasimamizi wanaweza kutumia /admin.html kudhibiti hali ya mtumiaji, majukumu, manenosiri, na sera za kuisha kwa Tokeni za MCP kwa kila mtumiaji, ikiwemo Tokeni za muda mrefu zinazodumu.

Vidokezo vya juu vya uendeshaji

• Weka mipangilio ya API na MCP ikiwa imeoanishwa. Huduma zote mbili lazima zielekee kwenye hifadhidata ileile ya SQLite na njia zilezile za hifadhi, na zitumie siri ileile ya JWT.
• Tumia utambulisho wenye ruhusa chache. Wakala wa MCP hurithi wigo wa hati zinazoweza kusomwa wa mtumiaji wa tokeni yake.
• Linda tokeni za Bearer. Usiweke vitambulisho vya API au MCP katika udhibiti wa msimbo chanzo, kumbukumbu, au pato la kawaida la koni.
• Hifadhi itifaki ya stdio. Tuma uchunguzi wa MCP kwenye hitilafu ya kawaida badala ya pato la kawaida.
• Tumia HTTPS ukiwa mbali. Weka mwisho wa Streamable HTTP nyuma ya proksi ya HTTPS kabla ya kuufanya upatikane nje ya mashine ya ndani.
• Kumbuka mipaka ya Awamu ya 1. Docker Compose, PostgreSQL, na hifadhi ya vitu ni malengo ya uhamishaji badala ya mahitaji ya sasa ya uendeshaji.
• Kagua vizuizi vya umiliki. Kuhariri hati, kufuta kwa muda, kurejesha, kubadilisha jina la folda, na kufuta folda tupu ni shughuli za mmiliki pekee.
• Tumia nyaraka za API zilizotengenezwa. Ukurasa wa /docs ndiyo njia ya moja kwa moja zaidi ya kukagua sehemu za maombi na majibu zinazopatikana zaidi ya mifano iliyoonyeshwa hapa.

Hitimisho

Awamu ya 1 ya Hifadhidata ya Maarifa hutoa msingi wa ndani unaofaa kwa kupanga faili zilizo na uthibitishaji, kuhakiki, kupata, na kutoa ufikiaji kwa mawakala. Kwa kutumia Python, SQLite, na hifadhi ya ndani pekee, unaweza kuanzisha huduma, kupakia mikusanyiko ya hati zilizopangwa, kudhibiti folda na metadata, na kufichua kwa usalama zana za maarifa za kusoma pekee kupitia usafirishaji wa MCP wa stdio wa ndani au Streamable HTTP wa mbali.