Getting started
AI assistant troubleshooting
Diagnose the local Qwen worker: not-ready status, the two separate on/off switches, role allowlists, FAQ fallback answers, and slow generation.
Getting started guide for day and boarding schools.
Last updated August 29, 2026
The assistant is a local model, not a hosted API. A sidecar process loads Qwen2.5-1.5B-Instruct as a quantised GGUF file through node-llama-cpp and exposes two endpoints on loopback: a health check and a chat completion. Every symptom below is either that process not running, one of the two on/off switches being off, a role allowlist, or the small model doing what a small model does.
How the worker is wired
| Setting | Default | What it controls |
|---|---|---|
| AI_WORKER_ENABLED | 0 | Server-wide switch. Anything other than 1 and the app reports the assistant as disabled and the systemd unit exits on start. |
| AI_WORKER_URL | http://127.0.0.1:11435 | Where the app looks for the worker. AI_WORKER_PORT sets the port the worker binds, always on loopback. |
| AI_WORKER_TOKEN | unset | Optional shared secret sent as an X-AI-Worker-Token header. Set on one side only and every call returns 401. |
| AI_MODEL_PATH | var/models/qwen2.5-1.5b-instruct-q4_k_m.gguf | The GGUF file to load. If it is missing the worker downloads the Q4_K_M build from Hugging Face on first start. |
| AI_CONTEXT_SIZE | 4096 | Context window. It has to hold the system prompt, the retrieved documentation, and the answer. |
| AI_CHAT_ALLOWED_ROLES | Platform Admin, Admin, Principal, Vice Principal, Teacher | Who sees AI Chat at all. Roles outside the list get a not-available message. |
| AI_CHAT_HELP_STYLE | llm | Set to faq to answer from the FAQ bank verbatim and skip the model entirely. |
| AI_CHAT_DATA_TOOLS | enabled | Set to 0 to stop help mode running the built-in read-only lookups such as live counts. |
On a server the worker runs as the systemd unit schoolyi-ai-worker, reads the same .env as the app, restarts on failure after fifteen seconds, and is capped at 1536M of memory. That cap is chosen for this quantisation on a small VPS; if the model is swapped for a larger one without raising the cap, the kernel will kill the process and the unit will loop.
Not ready and access problems
| Symptom | Cause | Fix |
|---|---|---|
| Status says the worker is disabled | AI_WORKER_ENABLED is not 1 | Set it in .env and restart both the app and schoolyi-ai-worker. The unit deliberately exits when the flag is off. |
| Status says the assistant is turned off for this school | School-level toggle is off | A Platform Admin flips the availability switch on the AI Chat page. This is stored per school and is independent of the environment flag. |
| Health check reports loading for several minutes | First start is downloading or loading the model | The worker answers health immediately but only reports ready once the GGUF file is loaded. Watch the service log; the first boot also downloads the file. |
| Every request returns 401 from the worker | Token mismatch | AI_WORKER_TOKEN must be identical for the app and the worker process, or unset on both. |
| Chat page loads but sending fails with 503 | Worker unreachable from the app | Confirm AI_WORKER_URL points at the port the worker bound, and that both processes are on the same host — the worker listens on loopback only. |
Answer quality and mode behaviour
Help mode retrieves documentation chunks and asks the model to answer from them, then checks the result. A reply that is empty, truncated, or not grounded in the retrieved material is discarded and replaced with the best FAQ answer. Draft notice and polish have no such safety net: they need a working worker and fail outright without one. Thumbs-down feedback is appended to a JSON Lines file on the server under var/ai-feedback rather than surfaced in the interface, so treat it as an engineering signal, not a support queue.
| Symptom | Cause | Fix |
|---|---|---|
| Draft notice and polish fail while help still works | Help can fall back to the FAQ bank; the writing modes cannot | Bring the worker back up. FAQ-only operation is a degraded mode for navigation help, not a substitute for generation. |
| Answers name the wrong screen | Retrieval matched the wrong documentation | Name the module in the question. The assistant answers from indexed documentation, so a vague question retrieves vague sources. |
| Long answers stop mid-sentence | Generation limit | Help replies are capped a few hundred tokens; ask a narrower question rather than one broad one. |
| Replies are slow when several staff use it at once | The worker serialises generation | One request is processed at a time and the rest queue. A 1.5B model on shared CPU is the constraint; keep threads short. |
| Learning Studio fails but staff chat works | Learning has no fallback path | Student and parent tools call the model directly and return an error when it is unavailable. Fix the worker rather than the page. |
Common questions
Quick answers in plain language.
AI Chat says the assistant is not ready. What do I check first?+
Check the two switches separately. The server switch is AI_WORKER_ENABLED=1 in .env; the school switch is a Platform Admin toggle on the AI Chat page. If both are on, curl the worker health endpoint on the server — by default http://127.0.0.1:11435/health — and read the status the app reports at /api/ai/status.
Does Schoolyi send AI requests to OpenAI or another hosted API?+
No. The assistant is a local sidecar process running Qwen2.5-1.5B-Instruct as a quantised GGUF file through node-llama-cpp. It binds to loopback on the app server and is not reachable from outside. The only outbound traffic is the one-off model download from Hugging Face the first time the worker starts.
Why does the assistant answer with a plain FAQ entry instead of a written reply?+
Two reasons produce that. With AI_CHAT_HELP_STYLE=faq the top matching FAQ is returned verbatim and the model is never called. Otherwise help mode still falls back to the FAQ answer when the generated reply is too short, cut off, or not grounded in the retrieved documentation — that is deliberate, so the assistant does not invent routes.
A teacher cannot open AI Tools at all. What controls that?+
Access is a role allowlist, AI_CHAT_ALLOWED_ROLES, which defaults to Platform Admin, Admin, Principal, Vice Principal, and Teacher. Removing Teacher from that list hides AI Chat for teachers. The MCP Server page is separately restricted to Platform Admin, and AI Learning Studio is additionally open to student and parent accounts.
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.