Axel am 23. Juli 2026 um 10:58 Uhr

2026-07-23T10:58:09Z

@@ Zeile 1: / Zeile 1: @@
 = Eigenen Company Server fuer den S57AI-Copilot einrichten =
@@ Zeile 11: / Zeile 10: @@
 Referenzimplementierung. Auf dem Server muss weder S57AI noch ein anderes
 IBHsoftec-Produkt installiert sein.
 '''Download:'''
@@ Zeile 118: / Zeile 120: @@
 company-server.env.example
 s57ai-customer-company-server.service
 README.md
 COMPANY-SERVER-ANLEITUNG.md
@@ Zeile 137: / Zeile 141: @@
 | <code>s57ai-customer-company-server.service</code>
 | systemd-Dienstdefinition
 |-
 | <code>README.md</code>
@@ Zeile 158: / Zeile 168: @@
 </pre>
-== Dienst installieren ==
+== Alternative Installation mit Docker ==
 === Systempakete und Dienstbenutzer ===

Axel: Die Seite wurde neu angelegt: „ = Eigenen Company Server fuer den S57AI-Copilot einrichten = == Zweck dieser Anleitung == Diese Anleitung beschreibt, wie ein Anwender ohne Zugriff auf das IBHsoftec-Quellprojekt einen eigenen Company Server fuer den S57AI-Copilot einrichtet und betreibt. Das Kundenpaket enthaelt eine eigenstaendige Python-/FastAPI- Referenzimplementierung. Auf dem Server muss weder S57AI noch ein anderes IBHsoftec-Produkt installiert sein. '''Download:''' Media:S5…“

2026-07-23T10:47:05Z

Die Seite wurde neu angelegt: „ = Eigenen Company Server fuer den S57AI-Copilot einrichten = == Zweck dieser Anleitung == Diese Anleitung beschreibt, wie ein Anwender ohne Zugriff auf das IBHsoftec-Quellprojekt einen eigenen Company Server fuer den S57AI-Copilot einrichtet und betreibt. Das Kundenpaket enthaelt eine eigenstaendige Python-/FastAPI- Referenzimplementierung. Auf dem Server muss weder S57AI noch ein anderes IBHsoftec-Produkt installiert sein. '''Download:''' Media:S5…“

Neue Seite

= Eigenen Company Server fuer den S57AI-Copilot einrichten =

== Zweck dieser Anleitung ==

Diese Anleitung beschreibt, wie ein Anwender ohne Zugriff auf das
IBHsoftec-Quellprojekt einen eigenen Company Server fuer den S57AI-Copilot
einrichtet und betreibt.

Das Kundenpaket enthaelt eine eigenstaendige Python-/FastAPI-
Referenzimplementierung. Auf dem Server muss weder S57AI noch ein anderes
IBHsoftec-Produkt installiert sein.

'''Download:'''
[[Media:S57AI-Company-Server-Kundenpaket.zip|S57AI Company Server Kundenpaket herunterladen]]

== Was ist ein Company Server? ==

Der Company Server ist ein kontrolliertes Gateway zwischen den
S57AI-Arbeitsplaetzen und einem KI-Dienst.

<pre>
S57AI-Copilot
|
| HTTPS und Rechner-Fingerprint
v
Company Server
|
| zentral verwalteter API-Key
v
Ollama, Open WebUI, vLLM, LiteLLM, OpenAI oder anderer LLM-Dienst
</pre>

Der Company Server fuehrt das Sprachmodell normalerweise nicht selbst aus. Er
leitet freigegebene Anfragen an einen vorhandenen LLM-Dienst weiter. Der
LLM-Dienst kann auf demselben Linux-Rechner, im Firmennetz oder bei einem
Cloud-Anbieter laufen.

== Funktionen und Aufgaben ==

=== Zentrale Verwaltung des KI-Zugangs ===

* Der Upstream-API-Key wird nur auf dem Company Server gespeichert.
* Auf den S57AI-Arbeitsplaetzen wird lediglich die URL des Company Servers eingetragen.
* Ein ausgetauschter Upstream-Key muss nur einmal auf dem Server geaendert werden.
* Der eigentliche LLM-Dienst muss nicht direkt aus dem Arbeitsplatznetz erreichbar sein.

