Fehlerbehebung

Zuerst: Status prüfen#

sudo aictl status

Der Befehl prüft alle Bausteine, die Erweiterungen, die Modelle, die Anmeldung, alle angehängten Rechner und die Lizenz. Alles, was nicht in Ordnung ist, wird mit [warn] oder [FAIL] markiert, meistens zusammen mit dem Befehl, der das Problem behebt. Wie du die Ausgabe liest, steht unter Betrieb im Alltag.

Automatische Diagnose#

sudo aictl doctor

Die Diagnose geht über status hinaus und prüft die Umgebung, von der die Plattform abhängt. Zu jedem Problem zeigt sie in einer Zeile fix: an, wie du es behebst.

Die Diagnose endet nur bei einem [FAIL] mit einem Fehler, Warnungen nicht.

Meldungen ansehen#

sudo aictl logs <erweiterung>
sudo aictl logs <erweiterung>/<dienst> -f
sudo aictl logs -n 100 --since 10m

Alle Möglichkeiten stehen unter Betrieb im Alltag. Die Meldungen helfen auch unserem Support bei der Analyse.

Häufige Probleme#

Die Adresse ist im Browser nicht erreichbar#

• Zeigt der DNS-Eintrag auf die richtige IP-Adresse? Siehe Domain und Zertifikate.
• Sind die Ports 80 und 443 in der Firewall und im Router offen?
• Ist der Bereich überhaupt veröffentlicht? sudo aictl proxy hostname zeigt es. Nach einer Änderung ist sudo aictl apply nötig.
• Läuft die Plattform? Prüfe mit sudo aictl status.

Der Browser meldet ein unsicheres Zertifikat#

• Automatische Zertifikate werden kurz nach dem Start ausgestellt. Warte ein paar Minuten. Bleibt die Warnung, prüfe mit sudo aictl doctor, ob die Zugangsdaten deines DNS-Anbieters gespeichert und gültig sind.
• Ein eigenes Firmenzertifikat muss alle Adressen abdecken, am besten als Wildcard-Zertifikat für *.<deine-domain>. Adressen mit mehreren Stufen, etwa api.kb.ki.firma.ch, muss das Zertifikat einzeln aufführen.
• Abgelaufen? status warnt 30 Tage vor dem Ablauf eines eigenen Zertifikats und meldet einen Fehler, sobald es abgelaufen ist. Spiele das neue Zertifikat mit sudo aictl proxy set-cert ein und übernimm es mit sudo aictl apply.

Die Antworten sind sehr langsam#

• Ist das Modell zu gross für den Arbeitsspeicher? Wähle ein kleineres Modell.
• Ohne Grafikkarte sind grosse Modelle deutlich langsamer.
• Arbeiten viele Personen gleichzeitig, hilft ein zusätzlicher Modell-Rechner.

Niemand kann sich anmelden#

• sudo aictl auth info zeigt, ob und wo der Firmen-Login erreichbar ist. Er funktioniert nur, wenn eine Domain eingerichtet und der Bereich auth veröffentlicht ist.
• status zeigt im Abschnitt «Sign-in» für jeden Bereich, ob die Anmeldung funktioniert. Schlägt eine Zeile fehl, hilft meistens sudo aictl apply.
• Meldet status bei tls-cert «does not chain to a trusted root CA», fehlt den Diensten das Stammzertifikat deines Firmenzertifikats. Die Anmeldung scheitert dann, auch wenn «Sign-in» grün ist. Spiele das Zertifikat mit --ca erneut ein, siehe Domain und Zertifikate.
• Ist der Firmen-Login aktiv, hat der Chat kein eigenes Anmeldeformular mehr. Als Notzugang dienen das Administrationskonto akadmin in der Benutzerverwaltung und das Konto aictl-admin unter /fallback/login der KI-Zentrale. Beide Passwörter zeigt sudo aictl auth info --show-password.
• Das angezeigte Startpasswort von akadmin gilt nur, bis es in der Benutzerverwaltung geändert wurde.

Nach einem Stromausfall läuft nicht alles#

Die Plattform startet nach einem Neustart des Servers automatisch, der Hintergrunddienst bringt die Bausteine innerhalb von etwa 30 Sekunden hoch. Fehlen trotzdem Dienste:

sudo aictl restart

Hast du die Plattform vorher mit aictl stop angehalten, bleibt sie absichtlich aus. Starte sie mit sudo aictl start.

