Erweiterungen verwalten

Was ist eine Erweiterung?#

Eine Erweiterung ist eine fertige Fachanwendung, zum Beispiel für Sitzungsprotokolle oder ein Dokumentenarchiv. Sie läuft vollständig auf deinem Server und nutzt automatisch, was die Plattform bietet:

• den Firmen-Login, damit sich niemand ein neues Passwort merken muss,
• die lokalen Sprachmodelle über die KI-Zentrale,
• eine eigene Adresse, zum Beispiel protocol.ki.firma.ch, mit verschlüsselter Verbindung,
• den Chat, in dem sie als Werkzeug zur Verfügung stehen kann,
• das Backup, in dem ihre Daten automatisch enthalten sind,
• dein Branding mit Firmenname und Logo.

Erweiterungen werden über denselben Lizenzschlüssel freigeschaltet wie die Plattform. Alle verfügbaren Erweiterungen und ihre Preise findest du im Katalog.

Verfügbare Erweiterungen anzeigen#

sudo aictl extension catalog

Der Befehl zeigt alle Erweiterungen, die deine Lizenz freischaltet, mit den Spalten EXTENSION, ENTITLED und INSTALLED. Unter INSTALLED steht die festgelegte Version oder -, wenn die Erweiterung nicht installiert ist.

catalog arbeitet ohne Internetverbindung mit der Lizenz, die auf dem Server gespeichert ist. Hast du gerade eine Erweiterung gekauft und sie fehlt noch, hol die neue Freischaltung ab:

sudo aictl license renew

Eine Erweiterung installieren#

sudo aictl extension install <name>

Die Installation läuft in dieser Reihenfolge:

1. Lizenz prüfen: Ist die Lizenz abgelaufen oder eingeschränkt, ist die Installation gesperrt. Die Erweiterung muss auf deiner Lizenz freigeschaltet sein, sonst erscheint: «your license does not include extension … — contact your vendor to add it».
2. Version bestimmen: Ohne --version nimmt aictl die neueste Version, die deine Lizenz erhalten darf.
3. Herunterladen: Liegt das Paket schon auf dem Server, wird es wiederverwendet. Sonst wird es heruntergeladen und auf Echtheit geprüft. Dafür müssen mindestens 6 GiB frei sein.
4. Plan anzeigen: Du siehst, was eingerichtet wird: Dienste, Modelle, Adressen, Datenbanken, benötigter Speicherplatz (mit dem freien Platz daneben) und wie viele Zugangsdaten nötig sind.
5. Bestätigen: «Continue?» mit Ja als Vorgabe.
6. Zugangsdaten abfragen: Braucht die Erweiterung Zugangsdaten, fragt die Installation verdeckt danach. Details unter Zugangsdaten.
7. Empfohlene Modelle: Für jedes empfohlene Modell eine Ja/Nein-Frage. Optionale Modelle werden nur erwähnt.
8. Rechner wählen: Hast du mehrere Rechner, wählst du für jedes Modell, wo es läuft. Siehe Modelle und Rechner.
9. Festhalten: Version und deine Antworten werden in den Einstellungen gespeichert.
10. Einrichten: Prozessorkerne, Grafikkarte und Speicherplatz werden geprüft, die Datenbank angelegt, die Modelle heruntergeladen und die Dienste gestartet. Die öffentliche Adresse wird erst gesetzt, wenn die Dienste gesund sind.
11. Zusammenfassung: Am Ende siehst du die Adresse der Erweiterung und Hinweise auf übersprungene Modelle oder optionale Zugangsdaten.

Ist die Plattform auf dem Server noch gar nicht installiert, hält aictl die Erweiterung nur fest und richtet sie bei der nächsten Installation ein. Hast du die Plattform mit aictl stop angehalten, starte sie vorher mit sudo aictl start, denn die Einrichtung braucht die laufende Plattform.

Optionen#

Ohne Terminal#

Läuft die Installation ohne Terminal, etwa in einem Skript, verhält sie sich wie mit --yes: Sie fährt ohne Bestätigung fort, installiert empfohlene Modelle, wählt die vorgeschlagenen Rechner und fragt keine Zugangsdaten ab. Fehlt dann ein Pflichtwert, scheitert die Einrichtung mit einem Hinweis auf secret set.

Gut zu wissen#

