Getting started
AI assistant troubleshooting
Local worker health, help mode, FAQ bank, and chat access issues.
This getting started guide covers school software onboarding for K-12 day schools. Whether you are evaluating cloud school management software or configuring Schoolyi after go-live, you will find practical steps for school ERP go live checklist, migrate from Excel to school ERP - written for administrators and staff, not developers.
Last updated August 27, 2026
| Symptom | Check | Fix |
|---|---|---|
| AI Chat shows Not ready | Worker service and env | Set AI_WORKER_ENABLED=1; restart schoolyi-ai-worker; verify model path in .env. |
| Help answers wrong screen | Question specificity | Rephrase with module name; thumbs down to log feedback; check /docs for full guide. |
| Draft notice or polish disabled | Worker required | Help can run FAQ-only; draft/polish need running worker — not FAQ mode. |
| Teacher cannot open AI Tools | Role allowlist | AI_CHAT_ALLOWED_ROLES must include Teacher; Platform Admin configures in .env. |
| Slow responses | Model and memory | Qwen 1.5B on 1.5GB cap; avoid long threads; restart worker if OOM in journalctl. |
Common questions
Quick answers in plain language.
AI chat says worker not ready — what do I check?+
Confirm AI_WORKER_ENABLED=1, model downloaded (npm run ai:model:download), and schoolyi-ai-worker service running. Check GET /api/ai/status and worker health at AI_WORKER_URL/health. See /docs/deploy/ai-worker.
What is the difference between FAQ mode and LLM help mode?+
Default help uses Qwen2.5-1.5B with retrieved FAQs (RAG). Set AI_CHAT_HELP_STYLE=faq for verbatim top FAQ without the model. Draft notice and polish always need the worker.
Related searches
School leaders and IT teams often search for: how to module troubleshooting ai in school management software, best school software onboarding for K-12 schools, Schoolyi module troubleshooting ai guide, school ERP go live checklist, migrate from Excel to school ERP, and school software training guide.