মূল কনটেন্টে যান
এআই টিউটোরিয়াল

FastAPI, SQLite ও MCP দিয়ে স্থানীয় ফাইল নলেজ বেস তৈরি ও ব্যবহার

FastAPI নলেজ বেস ইনস্টল, SQLite ডেটাবেস初始化, ব্যবহারকারী প্রমাণীকরণ, নথি আপলোড ও সংগঠিত করা, সমর্থিত ফাইলের প্রিভিউ দেখা এবং অন্তর্ভুক্ত শুধুমাত্র-পাঠযোগ্য MCP সার্ভিসের মাধ্যমে AI এজেন্ট সংযুক্ত করা শিখুন।

পড়তে প্রায় 22 মিনিট লাগবে
FastAPI, SQLite ও MCP দিয়ে স্থানীয় ফাইল নলেজ বেস তৈরি ও ব্যবহার

সংক্ষিপ্ত বিবরণ

Knowledge Base Phase 1 হলো FastAPI, SQLite এবং স্থানীয় ফাইলসিস্টেম স্টোরেজ দিয়ে তৈরি একটি ন্যূনতম কার্যকর ফাইল জ্ঞানভান্ডার। এতে প্রমাণীকৃত ডকুমেন্ট ব্যবস্থাপনা, নেস্টেড ফোল্ডার, ব্রাউজার-স্থানীয় প্রিভিউ, মেটাডেটা ও ট্যাগ, প্রশাসনিক সরঞ্জাম, অডিট তথ্য এবং Model Context Protocol বা MCP-এর মাধ্যমে AI এজেন্টদের জন্য শুধু-পঠনযোগ্য অ্যাক্সেস রয়েছে।

এই পর্যায়টি ইচ্ছাকৃতভাবে হালকা রাখা হয়েছে। এতে Docker, PostgreSQL, MinIO, LibreOffice, ONLYOFFICE বা চলমান অন্য কোনো ডেটাবেস সার্ভিসের প্রয়োজন নেই। PostgreSQL এবং অবজেক্ট স্টোরেজ পরবর্তী মাইগ্রেশনের জন্য রাখা হয়েছে।

প্রকল্পটি যা প্রদান করে

  • প্রশাসক-নির্মিত ব্যবহারকারী, লগইন এবং JWT প্রমাণীকরণ।
  • নেস্টেড ফোল্ডার ও ব্রেডক্রাম্ব নেভিগেশনসহ পাবলিক জ্ঞানভান্ডার।
  • ফোল্ডার-ভিত্তিক ডকুমেন্ট তালিকা, একক-ফাইল আপলোড এবং ব্যাচ আপলোড।
  • PDF, টেক্সট, Markdown, HTML, ছবি, PowerPoint, Word এবং Excel ফাইলের সমর্থন।
  • ডকুমেন্টের মেটাডেটা, ট্যাগ, মালিক এবং আপলোডকারীর তথ্য।
  • মূল ফাইলের প্রিভিউ ও ডাউনলোড।
  • টেক্সট, Markdown, PDF, DOCX, XLSX, PPTX এবং ছবির জন্য অ্যাপের ভেতরে পড়ার সুবিধা।
  • পুরোনো DOC, XLS এবং PPT ফাইল থেকে সম্ভাব্য সর্বোত্তম পদ্ধতিতে টেক্সট নিষ্কাশন।
  • শুধু মালিকের জন্য ডকুমেন্ট সম্পাদনা, সফট ডিলিশন, পুনরুদ্ধার, ফোল্ডারের নাম পরিবর্তন এবং খালি ফোল্ডার মুছে ফেলার সুবিধা।
  • মুছে ফেলা ডকুমেন্টের জন্য রিসাইকেল বিন।
  • রিকর্সিভ ফোল্ডার কপি এবং ফিজিক্যাল স্টোরেজ ডুপ্লিকেশনসহ বিভিন্ন স্কোপের ডকুমেন্ট ও ফোল্ডার কপি।
  • শুধু প্রশাসকের জন্য ব্যবহারকারী ব্যবস্থাপনা, অডিট লগ এবং MCP ইনভোকেশন লগ।
  • শুধু-পঠনযোগ্য REST API, তৈরি করা OpenAPI ডকুমেন্টেশন এবং MCP ইন্টিগ্রেশন।