• Installierst du eine Erweiterung, die schon installiert ist, wirkt der Befehl wie ein Update oder eine Reparatur. Deine früheren Antworten bleiben erhalten.
• Ist das Paket als veraltet markiert, warnt die Installation: Es funktioniert weiter, bekommt aber keine neuen Versionen mehr.
• Brichst du die Rechnerwahl mit Esc ab, meldet aictl «setup cancelled», und die Installation der Erweiterung wird abgebrochen.
• Den Arbeitsspeicher prüft die Installation nicht. Prüfe selbst, ob Modelle und Dienste neben dem Bestehenden Platz haben.
• Die Prüfung von Prozessorkernen, Grafikkarte und Speicherplatz läuft erst beim Einrichten, also nach dem Herunterladen. Eine Erweiterung, die eine Grafikkarte zwingend braucht, setzt eine NVIDIA-Grafikkarte mit eingerichtetem Treiber voraus. Fehlt diese, nennt die Meldung die nötigen Pakete («install the NVIDIA driver and nvidia-container-toolkit first»). aictl installiert sie nicht selbst.

Installierte Erweiterungen anzeigen#

sudo aictl extension ls

Statt ls geht auch list. Die Tabelle hat diese Spalten:

Gibt es neuere Versionen, endet die Liste mit «N extension(s) have a newer version — sudo aictl extension update». Mit --json erhältst du pro Erweiterung name, installed, pinned, latest, updateAvailable und status.

Die Abfrage der neuesten Versionen dauert höchstens fünf Sekunden. Ohne Internet funktioniert die Liste trotzdem.

Erweiterungen aktualisieren#

Alle Erweiterungen auf den neuesten Stand bringen:

sudo aictl extension update

Oder nur eine bestimmte:

sudo aictl extension update <name>

• Läuft eine Erweiterung bereits auf der neuesten Version, bleibt sie unberührt: Es wird nichts heruntergeladen und kein Dienst neu gestartet.
• Sonst durchläuft das Update denselben Ablauf wie die Installation, mit Plan, Bestätigung und Fragen zu neuen Zugangsdaten, neuen empfohlenen Modellen und Rechnern für neue Modelle. --yes beantwortet alles mit der Vorgabe.
• Ein Update ist zugleich eine Reparatur: Eine unvollständige Einrichtung, ein gelöschtes Paket oder eine nachhinkende Version werden dabei nachgeholt.
• Schlägt bei «alle aktualisieren» eine Erweiterung fehl, geht es mit den übrigen weiter. Am Ende meldet der Befehl, wie viele fehlgeschlagen sind, und endet mit einem Fehlercode.
• --force richtet auch eine aktuelle Erweiterung erneut ein. Ein neuer Download findet dabei nicht statt.

Das normale sudo aictl update lässt Erweiterungen auf ihrer festgelegten Version. Nur extension update hebt sie bewusst an. Welche Updates bereitstehen, zeigen extension ls und license renew.

Auf eine ältere Version zurück#

extension update stuft nie zurück. Gibt es mit einer neuen Version Probleme, installierst du gezielt eine frühere:

sudo aictl extension install <name> --version <version>

Die Plattform behält die Bestandteile der vorherigen Version auf dem Server, damit dieser Schritt schnell und ohne Download geht. Ob die Daten, die die neuere Version geschrieben hat, zurückgeführt werden können, hängt von der Erweiterung ab. Erstelle vor einem Rückwechsel ein Backup.

Eine Erweiterung entfernen#

sudo aictl extension remove <name>

Statt remove geht auch rm. Der Befehl fragt nach («Its database, volumes, credentials and models are preserved.», Vorgabe Ja), hält die Dienste an, entfernt die Adresse und das Werkzeug im Chat und trägt die Erweiterung aus den Einstellungen aus.

Erhalten bleiben: Datenbank, Daten, Zugangsdaten und Modelle. Installierst du die Erweiterung später wieder, findet sie ihre Daten vor.

Sollen auch die Daten gelöscht werden:

sudo aictl extension remove <name> --purge

Mit --purge werden zusätzlich gelöscht: die Daten der Erweiterung, die Datenbanken und Sammlungen im Wissensspeicher, die sie als ihre eigenen ausweist, und ihre Zugangsdaten, sowohl die von dir gesetzten als auch die erzeugten. Zugangsdaten, die eine andere installierte Erweiterung noch nutzt, bleiben erhalten. Die Rückfrage hat hier die Vorgabe Nein.