Ein Port ist belegt#

install, update und apply brechen ab, wenn ein anderes Programm einen Port der Plattform belegt, und nennen es, zum Beispiel:

port 443 (…) is held by nginx (pid 812, nginx.service) — sudo systemctl disable --now nginx.service

Halte das andere Programm an, oder lege den Port der Plattform in den Einstellungen auf einen anderen Wert und führe den Befehl erneut aus. Der Server sollte ausschliesslich für swaiz verwendet werden.

Der Speicherplatz wird knapp#

status warnt unter 5 GiB freiem Platz und meldet unter 1 GiB einen Fehler. Dann schlagen Schreibvorgänge fehl, zuerst in der Datenbank, und die Symptome zeigen oft an eine ganz andere Stelle. So schaffst du Platz:

• nicht mehr benötigte Modelle mit sudo aictl model rm <modell> entfernen,
• nicht mehr genutzte Daten von Erweiterungen mit sudo aictl extension prune löschen,
• alte Backups auf dem Server aufräumen, künftig automatisch mit backup --keep (siehe Alte Backups aufräumen).

Das Herunterladen einer Erweiterung braucht mindestens 6 GiB freien Platz.

Die Systemuhr geht falsch#

status warnt, sobald die Uhr zwei Minuten oder mehr vom Lizenzserver abweicht, und eine Installation kann die Lizenz dann ablehnen. Schalte die Zeitsynchronisierung ein:

sudo timedatectl set-ntp true

Hinweis zur Lizenz#

Siehst du einen Lizenzhinweis, prüfe mit sudo aictl license check, ob der Server den Lizenzserver erreicht. Was bei fehlender Verbindung passiert und was du tun kannst, steht unter Lizenz.

Die Einstellungsdatei ist fehlerhaft#

Nach einer Änderung von Hand an /etc/aictl/spec.yaml brechen apply und update mit einer Fehlermeldung ab. Unbekannte oder falsch geschriebene Einstellungen werden nie still ignoriert. Die Plattform läuft mit dem zuletzt angewendeten Stand weiter, und status zeigt im Abschnitt «Deployment» eine Warnung spec.

So siehst du, was du geändert hast:

sudo diff /var/lib/aictl/spec.yaml /etc/aictl/spec.yaml

Korrigiere die Datei und führe sudo aictl apply aus. Solange die Datei fehlerhaft ist, pausieren Modell-Verteilung und geplante Aufgaben. Wird der Hintergrunddienst in dieser Zeit neu gestartet, wartet er, bis die Datei wieder stimmt.

Die Einstellungsdatei wurde gelöscht#

Fehlt /etc/aictl/spec.yaml, stellt aictl sie beim nächsten Befehl automatisch aus der Kopie unter /var/lib/aictl/spec.yaml wieder her und meldet das.

Fehlt auch die Kopie, verweigert install die Arbeit, statt die Plattform mit leeren Einstellungen neu aufzusetzen. Hole die Datei dann aus einem Backup (dort liegt sie als configs/spec.yaml) oder stelle das ganze Backup wieder her.

Fehlen nur die übrigen erzeugten Dateien unter /etc/aictl, erzeugt sudo aictl apply sie neu.

Die Zugangsdaten der Plattform fehlen#

Fehlt die Datei mit den Zugangsdaten der Plattform (/var/lib/aictl/stack.env), verweigern die Befehle die Arbeit. install erzeugt bewusst keine neuen, weil neue Passwörter die Plattform von ihren eigenen Daten aussperren würden. Hole die Datei aus einem Backup zurück (dort liegt sie als secrets/stack.env) oder stelle das ganze Backup wieder her. Willst du wirklich mit leeren Daten neu beginnen, entferne die Plattform zuerst mit sudo aictl uninstall.

Die Zugangsdaten der Erweiterungen fehlen#

Fehlt /var/lib/aictl/ext-secrets.env, meldet status einen Fehler ext secrets. Die laufenden Erweiterungen arbeiten weiter, lassen sich aber nicht neu einrichten.

• Am besten holst du die Datei aus einem Backup zurück (secrets/ext-secrets.env) und führst sudo aictl apply aus. Dann ist alles wie vorher.
• Ohne Backup erzeugt sudo aictl apply neue Passwörter und Schlüssel. Zugangsdaten, die du selbst gesetzt hast, musst du mit sudo aictl secret set erneut setzen. Werte, die eine Erweiterung selbst erzeugt hat, sind danach neu. Was sie damit früher signiert hat, kann ungültig werden.

