Hướng dẫn AI

Xây dựng và sử dụng cơ sở tri thức tệp cục bộ với FastAPI, SQLite và MCP

Tìm hiểu cách cài đặt cơ sở tri thức FastAPI, khởi tạo cơ sở dữ liệu SQLite, xác thực người dùng, tải lên và sắp xếp tài liệu, xem trước các tệp được hỗ trợ, cũng như kết nối tác nhân AI thông qua dịch vụ MCP chỉ đọc đi kèm.

23 tháng 9, 2026Thời gian đọc khoảng 21 phút

Xây dựng và sử dụng cơ sở tri thức tệp cục bộ với FastAPI, SQLite và MCP

Tổng quan

Knowledge Base Phase 1 là cơ sở tri thức tệp tối thiểu khả dụng được xây dựng bằng FastAPI, SQLite và hệ thống lưu trữ tệp cục bộ. Hệ thống hỗ trợ quản lý tài liệu có xác thực, thư mục lồng nhau, tính năng xem trước trên trình duyệt cục bộ, siêu dữ liệu và thẻ, công cụ quản trị, thông tin kiểm toán và quyền truy cập chỉ đọc cho các tác nhân AI thông qua Model Context Protocol, hay MCP.

Giai đoạn này được thiết kế gọn nhẹ. Hệ thống không yêu cầu Docker, PostgreSQL, MinIO, LibreOffice, ONLYOFFICE hoặc một dịch vụ cơ sở dữ liệu đang chạy khác. PostgreSQL và bộ nhớ đối tượng được dành cho lần chuyển đổi sau.

Dự án cung cấp

Người dùng do quản trị viên tạo, chức năng đăng nhập và xác thực JWT.
Cơ sở tri thức công khai với thư mục lồng nhau và điều hướng breadcrumb.
Liệt kê tài liệu theo phạm vi thư mục, tải lên từng tệp và tải lên hàng loạt.
Hỗ trợ các tệp PDF, văn bản, Markdown, HTML, hình ảnh, PowerPoint, Word và Excel.
Siêu dữ liệu tài liệu, thẻ, thông tin chủ sở hữu và người tải lên.
Xem trước và tải xuống tệp gốc.
Đọc trực tiếp trong ứng dụng đối với tệp văn bản, Markdown, PDF, DOCX, XLSX, PPTX và hình ảnh.
Trích xuất văn bản ở mức cố gắng tối đa đối với các tệp DOC, XLS và PPT cũ.
Chỉnh sửa tài liệu chỉ dành cho chủ sở hữu, xóa mềm, khôi phục, đổi tên thư mục và xóa thư mục trống.
Thùng rác dành cho tài liệu đã xóa.
Sao chép tài liệu và thư mục giữa các phạm vi, bao gồm sao chép thư mục đệ quy và nhân bản bộ nhớ vật lý.
Quản lý người dùng, nhật ký kiểm toán và nhật ký gọi MCP chỉ dành cho quản trị viên.
REST API chỉ đọc, tài liệu OpenAPI được tạo tự động và tích hợp MCP.

Cách thức lưu trữ

Ứng dụng tạo các tệp runtime trong backend/data/. Cơ sở dữ liệu SQLite được lưu tại backend/data/knowledge_base.db, còn các tệp đã tải lên và tệp Markdown được tạo nằm trong backend/data/storage/.

Bộ nhớ cục bộ có cơ chế bảo vệ chống truy cập vượt đường dẫn. Cấu hình Docker Compose hiện có dành cho lần chuyển đổi sang PostgreSQL và bộ nhớ đối tượng sau này, không cần thiết cho giai đoạn này.

Cài đặt backend

1. Tạo tệp môi trường

Mở PowerShell, chuyển đến thư mục backend của repository và sao chép mẫu môi trường ở thư mục gốc thành backend/.env.

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

Các thiết lập vận hành được định nghĩa thông qua .env.example, backend/app/core/config.py và các tệp điều khiển PowerShell trong scripts/.

2. Tạo môi trường ảo Python

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

Chạy các lệnh này từ thư mục backend. Việc kích hoạt môi trường ảo giúp tách các gói của dự án khỏi cài đặt Python toàn cục.

3. Khởi tạo SQLite

python -m app.db.init_db