=== Einheitliche Schnittstelle fuer S57AI ===

Der Server stellt dem Copilot unabhaengig vom verwendeten LLM mindestens diese
Endpunkte bereit:

* <code>GET /health</code> - einfache Funktionskontrolle
* <code>GET /v1/models</code> - verfuegbare Modelle
* <code>POST /v1/copilot/chat</code> - Textanfragen

Damit kann der dahinterliegende Anbieter gewechselt werden, ohne alle
Arbeitsplaetze neu zu programmieren.

=== Modellvorgabe und Modellauswahl ===

Der Company Server kann:

* die Modellliste des Upstream-Dienstes durchreichen;
* bei nicht verfuegbarer Modellliste ein konfiguriertes Standardmodell melden;
* die effektive Kontextgroesse des Standardmodells an S57AI melden;
* bei einer Anfrage ohne Modell das serverseitige Standardmodell verwenden.

Das Modellfeld im S57AI-Copilot enthaelt dadurch nur Modelle, die der Company
Server bereitstellt.

=== Zugriffskontrolle ===

S57AI uebermittelt den Rechner-Fingerprint:

* bei <code>GET /v1/models</code> im Header <code>X-S57AI-Fingerprint</code>;
* bei <code>POST /v1/copilot/chat</code> im Feld <code>machine_fingerprint</code>.

Ueber <code>ALLOWED_FINGERPRINTS</code> legt der Administrator fest, welche
Rechner den Company Server verwenden duerfen.

=== Schutz und Entkopplung ===

* Der API-Key des LLM-Dienstes bleibt vor den Clients verborgen.
* nginx uebernimmt HTTPS und die externe Netzwerkverbindung.
* Der Python-Dienst lauscht nur lokal auf <code>127.0.0.1:5100</code>.
* Zeitueberschreitungen und Upstream-Fehler werden kontrolliert an den Client zurueckgegeben.

=== Grenzen der Referenzimplementierung ===

Das einfache Kundenpaket unterstuetzt Text-Chat und Modelllisten. Es enthaelt
keine grafische Administration, Mandantenverwaltung, Abrechnung,
Dateianhaenge, Spracherkennung oder Sprachausgabe.

== Voraussetzungen ==

Empfohlen werden:

* Ubuntu Server oder Debian;
* mindestens 1 CPU-Kern und 1 GB RAM fuer den Gateway-Dienst;
* feste IP-Adresse oder DNS-Name;
* Netzwerkzugriff vom Company Server zum LLM-Dienst;
* Netzwerkzugriff der S57AI-Arbeitsplaetze zum Company Server;
* Benutzer mit <code>sudo</code>-Rechten;
* fuer produktiven externen Zugriff ein TLS-Zertifikat.

Die Hardware fuer das eigentliche LLM kommt zusaetzlich hinzu. Ein lokal
ausgefuehrtes grosses Modell benoetigt je nach Modell ausreichend RAM oder
GPU-Speicher.

== Inhalt des Kundenpakets ==

Nach dem Entpacken sind mindestens diese Dateien vorhanden:

<pre>
server.py
requirements.txt
company-server.env.example
s57ai-customer-company-server.service
README.md
COMPANY-SERVER-ANLEITUNG.md
</pre>

{| class="wikitable"
! Datei
! Aufgabe
|-
| <code>server.py</code>
| Company-Server-Referenzimplementierung
|-
| <code>requirements.txt</code>
| Benoetigte Python-Pakete
|-
| <code>company-server.env.example</code>
| Beispiel fuer die geschuetzte Serverkonfiguration
|-
| <code>s57ai-customer-company-server.service</code>
| systemd-Dienstdefinition
|-
| <code>README.md</code>
| Kurzanleitung im Paket
|-
| <code>COMPANY-SERVER-ANLEITUNG.md</code>
| Ausfuehrliche Anleitung als Markdown
|}

== Kundenpaket uebertragen ==

Das ZIP-Paket auf den Linux-Rechner kopieren und nach
<code>/opt/s57ai-company-server</code> entpacken:

<pre>
sudo apt update
sudo apt install -y unzip
sudo mkdir -p /opt/s57ai-company-server
sudo unzip S57AI-Company-Server-Kundenpaket.zip \
-d /opt/s57ai-company-server
</pre>

== Dienst installieren ==

=== Systempakete und Dienstbenutzer ===

<pre>
sudo apt update
sudo apt install -y python3 python3-venv nginx curl

sudo useradd --system \
--home /opt/s57ai-company-server \
--shell /usr/sbin/nologin \
s57ai-company

sudo chown -R s57ai-company:s57ai-company \
/opt/s57ai-company-server
</pre>

Falls der Benutzer bereits vorhanden ist, kann die entsprechende Meldung
ignoriert werden.

=== Python-Umgebung ===

<pre>
cd /opt/s57ai-company-server

sudo -u s57ai-company python3 -m venv venv
sudo -u s57ai-company ./venv/bin/pip install --upgrade pip
sudo -u s57ai-company ./venv/bin/pip install -r requirements.txt
</pre>

=== Konfiguration und systemd ===

<pre>
sudo cp company-server.env.example \
/etc/s57ai-company-server.env

sudo chown root:root /etc/s57ai-company-server.env
sudo chmod 600 /etc/s57ai-company-server.env

sudo cp s57ai-customer-company-server.service \
/etc/systemd/system/s57ai-customer-company-server.service
</pre>

== LLM-Dienst konfigurieren ==

Die Konfigurationsdatei wird mit folgendem Befehl geoeffnet:

<pre>
sudo nano /etc/s57ai-company-server.env
</pre>

=== Einstellungen ===

{| class="wikitable"
! Einstellung
! Aufgabe
|-
| <code>UPSTREAM_BASE_URL</code>
| Basisadresse eines OpenAI-kompatiblen Dienstes
|-
| <code>UPSTREAM_MODELS_URL</code>
| Optionaler vollstaendiger Endpunkt fuer die Modellliste
|-
| <code>UPSTREAM_CHAT_URL</code>
| Optionaler vollstaendiger Endpunkt fuer Chat
|-
| <code>UPSTREAM_API_KEY</code>
| API-Key des LLM-Dienstes
|-
| <code>DEFAULT_MODEL</code>
| Ersatz und serverseitige Vorgabe, falls keine Modellliste verfuegbar ist
|-
| <code>DEFAULT_CONTEXT_LENGTH</code>
| Effektive Kontextgroesse des Standardmodells in Tokens; <code>0</code> bedeutet unbekannt
|-
| <code>UPSTREAM_TIMEOUT</code>
| Maximale Wartezeit auf eine Modellantwort in Sekunden
|-
| <code>ALLOWED_FINGERPRINTS</code>
| Zugelassene S57AI-Rechner, durch Komma getrennt
|}

Wenn <code>UPSTREAM_MODELS_URL</code> und <code>UPSTREAM_CHAT_URL</code> nicht
gesetzt sind, verwendet der Server:

<pre>
<UPSTREAM_BASE_URL>/v1/models
<UPSTREAM_BASE_URL>/v1/chat/completions
</pre>

=== Direktes Ollama ===

<pre>
UPSTREAM_BASE_URL=http://127.0.0.1:11434
UPSTREAM_API_KEY=ollama
DEFAULT_MODEL=deepseek-r1:latest
DEFAULT_CONTEXT_LENGTH=8192
UPSTREAM_TIMEOUT=300
ALLOWED_FINGERPRINTS=
</pre>

Vorher pruefen:

<pre>
ollama list
curl http://127.0.0.1:11434/v1/models
</pre>

Der Wert von <code>DEFAULT_MODEL</code> muss exakt einem installierten Modell
entsprechen.

=== Open WebUI ===

Open WebUI verwendet fuer die hier benoetigten Funktionen typischerweise die
Pfade <code>/api/models</code> und <code>/api/chat/completions</code>:

<pre>
UPSTREAM_BASE_URL=http://127.0.0.1:3000
UPSTREAM_MODELS_URL=http://127.0.0.1:3000/api/models
UPSTREAM_CHAT_URL=http://127.0.0.1:3000/api/chat/completions
UPSTREAM_API_KEY=HIER_DEN_OPEN_WEBUI_API_KEY_EINTRAGEN
DEFAULT_MODEL=deepseek-coder-v2:16b
DEFAULT_CONTEXT_LENGTH=8192
UPSTREAM_TIMEOUT=300
ALLOWED_FINGERPRINTS=
</pre>