Nach einer Aufräumaktion starten die Dienste nicht#

Wurden auf dem Server nicht benutzte Teile der Laufzeitumgebung aufgeräumt oder wurde sie neu installiert, erkennt aictl das beim nächsten Start und baut die betroffenen Dienste neu auf (a network the containers were created on is gone — recreating them on the current one). Fehlen ganze Dienste, baut sudo aictl start die Plattform vollständig neu auf. Das braucht eine gültige Lizenz.

Der Hintergrunddienst läuft nicht#

status meldet im Abschnitt «Cluster» einen Fehler control-plane. Starte den Dienst und schau nach der Ursache:

sudo systemctl start aictl
sudo journalctl -u aictl -n 100

Häufige Ursachen sind eine fehlerhafte Einstellungsdatei (siehe oben) oder ein anderes Programm auf Port 7700. sudo aictl apply und sudo aictl update richten den Dienst bei Bedarf neu ein und starten ihn, auch wenn update sonst nichts zu tun hat.

Eine Erweiterung ist nicht bereit#

sudo aictl extension ls zeigt den Zustand jeder Erweiterung:

Fehlen Zugangsdaten, nennt die Fehlermeldung die fehlenden Namen. Setze sie mit sudo aictl secret set <NAME> und führe sudo aictl apply aus.

Wurde eine Installation verweigert, weil der Server zu wenige Prozessorkerne, keine passende Grafikkarte oder zu wenig Speicherplatz hat, bleibt die Erweiterung trotzdem eingetragen, und jedes weitere apply meldet den Fehler erneut. Behebe die Ursache oder entferne die Erweiterung mit sudo aictl extension remove <name>. Mehr dazu unter Erweiterungen verwalten.

Ein Modell-Rechner ist nicht erreichbar#

status zeigt einen nicht erreichbaren Rechner als Warnung, sudo aictl node ls als unreachable. Seine Modelle werden nicht mehr angefragt, solange er weg ist.

• Ist der Rechner eingeschaltet, und läuft die Modell-Engine dort?
• Lässt die Firewall des Rechners den Port 11434 vom Hauptserver aus zu?
• Hat der Rechner eine neue IP-Adresse bekommen? Dann entferne ihn mit sudo aictl node rm <name> und lass ihn neu beitreten. Gib Modell-Rechnern deshalb am besten feste Adressen.

Sobald der Rechner wieder erreichbar ist, werden seine Modelle innerhalb von etwa 30 Sekunden wieder angefragt.

Lokale Modelle antworten nicht#

Prüft status, ob die KI-Zentrale die Modell-Engine erreicht, und schlägt das fehl, blockiert meistens eine Firewall auf dem Server den Weg zum Port 11434. Ist die Firewall ufw aktiv, legt sudo aictl apply die nötigen Regeln selbst an. Bei einer anderen Firewall nennt die Meldung, welche internen Netze der Plattform den Port erreichen müssen.

Die Websuche liefert nichts#

status zeigt bei der Websuche eine Warnung, wenn keine Suchmaschine Ergebnisse liefert. Meistens blockieren die öffentlichen Suchmaschinen Anfragen aus deinem Netz. Die Plattform prüft einmal täglich, welche Suchmaschinen antworten, und stellt automatisch um. Eine sofortige Prüfung erzwingst du mit sudo aictl install. Die Websuche ist nie ein Fehler, der Chat funktioniert ohne sie weiter.

Wenn alles nichts hilft#

Die Installation lässt sich jederzeit erneut ausführen. Sie behält deine Einstellungen und Daten und bringt in Ordnung, was fehlt:

sudo aictl install

Dafür braucht der Server eine Verbindung zum Lizenzserver. Fragen, die du bei der ersten Installation leer gelassen hast, stellt sie erneut.

Support kontaktieren#

Schreib an [email protected] und schick uns:

• die Ausgabe von sudo aictl status und sudo aictl doctor,
• die Ausgabe von sudo aictl version,
• bei Problemen mit einer Erweiterung die Ausgabe von sudo aictl logs <erweiterung> -n 200,
• eine kurze Beschreibung, was du getan hast und was passiert ist.

So können wir dir am schnellsten helfen.