স্টোরেজ কীভাবে কাজ করে

অ্যাপ্লিকেশনটি backend/data/-এর অধীনে রানটাইম ফাইল তৈরি করে। SQLite ডেটাবেস backend/data/knowledge_base.db হিসেবে সংরক্ষিত হয়, আর আপলোড করা ফাইল ও তৈরি করা Markdown ফাইল backend/data/storage/-এর অধীনে রাখা হয়।

স্থানীয় স্টোরেজে পাথ ট্রাভার্সাল সুরক্ষা রয়েছে। বিদ্যমান Docker Compose কনফিগারেশনটি পরবর্তী PostgreSQL ও অবজেক্ট-স্টোরেজ মাইগ্রেশনের জন্য তৈরি এবং এই পর্যায়ে এটি প্রয়োজনীয় নয়।

ব্যাকএন্ড ইনস্টল করুন

১. এনভায়রনমেন্ট ফাইল তৈরি করুন

PowerShell খুলুন, রিপোজিটরির backend ডিরেক্টরিতে প্রবেশ করুন এবং রুট এনভায়রনমেন্ট টেমপ্লেটটি backend/.env-এ কপি করুন।

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

অপারেশনাল সেটিংস .env.example, backend/app/core/config.py এবং scripts/-এর অধীনে থাকা PowerShell কন্ট্রোল ফাইলের মাধ্যমে নির্ধারিত হয়।

২. একটি Python ভার্চুয়াল এনভায়রনমেন্ট তৈরি করুন

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

backend ডিরেক্টরি থেকে এই কমান্ডগুলো চালান। ভার্চুয়াল এনভায়রনমেন্ট সক্রিয় করলে প্রকল্পের প্যাকেজগুলো আপনার গ্লোবাল Python ইনস্টলেশন থেকে আলাদা থাকে।

৩. SQLite ইনিশিয়ালাইজ করুন

python -m app.db.init_db

এই কমান্ডটি প্রয়োজনীয় SQLite টেবিল ইনিশিয়ালাইজ বা পুনরায় তৈরি করে। টেবিল পুনরায় তৈরি করলে বিদ্যমান ডেটা প্রভাবিত হতে পারে, তাই ডকুমেন্ট সংরক্ষণ শুরু করার পর সতর্কতার সঙ্গে এটি ব্যবহার করুন।

৪. FastAPI চালু করুন

uvicorn app.main:app --reload

এরপর ডেভেলপমেন্ট সার্ভারটি http://127.0.0.1:8000-এ পাওয়া যাবে। সোর্স ফাইলে পরিবর্তন হলে --reload অপশনটি স্বয়ংক্রিয়ভাবে অ্যাপ্লিকেশন পুনরায় লোড করে।

৫. API ডকুমেন্টেশন খুলুন

তৈরি করা OpenAPI এন্ডপয়েন্ট পর্যালোচনা ও পরীক্ষা করতে http://127.0.0.1:8000/docs ভিজিট করুন।

ইনস্টলেশন যাচাই করুন

টেস্ট চালানোর জন্য backend ডিরেক্টরিটি PYTHONPATH-এ থাকতে হবে। Windows Command Prompt-এ চালান:

set PYTHONPATH=.
python -m pytest

PowerShell-এ ব্যবহার করুন:

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

সার্ভিস চালু, পুনরায় চালু, বন্ধ এবং স্ট্যাটাস দেখার জন্য রিপোজিটরিতে scripts/-এর অধীনে আলাদা PowerShell কন্ট্রোল ফাইলও রয়েছে।

REST API-তে প্রমাণীকরণ করুন

ব্যবহারকারী একজন প্রশাসক তৈরি করেন। একটি অ্যাকাউন্ট পাওয়ার পর তার ব্যবহারকারীর নাম ও পাসওয়ার্ড লগইন এন্ডপয়েন্টে পাঠান। উত্তরে প্রমাণীকৃত অনুরোধের জন্য প্রয়োজনীয় টোকেন থাকবে।

$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

ফেরত পাওয়া অ্যাক্সেস টোকেন কপি করে Bearer ক্রেডেনশিয়াল হিসেবে ব্যবহার করুন। টোকেনের অনুমতিগুলো প্রমাণীকৃত ব্যবহারকারীর পরিচয় ও ভূমিকা অনুসরণ করে।