Der Open-WebUI-API-Key wird in Open WebUI fuer einen technischen Benutzer
erzeugt. Er darf nicht an S57AI-Anwender verteilt werden.

<pre>
curl -H "Authorization: Bearer HIER_DEN_API_KEY_EINTRAGEN" \
http://127.0.0.1:3000/api/models
</pre>

=== OpenAI ===

<pre>
UPSTREAM_BASE_URL=https://api.openai.com
UPSTREAM_API_KEY=HIER_DEN_OPENAI_API_KEY_EINTRAGEN
DEFAULT_MODEL=EIN_FREIGESCHALTETES_MODELL
DEFAULT_CONTEXT_LENGTH=0
UPSTREAM_TIMEOUT=300
ALLOWED_FINGERPRINTS=
</pre>

Der konkrete Modellname muss fuer das verwendete OpenAI-Projekt freigeschaltet
sein. Ein frei erfundener oder nicht verfuegbarer Modellname fuehrt zu einer
Fehlermeldung.

=== vLLM, LiteLLM und andere kompatible Server ===

Wenn der Dienst eine vollstaendige OpenAI-kompatible <code>/v1</code>-API
bereitstellt:

<pre>
UPSTREAM_BASE_URL=https://llm.intern.example
UPSTREAM_API_KEY=GEHEIMER_API_KEY
DEFAULT_MODEL=modellname-des-anbieters
DEFAULT_CONTEXT_LENGTH=32768
UPSTREAM_TIMEOUT=300
ALLOWED_FINGERPRINTS=
</pre>

Bei abweichenden Pfaden werden <code>UPSTREAM_MODELS_URL</code> und
<code>UPSTREAM_CHAT_URL</code> ausdruecklich gesetzt.

== Rechner freigeben ==

Der Fingerprint wird im S57AI-Copilot beim Provider
<code>Company Server</code> maskiert angezeigt und kann kopiert werden.

Mehrere Rechner werden durch Komma getrennt:

<pre>
ALLOWED_FINGERPRINTS=8B4F...F03A,4A21...91C0
</pre>

Ein leerer Wert erlaubt alle Rechner:

<pre>
ALLOWED_FINGERPRINTS=
</pre>

Das ist fuer einen ersten Test geeignet, sollte aber produktiv nicht dauerhaft
verwendet werden.

Nach einer Aenderung:

<pre>
sudo systemctl restart s57ai-customer-company-server
</pre>

== Dienst starten und lokal testen ==

<pre>
sudo systemctl daemon-reload
sudo systemctl enable --now s57ai-customer-company-server
sudo systemctl status s57ai-customer-company-server --no-pager
</pre>

Der Dienst lauscht absichtlich nur lokal:

<pre>
ss -ltnp | grep ':5100'
</pre>

Gesundheitspruefung:

<pre>
curl http://127.0.0.1:5100/health
</pre>

Erwartete Antwort:

<pre>
{"status":"ok"}
</pre>

Modellliste:

<pre>
curl -H "X-S57AI-Fingerprint: FREIGEGEBENER_FINGERPRINT" \
http://127.0.0.1:5100/v1/models
</pre>

Beispielantwort:

<pre>
{
"object": "list",
"data": [
{
"id": "deepseek-r1:latest",
"object": "model",
"owned_by": "customer-company-server",
"context_length": 8192
}
]
}
</pre>

Chat testen:

<pre>
curl -X POST http://127.0.0.1:5100/v1/copilot/chat \
-H "Content-Type: application/json" \
-d '{
"machine_fingerprint": "FREIGEGEBENER_FINGERPRINT",
"model": "",
"messages": [
{"role": "user", "content": "Antworte nur mit OK."}
]
}'
</pre>

Ein leerer Modellname bewirkt, dass <code>DEFAULT_MODEL</code> verwendet wird.

== HTTPS mit nginx ==

Datei <code>/etc/nginx/sites-available/s57ai-company-server</code> erstellen:

<pre>
server {
listen 80;
server_name ai.example.com;

client_max_body_size 10m;

location / {
proxy_pass http://127.0.0.1:5100;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 360s;
proxy_send_timeout 360s;
}
}
</pre>

Aktivieren:

<pre>
sudo ln -s /etc/nginx/sites-available/s57ai-company-server \
/etc/nginx/sites-enabled/s57ai-company-server

sudo nginx -t
sudo systemctl reload nginx
</pre>

TLS mit Let's Encrypt:

<pre>
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d ai.example.com
</pre>

Abschliessend:

<pre>
curl https://ai.example.com/health
curl -H "X-S57AI-Fingerprint: FREIGEGEBENER_FINGERPRINT" \
https://ai.example.com/v1/models
</pre>

Bei rein internem Betrieb kann ein Zertifikat der Unternehmens-PKI verwendet
werden. Das ausstellende Stammzertifikat muss auf den S57AI-Arbeitsplaetzen als
vertrauenswuerdig installiert sein.

== Firewall ==

Nach aussen wird nur HTTPS benoetigt:

<pre>
sudo ufw allow OpenSSH
sudo ufw allow 443/tcp
sudo ufw enable
</pre>

Port <code>5100</code> darf nicht oeffentlich geoeffnet werden. Auch
Ollama-Port <code>11434</code> und Open-WebUI-Port <code>3000</code> sollten
nur aus den tatsaechlich benoetigten Netzen erreichbar sein.

== S57AI-Copilot konfigurieren ==

Im KI-Copilot:

<pre>
Provider: Company Server
Server-URL: https://ai.example.com
</pre>

# Provider <code>Company Server</code> auswaehlen.
# Server-URL eintragen.
# Modellauswahl oeffnen.
# Pruefen, ob die vom Server gemeldeten Modelle erscheinen.
# Eine kurze Anfrage senden.

Der Upstream-API-Key wird nicht im S57AI-Copilot eingetragen.

== Sicherheitsempfehlungen ==

* Produktiv ausschliesslich HTTPS verwenden.
* Upstream-API-Keys nur in <code>/etc/s57ai-company-server.env</code> speichern.
* Die Konfigurationsdatei mit Dateirecht <code>600</code> schuetzen.
* Den Python-Dienst nur an <code>127.0.0.1</code> binden.
* Nur benoetigte Rechner-Fingerprints freigeben.
* Einen technischen Upstream-Benutzer mit begrenztem Budget verwenden.
* Token-, Kosten- und Rate-Limits beim Upstream konfigurieren.
* Betriebssystem und Python-Abhaengigkeiten regelmaessig aktualisieren.
* Keine Projektdaten oder vollstaendigen KI-Anfragen in allgemein zugaengliche Logs schreiben.
* API-Keys niemals in ein unverschluesseltes Backup oder Quellcode-Repository aufnehmen.

Der Rechner-Fingerprint ist eine zusaetzliche Freigabekontrolle. Er ersetzt
nicht HTTPS, Firewallregeln und eine sichere Netzwerkarchitektur.

== Betrieb und Wartung ==

Status:

<pre>
sudo systemctl status s57ai-customer-company-server --no-pager
</pre>

Live-Protokoll:

<pre>
sudo journalctl -u s57ai-customer-company-server -f
</pre>

Letzte Meldungen:

<pre>
sudo journalctl -u s57ai-customer-company-server \
-n 200 --no-pager
</pre>

Neustart:

<pre>
sudo systemctl restart s57ai-customer-company-server
</pre>

== Aktualisierung ==

Vor einer Aktualisierung:

<pre>
sudo cp /etc/s57ai-company-server.env \
/root/s57ai-company-server.env.backup
</pre>

Neue Paketdateien nach <code>/opt/s57ai-company-server</code> kopieren:

<pre>
cd /opt/s57ai-company-server
sudo chown -R s57ai-company:s57ai-company .
sudo -u s57ai-company ./venv/bin/pip install -r requirements.txt
sudo systemctl restart s57ai-customer-company-server
</pre>

Danach <code>/health</code>, <code>/v1/models</code> und eine Chat-Anfrage
testen.

== Fehlerdiagnose ==

=== Modellliste nicht erreichbar ===