Lệnh này khởi tạo hoặc tạo lại các bảng SQLite cần thiết. Vì việc tạo lại bảng có thể ảnh hưởng đến dữ liệu hiện có, hãy thận trọng sau khi bắt đầu lưu trữ tài liệu.

4. Khởi động FastAPI

uvicorn app.main:app --reload

Sau đó, máy chủ phát triển sẽ hoạt động tại http://127.0.0.1:8000. Tùy chọn --reload tự động tải lại ứng dụng khi các tệp mã nguồn thay đổi.

5. Mở tài liệu API

Truy cập http://127.0.0.1:8000/docs để kiểm tra và dùng thử các endpoint OpenAPI được tạo tự động.

Xác minh cài đặt

Để chạy kiểm thử, thư mục backend phải có trong PYTHONPATH. Trong Windows Command Prompt, chạy:

set PYTHONPATH=.
python -m pytest

Trong PowerShell, sử dụng:

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

Repository cũng cung cấp các tệp điều khiển PowerShell riêng trong scripts/ để khởi động, khởi động lại, dừng và kiểm tra trạng thái dịch vụ.

Xác thực với REST API

Người dùng được quản trị viên tạo. Sau khi có tài khoản, gửi tên người dùng và mật khẩu đến endpoint đăng nhập. Phản hồi chứa token cần thiết cho các yêu cầu đã xác thực.

$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

Sao chép access token được trả về và sử dụng token đó làm thông tin xác thực Bearer. Quyền của token tuân theo danh tính và vai trò của người dùng đã xác thực.

Tải tài liệu lên

Endpoint tải lên chấp nhận dữ liệu biểu mẫu multipart. Cung cấp ID cơ sở tri thức, các thẻ tùy chọn, tệp và token 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"

Dự án hỗ trợ cả tải lên từng tệp và tải lên hàng loạt. Tệp gốc đã tải lên vẫn được lưu trong bộ nhớ cục bộ, còn nội dung được hỗ trợ có thể mở bằng trình đọc trong ứng dụng.

Tạo và sử dụng thư mục

Tạo thư mục bằng cách gửi ID cơ sở tri thức và tên thư mục đến endpoint thư mục:

$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

Để tải lên một thư mục cụ thể, thêm folder_id vào biểu mẫu tải lên multipart. Giao diện web sẽ tự động thêm giá trị này khi một thư mục được chọn.

Bộ chọn cơ sở kiến thức mặc định là 全部, nghĩa là “tất cả”. Chế độ xem này hiển thị các tài liệu và thư mục gốc trên tất cả cơ sở kiến thức công khai. Khi tạo thư mục, hãy chọn cơ sở kiến thức đích trong hộp thoại. Tệp tải lên từ chế độ xem tất cả cơ sở kiến thức sẽ sử dụng cơ sở kiến thức khả dụng đầu tiên, trừ khi một thư mục được chọn.

Tìm hiểu về bản xem trước cục bộ trên trình duyệt

Frontend tải tệp thông qua API đã xác thực, giữ tệp trong bộ nhớ trình duyệt và hiển thị cục bộ. Ứng dụng sử dụng vue3-office-preview cho DOCX, PPTX, XLS và XLSX, @vue3-office/vue-pdf cho PDF, và @deot/docs-markdown cho Markdown. Việc hiển thị PPTX sử dụng pptx-renderer đi kèm.

Quy trình này không cần LibreOffice, ONLYOFFICE, Docker hoặc SDK xem trước tài liệu Python. Tệp gốc vẫn được lưu trữ cục bộ. Việc trích xuất Markdown và xử lý dự phòng cho các tệp .doc, .xls và .ppt cũ vẫn thuộc trách nhiệm của backend.

Kết nối tác nhân AI thông qua MCP

Kho mã nguồn bao gồm một dịch vụ MCP chỉ đọc riêng biệt. Dịch vụ này dùng chung cơ sở dữ liệu SQLite, bộ nhớ lưu trữ cục bộ, bí mật JWT và trình đọc tài liệu của ứng dụng FastAPI. Các công cụ có trong Giai đoạn 1 là:

list_knowledge_bases
list_documents
search_knowledge
get_document
get_document_metadata

Tiến trình MCP không thể tải lên, di chuyển, xóa hoặc quản lý thư mục. Quyền truy cập tài liệu của tiến trình bị giới hạn trong phạm vi mà người dùng liên kết được phép đọc.

Cài đặt các phụ thuộc MCP