একটি ডকুমেন্ট আপলোড করুন

আপলোড এন্ডপয়েন্টটি multipart form data গ্রহণ করে। একটি জ্ঞানভান্ডার ID, ঐচ্ছিক ট্যাগ, ফাইল এবং 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"

প্রকল্পটি একক ও ব্যাচ উভয় ধরনের আপলোড সমর্থন করে। আপলোড করা মূল ফাইলগুলো স্থানীয় স্টোরেজে থেকে যায়, আর সমর্থিত কনটেন্ট অ্যাপের ভেতরের রিডারে খোলা যায়।

ফোল্ডার তৈরি ও ব্যবহার করুন

ফোল্ডার এন্ডপয়েন্টে তার জ্ঞানভান্ডার ID ও নাম POST করে একটি ফোল্ডার তৈরি করুন:

$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

নির্দিষ্ট কোনো ফোল্ডারে আপলোড করতে multipart upload form-এ folder_id যোগ করুন। কোনো ফোল্ডার নির্বাচন করলে ওয়েব ইন্টারফেস স্বয়ংক্রিয়ভাবে এটি যোগ করে।

জ্ঞানভিত্তি নির্বাচকটির ডিফল্ট মান হলো 全部, যার অর্থ “সব।” এই ভিউতে সব পাবলিক জ্ঞানভিত্তি জুড়ে রুট ডকুমেন্ট ও ফোল্ডার দেখানো হয়। ফোল্ডার তৈরি করার সময় ডায়ালগে এর গন্তব্য জ্ঞানভিত্তি নির্বাচন করুন। সব জ্ঞানভিত্তির ভিউ থেকে আপলোড করলে কোনো ফোল্ডার নির্বাচিত না থাকলে প্রথম উপলভ্য জ্ঞানভিত্তি ব্যবহার করা হয়।

ব্রাউজার-স্থানীয় প্রিভিউ বুঝে নিন

ফ্রন্টএন্ড অনুমোদিত API-এর মাধ্যমে ফাইল সংগ্রহ করে, সেগুলো ব্রাউজারের মেমোরিতে রাখে এবং স্থানীয়ভাবে রেন্ডার করে। DOCX, PPTX, XLS এবং XLSX-এর জন্য এটি vue3-office-preview, PDF-এর জন্য @vue3-office/vue-pdf, এবং Markdown-এর জন্য @deot/docs-markdown ব্যবহার করে। PPTX রেন্ডারিংয়ে বান্ডেল করা pptx-renderer ব্যবহৃত হয়।

এই পদ্ধতিতে LibreOffice, ONLYOFFICE, Docker বা কোনো Python document-preview SDK প্রয়োজন হয় না। মূল ফাইলটি স্থানীয় স্টোরেজেই থাকে। Markdown এক্সট্রাকশন এবং পুরোনো .doc, .xls ও .ppt ফাইলের জন্য fallback processing ব্যাকএন্ডের দায়িত্বে থাকে।

MCP-এর মাধ্যমে একটি AI এজেন্ট সংযুক্ত করুন

রিপোজিটরিতে একটি পৃথক read-only MCP সার্ভিস অন্তর্ভুক্ত রয়েছে। এটি FastAPI অ্যাপ্লিকেশনের SQLite ডেটাবেস, স্থানীয় স্টোরেজ, JWT secret এবং document reader শেয়ার করে। Phase 1-এর উপলভ্য টুলগুলো হলো:

  • list_knowledge_bases
  • list_documents
  • search_knowledge
  • get_document
  • get_document_metadata

MCP প্রক্রিয়া আপলোড, সরানো, মুছে ফেলা বা ফোল্ডার পরিচালনা করতে পারে না। এর ডকুমেন্ট অ্যাক্সেস সংশ্লিষ্ট ব্যবহারকারী যে ডকুমেন্ট পড়ার অনুমতি পেয়েছেন, তার মধ্যেই সীমাবদ্ধ।

MCP নির্ভরতা ইনস্টল করুন

backend ডিরেক্টরি থেকে একটি নির্দিষ্ট MCP virtual environment তৈরি করুন:

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

স্ট্যান্ডার্ড ইনপুট ও আউটপুটের মাধ্যমে MCP চালান

