Zum Hauptinhalt springen

Umgebungsvariablen konfigurieren

Die Konfiguration von PlantPulse AI beginnt bei einer einzigen Datei: /etc/kopens/plantpulse-ai.env.

sudo vi /etc/kopens/plantpulse-ai.env
Die maßgebliche Konfiguration liegt unter /etc/kopens/

Der Pfad lautet /etc/kopens/plantpulse-ai.env. Sie liegt nicht im Installationsverzeichnis (/opt/kopens/plantpulse-ai-docker), sondern außerhalb des Repo-Baums, mit den Rechten 0600. Die drei Produkte platform · ai · studio verwenden /etc/kopens/plantpulse-<product>.env nach derselben Konvention.

🔴 Ändern Sie compose/.env nicht. Niemand liest sie — der Stack ändert sich dadurch nicht.

Passwörter und API-Schlüssel nicht direkt bearbeiten

Bei *_PASSWORD · *_API_KEY aus der Tabelle unten genügt das Bearbeiten der Datei nicht. Werte, deren maßgebliche Quelle das Serverkonto ist (wie bei Neo4j), müssen auch serverseitig geändert werden; bei falscher Reihenfolge bleibt die Authentifizierung defekt. Verwenden Sie das dafür vorgesehene Werkzeug — Passwörter und API-Schlüssel ändern.

Werte leben an drei Orten (2026.10)​

Ab 2026.10 enthält die Host-env nur noch Werte, die nur für diese Installation gelten. Alles Übrige wird mit dem Release versioniert.

WoWasWie ändern
Host-env /etc/kopens/plantpulse-ai.envHardwareform (PP_HW_PROFILE) · Standortwerte (Sprache · Zeitzone · Zertifikatsname) · Plattformverbindung · GeheimnisseDiese Datei bearbeiten und die Dienste neu erstellen
Hardwareprofil compose/profiles/<모양>.envWerte, die je Hardware abweichen — GPU-Anteile der drei vLLM-Instanzen und deren SummengrenzeLegt das Release fest
compose-StandardwerteProduktstandards — Images · Modellnamen und -pfade · Dienst-TuningLegt das Release fest. Ein abweichender Wert in der Host-env überschreibt dies nur für diese Installation

PP_HW_PROFILE ist entweder gb10 (GB10 · aarch64) oder g7e (AWS g7e · x86_64). Die Vorlage trägt dies bereits ein; fehlt der Wert oder passt er nicht zur Architektur der Maschine, startet der Stack nicht.

In den Tabellen unten sind Variablen, die nicht in der Host-env-Vorlage stehen (also solche mit angegebenem Standardwert), compose-Standardwerte. Sie unverändert zu verwenden ist der Normalfall; nur bei einer Änderung tragen Sie diese Zeile mit einem abweichenden Wert in die Host-env ein.

Nach einer Wertänderung müssen die Dienste neu erstellt werden (docker restart liest die env nicht erneut ein).

cd /opt/kopens/plantpulse-ai-docker
bin/restart.sh

Das Startskript prüft vor dem Hochfahren mit bin/lint-env.sh zeilenweise, ob jede Zeile am richtigen Platz steht, und startet nicht, wenn auch nur einer der folgenden Punkte zutrifft.

