Repository navigation
Erste Schritte
Diese Seite beschreibt den Weg von einem leeren Rechner bis zur ersten Frage, die der Chat mit Quellenangabe beantwortet. Sie ersetzt weder das Betriebshandbuch noch die Wissensportal-Dokumentation — sie ordnet ein, in welcher Reihenfolge man beides liest und an welchen Stellen Leute typischerweise hängenbleiben. Alle Werte, Variablennamen und Fehlerbilder stehen im Betriebshandbuch und werden hier nicht wiederholt.
Verarbeiten bringt nichts in den Index. Erst die Freigabe tut das.
Ein hochgeladenes und fertig verarbeitetes Dokument ist kein durchsuchbares
Dokument. Weave-Knowledge indiziert regulär ausschließlich das Ereignis
document.released;
das Ereignis
document.processed
wird nur mit awaiting_release quittiert. Wer einen Ordner hochlädt, das
Portal zuklappt und danach im Chat sucht, findet nichts — und zwar ohne
Fehlermeldung, weil technisch nichts kaputt ist. Auch die
Symptomtabelle des Betriebshandbuchs
nennt zu „Dokumente erscheinen nicht im Index“ zuerst die fehlende Freigabe und
erst danach ein abweichendes Webhook-Secret.
Was eine Freigabe ist, wer sie auslösen darf und warum sie ein unveränderlicher Snapshot ist: Wissensbereiche-und-Freigaben.
- Docker mit Compose und Python für die beiden Konfigurationsbefehle.
- Die Pflicht-Geheimnisse als Umgebungsvariablen — über direnv, einen
Passwort-Manager, einen CI-Secret-Store, wie ist gleichgültig. Fehlt eines,
nennt
renderalle fehlenden Variablen auf einmal und bricht ab, statt eine halbe Datei zu schreiben. Welche das sind, steht in betrieb.md, Abschnitt 11. - Ausgehende Verbindungen für die Image-Pulls und, falls Sie den OCR-Worker starten, für die PaddleOCR-Gewichte. Fehlt dieser Ausgang, fällt die Verarbeitung still auf reine Textextraktion zurück (README, Outbound connections).
Ein LLM-Zugang wird für den ersten Durchlauf nicht gebraucht. Der Stack startet mit Attrappen-Providern und erreicht keinen externen Dienst; siehe Schritt 7.
weave.yaml im
Wurzelverzeichnis ist die einzige Konfigurationsquelle. Sie
enthält keine Geheimnisse im Klartext, sondern nur die Namen der
Umgebungsvariablen, aus denen die Werte gelesen werden. Die Datei
deploy/.env wird daraus erzeugt und nicht von Hand gepflegt.
python scripts/weave_config.py render # schreibt deploy/.env
python scripts/weave_config.py check # prüft die Datei auf Widersprüchecheck findet genau die Fehler, die sonst erst später als unerklärliches 401
oder 503 an einer Dienstgrenze auftauchen — geteilte Werte, die auseinander
laufen, fehlende Pflichtwerte, unpassende Embedding-Dimensionen. Führen Sie
ihn nach jeder Änderung an einem Geheimnis oder einer Adresse erneut aus.
Hinweis zur Lesereihenfolge:
Abschnitt 2
des Betriebshandbuchs zeigt noch den älteren Weg über cp .env.example .env.
Abschnitt 11
derselben Datei hält fest, dass Handarbeit an der .env vollständig entfällt —
dieser Weg ist der aktuelle.
docker compose --env-file deploy/.env \
-f deploy/docker-compose.weave.yml \
-f deploy/docker-compose.local.yml \
up -d --buildDie Compose-Datei allein zeigt auf Registry-Images, die nie veröffentlicht wurden; das lokale Override baut die Dienste aus diesem Monorepo. Deshalb immer beide Dateien angeben.
Danach ist das Wissensportal unter http://localhost:3000 erreichbar und die
Chat-Oberfläche unter http://localhost:3001. Ein Punkt, der spätestens beim
Veröffentlichen hinter einem Reverse Proxy zählt: Die Portal-Oberfläche leitet
Anfragen nicht weiter, der Browser spricht die Ingest-API direkt an. Port
3000 und Port 8000 müssen also beide vom Arbeitsplatz aus erreichbar sein.
Ist Port 3000 belegt, setzen Sie FRONTEND_PORT und CORS_ORIGINS
gemeinsam, bevor Sie neu rendern. Wer nur den Port verschiebt, bekommt im
Browser einen Access-Control-Fehler und hält daraufhin CORS für das Problem —
tatsächlich ist es der Port. CORS_ORIGINS steuert nämlich nicht nur CORS,
sondern zugleich die Herkunftsprüfung gegen CSRF, an der dann jede schreibende
Anfrage scheitert, die Anmeldung eingeschlossen. check meldet diesen
Widerspruch.
Derselbe Aufruf noch einmal, nur endet er auf
--profile ocr up -d weave-ingest-worker statt auf up -d --build.
Der Worker bringt PaddleOCR mit und ist mehrere Gigabyte groß. Er hängt hinter
einem eigenen Profil, damit der übrige Stack in Minuten hochkommt. Ohne ihn
bleiben hochgeladene Aufträge in PENDING stehen — auch das ohne
Fehlermeldung.
Öffnen Sie das Portal und legen Sie über die Setup-Seite (/setup) das erste
Konto an. Der erste Nutzer wird automatisch Administrator. Weitere Nutzer,
Teams und OIDC-Verbindungen verwaltet dieser Administrator anschließend unter
/admin; Weave-Ingest ist der Identitätsanbieter der Plattform
(ADR-0006).
Wer sich hier anmelden kann, kann auch chatten — eine zweite Benutzerverwaltung
im Gateway gibt es nicht. Wie Teams, Wissensbereiche und Sichtbarkeit
zusammenhängen, steht in Rechte-und-Sichtbarkeit.
Dieser Schritt ist der einzige zyklische Punkt der Erstinbetriebnahme, und er
lässt sich nicht vorziehen: Weave-Knowledge braucht einen persönlichen
API-Token, der einem Administrator gehört, weil es die Collection-Registry
über einen Admin-Endpunkt holt — dieser Endpunkt gibt die vollständige
Zugriffskarte aus. Der Token kann erst existieren, wenn der Stack läuft und
Schritt 4 erledigt ist, render verlangt ihn aber bereits als Pflichtwert.
Beim ersten Rendern steht dort daher zwangsläufig ein vorläufiger Wert, den Sie
jetzt ersetzen.
Erzeugen Sie den Token als Administrator im Portal unter Konto →
API-Tokens, setzen Sie ihn als WEAVE_KNOWLEDGE_INGEST_API_TOKEN, rendern
Sie neu und erstellen Sie die beiden Knowledge-Container neu — mit
up -d --no-deps weave-knowledge weave-knowledge-worker; den vollständigen
Befehl nennt die
Wissensportal-Dokumentation, Abschnitt Betriebskonfiguration.
Abschnitt 3
des Betriebshandbuchs nennt an dieser Stelle noch ein restart; Abschnitt 7.5
derselben Datei hält fest, dass geänderte .env-Werte erst durch up -d in
den Container gelangen — deshalb der obige Aufruf. Im Container selbst heißt
der Wert WEAVE_INGEST_API_TOKEN; wer in Logs oder printenv danach sucht,
findet ihn unter diesem Namen.
Bis dahin läuft der Registry-Sync in ein 401, und die Collections in Chat und Suche bleiben leer. Bleiben sie es auch danach, gehört der Token höchstwahrscheinlich keinem Administrator.
Ab hier arbeiten Sie nur noch in der Oberfläche. Der Ablauf ist im
Wissensportal geführt: Wissensbereich anlegen, dabei die berechtigten Teams
wählen, dann Quellen hinzufügen — Dateien, einzelne .eml-E-Mails oder eine
Confluence-Startseite — und ein Verarbeitungsprofil auswählen.
Wenn die Verarbeitung durch ist, steht das Dokument unter Prüfen und freigeben. Lesen Sie den aufbereiteten Text; reicht die Qualität nicht, verarbeiten Sie mit einem anderen Profil neu. Erst die ausdrückliche Bestätigung speichert die Freigabe. Danach läuft die Anzeige selbsttätig durch Freigegeben → Wird indiziert → Für KI verfügbar und nennt am Ende Zeitpunkt und Anzahl der durchsuchbaren Textabschnitte.
Warten Sie diesen letzten Zustand ab, bevor Sie in den Chat wechseln. „Verarbeitet“ heißt weder „freigegeben“ noch „indiziert“, und der Zustellstatus eines Webhooks sagt nichts über den Abschluss der Indexierung. Die Details zu Zuständen, Berechtigungen und Sonderfällen wie Confluence stehen in Wissensbereiche-und-Freigaben.
Der Chat ist eine eigene Oberfläche, die aus dem Portal heraus verlinkt ist, und er nutzt dieselbe Anmeldung. Wählen Sie einen Bot, stellen Sie die Frage, und schränken Sie das Gespräch bei Bedarf auf einzelne Ihrer Wissensbereiche ein.
Zwei Erwartungen sind hier wichtig:
- Findet die Suche nichts, sagt der Bot das. Er formuliert keine flüssige, unbelegte Antwort. Eine leere Antwort ist bei frisch aufgesetztem Stack fast immer ein Hinweis auf eine fehlende Freigabe oder ein fehlendes Team, nicht auf einen Defekt.
-
Antworten, die mit
[fake-llm]beginnen, sind korrekt und erwartbar.LLM_PROVIDERsteht bis zur Umstellung auffake, ebenso arbeiten Embeddings und Reranking zunächst mit Attrappen. Der erste Durchlauf zeigt damit den vollständigen Weg vom Dokument bis zur Antwort, ohne dass Daten oder Budget das Haus verlassen. Wie man auf echte Modelle umstellt — und warum eine Umstellung der Embeddings bei bereits gefüllter Datenbank eine Migration und ein Reindex nach sich zieht — steht in Abschnitt 7 des Betriebshandbuchs.
Bleibt eine Antwort aus, ist der
Selbsttest in Abschnitt 10
der schnellste Weg: Er prüft der Reihe nach Erreichbarkeit,
Bot-Liste, lesbare Collections und eine echte Antwort samt trace, und die
zugehörige Symptomtabelle nennt zu jedem Fehlerbild die wahrscheinliche
Ursache. Die häufigsten Fälle sind auch in Haeufige-Fragen eingeordnet.
Unter docs/screenshots/user-wiki/ liegen 31 Screenshots der aktuellen Oberfläche, geordnet nach Anmeldung und Wissensablauf, persönlichen Einstellungen und Chat, Verbindungen und Fachwerkzeugen sowie Administration. Die Galerie zeigt sie zusammen mit einer Beispielanimation, die den fachlichen Teil dieser Seite in fünf Schritten durchläuft: anmelden, Quelle zu einem Wissensbereich hinzufügen, Verarbeitung verfolgen, prüfen und freigeben, im Chat fragen.
Die Animation ist ausdrücklich eine Demonstration mit simulierten Oberflächenzuständen und erfundenen Beispieldaten; die gezeigte Chat-Antwort ist als Attrappe gekennzeichnet, und die Zeitverhältnisse entsprechen weder echter OCR- noch Indexierungs- oder Modelllaufzeit. Die Einzelbilder dagegen sind echte Browser-Renderings der laufenden Anwendung mit ersetzten Daten. Herkunft und Aufnahmeverfahren stehen im README der Bildstrecke.
Der oben beschriebene Stand ist eine lauffähige Bewertungsumgebung, kein Betriebszustand. Drei Dinge sind vorher zu klären, und alle drei sind in der ausgelieferten Konfiguration bewusst offen gelassen:
- Der Stack veröffentlicht zehn Host-Ports, aber nur fünf davon sind für jemanden außerhalb des Stacks gedacht. Kein Eintrag bindet an eine bestimmte Adresse.
- Es gibt an keiner Stelle TLS — weder Reverse Proxy noch Ingress noch Zertifikatsverwaltung liegen bei.
- Die Modelle sind Attrappen, solange sie nicht umgestellt sind.
Welche Ports das im Einzelnen sind, welcher Dienst welchen Token verlangt und wie die Umstellung auf echte Modelle abläuft: Betrieb ordnet es ein, „Network design“ in der README und die Abschnitte 6 bis 10 des Betriebshandbuchs sind die maßgeblichen Fassungen.
- Wissensbereiche-und-Freigaben — warum Verarbeiten und Veröffentlichen getrennt sind und was eine Freigabe genau festschreibt
- Rechte-und-Sichtbarkeit — Teams, Wissensbereiche und warum die Rechte Teil der Suchanfrage sind
- Chat-und-Bots — Bots, Quellenangaben und der Umgang mit leeren Treffern
- Betrieb — Netzaufbau, Tokens, Modelldienste