API-এর মতো একই ডেটাবেস ও স্টোরেজ সেটিংস দিয়ে MCP প্রক্রিয়াটি কনফিগার করুন। KB_MCP_TOKEN-এ একটি login access token রাখুন, তারপর সার্ভার চালু করুন:

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

স্থানীয় stdio ক্লায়েন্টের ক্ষেত্রে KB_MCP_TOKEN বাদ দেওয়া যেতে পারে। সে ক্ষেত্রে এজেন্টকে ব্যবহারকারীর username ও password দিয়ে একবার authenticate টুল কল করতে হবে। এর ফলে তৈরি হওয়া স্বল্পস্থায়ী session কেবল MCP প্রক্রিয়ার মেমোরিতেই থাকে।

stdio MCP সার্ভিসে সাধারণ print() কল যোগ করবেন না। স্ট্যান্ডার্ড আউটপুটে প্রোটোকল বার্তা বহন করা হয়, তাই diagnostics অবশ্যই standard error-এ লিখতে হবে।

MCP smoke test চালান

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

Streamable HTTP-এর মাধ্যমে MCP প্রকাশ করুন

একই MCP মডিউল চালু করার আগে transport, listening address, port, path এবং stateless mode সেট করুন:

$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 কনফিগার করার পর public endpoint হতে পারে https://your-domain/mcp। Remote client-গুলোকে Authorization: Bearer <access_token> পাঠাতে হবে এবং API connection-এর মতো একই সুরক্ষিত Bearer credential ব্যবহার করা উচিত।

/mcp-token.html ব্রাউজার পেজটি password পড়া বা সংরক্ষণ না করেই লগইন করা অ্যাকাউন্টের জন্য একটি MCP Token অনুরোধ করতে পারে। Administrators /admin.html ব্যবহার করে ব্যবহারকারীর status, roles, passwords এবং প্রত্যেক ব্যবহারকারীর MCP Token expiration policies পরিচালনা করতে পারেন, যার মধ্যে দীর্ঘমেয়াদি persistent Token-ও রয়েছে।

উন্নত অপারেশনাল পরামর্শ

  • API এবং MCP সেটিংস সামঞ্জস্যপূর্ণ রাখুন। উভয় সার্ভিসকে একই SQLite ডেটাবেস ও স্টোরেজ পাথ নির্দেশ করতে হবে এবং একই JWT secret ব্যবহার করতে হবে।
  • ন্যূনতম-সুবিধাপ্রাপ্ত পরিচয় ব্যবহার করুন। একটি MCP agent তার token-এর ব্যবহারকারীর readable document scope উত্তরাধিকারসূত্রে পায়।
  • Bearer token সুরক্ষিত রাখুন। API বা MCP credential source control, logs বা সাধারণ console output-এ রাখবেন না।
  • stdio protocol অক্ষুণ্ণ রাখুন। MCP diagnostics standard output-এর পরিবর্তে standard error-এ পাঠান।
  • দূরবর্তী ব্যবহারে HTTPS ব্যবহার করুন। স্থানীয় মেশিনের বাইরে প্রকাশ করার আগে Streamable HTTP endpoint-কে একটি HTTPS reverse proxy-এর পেছনে রাখুন।
  • Phase 1-এর সীমা মনে রাখুন। Docker Compose, PostgreSQL এবং object storage বর্তমান runtime requirement নয়, বরং migration target।
  • মালিকানা-সংক্রান্ত সীমাবদ্ধতা পর্যালোচনা করুন। Document editing, soft deletion, restoration, folder renaming এবং empty-folder deletion কেবল owner-only operation।
  • উৎপন্ন API documentation ব্যবহার করুন। এখানে দেখানো উদাহরণের বাইরে উপলভ্য request field ও response পরিদর্শনের সবচেয়ে সরাসরি উপায় হলো /docs পেজ।

উপসংহার

Knowledge Base Phase 1 অনুমোদিত file organization, preview, retrieval এবং agent access-এর জন্য একটি ব্যবহারিক স্থানীয় ভিত্তি প্রদান করে। শুধু Python, SQLite এবং local storage ব্যবহার করেই আপনি সার্ভিস initialize করতে, কাঠামোবদ্ধ document collection আপলোড করতে, folder ও metadata পরিচালনা করতে এবং স্থানীয় stdio অথবা remote Streamable HTTP MCP transport-এর মাধ্যমে নিরাপদে read-only knowledge tools প্রকাশ করতে পারেন।