Tạo môi trường ảo MCP riêng từ thư mục backend:

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

Chạy MCP qua đầu vào và đầu ra tiêu chuẩn

Cấu hình tiến trình MCP với cùng các thiết lập cơ sở dữ liệu và bộ nhớ lưu trữ như API. Đặt mã thông báo truy cập đăng nhập vào KB_MCP_TOKEN, sau đó khởi động máy chủ:

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

Đối với các ứng dụng khách stdio cục bộ, có thể bỏ qua KB_MCP_TOKEN. Khi đó, tác nhân phải gọi công cụ authenticate một lần bằng tên người dùng và mật khẩu của người dùng. Phiên ngắn hạn được tạo chỉ tồn tại trong bộ nhớ của tiến trình MCP.

Không thêm các lệnh gọi print() thông thường vào dịch vụ MCP stdio. Đầu ra tiêu chuẩn truyền các thông báo giao thức, vì vậy thông tin chẩn đoán phải được ghi vào lỗi tiêu chuẩn.

Chạy kiểm thử nhanh MCP

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

Cung cấp MCP qua Streamable HTTP

Đặt giao thức truyền tải, địa chỉ lắng nghe, cổng, đường dẫn và chế độ không trạng thái trước khi khởi động cùng mô-đun 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

Sau khi cấu hình proxy ngược HTTPS, điểm cuối công khai có thể là https://your-domain/mcp. Ứng dụng khách từ xa phải gửi Authorization: Bearer <access_token> và nên sử dụng cùng thông tin xác thực Bearer được bảo vệ như kết nối API.

Trang trình duyệt /mcp-token.html có thể yêu cầu Mã thông báo MCP cho tài khoản đang đăng nhập mà không đọc hoặc lưu trữ mật khẩu của tài khoản đó. Quản trị viên có thể sử dụng /admin.html để quản lý trạng thái người dùng, vai trò, mật khẩu và chính sách hết hạn Mã thông báo MCP theo từng người dùng, bao gồm cả các Mã thông báo dài hạn được lưu trữ liên tục.

Mẹo vận hành nâng cao

Giữ các thiết lập API và MCP đồng bộ. Cả hai dịch vụ phải trỏ đến cùng cơ sở dữ liệu SQLite và các đường dẫn lưu trữ, đồng thời sử dụng cùng một bí mật JWT.
Sử dụng danh tính với quyền tối thiểu. Tác nhân MCP thừa hưởng phạm vi tài liệu có thể đọc của người dùng sở hữu mã thông báo.
Bảo vệ mã thông báo Bearer. Không đặt thông tin xác thực API hoặc MCP trong hệ thống quản lý mã nguồn, nhật ký hoặc đầu ra bảng điều khiển thông thường.
Duy trì giao thức stdio. Gửi thông tin chẩn đoán MCP đến lỗi tiêu chuẩn thay vì đầu ra tiêu chuẩn.
Sử dụng HTTPS khi truy cập từ xa. Đặt điểm cuối Streamable HTTP phía sau proxy ngược HTTPS trước khi cung cấp ra ngoài máy cục bộ.
Ghi nhớ các giới hạn của Giai đoạn 1. Docker Compose, PostgreSQL và bộ nhớ đối tượng là mục tiêu di chuyển, không phải yêu cầu thời gian chạy hiện tại.
Kiểm tra các hạn chế về quyền sở hữu. Chỉnh sửa tài liệu, xóa mềm, khôi phục, đổi tên thư mục và xóa thư mục trống là các thao tác chỉ dành cho chủ sở hữu.
Sử dụng tài liệu API được tạo tự động. Trang /docs là cách trực tiếp nhất để kiểm tra các trường yêu cầu và phản hồi khả dụng ngoài những ví dụ được trình bày ở đây.

Kết luận

Knowledge Base Giai đoạn 1 cung cấp nền tảng cục bộ thiết thực cho việc tổ chức, xem trước và truy xuất tệp đã xác thực, cũng như truy cập của tác nhân. Chỉ với Python, SQLite và bộ nhớ lưu trữ cục bộ, bạn có thể khởi tạo dịch vụ, tải lên các bộ sưu tập tài liệu có cấu trúc, quản lý thư mục và siêu dữ liệu, đồng thời cung cấp an toàn các công cụ kiến thức chỉ đọc thông qua MCP stdio cục bộ hoặc giao thức MCP Streamable HTTP từ xa.