BefundWas
releaseImage-Referenzen — DOCKER_REGISTRY · DOCKER_NAMESPACE · UPSTREAM_* · *_IMAGE · PI_IMAGE_TAG_* · PP_IMAGE_TAG mit Wert
profileHardwareprofil-Schlüssel (z. B. LLM_GPU_UTIL)
redundantZeilen, die einen compose-Standardwert unverändert wiederholen
derivedPP_HOST — wird auf dem Host aus PP_DATALAKE_ADMIN_URL berechnet
unknownSchlüssel, die nirgends gelesen werden
renamedUmbenannte Altschlüssel (CH_* → CO_*) — meldet nicht «löschen», sondern «verschieben» (siehe „Copilot-Konfiguration" unten)

Außerdem stoppen eine ${…}-Ersetzung an Wertstellen, ein fehlendes PP_HW_PROFILE sowie eine Überschreitung der GPU-Anteile den Start. Werte, die von compose-Standardwerten abweichen, gelten als beabsichtigtes Überschreiben und erzeugen nur einen Hinweis ([note]). Die Prüfung gibt je Zeile den Grund aus und zusätzlich einen sed-Befehl (mit Backup), der alle zu löschenden Zeilen auf einmal entfernt. renamed-Zeilen landen nicht in der Löschliste; dafür wird separat ein sed ausgegeben, das nur den Namen ändert. Werte werden nicht ausgegeben.

Zeilen, die nichts bewirken, wenn man sie stehen lässt, werden nur als [warn] gemeldet und blockieren den Start nicht — das sind in diesem Release die noch gelesenen Alias-Altnamen (alias), Altzeilen mit demselben Wert wie der neue Name (oldname) und Zeilen mit demselben Wert, den der Video-/Audio-Schalter liefert (media-same). Die Prüfung gibt dazu eine einzelne sed-Zeile aus, die all dies auf einmal bereinigt, und bin/doctor.sh zeigt diese Zeilen nicht als «bad», sondern separat als «old or redundant lines». Liegt der Wert des Video-/Audio-Schalters außerhalb von true · false oder ist PI_INBOUND_API_KEY leer, wird der Start gestoppt (siehe „Video- und Audio-Erfassung" · „Inbound-Schlüssel der Backend-Dienste" unten).

Images und Registry​

🔴 Ab 2026.10 werden Image-Referenzen nicht mehr in die Host-env eingetragen. Welches Image mit welchem Tag startet, legt die compose des Releases fest; steht eine der folgenden Variablen in der Host-env, stoppt die Vorstartprüfung den Start mit release. Grund: Auf dem Host verbliebene Pins haben das nächste Release verdeckt, und beim Erstellen von Bundles sind sie dorthin ausgeblutet.

VariableBedeutung
DOCKER_REGISTRY · DOCKER_NAMESPACEBezugsort der eigenen Images (docker.kopens.io / pi)
UPSTREAM_DOCKERHUB · UPSTREAM_NVCRInterner Proxy, der externe Images stellvertretend bezieht
PP_IMAGE_TAGStandard-Tag des Satzes. In der Vorlage nur als leere Zeile vorhanden
PI_IMAGE_TAG_<component>Wenn nur eine Komponente auf einen anderen Snapshot gepinnt wird (Hotfix · Rollback). Es gibt dreizehn davon; das Suffix ist der Image-Name in Großbuchstaben (plantpulse-timeseries-insight-api → PI_IMAGE_TAG_TIMESERIES_INSIGHT_API)

Muss im Notfall nur eine Komponente mit einem anderen Tag starten, geben Sie dies nicht über die Datei, sondern über die Shell-Umgebung nur für diesen Lauf mit. Der nächste normale Start fällt auf das Release-Tag zurück.

cd /opt/kopens/plantpulse-ai-docker
PI_IMAGE_TAG_RAG_API=<태그> bin/up.sh

In 2026.10 ist die Zahl der eigenen Images auf zwölf gestiegen — der Digital Thread (plantpulse-digital-thread-api) ist neu hinzugekommen, und auch LightRAG und LiteLLM laufen nicht mehr mit den Original-Images, sondern mit von uns gekapselten Images (pi/plantpulse-lightrag · pi/plantpulse-litellm). Auch diese beiden gekapselten Images folgen wie die übrigen eigenen Images dem Monats-Tag (2026.10); zum Pinnen einzelner Images dienen PI_IMAGE_TAG_LIGHTRAG · PI_IMAGE_TAG_LITELLM. Die gekapselten Basen sind LightRAG v1.5.7 · LiteLLM v1.103.0.

Mit Re-Release 3 von 2026.10 kam ein weiteres hinzu, also dreizehn — das Audio-Bibliotheks-Image pi/plantpulse-asr-audio für das Transkriptions-Serving (ca. 130 MB; zum Pinnen PI_IMAGE_TAG_ASR_AUDIO). Es startet nur bei Installationen mit aktiviertem Video/Audio, ist im Bundle aber immer enthalten (siehe „Video- und Audio-Erfassung" unten).

PP_IMAGE_TAG bleibt leer

Bleibt der Wert leer, wird das in compose fest eingetragene CalVer-Literal verwendet. Dieses Literal wird bei jedem Release von bin/bump-version.sh fortgeschrieben, sodass der Release-Monat nur an einer einzigen Stelle steht. Mit gesetztem Wert stoppt die Vorstartprüfung den Start.

YYYY.MM ist ein «bewegliches» Tag

Ein erneutes Release im selben Monat überschreibt es. Um einen Stand festzunageln, geben Sie das Datums-Tag (YYYY.MM-YYYYMMDD) über den oben beschriebenen Shell-Umgebungsweg mit — prüfen Sie dabei je Image, ob es existiert, und pinnen Sie nur vorhandene einzeln: Es existiert nicht für alle, und ein pauschaler Wechsel lässt den Pull für fehlende Images scheitern.

Die Admin-Konsole besteht aus zwei Images — zum Pinnen dienen PI_IMAGE_TAG_ADMIN_API und PI_IMAGE_TAG_ADMIN_WEB (sind beide leer, folgen sie PP_IMAGE_TAG). Da sie aus demselben Commit stammen, müssen beim Einzel-Pinnen immer beide gemeinsam gesetzt werden. Laufen sie auseinander, wird die Konsole mit einem Backend gepaart, das die von ihr aufgerufenen APIs nicht besitzt.

Sprache und Zeitzone​

VariableStandardwertBedeutung
PP_LANGkoStandardsprache der Installation — die Sprache an Stellen ohne Anfrage, etwa E-Mails · geplante Ausführungen · gespeicherte Beiträge. Auch die vom Server geschriebenen Automatisierungstexte — Zusammenfassungen · Durchlaufgründe · PDF-Abschnittsnamen · Excel-Blattnamen — erscheinen in dieser Sprache → Automatisierung — Berichtstitel. In der Copilot-Oberfläche haben die selbst gewählte Sprache → die Browsersprache Vorrang; dieser Wert gilt nur, wenn keine von beiden Koreanisch · Englisch ist → Oberflächensprache. Die Admin-Konsole folgt diesem Wert nur bei den Namen der Startseiten-Karten; alle übrigen Seiten richten sich nach der Sprachumschaltung auf der Anmeldeseite (English · 한국어) · Gültig sind nur ko und en. Ist der Wert leer oder ein anderer, starten die Dienste nicht (Standard der Installationsvorlage ko)
PP_TZAsia/SeoulZeitzone der Installation — alle Dienste und das Host-OS verwenden diese eine. Das Installationsprogramm wählt sie aus (Reihenfolge: bei der Installation angegebener Wert → bereits in der env vorhandener Wert → Host-Zeitzone (sofern nicht UTC) → Asia/Seoul)
LIGHTRAG_SUMMARY_LANGUAGEKoreanSprache, in der RAG Wissen zusammenfasst

Die Zusammenfassungssprache ist bewusst von der Oberflächensprache getrennt: Auch wenn die Oberfläche auf Englisch läuft, ist der Korpus (SOPs Vor-Ort) häufig auf Koreanisch.

Was von der Plattform mitbenutzt wird​

🔴 Der AI-Stack startet weder PostgreSQL noch Aster TSDB, Redis oder RustFS. Er nutzt die Plattforminstallation gemeinsam. Sind diese Werte falsch, startet AI zwar, speichert aber nichts.

Plattform-Zugangsdaten erhält der Container «beim Start»​

Ab 2026.10 übergibt compose Konten, Passwörter und Ports der Plattformspeicher (PG · Aster TSDB · Redis · RustFS) nicht mehr an die Container. Die sechs Dienste, die sie nutzen (copilot-web · timeseries-insight-api · lightrag · rag-api · digital-thread-api · litellm), beziehen sie beim Start von der Zugangsdaten-API der Plattform, übertragen sie auf ihre eigenen Namen und starten dann die Anwendung. In der Host-env stehen nur zwei Dinge: die Adresse dieser API und der Schlüssel.

VariableBedeutung
PP_DATALAKE_ADMIN_URLData-Lake-Verwaltungs-API der Plattform — https://<플랫폼 호스트>:4950. Der Host dieser URL ist zugleich der Plattform-Host
PP_DATALAKE_ADMIN_API_KEYSchlüssel dieser API. Die gleichnamige Zeile unverändert aus /etc/kopens/plantpulse-platform.env des Plattform-Hosts übernehmen

Die Vorlage enthält beide Zeilen mit Platzhalterwerten, und die interaktive Installation (INTERACTIVE=1) fragt beide Werte ab. Die nötigen Vorbereitungen finden Sie unter Installationsübersicht (Plattform-Allowlist · Trust Anchor root.crt).

Ohne erfolgreichen Bezug «stoppt» der Container
  • Ist nur einer der beiden Werte gesetzt, verweigert der Container den Dienst.
  • Schlägt der Bezug fehl, stoppt der Container mit FATAL (Verbindungsfehler · 5xx werden kurz wiederholt, 4xx sofort abgebrochen). Es gibt keinen Cache, mit dem er auf dem letzten Wert startet.
  • Das Serverzertifikat wird ausschließlich gegen /etc/kopens/ca/root.crt geprüft. Fehlt die Datei, ist dies FATAL, und es gibt keinen Weg, die Prüfung abzuschalten.

Wurde das Passwort auf der Plattform geändert, ist auf AI-Seite keine Datei anzupassen — ein Neustart des Containers holt den neuen Wert. Vom Bezug bleiben im Log nur Schlüsselnamen und Anzahl zurück (docker logs <컨테이너> 2>&1 | grep credentials:).

Auch Host-Skripte beziehen die Daten auf demselben Weg. Die DB-Provisionierung vor dem Start (provision-platform-db.sh), manuell ausgeführte DB-Migrationsskripte und die Vorabprüfung von install.sh START=1 rufen dieselbe API nach denselben Regeln auf (Prüfung gegen root.crt). Deshalb stehen auch in der Host-env keine Plattformkonten und -passwörter. Bei einem Fehlschlag wird der Grund in einer [FATAL] [platform-credentials] …-Zeile genannt (nicht erreichbar · 401/403 · kein Schlüssel · URL/Schlüssel/CA fehlt) und abgebrochen. Nur wenn Sie an einer Stelle ohne Plattformzugang testen, können Sie die Werte über die Shell-Umgebung dieses Laufs mitgeben — dann gewinnen diese.

Von den Plattformwerten verbleiben in der Host-env nur die folgenden.

VariableBedeutung
PP_DATALAKE_ADMIN_URL · PP_DATALAKE_ADMIN_API_KEYSiehe oben — Bezugsort der Zugangsdaten
PP_API_URL · PP_API_TOKENPlattform-V5-API — steht nicht im Zugangsdatenspeicher und verbleibt daher in der Host-env (siehe „Plattform-Integrations-MCP" unten)
PP_PG_PORT · PP_CASSANDRA_PORTIn der Vorlage nur auskommentiert vorhanden. Werden nur von Host-Skripten gelesen; bei den Standardports der Plattform leer lassen

Der Plattform-Host (PP_HOST) wird nicht eingetragen — der Host aus PP_DATALAKE_ADMIN_URL ist zugleich dieser, und Container wie Host-Skripte berechnen ihn nach derselben Regel. Die von AI genutzten PG-Datenbanknamen (PP_LIGHTRAG_PG_DB standardmäßig lightrag usw.) sind compose-Standardwerte.

Die eigenen PG-Daten der AI-Anwendungen liegen in DB pi des Plattform-PG, je Anwendung in eigenen Schemata (Copilot co · Digital Thread dt, Konto PP_PG_USER). Die DB ch aus Altinstallationen wird beim Start nach pi.co migriert.

Beim Upgrade auf 2026.10 — eine alte env startet so nicht

Das Installationsprogramm und update.sh erstellen eine vorhandene env nicht neu. In env-Dateien von 2026.09 und älter verbleiben viele Zeilen, die nicht mehr am richtigen Platz sind — Image-Referenzen, GPU-Anteile, Werte identisch zu compose-Standardwerten, PP_HOST, Plattformkonten und -passwörter (PP_PG_USER · PP_PG_PASSWORD · PP_CASSANDRA_* · PP_REDIS_PASSWORD · PP_S3_* usw.) —, sodass die Vorstartprüfung den Start stoppt. Bereinigen Sie die Datei vor dem Upgrade.

cd /opt/kopens/plantpulse-ai-docker
sudo bash bin/lint-env.sh                 # 무엇이 남았나 — 바꾸지 않습니다
sudo cp -p /etc/kopens/plantpulse-ai.env ~/plantpulse-ai.env.bak-$(date +%Y%m%d-%H%M)
# lint-env 가 찍은 sed 한 줄을 그대로 실행한 뒤, 하드웨어 모양을 더합니다(GB10 = gb10 · g7e = g7e)
grep -q '^PP_HW_PROFILE=' /etc/kopens/plantpulse-ai.env || echo 'PP_HW_PROFILE=gb10' | sudo tee -a /etc/kopens/plantpulse-ai.env >/dev/null
sudo bash bin/lint-env.sh && bin/restart.sh
  • Vor dem Löschen eintragen — PP_DATALAKE_ADMIN_URL · PP_DATALAKE_ADMIN_API_KEY neu eintragen und den Trust Anchor ablegen. Zu den alten Plattformkonto-Zeilen sagt die Prüfung nur «löschen», tragen Sie diese beiden also zuerst ein.
  • Alte CH_*-Zeilen erkennt die Prüfung als renamed und gibt separat ein sed aus, das nur den Namen ändert — führen Sie es aus, wandert der Wert unverändert nach CO_* (siehe „Copilot-Konfiguration" unten).
  • Absichtlich vom Standard abweichende Werte (z. B. Modellpfade) bleiben als override-Hinweis bestehen und werden nicht gelöscht.
Anlagenalarme kommen über MQTT

Der Copilot abonniert die Anlagenalarme der Plattform über MQTT (ab 2026.09, zuvor Kafka). Die Broker-Adresse folgt dem Host aus PP_API_URL, der Standardport ist 1884 (TLS) — es ist also nichts gesondert einzutragen. Das frühere PP_KAFKA_PORT entfällt — selbst wenn es noch vorhanden ist, liest es niemand.

Plattform-Integrations-MCP​

Der Kanal, über den der Copilot-Chat Echtzeitdaten der Plattform abruft.

VariableBedeutung
PP_API_URLBasis-URL von server-web der Plattform
PP_API_TOKENVon der Plattform ausgestelltes API-Token
Auch mit «falschem» Token startet der Stack

compose verlangt beide Werte zwingend — sind sie leer, startet der Stack nicht. Verbleiben Platzhalter, startet bin/up.sh ihn nicht. Bei einem falschen Token startet der Stack jedoch normal, und nur die Plattform-MCP-Werkzeuge im Chat sind stillschweigend 0. Beim Symptom „Werkzeuge sind nicht sichtbar" zuerst hier nachsehen.

Modelle und Gateway​

Die Modell- und Gateway-Werte sind sämtlich compose-Standardwerte (in der Host-env stehen nur die vom Installationsprogramm erzeugten Schlüssel/Geheimnisse); vLLM ist v0.31.0, docling-serve ist v1.36.0. Die Images (VLLM_IMAGE · DOCLING_IMAGE) folgen den Regeln aus „Images und Registry" oben und werden daher nicht in die Host-env eingetragen. Die Modellablage ist LLM_MODEL_PATH · EMB_MODEL_PATH · RERANK_MODEL_PATH (standardmäßig das Verzeichnis Aura-* unter /opt/kopens/models).

VariableStandardwertBedeutung
LLM_NAMEaura-liteAufrufname des Generierungsmodells. Zugleich Vision-fähig
EMB_NAMEaura-embedding-4bName des Embedding-Modells
RERANK_NAMEaura-reranker-0.6bName des Reranking-Modells
LLM_MODEL_PATH/opt/kopens/models/Aura-Lite-NVFP4Gewichtsordner des Generierungsmodells. Der letzte Ordnername liefert Aura-Lite-NVFP4.tar.zst
LLM_MODEL_ARGS--tool-call-parser gemma4 --reasoning-parser gemma4 --async-scheduling --enable-chunked-prefillStartargumente von vLLM. Der Parser ist auf die Gewichte (Gemma-4-Reihe) abgestimmt, daher nur gemeinsam mit den Gewichten ändern
VISION_LLM_MODEL(leer)Nur, wenn für Vision-Anfragen ein anderes Modell verwendet wird. Leer bedeutet LLM_NAME
PI_VLLM_API_KEYwird vom Installationsprogramm erzeugtSchlüssel vor vLLM
PI_LLM_API_KEYwird vom Installationsprogramm erzeugtLiteLLM-Masterkey
PI_LITELLM_SALT_KEYwird vom Installationsprogramm erzeugtSalt, mit dem LiteLLM gespeicherte Werte verschlüsselt
PI_LITELLM_UI_USERNAME · PI_LITELLM_UI_PASSWORDadmin · admin123!Anmeldung an der LiteLLM-Verwaltungsoberfläche (:4000/ui). Das Passwort ist Pflicht → Initialpasswort ändern
PI_LITELLM_PORT4000Port, unter dem LiteLLM auf dem Host veröffentlicht wird. Nur ändern, wenn auf diesem Host bereits ein anderes LiteLLM Port 4000 belegt. Verbraucher innerhalb des Stacks rufen plantpulse-litellm:4000 über das Containernetz auf und sind von diesem Wert unabhängig. Nach einer Änderung mit bin/restart.sh plantpulse-litellm neu erstellen
LITELLM_IMAGE entfällt

Ab 2026.10 ist das Gateway-Image ein eigenes Image (pi/plantpulse-litellm) und folgt damit den obigen Image-Tag-Regeln. Eine in alten env-Dateien verbliebene LITELLM_IMAGE-Zeile erkennt die Vorstartprüfung als Image-Referenz (release) und stoppt den Start — löschen Sie sie.

Der Modellname lautet aura-* — Aliase für alte Namen gibt es nicht

Am Gateway registriert sind die Namen aura-lite · aura-vision (Vision-Alias) · aura-embedding-4b · aura-reranker-0.6b. Der Serving-Name des LLM wurde in 2026.09 von gpt-4o auf aura-35b und in Re-Release (2026-10-20) von 2026.10 von aura-35b auf aura-lite geändert; Kompatibilitätsaliase für die alten Namen gibt es nicht — ein Aufruf mit dem alten Namen liefert 404, daher müssen Sie den model-Wert externer Integrationen auf den neuen Namen umstellen. Auch VLM_NAME entfällt (den Vision-Alias hält die Gateway-Konfiguration).

Serving-Name (LLM_NAME) und Gewichtsordner (LLM_MODEL_PATH, standardmäßig /opt/kopens/models/Aura-Lite-NVFP4) sind getrennte Einstellungen. In Re-Release (2026-10-20) haben sich beide geändert — der Gewichtsordner von Aura-35B-A3B-NVFP4 auf Aura-Lite-NVFP4 (Bundle-Modelldatei Aura-Lite-NVFP4.tar.zst). Tragen Sie diese drei (LLM_NAME · LLM_MODEL_PATH · LLM_MODEL_ARGS) mit demselben Wert wie der Standard in die Host-env ein, blockiert die Vorstartprüfung (lint-env) den Start mit redundant — tragen Sie sie nur zum Testen anderer Modelle mit «abweichendem Wert» ein.

PI_LITELLM_SALT_KEY nicht ändern

Dies ist der Schlüssel, mit dem die im Bildschirm Modellregistrierung der Admin-Konsole eingetragenen API-Schlüssel externer Anbieter verschlüsselt werden. Nach einer Änderung lassen sich bereits gespeicherte Werte nicht mehr entschlüsseln — der Container startet als healthy, die Modellliste bleibt unverändert, aber nur die Aufrufe scheitern stillschweigend. Lassen Sie den anfangs festgelegten Wert unverändert und nehmen Sie ihn in die Sicherung auf.

GPU-Speicheranteile​

Die drei vLLM-Instanzen (Generierung · Embedding · Reranking), das vLLM der Sprachtranskription (plantpulse-asr) und der Zeitreihen-Inferenzserver teilen sich dieselbe GPU. Die jeweiligen Anteile und deren Summengrenze stehen sämtlich im Hardwareprofil (compose/profiles/<PP_HW_PROFILE>.env) — stehen sie in der Host-env, stoppt die Vorstartprüfung den Start mit profile.

Variablegb10 / g7eBedeutung
LLM_GPU_UTIL · EMB_GPU_UTIL · RERANK_GPU_UTIL0.4 · 0.10 · 0.08 / 0.53 · 0.13 · 0.10GPU-Speicheranteile der drei vLLM-Instanzen
TS_GPU_UTIL0.13 / 0.15Anteil des Zeitreihen-Inferenzservers
ASR_GPU_UTIL0.03 / 0.04Anteil des Transkriptions-vLLM — startet nur bei Installationen mit aktiviertem Video/Audio (PI_MEDIA_ENABLED=true), wird aber auch im ausgeschalteten Zustand in die Summe einbezogen (damit die Grenze am Tag der Aktivierung nicht überschritten wird)
PP_GPU_BUDGET_CEILING0.75 / 0.95Summengrenze der fünf Anteile. Bei Überschreitung Abbruch vor dem Start

Beim GB10 liegt die Grenze wegen des Unified Memory bei 0.75 (Summe 0.74), bei Geräten mit dediziertem VRAM (AWS g7e) bei 0.95 (Summe 0.95).

Wird die Summe überschritten, stirbt vLLM alle 24 Sekunden und startet neu

vLLM prüft beim Start «verbleibender Speicher ≥ eigener Anteil» und beendet sich bei zu wenig Speicher. Ist die Summe zu groß, wird daraus ein Wettlauf, bei dem der zuerst startende gewinnt; der Verlierer startet endlos neu und der Chat steht — nirgends im Log steht, dass „die Konfiguration zu groß war". Deshalb blockieren wir es rechnerisch vor dem Start. Muss reduziert werden, beginnen Sie beim größten Anteil.

Beim GB10 liegt der GPU-Speicher im selben Pool wie der System-RAM: Hebt man die Grenze an, bleibt für OS und DB nichts übrig. Aus demselben Grund bricht das Installationsprogramm ab, wenn Vorlage und Maschinenarchitektur nicht zusammenpassen.

Copilot-Konfiguration — das Präfix lautet CO_​

Umgebungsvariablen für den Copilot (copilot-web) beginnen ab 2026.10 mit CO_ (zuvor CH_). Das gilt für CO_LLM_* · CO_TOOL_RESULT_MAX_CHARS · CO_API_V1_KEY · CO_JAVA_OPTS · CO_NAVIGATOR_CRON · CO_ANOMALY_CRON · CO_INCIDENT_DIAG_CONCURRENCY · CO_OTEL_* gleichermaßen.

Beim Upgrade auf 2026.10 — CH_*-Zeilen nicht löschen, sondern «verschieben»

Es gibt keinen Fallback auf die alten Namen. Da das Installationsprogramm eine vorhandene env nicht neu erstellt, bleiben Zeilen wie CH_API_V1_KEY · CH_LLM_MAX_COMPLETION_TOKENS · CH_OTEL_GENAI_CONTENT aus alten env-Dateien bestehen, aber der Copilot liest diese Namen nicht. Löschen Sie die Zeilen nur, fällt der Wert auf den Standard zurück — eine zum Beispiel mit CH_API_V1_KEY geöffnete öffentliche API ist mit diesem Schlüssel dann nicht mehr erreichbar.

Die Vorstartprüfung (bin/lint-env.sh) erkennt diese Zeilen als renamed, stoppt den Start und nennt je Zeile die nötige Maßnahme.

Ausgabe der PrüfungBedeutung · Maßnahme
only the old name is set — rename itNur der alte Name ist vorhanden. Das mitausgegebene sed (mit Backup) ändert nur den Namen und lässt den Wert unverändert
both set with the same valueDer neue Name existiert bereits mit demselben Wert. Alte Zeile löschen
both set and DIFFERENTBeide vorhanden, mit unterschiedlichen Werten. Der neue Name gewinnt — prüfen Sie, welcher Wert richtig ist, und löschen Sie dann die alte Zeile
sudo grep -n '^CH_' /etc/kopens/plantpulse-ai.env     # 남은 옛 줄

Nach dem Verschieben mit bin/restart.sh plantpulse-copilot-web neu erstellen.

Ausgabewege der Automatisierung — E-Mail · Messenger · PDF​

Der Weg, Automatisierungsergebnisse per E-Mail oder Messenger auszugeben, ist standardmäßig geschlossen und öffnet sich erst mit den folgenden Werten. PDFs entstehen nur, wenn der Konvertierungsdienst erreichbar ist.

WasWo festgelegtWenn leer
PDF-Konvertierungsdienst (Gotenberg)Umgebungsvariable CO_GOTENBERG_URL — compose-Standardwert http://plantpulse-gotenberg:3000 (der mit dem Stack startende Konvertierungscontainer)Ist der Wert leer oder antwortet der Konvertierungscontainer unter dieser Adresse nicht, wird nur PDF deaktiviert. Der PDF-Download in Berichten und die Schaltfläche für den PDF-Anhang in Automatisierungs-Mails sind deaktiviert, und die Oberfläche nennt den Grund. Excel und CSV sind von diesem Wert unabhängig
Zugelassene Mail-DomänenAdmin-Konsole › Benachrichtigungskanäle, «Zugelassene Mail-Domänen» (Konfigurationsschlüssel automation.mail.allowed-domains, kommagetrennt · bis zu 20)🔴 Automatisierungs-Mails sind deaktiviert. Erst mit eingetragener Unternehmensdomäne aktiv
MailserverAdmin-Konsole › Systemeinstellungen: smtp.host · smtp.port · smtp.username · smtp.password · smtp.starttls, Absender navigator.report.email.fromEs gehen keine Mails hinaus (im Ausführungsprotokoll „Mailserver ist nicht konfiguriert")
Messenger-Kanäle (Teams · Slack)Webhook-Adresse in der Admin-Konsole › Benachrichtigungskanäle registrieren — keine UmgebungsvariableBeim «Senden» der Automatisierung lässt sich kein Messenger-Kanal auswählen
Links im Text von Mail und MessengerAdmin-Konsole › Systemeinstellungen, app.base.url (externe Adresse dieser Installation)Im Text werden keine Links eingefügt

CO_GOTENBERG_URL muss eine http://- oder https://-Adresse sein. Bei anderen Werten wird eine Warnung protokolliert und PDF deaktiviert. Die PDF-Schaltfläche und der Anhang-Chip in der Oberfläche richten sich nicht danach, ob eine Adresse eingetragen ist, sondern danach, ob der Konverter gerade antwortet (/health, Prüfung alle 30 Sekunden) — bei Installationen mit Adresse, aber ohne Container erscheinen sie deaktiviert. Ist der Konverter nicht erreichbar, geht die Mail nur ohne PDF hinaus (im Ausführungsprotokoll „konnte nicht angehängt werden"), und der Download im Bericht antwortet mit „PDF kann derzeit nicht erzeugt werden.". Der Zustand des Konverters erscheint in gotenberg von /actuator/health/deps als off · unreachable · up; ein Ausfall des Konverters fließt nicht in die Startprüfung des Copilot ein.

Das Tageslimit für den Versand ist ein Wert der Systemeinstellungen (Änderungen wirken ohne Neustart). Auch ohne jede Änderung erscheint es mit seinem Standardwert in der Admin-Konsole › Systemeinstellungen; dort ändern oder auf den Standardwert zurücksetzen. Auch Intervall und Token-Limit der Automatisierung (agentdef.*) sowie das Vier-Augen-Freigabewerkzeug (access.two_person.tools) stehen in derselben Liste → Copilot-Admin-Konsole — Systemeinstellungen

KonfigurationsschlüsselStandardwertBedeutung
automation.deliver.mail.daily-max6Anzahl der Mails, die eine Automatisierung pro Tag an eine Person sendet
automation.deliver.webhook.daily-max12Anzahl der Messenger-Nachrichten, die eine Automatisierung pro Tag in einen Kanal sendet
automation.deliver.role.max-members50Anzahl der Personen, auf die eine per Rolle gewählte Empfängergruppe aufgelöst wird

Was in der Oberfläche zu tun ist, steht unter Copilot-Admin-Konsole — Benachrichtigungskanäle.

Copilot-Chat — Denkmodus und drei Obergrenzen​

Drei Werte, die festlegen, wie der dialogorientierte Copilot (copilot-web) das Gateway aufruft. Alle drei behandeln denselben einen Fehlerfall über verschiedene Stellschrauben — dass das Modell vor seiner Antwort «denkt» und dieses Denken ebenfalls Generierungstoken verbraucht.

VariableStandardwertBedeutung
CO_LLM_THINKING_ENABLEDtrue (compose, ab Re-Release (2026-10-20) von 2026.10. Der App-Standard allein ist leer)Schalter für den Denkmodus → chat_template_kwargs.enable_thinking. Leer bedeutet: nichts senden (es gilt der Modellstandard — der Vorlagenstandard von AURA-Lite ist «aus»)
CO_LLM_MAX_COMPLETION_TOKENS4096 (bei Deployments mit eigenem Stack 16384)Obergrenze der Generierungstoken pro Aufruf. Muss groß genug sein, dass Denken und Antwort gemeinsam hineinpassen. Bei 0 wird keine Obergrenze gesendet
CO_TOOL_RESULT_MAX_CHARS24000Maximale Zeichenzahl, mit der ein einzelnes Werkzeugergebnis an das Modell übergeben wird. Bei Überschreitung werden zuerst tief verschachtelte Arrays entfernt und eine _truncated-Markierung hinterlassen. Bei 0 wird nicht gekürzt
Ohne Denken wird es schneller, aber das Modell «erfindet»

Schaltet man es bei der Qwen3.5-Reihe mit CO_LLM_THINKING_ENABLED=false ab, sinkt die Antwortzeit auf wenige Sekunden, aber das Modell ruft keine Werkzeuge auf und erfindet nicht existierende Assets und Alarme (Messung im Staging am 18.09.2026). Das ist keine Abwägung zwischen Geschwindigkeit und Qualität, sondern die Frage, ob die Antwort richtig oder falsch ist.

Die Option, es abzuschalten, ist nur bei Modellen sinnvoll, die auch ohne Denken Werkzeuge aufrufen.

Denktiefe — Standardwerte je Pfad​

Ab Re-Release (2026-10-20) von 2026.10 lässt sich zusätzlich zum Ein- und Ausschalten des Denkens wählen, wie tief gedacht wird (reasoning_effort). Das ist keine env-Variable, sondern ein Schlüssel unter Verwaltung › Systemeinstellungen des Copilot (/admin/config); nach dem Speichern gilt er ab dem nächsten Aufruf ohne Neustart.

SchlüsselBezeichnung in der Oberfläche
llm.reasoning.chatStandard-Denktiefe im Chat
llm.reasoning.automationDenktiefe der Automatisierung
llm.reasoning.diagnosisDenktiefe der Anomaliediagnose
llm.reasoning.proposalDenktiefe der Maßnahmenvorschläge
llm.reasoning.otherDenktiefe der übrigen Generierung
  • Mögliche Werte: none (aus) · low · medium · high oder leer («Serverstandard folgen»). none schaltet das Denken ab, die übrigen senden mit eingeschaltetem Denken in der jeweiligen Tiefe.
  • Die Reihenfolge der Festlegung ist: vom Benutzer in der Anfrage gewählter Wert → obiger pfadbezogener Schlüssel → CO_LLM_THINKING_ENABLED.
  • Die Schaltfläche Denktiefe im Abfragebildschirm erscheint nur, wenn der globale Wert oder llm.reasoning.chat gesetzt ist.
Endet die Antwort «leer», sehen Sie die Obergrenze an

Kann das Denken nicht innerhalb der Obergrenze abschließen, wird die Generierung mit length abgeschnitten und der Antworttext hat 0 Zeichen. Da der Stream regulär endet, sieht man in der Oberfläche nur „es kommt keine Antwort", und es liest sich wie eine Gateway-Störung.

Dieselbe Frage, im Staging nebeneinander gemessen:

KonfigurationErgebnis
Denken ein + 4096Leere Antwort — das Denken verbraucht die gesamte Obergrenze
Denken ausSchnell, überspringt aber Werkzeuge und erfindet
Denken ein + 16384Ruft Werkzeuge auf und antwortet richtig (je nach Frage 20 Sekunden bis 4 Minuten)

Endet es auch mit höherer Obergrenze nicht, sollten Sie den Prompt oder die Größe der Werkzeugergebnisse (CO_TOOL_RESULT_MAX_CHARS) reduzieren.

Zeitbudget der Dokumentindizierung (LightRAG)​

Die Standardwerte unverändert zu lassen ist der Normalfall. Ändern Sie sie nur, wenn Sie gemessen haben, dass dieses Gerät mehr oder weniger benötigt.

VariableStandardwertBedeutung
LIGHTRAG_LLM_TIMEOUT3600Limit (Sekunden) für LLM-Aufrufe zur Entitätsextraktion. Das Worker-Limit beträgt das Doppelte dieses Werts
LIGHTRAG_LLM_MAX_TOKENS32768Maximale Tokenzahl, die ein Extraktionsaufruf erzeugen darf — Deckel gegen Ausreißer
LIGHTRAG_MAX_ASYNC4Anzahl gleichzeitiger LLM-Aufrufe. 🔴 Ein kleinerer Wert macht es langsamer
Wenn die Indizierung mit Worker execution timeout scheitert

Ein denkendes Modell verbraucht pro Aufruf viele Token. Mit den früheren Standardwerten (240 s, Worker 480 s) scheiterten große PDFs mitten in der Indizierung vollständig. Erscheint dieser Fehler, erhöhen Sie LIGHTRAG_LLM_TIMEOUT, sehen Sie dabei aber auch LIGHTRAG_LLM_MAX_TOKENS an — ohne Obergrenze belegt ein einziger Ausreißer entsprechend lange einen GPU-Slot.

Maschinenauthentifizierung der öffentlichen API​

Der Schlüssel, mit dem externe Systeme die öffentliche API des Copilot (/api/v1) aufrufen → API-Integrationsleitfaden

VariableStandardwertBedeutung
CO_API_V1_KEY(leer)Schlüssel, der über den Header X-API-Key: <value> entgegengenommen wird. Bis 2026.09 lautete der Name CH_API_V1_KEY — verschieben Sie ihn
Leer bedeutet «kein Zugang» über diesen Schlüssel — nicht freier Durchlass

Ist der Wert leer, wird dieser Umgebungsvariablen-Schlüssel nicht akzeptiert. Über X-API-Key kommen dann nur Schlüssel herein, die im Bildschirm API-Schlüssel der Copilot-Admin-Konsole (/admin/api-keys) benannt ausgestellt wurden; fehlen auch diese, wird nur die Sitzungsanmeldung akzeptiert. So wird verhindert, dass ein Deployment mit vergessener Konfiguration zur unauthentifizierten öffentlichen API wird. Jeder dieser Schlüssel hat nur Zugriff auf die öffentliche API, nicht auf die Verwaltungsoberfläche (/admin/**) und nicht auf die API-Dokumentation.

Bei einem einzelnen Umgebungsvariablen-Schlüssel lässt sich nicht unterscheiden, wem er gegeben wurde; wird er bekannt, brechen alle Nutzungen auf einmal ab. Wollen Sie je externem System einen eigenen Schlüssel vergeben, nutzen Sie die Ausstellung in der Copilot-Admin-Konsole → Copilot-Admin-Konsole — API-Schlüssel

Admin-Konsole und API-Schlüssel​

VariableBedeutung
PI_ADMIN_USER · PI_ADMIN_PASSWORDAnmeldung an der Admin-Konsole. Benutzername standardmäßig admin, das Passwort legt bei der Installation ein Mensch fest
PI_ADMIN_SESSION_SECRETSignierschlüssel der Admin-Konsolen-Sitzung — wird vom Installationsprogramm erzeugt
ADMIN_SESSION_MAX_AGESitzungsgültigkeit (Minuten). Standard 480
PI_ADMIN_WEB_PORTHTTP-Port der Admin-Konsole. Standard 5959
PI_ADMIN_WEB_TLS_PORTHTTPS-Port der Admin-Konsole. Standard 5960 — der Proxy nimmt ihn an und leitet an dieselbe Konsole weiter (Zertifikat: derselbe Satz wie bei :443)
PI_NEO4J_USER · PI_NEO4J_PASSWORDGraph-Konto — beide Neo4j-Instanzen (LightRAG-Wissensgraph plantpulse-neo4j · Fabrikgraph-Spiegel plantpulse-digital-thread-neo4j) nutzen dasselbe Konto
PI_RAG_API_KEYSchlüssel für RAG-API-Aufrufe
PI_INBOUND_API_KEYSchlüssel für eingehende Anfragen an die Backend-Dienste (RAG · Zeitreihen-Insights · Dokumentenverständnis · Vision · Digital Thread). Ist er leer, stoppt die Vorstartprüfung den Stack (siehe „Inbound-Schlüssel der Backend-Dienste" unten)

Bei diesen Werten genügt das Bearbeiten der Datei nicht — wo die maßgebliche Quelle das Serverkonto ist (wie bei Neo4j), muss auch serverseitig geändert werden. bin/passwd.sh führt diese Reihenfolge für Sie aus → Passwörter und API-Schlüssel ändern.

Die Ports der Admin-Konsole sind von 9080 auf 5959 · 5960 gewandert (2026.10)

Beide Eingänge rufen dieselbe Konsole auf, und beide sind offen (Klartext wird nicht auf HTTPS umgeleitet). Bleiben sie leer, gelten die obigen Standardwerte; bei einer Änderung öffnet das Installationsprogramm die Firewall für diese Werte. Nach einer Änderung beide Container mit bin/restart.sh plantpulse-admin-web plantpulse-proxy neu erstellen.

Verschlüsselungsschlüssel für gespeicherte Zugangsdaten — PI_COPILOT_SECRET_KEY · PI_DT_SECRET_KEY​

Der Schlüssel, der in der Oberfläche eingetragene Zugangsdaten mit AES-256-GCM in der DB versiegelt. Der Wert ist base64-kodiert 32 Byte lang und wird bei der Erstinstallation vom Installationsprogramm erzeugt.

VariableWas wird versiegeltWenn leer
PI_COPILOT_SECRET_KEYVom Copilot gespeicherte Zugangsdaten — Authentifizierungswerte externer MCP-Konnektoren, LLM-Schlüssel, SMTP-Passwörter, Slack-Webhooks, Web-Push-Privatschlüssel🔴 Nur der Copilot verweigert den Start und gibt die einzutragende Zeile ins Log. Der übrige Stack startet
PI_DT_SECRET_KEYKonnektor-Zugangsdaten aus dem Konnektorregister des Digital ThreadNur das Konnektorregister ist config_error (503). Der Graph-Spiegel läuft
Bei Änderung oder Verlust lassen sich gespeicherte Zugangsdaten nicht mehr entschlüsseln

  • Diese beiden Werte müssen gemeinsam in der /etc/kopens/plantpulse-ai.env-Sicherung enthalten sein. Stellt man nur die DB wieder her und der Schlüssel fehlt, müssen Konnektor- und Benachrichtigungs-Zugangsdaten neu eingetragen werden.

  • Auf Hosts, die von 2026.09 oder älter aktualisiert wurden, fehlen diese Zeilen. Das Installationsprogramm fügt einer vorhandenen env keine Zeilen hinzu; die Vorstartprüfung meldet «Verschlüsselungsschlüssel für gespeicherte Zugangsdaten fehlt». Tragen Sie sie selbst ein (in einer Form, die den Wert nicht auf dem Bildschirm ausgibt).

    echo "PI_COPILOT_SECRET_KEY=$(openssl rand -base64 32)" | sudo tee -a /etc/kopens/plantpulse-ai.env >/dev/null
    echo "PI_DT_SECRET_KEY=$(openssl rand -base64 32)" | sudo tee -a /etc/kopens/plantpulse-ai.env >/dev/null

  • bin/passwd.sh rotiert diese beiden Schlüssel nicht. Ein Austausch erfolgt ausschließlich über das Verfahren, den alten Wert in _PREVIOUS abzulegen → Passwörter und API-Schlüssel ändern

Digital Thread​

plantpulse-digital-thread-api ist ab 2026.10 standardmäßig im Stack enthalten (ohne Port auf dem Host; der Aufruf erfolgt innerhalb des Stacks über 7140). Der Fabrikgraph-Spiegel liegt in einem eigenen Neo4j (plantpulse-digital-thread-neo4j), das Konnektorregister im Schema dt der PG-DB pi. Der Plattform-Ereignisleser wird eingeschaltet ausgeliefert.

Die auf dem Host verfügbaren Stellschrauben. Die Standardwerte unverändert zu lassen ist der Normalfall.

VariableStandardwertBedeutung
PI_DT_SECRET_KEYwird vom Installationsprogramm erzeugtVerschlüsselungsschlüssel der Konnektor-Zugangsdaten (siehe oben)
DT_INSIGHT_EVENTS_PUSHfalseOb vom Digital Thread gelesene Plattformereignisse an Zeitreihen-Insights weitergereicht werden
TS_EVENTS_SOURCEdirectWoher Zeitreihen-Insights Plattformereignisse bezieht — direct (direkt lesen) · shadow (direkt lesen und mit dem Weitergereichten abgleichen) · digital_thread (nur das Weitergereichte verwenden — der obige Schalter muss eingeschaltet sein)
DT_PLATFORM_READ · CO_PLATFORM_READ · TS_PLATFORM_READdbWeg zum Lesen des Plattformregisters — db (Plattformtabellen direkt) · shadow (beides lesen, mit db antworten und Abweichungen zählen) · api (Plattform-V5-REST, nutzt die bestehenden PP_API_URL · PP_API_TOKEN)

Periodische Konnektorsynchronisierung und Aktualität (2026.10 Re-Release 3)​

Eingeschaltete Konnektoren werden periodisch neu synchronisiert. Die Synchronisierung löscht verschwundene Verbindungen nicht, sondern «schließt» sie (trägt den Endzeitpunkt ein), sodass die Historie für Abfragen zu vergangenen Zeitpunkten korrekt bleibt. Die Standardwerte unverändert zu lassen ist der Normalfall.

VariableStandardwertBedeutung
DT_CONNECTOR_SYNC_ENABLEDtruePeriodische Synchronisierung. Bei false stoppt sie, und es bleibt nur «Jetzt synchronisieren» in der Admin-Konsole
DT_CONNECTOR_SYNC_INTERVAL_S0Synchronisierungsintervall (Sekunden). Bei 0 familienabhängig — die Hälfte der Aktualitätsgrenze der jeweiligen Familie, mindestens 300 Sekunden
DT_CONNECTOR_MAX_AGE(leer)Aktualitätsgrenze der Konnektordaten. Liste in der Form 가족=기간 (z. B. mes=2h,erp=1d, Einheiten s · m · h · d). Leer bedeutet familienabhängige Standardwerte — ehs 1h, mes · sched · wms 2h, cmms 4h, lims 12h, übrige 1d. Gibt es einen Konnektor, der älter als die Grenze ist, werden keine Wiederherstellungs- und Auswirkungskennzahlen ausgegeben
DT_LINK_HISTORY_DAYS(leer — 180)Aufbewahrungsdauer geschlossener Verbindungen (Tage, 1–3650)

Die aktuell laufenden Werte und den Synchronisierungsstatus zeigen /api/v1/config des Digital Thread (z. B. dt_connector_max_age_effective) und connector_sync von /health. connector_sync ist lediglich eine Information und setzt den Dienst nicht auf degraded.

Inbound-Schlüssel der Backend-Dienste — ohne ihn startet nichts​

RAG (rag-api) · Zeitreihen-Insights-API · Dokumentenverständnis · Vision · Digital Thread prüfen eingehende Anfragen mit einem einzigen gemeinsamen Schlüssel (PI_INBOUND_API_KEY). compose verteilt diesen Wert je Dienst unter dessen eigenem Namen (RAG_INBOUND_API_KEY · TS_INBOUND_API_KEY · INBOUND_API_KEY …), und auch Copilot und Admin-Konsolen-Backend rufen diese Dienste mit demselben Wert auf.

Ist der Schlüssel leer, gibt es keinen Weg, auf dem etwas «versehentlich» unauthentifiziert offen startet.

WoWenn der Schlüssel leer ist
Vorstartprüfung (bin/lint-env.sh)Stoppt mit [fail] PI_INBOUND_API_KEY is empty and PI_INBOUND_AUTH_DISABLED is not true und erstellt keinen einzigen Container
Jeder DienstIst der eigene Schlüssel leer, verweigert er den Start und hinterlässt eine Zeile der Art FATAL: … is empty — refusing to start …

Es gibt genau einen expliziten Schalter, um ohne Authentifizierung zu starten, und er ist für Entwicklung und Test gedacht.

VariableStandardwertBedeutung
PI_INBOUND_AUTH_DISABLEDfalseNur wenn true und der Schlüssel leer ist, starten die fünf Dienste ohne Authentifizierung. compose reicht dies je Dienst als RAG_INBOUND_AUTH_DISABLED · TS_INBOUND_AUTH_DISABLED · DT_INBOUND_AUTH_DISABLED · INBOUND_AUTH_DISABLED (Dokumentenverständnis · Vision) weiter

Was die Vorstartprüfung zu diesem Schalter ausgibt:

AusgabeBedeutung
[fail] PI_INBOUND_AUTH_DISABLED=<value> — write true or falseWert außerhalb von true · false
[note] PI_INBOUND_AUTH_DISABLED=true is ignored — PI_INBOUND_API_KEY is set and the key winsIst ein Schlüssel vorhanden, gewinnt der Schlüssel — die Authentifizierung bleibt eingeschaltet

Ein ohne Authentifizierung gestarteter Dienst weist dies in /health aus (Dokumentenverständnis inbound_auth: "disabled", Digital Thread auth.inbound=disabled usw.). In Produktivinstallationen ist das Eintragen des Schlüssels die richtige Antwort.

Ohne Authentifizierung offen sind nur die Health-Pfade /ping · /health (exakt diese Pfade). Auch die Metriken /metrics liegen hinter dem Schlüssel → Logging und Monitoring

Platzhalter bestehen diese Prüfung

CHANGE_ME_… ist kein leerer Wert, also blockieren weder compose noch die Dienste, und diese Zeichenkette ist in allen Installationen gleich. Das Installationsprogramm ersetzt sie bei der Erstinstallation durch einen neuen Wert; bei einer von Hand erstellten env tragen Sie mit bin/passwd.sh --generate PI_INBOUND_API_KEY einen neuen Wert ein → Passwörter und API-Schlüssel ändern

Dokument- und Bildwerkzeuge für interne URLs freigeben​

Die Werkzeuge für Dokumentenverständnis und Vision nehmen keine Dateien, sondern URLs entgegen und laden sie selbst herunter. Löst die Adresse auf Loopback, ein privates Netz oder Link-Local auf, wird sie abgelehnt → MCP-Werkzeugübersicht

Stellen, die bewusst geöffnet werden sollen (etwa ein interner Dateiserver), tragen Sie in die Allowlist ein. compose reicht diesen Wert an beide Dienste, Dokumentenverständnis und Vision, weiter.

VariableStandardwertBedeutung
FETCH_ALLOWED_HOSTS(leer)Hosts, von denen auch bei internen Adressen geladen wird. Mehrere kommagetrennt. Muss exakt dem Hostnamen der URL entsprechen (Groß-/Kleinschreibung wird ignoriert) — bei Angabe mit Port wie files.example.local oder files.example.local:8080 gilt nur dieser Port; bei per IP angesprochenen Servern tragen Sie die IP unverändert ein
echo 'FETCH_ALLOWED_HOSTS=files.example.local,10.0.0.15' | sudo tee -a /etc/kopens/plantpulse-ai.env >/dev/null
cd /opt/kopens/plantpulse-ai-docker
bin/restart.sh plantpulse-document-understanding-api plantpulse-vision-api
  • Wildcards und Bereiche (CIDR) gibt es nicht. Auch Subdomänen werden einzeln eingetragen.
  • Auch bei zugelassenen Hosts werden nur http · https akzeptiert, und die Größengrenzen (Dokumente 200 MiB · Bilder 32 MiB) bleiben bestehen. Redirects werden bei jedem Sprung erneut geprüft; leitet ein zugelassener Host auf eine nicht zugelassene interne Adresse weiter, wird dort abgelehnt.
  • Diese Zeile überschreibt einen compose-Standardwert (leer), daher gibt die Vorstartprüfung einen override-Hinweis aus — das ist normal.

RAG-Objektspeicher-Bucket​

rag-api legt manuell hochgeladene Dokumentoriginale, Zeichnungsstruktur und Vorschauen sowie Videowiedergaben und Transkripte in einem einzigen Bucket des Plattform-RustFS ab.

VariableStandardwertBedeutung
RAG_S3_BUCKETplantpulse-ragName dieses Buckets. Nur wenn zwei AI-Installationen dieselbe Plattform gemeinsam nutzen, erhält die zweite einen anderen Namen

→ Datenbanken

Zeichnungserfassung — standardmäßig aus​

Funktion, die Zeichnungen (DXF · Vektor-PDF mit Textebene) als Schriftfeld, Maße, Toleranzen und BOM-Zeilen einliest und indiziert. Sie wird ausgeschaltet ausgeliefert; im ausgeschalteten Zustand entstehen die Zeichnungs-APIs von rag-api und die zugehörigen Tabellen gar nicht erst (wie vor Einführung dieser Funktion).

VariableStandardwertBedeutung
DRAWING_INGEST_ENABLEDfalseBei true aktiviert rag-api die Zeichnungserfassung. .dxf gilt immer als Zeichnung; PDFs nur dann, wenn beim Upload als Typ «Zeichnung» (document_kind=drawing) angegeben wird. Werte außerhalb von true · false erzeugen eine Warnung und werden als «aus» gelesen
echo 'DRAWING_INGEST_ENABLED=true' | sudo tee -a /etc/kopens/plantpulse-ai.env >/dev/null
cd /opt/kopens/plantpulse-ai-docker
bin/restart.sh plantpulse-rag-api
  • DWG wird nicht angenommen — exportieren Sie nach DXF oder PDF und laden Sie das hoch. Die Grenze je Datei beträgt 50 MB.
  • Auch Anlagendokumente der Plattform kommen als Zeichnungen herein (2026.10 Re-Release 3). Die Synchronisierung, die an Plattform-Assets angehängte Dokumente übernimmt, leitet .dxf-Dateien und PDFs mit «Dokumenttyp» DRAWING in den Zeichnungspfad. Für so eingegangene Zeichnungen ist die Plattform maßgeblich; überschreibendes Hochladen oder Löschen in der Admin-Konsole ergibt 409 („drawing is platform-managed …") — Ändern und Löschen erfolgt auf der Plattform. Um sie nur aus der Suche zu nehmen, wählen Sie in der Dokumenttabelle der Admin-Konsole «Aus dem Korpus ausschließen» (ab 2026.10 Re-Release 4 ist die Konsolen-Schaltfläche für Registerzeichnungen freigeschaltet. Selbst hochgeladene Zeichnungen lassen sich weiterhin nicht ausschließen). Ist die Funktion aus, zählt .dxf nur (drawing_disabled) und übernimmt nichts; PDFs gehen als normale Dokumente ein.
  • Ob der Stand (Revision) einer Zeichnung der aktuell gültige Arbeitsstand ist, wird beim Digital Thread erfragt (freigegebener Stand im PLM · offene Konstruktionsänderungen). Fehlen im Schriftfeld Teilenummer oder Stand oder kann der Digital Thread nicht antworten, ist der Standstatus unknown und die Zeichnung erscheint nicht als «aktuell».
  • Nach dem Einschalten legt rag-api beim Start die Zeichnungstabellen (rag_drawing_*) in der DB rag_ingest an — eine manuelle Migration entfällt.

Video- und Audio-Erfassung — standardmäßig aus, Aktivierung mit einer Zeile​

Die Funktion, Video und Audio zu transkribieren (Sprache → zeitmarkierter Text) und zu indizieren, sowie die Spracheingabe im Eingabefeld des Copilot-Chats nutzen dasselbe Transkriptions-Serving (plantpulse-asr). Beides wird ausgeschaltet ausgeliefert, und eingeschaltet wird es mit einer Zeile in der Host-env: PI_MEDIA_ENABLED=true (in der Vorlage als Kommentar #PI_MEDIA_ENABLED=true enthalten). Die Bedienung steht unter Video- und Audiosuche.

Was diese eine Zeile mitbestimmtInhalt
Startende Diensteplantpulse-asr-audio — ein einmaliger Dienst, der die Audio-Bibliothek in das Volume pi-asr-audio überträgt und dann endet · plantpulse-asr — vLLM Whisper large-v3-turbo, Serving-Name aura-asr, intern 8000 (nicht auf dem Host veröffentlicht). Die Betriebsskripte starten sie mit dem compose-Profil media
Containerwerterag-api MEDIA_INGEST_ENABLED=true · Dokumentenverständnis ASR_URL=http://plantpulse-asr:8000 (compose/media/true.env der Installation)
Modellbin/fetch-models.sh lädt das Transkriptionsmodell Aura-ASR-Turbo (Download ca. 1,5 GB, entpackt ca. 1,6 GB). Bei ausgeschalteten Installationen wird es nicht geladen
GPUASR_GPU_UTIL ist auch im ausgeschalteten Zustand in der Summe des Hardwareprofils enthalten, sodass die Grenze auch nach dem Einschalten nicht überschritten wird
cd /opt/kopens/plantpulse-ai-docker
sudo cp -p /etc/kopens/plantpulse-ai.env /etc/kopens/plantpulse-ai.env.bak-media-$(date +%Y%m%d-%H%M)
sudo sed -i '/^#\?PI_MEDIA_ENABLED=/d' /etc/kopens/plantpulse-ai.env && echo PI_MEDIA_ENABLED=true | sudo tee -a /etc/kopens/plantpulse-ai.env >/dev/null
sudo bash bin/fetch-models.sh                    # Aura-ASR-Turbo — 이미 있으면 건너뜁니다
sudo bash bin/lint-env.sh && bin/restart.sh      # rag-api · 문서 이해가 새 값으로 다시 만들어집니다
bin/status.sh                                    # 켠 설치는 23/23 — plantpulse-asr-audio 는 «Exited (0)» 이 정상입니다

Ob es eingeschaltet ist, sehen Sie an drei Stellen.

# rag-api — "media_ingest_enabled":true
curl -s -H "X-API-Key: <PI_INBOUND_API_KEY>" http://127.0.0.1:7115/api/v1/config | grep -o '"media_ingest_enabled":[a-z]*'
# 문서 이해 — components.asr.status 가 "up"
docker exec plantpulse-document-understanding-api python3 -c \
  "import urllib.request;print(urllib.request.urlopen('http://localhost:7120/health').read().decode())"

bin/status.sh wertet einmalige Dienste (plantpulse-asr-audio), die mit «Exit-Code 0» enden, als normal. Ist der Code nicht 0, startet auch plantpulse-asr nicht — sehen Sie dann zuerst in dessen Log.

  • Abschalten — die Zeile löschen oder auf PI_MEDIA_ENABLED=false setzen, bin/restart.sh ausführen und anschließend die verbliebenen beiden Container mit docker rm -f plantpulse-asr plantpulse-asr-audio entfernen (ist das Profil aus, fassen die Betriebsskripte diese beiden nicht mehr an).
  • Air-Gap-Netzwerk — die Images sind immer im Bundle enthalten. Nur das Modell wird separat eingebracht → Installation im Air-Gap-Netzwerk
  • Bei Werten außerhalb von true · false bricht die Vorstartprüfung mit [fail] PI_MEDIA_ENABLED=<value> — true 또는 false 만 받는다 ab.
Alter Name MEDIA_INGEST_ENABLED — nur in diesem Release ein Alias

Haben Sie in Versionen vor 2026.10 MEDIA_INGEST_ENABLED · ASR_URL von Hand in die Host-env eingetragen, bricht das Upgrade nicht ab und läuft mit diesen Werten weiter (fehlt die PI_MEDIA_ENABLED-Zeile, wird der alte Name als Schalter gelesen). Beim ersten Lauf verschiebt das Betriebsskript den alten Namen nach PI_MEDIA_ENABLED und löscht ASR_URL-Zeilen, deren Wert dem des Schalters entspricht.

VorstartprüfungBedeutung
alias [warn]Nur der alte Name ist vorhanden — der Start erfolgt. Mit dem mitausgegebenen sed verschieben. Wird der Alias in 2026.11 entfernt, werden nicht verschobene Zeilen zu renamed [fail]
media-same [warn]ASR_URL in der Host-env entspricht dem Wert des Schalters — kann gelöscht werden
media [fail]ASR_URL in der Host-env weicht vom Wert des Schalters ab — klären Sie, was gewollt war, und löschen Sie die Zeile. Eingeschaltet wird mit der einen Zeile PI_MEDIA_ENABLED=true
Beide Namen mit unterschiedlichen Werten[fail] — ein Mensch entscheidet, was gemeint war

Läuft es unter einem Konto ohne Schreibrecht auf die env-Datei, kann es nicht selbst verschieben und gibt [paths] [warn] cannot write … sowie den von Hand auszuführenden sudo sh -c '…'-Befehl aus. Der im Container (rag-api) gelesene Name ist weiterhin MEDIA_INGEST_ENABLED — den legt der Schalter fest, er wird also nicht in die Host-env eingetragen.

Die Stellschrauben sind compose-Standardwerte. Sie unverändert zu lassen ist der Normalfall.

VariableDienstStandardwertBedeutung
PI_MEDIA_ENABLED(Host-Schalter)falseSiehe oben — aktiviert Video-/Audio-Erfassung und Spracheingabe gemeinsam
MEDIA_MAX_FILE_MBrag-api2048Obergrenze je Videodatei (MB). Unabhängig von der Dokumentgrenze
MEDIA_MAX_DURATION_MINrag-api120Längenobergrenze je Video (Minuten)
MEDIA_TEXT_TRACKSrag-apisubtitlesText im Video — off · subtitles (eingebettete Untertitelspuren · begleitende Untertitel srt/vtt) · all (+ eingebrannte Untertitel und Bildschirmtext, vom LLM gelesen)
MEDIA_SPAN_TARGET_SECrag-api0Länge der Indexabschnitte (Sekunden, 20–300). Bei 0 bildet ein Transkriptionsfragment (ca. 120 Sekunden) einen Abschnitt. Werte außerhalb des Bereichs erzeugen eine Warnung und werden als 0 gelesen. Änderungen wirken ab der nächsten Neuindizierung
MEDIA_PROCESSING_WINDOWrag-api(leer — 20:00-06:00)Zeitfenster, in dem die Videoverarbeitung starten darf (HH:MM-HH:MM nach PP_TZ; ist der Start später als das Ende, geht das Fenster über Mitternacht). Für durchgehende Verarbeitung always. Bei leerem oder fehlerhaftem Format gilt der rag-api-Standard 20:00-06:00. Das Fenster gilt nur für den Start der Verarbeitung — eine begonnene Verarbeitung läuft auch nach Schließen des Fensters zu Ende. Die Verarbeitung teilt sich dasselbe LLM mit dem Chat
ASR_URLDokumentenverständnis(legt der Schalter fest)Adresse des Transkriptions-Servings. Eingeschaltet http://plantpulse-asr:8000, ausgeschaltet leer (der Transkriptionseingang ist 503). 🔴 Nicht in die Host-env eintragen — siehe media · media-same in der obigen Tabelle
ASR_NAME · ASR_BACKENDDokumentenverständnis · asraura-asr · vllmServing-Name · Engine (akzeptiert nur vllm)
ASR_MODEL_PATHasr/opt/kopens/models/Aura-ASR-TurboAblageort des Transkriptionsmodells
OCR_URL · OCR_BACKENDDokumentenverständnishttp://plantpulse-llm:8000 · vlmServing-LLM zum Lesen von Text im Video. Wird nur bei aktivierter Transkription verwendet

Vision-Engine zum Lesen von Text​

VariableStandardwertBedeutung
VISION_OCR_ENGINE(leer — Vision-Standard vlm)Engine von vision_ocr. Bei vlm liest das aktive Serving-LLM und antwortet nur, wenn die Zeichenkette in zwei von drei Durchläufen identisch ist (liest Koreanisch). docling überlässt es dem OCR des Dokumentenverständnisses (kann kein Koreanisch lesen)

Verwandte Dokumente​