Achtung: --purge löscht alle Daten der Erweiterung endgültig, zum Beispiel alle Protokolle oder Dokumente. Erstelle vorher ein Backup.

Gut zu wissen#

• Sprachmodelle bleiben immer erhalten, auch mit --purge. Entferne sie bei Bedarf mit sudo aictl model rm.
• Ohne Lizenzprüfung: Entfernen geht auch, wenn die Lizenz eingeschränkt ist.
• --yes überspringt die Rückfrage. Ohne Terminal und ohne --yes bricht der Befehl mit einem Fehler ab.
• Brichst du die Rückfrage ab, wird nichts entfernt, und der Befehl endet ohne Fehler.
• DNS-Einträge, die aictl für die Erweiterung angelegt hat, werden entfernt, solange sie unverändert sind.
• Aufräumschritte der Erweiterung laufen beim Entfernen mit. Scheitert der Schritt vor dem Herunterfahren, bricht das Entfernen ab; mit --force entfernst du die Erweiterung trotzdem. Ein Schritt nach dem Herunterfahren bricht nicht mehr ab, er meldet nur eine Warnung.
• --purge löscht auch Daten, die frühere Versionen hinterlassen haben.
• Nach einem einfachen remove löscht sudo aictl extension remove <name> --purge alles, was die Erweiterung hinterlassen hat: Daten, Datenbank und Zugangsdaten. Dafür behält remove eine kleine Beschreibung der Erweiterung auf dem Server, bis du sie mit --purge löschst oder die Erweiterung wieder installierst.

Alte Daten aufräumen#

sudo aictl extension prune [name]

Über die Zeit können Erweiterungen Daten zurücklassen, die keine aktuelle Version mehr nutzt. prune listet diese pro Erweiterung mit ihrer Grösse auf, fragt nach (Vorgabe Nein) und löscht sie dann endgültig. Ohne Namen prüft der Befehl alle installierten Erweiterungen. Mit dem Namen einer entfernten Erweiterung löscht er ihre zurückgelassenen Datenbereiche. Datenbank und Zugangsdaten löscht extension remove <name> --purge. Mit --yes entfällt die Rückfrage.

• Zwischengespeicherte Inhalte, die eine Erweiterung selbst wieder herunterlädt, etwa Modellgewichte, räumt die Plattform bei jedem Abgleich ohnehin auf.
• Was prune übrig lässt, kann Daten einer früheren Version enthalten. Erstelle im Zweifel vorher ein Backup.
• aictl status weist mit einer Warnung auf solche verwaisten Daten hin.

Was eine Erweiterung erhält#

sudo aictl extension env <name>

Der Befehl zeigt für jeden Dienst der Erweiterung, welche Einstellungen und Zugangsdaten er von der Plattform erhält, und zwar nur die Namen, nie die Werte. Er ist vor allem für deine IT oder den Support gedacht. Er setzt voraus, dass das Paket der Erweiterung auf dem Server liegt.

Einstellungen einer Erweiterung selbst anpassen#

Für Fachleute: Die Einstellungen einer installierten Erweiterung lassen sich mit einer eigenen Datei überschreiben, ohne das Paket zu verändern. Damit setzt du zum Beispiel einen eigenen Wert für eine Einstellung, gibst einem Dienst mehr Arbeitsspeicher oder legst eine andere Programmversion eines Dienstes fest.

• Die Datei liegt unter /etc/aictl/extensions/<name>/override.yaml. Sie enthält nur die Teile, die sich ändern sollen, im Aufbau der Paketbeschreibung. Name, Version und Beschreibung der Erweiterung lassen sich nicht ändern.
• aictl extension override lint [name] prüft die Datei und zeigt jede Änderung an.
• sudo aictl apply übernimmt sie. Ist die Datei fehlerhaft, läuft die Erweiterung im bisherigen Stand weiter, und apply meldet den Fehler.
• status und extension ls zeigen an, wenn eine Erweiterung mit einer eigenen Datei läuft. Die Datei ist im Backup.
• Aufbau und Regeln stehen in der Entwicklerdokumentation.

Wichtig: Eine Erweiterung mit eigener Anpassungsdatei ist vom Support ausgeschlossen. Für eine Supportanfrage entfernst du die Datei und führst sudo aictl apply aus.

Eine neue Erweiterung kaufen#

