AI Lab Simulator là nền tảng giả lập phòng thí nghiệm STEM tương tác hai phía tại Việt Nam, hỗ trợ giáo viên thiết kế bài thí nghiệm bằng prompt tiếng Việt và giúp học sinh thực hành trực quan qua hoạt ảnh 2D cùng đồ thị đồng bộ.
Fig. 01 · Ảnh dự án
Tài liệu dự án: AI Lab Simulator (Aurora Lab)
Hệ thống giả lập phòng thí nghiệm STEM (Toán, Vật lý, Hóa học) tương tác hai phía dành cho Giáo viên (Teacher) và Học sinh (Student) tại Việt Nam.
1. Giới thiệu chung (Project Overview)
AI Lab Simulator (còn gọi là Aurora Lab) là giải pháp hỗ trợ giảng dạy và thực hành các môn học STEM thông qua các kịch bản mô phỏng trực quan 2D và biểu đồ thời gian thực. Hệ thống giải quyết bài toán lớn về độ chính xác và tin cậy của Trí tuệ nhân tạo (LLM) trong giáo dục tự nhiên:
AI không tự tính toán vật lý, không tự render hình ảnh: LLM đóng vai trò giao tiếp (NLP) để phân tích yêu cầu từ prompt tiếng Việt của giáo viên, từ đó đối chiếu và trích xuất ra một bộ đặc tả thí nghiệm (Model Specification) cùng các tham số ban đầu (Parameters).
Trọng tâm là Engine tính toán tất định: Toàn bộ quá trình tính toán chuỗi số mô phỏng được thực hiện bằng các thư viện toán học/khoa học chuẩn của Python như scipy, numpy, sympy, và pint (quản lý đơn vị đo).
Validator kiểm tra định luật: Trước khi hiển thị kết quả cho học sinh, một bộ kiểm định sẽ quét qua các tham số đầu vào và chuỗi số đầu ra nhằm phát hiện các hành vi vi phạm các định luật bảo toàn hoặc giới hạn thực tế. Nếu vi phạm, mô phỏng sẽ bị chặn hiển thị (blocked: true) kèm theo lời giải thích mang tính giáo dục bằng tiếng Việt.
2. Tệp người dùng mục tiêu (Target Audience)
Hệ thống phục vụ ba nhóm đối tượng cốt lõi trong hệ sinh thái giáo dục Việt Nam:
Giáo viên STEM (Toán, Vật lý, Hóa học):
Muốn trực quan hóa bài giảng sinh động, thu hút học sinh mà không cần kỹ năng lập trình phức tạp.
Muốn thiết kế nhanh các kịch bản thực hành thông qua ngôn ngữ tự nhiên (tiếng Việt), điều chỉnh thông số vật lý tùy ý, lưu trữ và giao bài tập tập trung.
Cần công cụ chấm điểm tự động và bảng phân tích chuyên sâu (Engagement Analytics) để theo dõi tiến trình thực tế của từng học sinh.
Học sinh Trung học (Cấp 2, Cấp 3):
Học các môn tự nhiên nhưng thiếu điều kiện tiếp cận phòng thí nghiệm vật chất (do thiếu trang thiết bị, hóa chất độc hại, nguy hiểm).
Cần một công cụ mô phỏng chuẩn xác để tự học ở nhà, có Gia sư AI trực tuyến 24/7 am hiểu bối cảnh và trích dẫn trực tiếp từ Sách Giáo Khoa (SGK).
Thích học thông qua thực hành tương tác, trực quan hóa các đại lượng ẩn (như lực vector).
Nhà trường / Ban giám hiệu (Tenants/Admins):
§
Phụ lục — Demo & Slides
Video demo
Bản demo trực tiếp
Slide trình bày
Theo dõi chất lượng dạy học và hoạt động số hóa giáo án STEM trực tiếp trên nền tảng qua dashboard báo cáo.
3. Nỗi đau thị trường & Giải pháp dự án (Pain Points & Solutions)
Dự án ra đời nhằm giải quyết trực tiếp 4 nỗi đau (pain points) lớn của các phần mềm thí nghiệm và công cụ AI hiện nay:
Nỗi đau 1: Sự kém tin cậy của AI (LLM Hallucination) trong khoa học tự nhiên
Vấn đề (Pain Point): Khi học sinh hoặc giáo viên yêu cầu ChatGPT/LLM mô phỏng hoặc tính toán một hiện tượng vật lý/hóa học, LLM thường tính toán sai lệch kết quả số học hoặc bịa đặt (hallucinate) các định luật phi thực tế vì LLM chỉ dự đoán từ tiếp theo, không có tư duy logic toán lý thực thụ.
Giải pháp: Tách biệt hoàn toàn LLM khỏi phần tính toán. LLM chỉ chịu trách nhiệm dịch prompt của giáo viên thành cấu trúc dữ liệu ModelSpec chuẩn. Toàn bộ logic động học được giải quyết bởi các thuật toán khoa học tất định (scipy.integrate.solve_ivp). Thêm vào đó, bộ lọc định luật vật lý (Validator) sẽ tự động chặn mọi đầu ra sai lệch định luật bảo toàn.
Nỗi đau 2: Thư viện mô phỏng có sẵn bị "đóng băng" cấu hình (Fixed Catalogs) và rào cản ngôn ngữ
Vấn đề (Pain Point): Các nền tảng mô phỏng nổi tiếng (như PhET, Falstad) rất hữu ích nhưng là bộ sưu tập đóng băng (static catalog). Giáo viên không thể dễ dàng thêm mới mô hình hay chỉnh sửa thuật toán nếu không có lập trình viên viết code. Hơn nữa, hầu hết các phần mềm này sử dụng tiếng Anh và thiếu hệ thống quản lý học tập (LMS) đi kèm.
Giải pháp: Xây dựng hệ thống RAG-match & RAG-derive để giáo viên tự tạo mô phỏng từ tiếng Việt. Nếu chưa có spec phù hợp, pipeline AI Sandbox (POST /ai/generate-simulation) sẽ tự động dựng và sửa chữa spec mới. Hệ thống được Việt hóa toàn diện và tích hợp sẵn đầy đủ tính năng tạo lớp học, giao bài tập, chấm điểm tự động.
Nỗi đau 3: Thiếu thốn trang thiết bị thí nghiệm và nguy cơ mất an toàn vật chất
Vấn đề (Pain Point): Phòng thí nghiệm truyền thống tại các trường phổ thông Việt Nam thường thiếu dụng cụ, dụng cụ đo đạc kém chính xác hoặc hóa chất có tính ăn mòn, độc hại cao, gây nguy cơ cháy nổ mất an toàn cho học sinh.
Giải pháp: Hệ thống giả lập 2D hoạt ảnh trực quan và đồ thị đồng bộ giúp học sinh quan sát rõ ràng các hiện tượng khó (như va chạm đàn hồi nhanh, lực cản không khí, cân bằng hóa học dịch chuyển). Công cụ còn tích hợp tính năng kính hiển vi vật lý (Lenses) giúp nhìn thấy các vectơ lực ẩn đang tác động lên vật thể.
Nỗi đau 4: Học sinh bị quá tải và không có người hướng dẫn khi tự học
Vấn đề (Pain Point): Khi tự học ở nhà với các bài thí nghiệm mô phỏng, học sinh thường bối rối không hiểu bản chất hiện tượng hoặc không biết liên hệ công thức nào, trong khi giáo viên và phụ huynh không có mặt để giải đáp.
Giải pháp: Gia sư AI ảo (Cited Tutor) tích hợp sẵn trong không gian thực hành, cung cấp phản hồi nhanh 24/7 dựa trên dữ liệu SGK Việt Nam đã được vector hóa (pgvector RAG), trích dẫn chính xác chương, mục, trang sách để học sinh đối chiếu.
4. Kiến trúc hệ thống (System Architecture)
Dự án tuân thủ mô hình kiến trúc 3 lớp (Three-Tier Architecture) giúp phân tách rõ ràng trách nhiệm giữa giao diện người dùng, logic xử lý mô phỏng và cơ sở dữ liệu.
flowchart TB
subgraph FE["LỚP HIỂN THỊ (Presentation Layer - React + Vite SPA)"]
tcreate["TeacherCreate.tsx (Giao diện tạo lab bằng prompt)"]
swork["StudentWorkspace.tsx (Không gian thực hành học sinh)"]
plot["SeriesPlot.tsx (Đồ thị Plotly hiển thị chuỗi số thực)"]
canvas["SimulationCanvas (Bộ dựng hình 2D theo vị trí vật thể)"]
auth["AuthProvider.tsx (Quản lý đăng nhập Supabase)"]
end
subgraph API["LỚP ỨNG DỤNG (Application Layer - FastAPI Web Service)"]
create["POST /extract (Trích xuất tham số từ prompt bằng LLM)"]
kernel["POST /labs (Engine giải mô phỏng theo đặc tả)"]
valid["Validator (Kiểm định định luật vật lý và giới hạn miền giá trị)"]
tutor["POST /tutor (Gia sư ảo trả lời kèm trích dẫn SGK)"]
platform["Platform REST APIs (Lớp học, Bài tập, Chấm điểm)"]
end
subgraph SUPA["LỚP DỮ LIỆU (Data Layer - Supabase Managed Services)"]
pg["PostgreSQL DB (Lưu trữ lab, lớp học, bài nộp, nhật ký tương tác)"]
rls["Chính sách RLS (Phân quyền bảo mật cô lập dữ liệu học sinh/giáo viên)"]
pgv["pgvector (Tìm kiếm ngữ nghĩa RAG cho Gia sư AI)"]
end
subgraph EXT["DỊCH VỤ NGOÀI (External APIs)"]
llm["OpenAI / Nvidia API (Xử lý LLM cấu trúc & RAG)"]
bge["DeepInfra Embeddings (BGE-m3 sinh vector mật độ cao)"]
end
tcreate -->|"Yêu cầu phân tích prompt"| create
tcreate -->|"Lưu & Xuất bản"| platform
swork -->|"Giải phương trình mô phỏng"| kernel
kernel --> valid
swork -->|"Hỏi gia sư ảo"| tutor
tutor --> pgv
auth -->|"Xác thực JWT token"| platform
platform --> rls
rls --> pg
create -.-> llm
tutor -.-> llm
tutor -.-> bge
Chi tiết các tầng kiến trúc:
Frontend (React SPA): Được xây dựng bằng React 18, Vite 5 và TypeScript. Sử dụng thư viện Plotly để dựng đồ thị đồng bộ thời gian thực với mô phỏng và KaTeX để hiển thị công thức toán học.
Backend (FastAPI): Một Web Service không trạng thái (stateless) đảm nhận vai trò tính toán khoa học chính xác. Tất cả các router trong thư mục src/api/ tự động được quét và mount vào ứng dụng thông qua cơ chế phản chiếu tại src/main.py.
Database & Auth (Supabase): Sử dụng Supabase PostgreSQL quản lý người dùng (JWT tokens), bảo mật dữ liệu ở cấp hàng (Row-Level Security - RLS) để giáo viên không thể xem chéo lớp học của nhau và học sinh không thể sửa điểm bài tập của mình.
5. Các tính năng cốt lõi (Core Features)
5.1. Luồng tạo mô phỏng từ ngôn ngữ tự nhiên (Prompt-to-Simulation)
Giáo viên nhập một prompt tiếng Việt mô tả thí nghiệm (Ví dụ: "Tạo một bài lab ném xiên với góc ném 45 độ và vận tốc ban đầu là 15 m/s").
Endpoint POST /extract sử dụng LLM để phân tích ngữ nghĩa, trích xuất môn học (Toán/Lý/Hóa), tham số đầu vào và khớp với thư viện đặc tả có sẵn.
Nếu không có mô phỏng nào khớp trong thư viện, hệ thống kích hoạt luồng Dynamic Generation PipelinePOST /ai/generate-simulation: sinh code động -> kiểm tra cấu trúc -> duyệt nội dung khoa học -> duyệt phương pháp sư phạm -> sửa lỗi tự động (repair) tạo ra một DynamicSim an toàn trong môi trường sandbox.
5.2. Bộ Engine mô phỏng và Validator định luật
Engine: Khi chạy thí nghiệm, hệ thống gọi endpoint POST /labs. Bộ xử lý Kernel tại src/kernels/ nhận đặc tả ModelSpec và các tham số đầu vào. Nó tự động chuyển hóa các ký hiệu Sympy thành hàm Python, sau đó dùng scipy.integrate.solve_ivp để giải hệ phương trình vi phân mô tả hệ thống.
Pha 1 (Tham số): Kiểm tra miền giá trị giới hạn của tham số đầu vào (ví dụ: khối lượng quả cầu phải lớn hơn 0).
Pha 2 (Động học & Bảo toàn): Kiểm tra chuỗi số đầu ra sau khi giải. Ví dụ, trong bài toán va chạm đàn hồi hoặc dao động tắt dần, cơ năng của hệ phải bảo toàn hoặc giảm dần đơn điệu theo thời gian. Nếu phát hiện vi phạm do lỗi tính toán hoặc tham số bất khả thi, hệ thống sẽ trả về lỗi giáo dục chặn mô phỏng hiển thị giá trị sai lệch.
5.3. Gia sư ảo thông thái (Cited Tutor)
Học sinh trong quá trình chạy bài lab có thể hỏi gia sư AI qua cửa sổ chat. Endpoint POST /tutor thực hiện tìm kiếm ngữ nghĩa (RAG) sử dụng vector tìm kiếm BGE-m3 trên cơ sở dữ liệu tri thức pgvector (đã import tài liệu Sách giáo khoa Việt Nam). Phản hồi trả về luôn đi kèm trích dẫn nguồn cụ thể (tên sách, chương, trang) để đảm bảo độ tin cậy.
5.4. Quản lý lớp học, Bài tập và Chấm điểm (LMS)
Tạo lớp và tham gia lớp học: Giáo viên tạo lớp học và cung cấp mã tham gia cho học sinh POST /classes.
Giao bài tập: Giáo viên có thể giao bài lab kèm theo các câu hỏi trắc nghiệm, điền số hoặc câu hỏi tự luận/giải thích hiện tượng POST /assignments.
Chấm điểm tự động (Auto-grading): Khi học sinh nộp bài, các đáp án trắc nghiệm hoặc tính toán số được đối chiếu tự động với kết quả chính xác từ Engine POST /submissions. Các câu hỏi tự luận được hỗ trợ chấm điểm bằng thang chấm điểm AI (AI-rubric) để giáo viên duyệt và cho điểm cuối cùng.
Phân tích Engagement: Dashboard dành cho giáo viên hiển thị thống kê tổng hợp tần suất làm bài, điểm trung bình và số lượng tương tác của từng học sinh với Gia sư AI GET /classes/{id}/engagement.
Cấu trúc dự án được phân chia một cách khoa học giữa phần xử lý Backend (Python) và phần giao diện Frontend (React).
ai-lab-simulator/
├── data/
│ └── specs/ # Thư viện đặc tả thí nghiệm có sẵn (Toán/Lý/Hóa) dạng JSON
├── docs/ # Tài liệu kiến trúc, hướng dẫn code chuẩn của dự án
├── frontend/ # Mã nguồn Frontend (React + Vite + TypeScript)
│ ├── api/ # Định nghĩa các hàm fetch gọi lên API backend
│ ├── src/
│ │ ├── components/ # Các component React tái sử dụng (SeriesPlot, Tutor, v.v.)
│ │ │ ├── kit/ # Asset kit dựng hoạt hình 2D các thiết bị thí nghiệm
│ │ │ └── UniversalPhysicsLayout/ # Bố cục thí nghiệm chuẩn hóa đa năng
│ │ ├── pages/ # Các trang chức năng của giáo viên và học sinh
│ │ └── AuthProvider.tsx # Quản lý phiên đăng nhập và định tuyến phân vai
│ └── package.json # Các phụ thuộc Node.js và câu lệnh xây dựng ứng dụng
├── src/ # Mã nguồn Backend (FastAPI + Python Compute Engine)
│ ├── api/ # Các file định nghĩa endpoint API của hệ thống
│ ├── config.py # Cấu hình biến môi trường và thiết lập mặc định của mô hình LLM
│ ├── db/ # Kết nối và thao tác với cơ sở dữ liệu Supabase
│ ├── engine/ # Các thuật toán cốt lõi tính toán mô phỏng vật lý
│ ├── kernels/ # Bộ xử lý giải phương trình vi phân và các phương pháp tính toán khoa học
│ ├── main.py # Điểm khởi chạy FastAPI chính của hệ thống
│ ├── models/ # Khai báo cấu trúc dữ liệu Pydantic dùng cho API
│ ├── specs/ # Logic đọc và xử lý thư viện ModelSpec
│ ├── tutor/ # Logic xử lý RAG và prompt cho Gia sư AI
│ └── validation/ # Logic kiểm định định luật khoa học (Validator)
├── tests/ # Hệ thống kiểm thử tự động (Unit test, Integration test, Contract test)
├── requirements.txt # Các phụ thuộc thư viện Python
└── docker-compose.yml # Cấu hình chạy ứng dụng qua môi trường Container
7. Danh mục mô phỏng (Simulations Catalog)
Dự án hiện tại hỗ trợ 3 môn học STEM cốt lõi với danh mục mô phỏng vô cùng đa dạng, được định cấu hình dưới dạng tệp tin đặc tả tại thư mục data/specs/:
Biến cố tung đồng xu (bien_co_dong_xu.json): Mô phỏng xác suất thực nghiệm tung đồng xu.
Cấp số nhân lùi vô hạn (cap_so_nhan_lui_vo_han.json): Minh họa trực quan tổng của một chuỗi cấp số nhân lùi vô hạn hội tụ.
Đạo hàm hàm sin (dao_ham_sin.json) & Đạo hàm hàm bậc hai (dao_ham_x_binh.json): Biểu diễn độ dốc tiếp tuyến chuyển động trực quan trên đồ thị.
Giới hạn số e (gioi_han_e.json): Khảo sát sự hội tụ của biểu thức $(1 + 1/n)^n$ tiến tới số Euler $e$.
Góc nội tiếp (goc_noi_tiep.json): Minh họa tính chất góc nội tiếp bằng nửa góc ở tâm chắn cùng một cung tròn.
Luật số lớn (law_of_large_numbers.json): Mô phỏng thực nghiệm lặp lại nhiều lần để thấy tần suất hội tụ về xác suất lý thuyết.
Tích phân hàm sin (tich_phan_sin.json) & Tích phân hàm bậc hai (tich_phan_x_binh.json): Minh họa diện tích hình phẳng dưới đường cong bằng tổng Riemann.
Chỉ thị Axit-Bazơ (acid_base_indicator.json): Sự thay đổi màu sắc của dung dịch chỉ thị theo giá trị pH.
Phản ứng Cacbonat (carbonate_acid_reaction.json): Phản ứng giữa muối cacbonat và axit sinh khí CO2.
Cân bằng hóa học (chemical_equilibrium.json): Mô phỏng sự chuyển dịch cân bằng theo nguyên lý Le Chatelier khi thay đổi nồng độ, nhiệt độ.
Sự kết tinh (crystallization.json): Quá trình hình thành tinh thể khi hạ nhiệt độ dung dịch bão hòa.
Phân hủy H2O2 (decomposition_h2o2.json): Động học phản ứng phân hủy hydro peroxit dưới xúc tác MnO2.
Điện phân (electrolysis.json): Quá trình điện phân dung dịch muối dưới tác dụng của dòng điện một chiều.
Khí lý tưởng (ideal-gas.json): Mối liên hệ giữa áp suất, thể tích và nhiệt độ theo định luật khí lý tưởng.
Trao đổi ion (ion-exchange.json): Phản ứng tạo chất kết tủa, chất điện li yếu hoặc chất khí giữa các ion trong dung dịch.
Kim loại phản ứng Axit (metal_acid_reaction.json): Mô phỏng tốc độ thoát khí H2 khi cho kim loại hoạt động mạnh/yếu vào dung dịch axit.
Chuẩn độ Axit-Bazơ (titration.json): Xác định nồng độ axit chưa biết bằng dung dịch bazơ chuẩn độ.
8. Hướng dẫn thiết lập & Chạy dự án (Setup & Execution Guide)
8.1. Yêu cầu môi trường
Python >= 3.11
Node.js >= 22
Tài khoản Supabase (để làm dịch vụ Database + Auth)
API key của OpenAI, DeepInfra và Nvidia NIM (phục vụ các tính năng thông minh)
8.2. Cài đặt và chạy Backend (FastAPI)
Tạo môi trường ảo và cài đặt thư viện phụ thuộc:
# Tạo virtual environment
python -m venv .venv
# Kích hoạt môi trường ảo
# Trên Windows:
.venv\Scripts\activate
# Trên macOS/Linux:
source .venv/bin/activate
# Cài đặt thư viện phụ thuộc
pip install -r requirements.txt
Thiết lập tệp cấu hình môi trường:
Sao chép tệp cấu hình mẫu và điền thông tin các khóa bí mật của bạn:
cp .env.example .env
Chạy Server phát triển Backend:
uvicorn src.main:app --reload --port 8000
Sau khi chạy, tài liệu Swagger API sẽ có sẵn tại địa chỉ: http://localhost:8000/docs.
8.3. Cài đặt và chạy Frontend (React + Vite)
Di chuyển vào thư mục frontend và cài đặt thư viện:
cd frontend
npm install
Chạy ứng dụng Frontend ở chế độ phát triển:
npm run dev
Ứng dụng sẽ hoạt động tại địa chỉ mặc định http://localhost:5173. Khi build production, tệp tĩnh sẽ được xuất bản ra thư mục frontend/dist và được FastAPI tự động phân phối tại cổng dịch vụ chính.
8.4. Các lệnh kiểm thử (Testing Commands)
Kiểm thử Backend (Unit & Integration tests):
python -m pytest tests --ignore=tests/contract -q
Kiểm thử Contract API (chạy sau khi deploy hoặc khởi chạy local server):
python -m pytest tests/contract -q
Kiểm thử khói (Smoke Test) toàn bộ luồng nghiệp vụ lớn:
python scripts/smoke-main-flows.py --full-ai
Kiểm thử Frontend & Type-check:
cd frontend
npm run test # Chạy kiểm thử vitest cho frontend
npm run typecheck # Kiểm tra tính toàn vẹn của kiểu dữ liệu TypeScript
