Repository navigation
Haeufige Fragen
Die Fragen, die im Betrieb tatsächlich gestellt werden, nach Zielgruppe sortiert. Jede Antwort ist kurz und verweist auf die maßgebliche Stelle im Repository — die steht dort, nicht hier.
Zwei Quellen beantworten fast alles Weitere: die Symptomtabelle im Betriebshandbuch für Fehlerbilder aus Betreibersicht und Stille Fallen für die Fehlkonfigurationen, bei denen nichts abstürzt und keine Fehlermeldung erscheint.
Der häufigste Fall: die Freigabe fehlt. „Verarbeitet" heißt nur, dass der OCR-Auftrag fertig ist — nicht „für die KI freigegeben" und nicht „indexiert". Erst die ausdrückliche Freigabe erzeugt den unveränderlichen Snapshot, den Weave-Knowledge indiziert.
Weg dorthin: Prüfen und freigeben → Text lesen → „Geprüften Stand freigeben". Der vollständige Ablauf steht in wissensportal.md, „Ablauf für Fachbereiche"; das Konzept dahinter in Wissensbereiche-und-Freigaben.
Das sind zwei verschiedene Zustände. Die Kette ist Freigegeben → Wird indiziert → Für KI verfügbar. „Für KI verfügbar" erscheint erst, wenn Knowledge genau diese Freigabe samt Snapshot-Hash bestätigt und Textabschnitte und Embeddings vollständig gespeichert sind.
Die Anzeige aktualisiert sich selbst — bei ausstehender Indexierung alle fünf Sekunden, bei stabilen Zuständen alle 30. Hintergrund-Tabs pausieren und prüfen beim Öffnen erneut. Die Seite muss also nicht offen bleiben.
Nicht verwechseln mit dem Zustellstatus (pending, sent, failed): der
beschreibt ausschließlich die Zustellung des Webhooks, nie den Abschluss der
Indexierung. Siehe
wissensportal.md.
Das ist weder eine erfolgreiche noch eine fehlgeschlagene Indexierung, sondern eine fehlende Rückmeldung: fehlende Konfiguration, Timeout, HTTP-Fehler oder eine Bestätigung, die nicht zu dieser Freigabe passt. Eine ältere grüne Bestätigung bleibt in dem Fall nicht stehen.
Für Fachanwender heißt das: später erneut nachsehen. Für Betreiber ist es ein Hinweis auf die Verbindung Ingest → Knowledge — die Zustände im Einzelnen stehen im Vertrag zum Indexierungsstatus.
Dafür gibt es drei klar unterscheidbare Gründe, und der Trace im Chat benennt sie:
-
no_collections— es gibt keine Collection, die dieser Bot nutzen darf und du lesen darfst. Gesucht wird dann gar nicht erst. -
no_context— gesucht wurde, gefunden wurde nichts Verwertbares. Der Bot antwortet lieber mit einem festen Text als mit einer unbelegten Antwort. -
filter_excluded_all— deine eigene Auswahl in der Seitenleiste hat das Ergebnis geleert, nicht fehlende Rechte. Dieser Fall hat einen eigenen Antworttext und ist der einzige der drei, den du selbst beheben kannst.
Ist die Freigabe erfolgt und trotzdem kein Treffer da, siehe die zwei Fragen
oben. Die genauen Definitionen stehen im
Chat-Vertrag,
Abschnitt zu GuardTrace; die Einordnung in Chat-und-Bots.
Es gibt zwei verschiedene Sichtbarkeiten, und sie werden regelmäßig verwechselt:
- Im Portal entscheiden Eigentümer- und Teamrechte am jeweiligen Auftrag. Administratoren sehen alle Aufträge.
- Im Chat entscheiden die berechtigten Teams des Wissensbereichs. Ein Wissensbereich ohne Einschränkung ist für alle lesbar; sonst muss dein Team ausdrücklich genannt sein. Wer gar keinem Team zugeordnet ist, bekommt nur die uneingeschränkten Bereiche zu sehen.
Berechtigte Teams pflegt der Eigentümer beim Anlegen, ein Administrator nachträglich unter Administration → Wissensbereiche. Ohne Teamzuordnung hilft nur die Administration. Details in Rechte-und-Sichtbarkeit und in wissensportal.md.
Die Auswahl in der Chat-Seitenleiste ist ein Filter, kein Rechtebezug: sie
kann die Menge nur einengen, nie erweitern. Nennst du ausschließlich Bereiche,
die du ohnehin nicht lesen darfst oder die dieser Bot nicht nutzt, bleibt
nichts übrig — erkennbar am Grund filter_excluded_all. Auswahl aufheben und
erneut fragen.
Das ist so gewollt: eine Freigabe ist ein unveränderlicher Snapshot, pro Auftrag gibt es genau eine. Bearbeiten und erneutes Verarbeiten eines freigegebenen Auftrags werden mit HTTP 409 abgewiesen. Für geänderten Inhalt ist eine neue Dokumentversion nötig.
Vor der Freigabe steht dagegen Mit anderem Profil neu verarbeiten offen — auch dann, wenn die Qualitätsprüfung blockiert. Siehe wissensportal.md.
In dieser Version gar nicht. Freigegebene Aufträge lassen sich nicht löschen (HTTP 409), und der Entzug bereits publizierter Inhalte ist noch nicht implementiert — zuerst wird eine nachvollziehbare Rücknahme mit Entfernung aus dem Index gebraucht. Das ist in wissensportal.md als offener Punkt ausgewiesen.
Nein. In der Dokumentprüfung Mit anderem Profil neu verarbeiten wählen; die Auswahl bietet dieselben Profile wie der Quellenablauf. Der Neustart ersetzt den bisherigen Entwurf und erzeugt selbst keine Freigabe — das Ergebnis wird erneut geprüft und ausdrücklich freigegeben.
Ausnahme Confluence: Seitentext wird direkt importiert und lässt sich nicht durch ein OCR-Profil neu aufbereiten. Unterstützte Anhänge schon, nach abgeschlossenem Import.
Bei Confluence muss der gesamte Import erfolgreich abgeschlossen sein, damit abschließende Links und Hierarchiemetadaten im Snapshot enthalten sind. Vorher verweigert die Freigabe. Ebenso verweigert sie ein Quality-Block.
Zwei weitere Punkte, die regelmäßig überraschen: Confluence-Zugangsdaten sind nur für den jeweiligen Eigentümer nutzbar, und individuelle Seitenrechte aus Confluence werden nicht automatisch übertragen — die Zugriffsgrenze in Weave ist der Wissensbereich.
Das ist der übersetzte Text für jeden Serverfehler des Gateways; die Chat-Oberfläche zeigt bewusst nie einen rohen Statuscode. Kurz später erneut versuchen. Bleibt es dabei, ist es ein Betriebsproblem — dann gilt die Frage „Der Chat antwortet 502" weiter unten.
Ebenso übersetzt: eine abgelaufene Anmeldung, ein abgelehntes Token und ein Ratelimit. Die vollständige Zuordnung von Statuscode zu Satz steht in services/chat/src/lib/errors.ts.
Der reguläre Weg ist Mit Weave anmelden — wer sich im Wissensportal anmelden kann, kann auch chatten. Schlägt das fehl, landet man auf der Login-Seite mit einem von drei Gründen: der Code fehlte, der Code war ungültig (unbekannt, abgelaufen oder bereits verbraucht), oder das Gateway war nicht erreichbar. Der zweite Fall löst sich in der Regel dadurch, dass man den Anmeldevorgang neu startet, statt einen alten Link erneut zu öffnen.
Gemeint ist, wer die Ingest-Oberfläche unter /admin verwaltet — Nutzer, Teams,
Wissensbereiche, Verbindungen, Bots, Chat-Modell.
Zuerst prüfen, ob er überhaupt einem Team zugeordnet ist: Ein Nutzer ohne Team bekommt ausschließlich uneingeschränkt lesbare Bereiche. Danach unter Administration → Wissensbereiche die berechtigten Teams des Bereichs kontrollieren. Beides ist eine Einstellung in Ingest, kein Deployment-Problem.
Bleiben die Wissensbereiche für alle Nutzer leer, ist es dagegen der Registry-Sync — siehe die nächste Frage.
Dann scheitert der Registry-Sync von Ingest nach Knowledge, und das hat fast immer eine Ursache: der hinterlegte Ingest-Token gehört keinem Administrator. Knowledge holt die Collection-Registry über einen Admin-Endpunkt. Ein frei gewählter oder gelöschter Token führt zu HTTP 401.
Der Token wird unter Konto → API-Tokens erzeugt und vom Betreiber eingetragen; die Reihenfolge steht in betrieb.md, Erstinbetriebnahme.
Entweder ist er deaktiviert, oder seine Webhook-Adresse liegt außerhalb der erlaubten Basisadressen. Beides ist eine Einstellung, kein Fehler. Belegt in der Symptomtabelle.
Nein. Aktivierte Änderungen unter Administration → Chat & LLM gelten ab dem nächsten direkten Chat-Turn für alle Runtime-Replikate. Wichtig ist die Ausnahme: n8n-Bots verwenden weiterhin das Modell, das im jeweiligen n8n-Flow konfiguriert ist — die zentrale Einstellung erreicht sie nicht. Begründung in ADR-0007.
Ja, seit v0.7.1. Unter Administration → Chat & LLM → Weitere LLM-Endpunkte einen Endpunkt anlegen und ihn im Bot-Formular als LLM-Endpunkt wählen. Sollen Nutzer selbst wechseln dürfen, die Endpunkte zusätzlich unter Im Chat zur Auswahl anbieten eintragen; im Chat erscheint dann eine Auswahl Sprachmodell. Einzelheiten: Chat-und-Bots.
Die Dokumente stammen vermutlich aus der Zeit vor den Wissensbereichen und
tragen keinen Bereich. Seit v0.7.1 schliessen neue Bots solche Dokumente
standardmässig aus, bestehende Bots beziehen sie weiter ein. Abhilfe: einmal
reconcile-collections laufen lassen, das ordnet sie ihrem Bereich zu
(Wissensbereiche-und-Freigaben). Wer sie ohne Bereich braucht, schaltet im
Bot „Dokumente ohne Wissensbereich einbeziehen“ ein.
Dann liegen sie noch im Wissensindex, meist aus der Zeit, bevor Ingest jeden gelöschten Auftrag selbst zurückgezogen hat, oder von einem gelöschten Wissensbereich. Seit v0.7.1 findet und entfernt ein Admin-Job solche verwaisten Dokumente: erst Probelauf, dann Anwenden. Ablauf und Gründe in betrieb.md, Abschnitt 3.3.
Nein. Die Freigabe wird über Ingests eigenen internen Veröffentlichungskanal
zugestellt; die beiden nötigen Werte rendert weave.yaml bereits. Selbst
angelegte Webhooks bedienen fremde Konsumenten und haben mit dem Index nichts
zu tun.
Der Dokumenteigentümer, der Eigentümer des Wissensbereichs oder ein Administrator. Leserechte allein genügen nicht — auch nicht für Mit anderem Profil neu verarbeiten.
Gemeint ist, wer das Deployment und deploy/.env verantwortet. Die vollständige
Symptomtabelle steht in
betrieb.md, Abschnitt 10;
hier stehen nur die Fälle, bei denen die Einordnung wichtiger ist als der
Tabelleneintrag.
Der Standardfall ist ein RUNTIME_API_TOKEN, das zwischen Weave-API und
Weave-Runtime auseinanderläuft. Ein 502 heißt also fast immer „das Gateway
kommt nicht durch", nicht „der Dienst ist tot".
Zwei benachbarte Fälle mit demselben Statuscode: ein abweichendes
RETRIEVAL_API_TOKEN (Retrieval antwortet 401, die Aufrufer melden 502 — es
sieht aus wie ein Ausfall), und eine gesetzte, aber nicht erreichbare
Chat-Konfigurationsquelle, bei der /v1/bots scheitert und die Runtime sich
degraded meldet. Letzteres reißt die ganze Bot-Liste mit, auch die lokalen
YAML-Bots; das ist Absicht.
Geteilte Werte ohne Klartext vergleichen: die Fingerabdruck-Schleife in betrieb.md, Geteilte Werte.
LLM_PROVIDER steht noch auf fake. Die Voreinstellung ist absichtlich die
Attrappe — der Stack läuft damit vollständig, nur antwortet jeder Bot mit
Platzhaltertext. Dasselbe Muster gilt für Embeddings: bleibt
EMBEDDING_PROVIDER auf fake, indiziert der Dienst klaglos weiter, aber mit
bedeutungslosen Vektoren. Umstellung auf echte Provider:
betrieb.md, Abschnitt 7.
Erst im Trace nachsehen. retrieval.candidates: 0 bei vorhandenen Dokumenten
heißt fast immer, dass die Embedding-Einstellungen von Knowledge und Retrieval
nicht zusammenpassen: verglichen werden nur Chunks, deren gespeicherter
Modellname exakt dem konfigurierten entspricht. Das Ergebnis ist eine leere
Liste, kein Fehler — und der Volltextpfad läuft derweil weiter und verschleiert
es.
guard.reason: no_collections dagegen heißt, der Nutzer hat kein Team oder
keine freigegebene Collection: eine Rechte- oder Freigabefrage, kein
Konfigurationsfehler. Und wenn Dokumente überhaupt nicht im Index landen, fehlt
meist schlicht die Freigabe im Wissensportal; sonst weicht das
Webhook-Secret ab, was das Knowledge-Log als 401 zeigt.
CORS_ORIGINS steuert nicht nur CORS, sondern die Herkunftsprüfung gegen CSRF.
Fehlt die echte Frontend-Adresse, werden alle schreibenden Anfragen abgewiesen,
der Login eingeschlossen. Lokal hängt der Wert an FRONTEND_PORT: wer nur den
Port verschiebt, weil 3000 belegt ist, sieht einen Access-Control-Fehler,
obwohl das eigentliche Problem der Port ist. Beide Werte gehören zusammen
gesetzt. scripts/weave_config.py check meldet genau diesen Widerspruch.
Nein, er ist geschlossen. Diese Lese-Routen geben den indizierten Bestand
heraus, vorbei an der Team-Prüfung, durch die jede Suche geht. Ohne gesetztes
KNOWLEDGE_API_TOKEN antworten sie deshalb 503. Kein Dienst der Plattform ruft
sie auf — sie sind für Betrieb und Fehlersuche da. Setzen, wenn man sie
braucht, sonst leer lassen. Indizierung, Webhook-Eingang und /health sind
davon unberührt.
Der wahrscheinlichste Kandidat ist der Reranker. Weave-Retrieval fängt jeden Reranker-Fehler ab und fällt still auf die unrerankte Reihenfolge zurück — gut für die Verfügbarkeit, schlecht für die Beobachtbarkeit. Ein falscher Token, ein nie warm werdendes Modell oder ein zu knappes Dokumentlimit zeigen sich nicht als Fehler, sondern nur als leise schlechtere Reihenfolge.
Konsequenz für die Überwachung: warm aus /health aktiv beobachten, nicht
nur den HTTP-Status — der ist by design immer 200, auch während des Ladens.
Begründung und Details in
services/reranker/README.md.
Nein. Jeder laufende Auftrag meldet sich regelmäßig in der Datenbank. Bleibt das Lebenszeichen aus, weil der Worker abgestürzt ist oder beim Herunterskalieren beendet wurde, stellt Weave den Auftrag nach etwa zwei Minuten von selbst neu ein. Erst wenn derselbe Auftrag mehr als dreimal hintereinander verloren geht, steht er auf „Fehlgeschlagen“ — dann lohnt der Blick in die Worker-Logs, denn dann liegt es meist am Dokument, nicht am Pod.
Das ist die Budgetprüfung des Charts, kein Fehler. Die geplanten Repliken
würden zusammen mehr Verbindungen öffnen, als postgresql.maxConnections
zulässt. Entweder Repliken bzw. dbPool einzelner Dienste senken, oder
maxConnections erhöhen (am Datenbankserver etwa 5–10 MB RAM je Verbindung)
bzw. einen Pooler davorsetzen:
betrieb.md, Abschnitt 13.
In dieser Reihenfolge:
-
python scripts/weave_config.py check— findet fehlende Pflichtwerte, auseinanderlaufende geteilte Werte und ein paar konkrete Widersprüche, ohne Geheimnisse im Klartext auszugeben. - Der Selbsttest — vier Schritte von der Erreichbarkeit aller Dienste bis zu einer echten Antwort samt Trace.
- Der
traceaus dem letzten Aufruf. Er sagt, an welcher Station es aufgehört hat, und ist der schnellste Weg von „der Chat spinnt" zu einer konkreten Variable.
Die Betriebsseite dieses Wikis ordnet die drei Schritte ein: Betrieb.
- Fehlkonfigurationen, die keine Fehlermeldung erzeugen: Stille Fallen
- Wer was lesen darf und warum: services/retrieval/README.md und services/tools/README.md
- Leeres Ingest-Dashboard unter Windows und Worker-Warnungen bei eingeschränktem Egress: services/ingest/README.md, Troubleshooting
- Unbekannte Begriffe: docs/glossar.html
- Sicherheitsrelevante Funde: SECURITY.md
Einstieg
Konzepte
Betrieb
Im Repository