Schreib an [email protected]. Wir schalten die Erweiterung auf deiner bestehenden Lizenz frei, ein neuer Schlüssel ist nicht nötig. Danach holst du die Freischaltung mit sudo aictl license renew ab und installierst die Erweiterung wie oben beschrieben.

Eine eigene Erweiterung bauen#

Du bist nicht auf den Katalog beschränkt. Deine IT oder ein Dienstleister deiner Wahl kann eine eigene Erweiterung für deine Firma entwickeln, zum Beispiel für einen internen Ablauf oder die Anbindung einer Branchensoftware. Sie bekommt dieselben Bausteine wie jede andere Erweiterung: Firmen-Login, Sprachmodelle, eigene Adresse, Chat und Backup.

So läuft es ab:

1. Entwickeln: Wie das geht, steht in der Entwicklerdokumentation im Kundenportal.
2. Einreichen: Schick das fertige Paket an [email protected]. Wir prüfen und signieren es, denn die Plattform installiert nur signierte Pakete.
3. Installieren: Wir schalten die Erweiterung ausschliesslich auf deiner Lizenz frei. Sie erscheint nicht im öffentlichen Katalog. Danach installierst du sie wie jede andere mit sudo aictl extension install <name>.

Möchtest du deine Erweiterung auch anderen Firmen anbieten, kannst du sie als Drittentwickler im öffentlichen Katalog veröffentlichen.

Wichtig: Für selbst gebaute Erweiterungen bist du verantwortlich, sie sind nicht Teil des regulären Supports. Lies vorher das Kapitel zu Risiken und Verantwortung in der Entwicklerdokumentation.

Sonderfälle#

• Abgelehnte Installation: Mindestversion, Adresskonflikte, fehlende Zugangsdaten, Prozessorkerne, Grafikkarte und Speicherplatz werden geprüft, bevor die Erweiterung in den Einstellungen festgehalten wird. Scheitert eine Prüfung, bleibt alles, wie es war. Verlangt die Erweiterung ein neueres aictl, bring das Werkzeug mit sudo aictl update auf den neuesten Stand und wiederhole den Befehl.
• Update ausstehend: Scheitert ein Update erst beim Einrichten, ist die neue Version bereits festgelegt, während die alte weiterläuft. extension ls zeigt «update to … pending», sudo aictl apply versucht es erneut. Zurück zur alten Version geht es mit extension install <name> --version <alt>.
• Plan abgelehnt: Beantwortest du «Continue?» mit Nein, löscht aictl das eben heruntergeladene Paket wieder.
• Freischaltung entzogen: Steht eine installierte Erweiterung nicht mehr auf der Lizenz, warnen status und apply sofort und nennen das Datum, an dem sie angehalten wird. Nach 7 Tagen hält der Hintergrunddienst sie an. Ihre Daten bleiben erhalten. Installieren, Aktualisieren und erneutes Herunterladen werden schon vorher abgelehnt. Steht sie wieder auf der Lizenz, startet sie nach sudo aictl license renew von selbst wieder.
• Update-Zeitraum abgelaufen: Erscheint «this version was released after the license's update period ended», läuft alles Installierte weiter, und Sicherheitsupdates kommen weiterhin. Für neuere Versionen verlängerst du die Updates bei uns und führst danach sudo aictl license renew aus. Alternativ installierst du mit --version eine ältere Version.
• Paket fehlt auf dem Server: extension ls zeigt «bundle missing». sudo aictl apply lädt das Paket erneut herunter. Dafür braucht es eine Internetverbindung und eine gültige Freischaltung. Ist die Version auf dem Server nicht mehr verfügbar, installiere mit --version eine andere.
• Neustart des Servers: Die Dienste der Erweiterungen starten nach einem Neustart selbstständig wieder. Der Hintergrunddienst kümmert sich nur um die Kernplattform, nicht um die Erweiterungen. Hältst du einen einzelnen Dienst einer Erweiterung an (aictl stop <erweiterung>/<dienst>), bleibt er angehalten, bis du ihn startest oder apply ausführst.
• Nie eingerichtete Erweiterungen erscheinen in aictl status mit dem Hinweis «never provisioned» und in extension ls als «not provisioned». sudo aictl apply richtet sie ein.
• Backup: Die Daten der Erweiterungen und eigene Anpassungsdateien sind im Backup. Pakete nicht: Nach einer Wiederherstellung lädt die Plattform die Pakete erneut herunter. Siehe Backup und Wiederherstellung.