<pre>
curl -v http://127.0.0.1:5100/v1/models
sudo journalctl -u s57ai-customer-company-server \
-n 200 --no-pager
</pre>

Pruefen:

* Laeuft der Company Server?
* Stimmt die Server-URL im Copilot?
* Erlauben Firewall und nginx den Zugriff?
* Ist der Fingerprint freigegeben?

=== The model ... does not exist or you do not have access to it ===

<code>DEFAULT_MODEL</code> oder das ausgewaehlte Modell ist beim Upstream nicht
vorhanden. Den Modellnamen exakt aus der Modellliste des Upstreams uebernehmen.

=== HTTP 401 oder 403 ===

* Upstream-API-Key ungueltig;
* Rechner-Fingerprint nicht freigegeben;
* Zugriff beim Cloud-Anbieter nicht erlaubt.

=== HTTP 404 ===

Meist ist der konfigurierte Pfad falsch. Bei Open WebUI insbesondere
<code>UPSTREAM_MODELS_URL</code> und <code>UPSTREAM_CHAT_URL</code> pruefen.

=== HTTP 502 ===

Der Company Server laeuft, erreicht aber den Upstream nicht oder erhaelt von
ihm eine ungueltige Antwort.

=== Zeitueberschreitung ===

* <code>UPSTREAM_TIMEOUT</code> erhoehen;
* Auslastung und Arbeitsspeicher des LLM-Rechners pruefen;
* kleineres Modell verwenden;
* Netzwerkverbindung untersuchen.

=== Kontextgroesse wird nicht angezeigt ===

Der Upstream meldet keine <code>context_length</code>. Die tatsaechlich
konfigurierte Kontextgroesse in <code>DEFAULT_CONTEXT_LENGTH</code> eintragen
und den Dienst neu starten.

== API-Vertrag fuer eigene Implementierungen ==

Ein selbst entwickelter Company Server kann in jeder Programmiersprache
geschrieben werden. Entscheidend ist der API-Vertrag.

=== Modellliste ===

<pre>
GET /v1/models
X-S57AI-Fingerprint: <Fingerprint>
</pre>

Antwort:

<pre>
{
"object": "list",
"data": [
{
"id": "modell-id",
"object": "model",
"owned_by": "company-server",
"context_length": 8192
}
]
}
</pre>

=== Chat ===

<pre>
POST /v1/copilot/chat
Content-Type: application/json
</pre>

Anfrage:

<pre>
{
"machine_fingerprint": "ABC123",
"app_version": "1.0",
"language": "de",
"model": "modell-id",
"stream": false,
"messages": [
{"role": "system", "content": "Systemanweisung"},
{"role": "user", "content": "Benutzerfrage"}
]
}
</pre>

Antwort:

<pre>
{
"reply": "Antwort des Modells"
}
</pre>

Der Server muss Eingaben validieren, unbekannte Rechner ablehnen, Zeitlimits
setzen und Upstream-Fehler ohne Preisgabe von API-Keys zurueckgeben.

== Abnahmekriterien ==

Die Installation ist betriebsbereit, wenn:

* <code>systemctl status</code> den Zustand <code>active (running)</code> meldet;
* <code>GET /health</code> erfolgreich antwortet;
* <code>GET /v1/models</code> mindestens ein gueltiges Modell liefert;
* die Kontextgroesse korrekt gemeldet oder bewusst als unbekannt behandelt wird;
* ein freigegebener S57AI-Rechner chatten kann;
* ein nicht freigegebener Fingerprint mit HTTP 403 abgewiesen wird;
* der Upstream-API-Key auf keinem Client gespeichert ist;
* der externe Zugriff ausschliesslich ueber HTTPS erfolgt.

== Wiki-Hinweis fuer Administratoren ==

Damit der Downloadlink am Anfang dieser Seite funktioniert, muss die Datei
<code>S57AI-Company-Server-Kundenpaket.zip</code> ueber die
MediaWiki-Spezialseite <code>Spezial:Hochladen</code> unter genau diesem
Dateinamen in das Wiki geladen werden.

S5/S7 AI für Windows:Company Server - Versionsgeschichte

Axel am 23. Juli 2026 um 10:58 Uhr