Wie Antworten fundiert bleiben

Ein Assistent für Dokumentation ist nur dann sinnvoll, wenn er sich nichts ausdenkt. Eine falsche Antwort in selbstsicherem Ton kostet mehr als gar kein Assistent: Die Leserin oder der Leser handelt danach, und einen Tag später bekommt Ihr Support-Posteingang die Folgen zu spüren.

Die entscheidende Frage lautet also nicht „Nutzt er KI?“ — sondern aus welchen Quellen darf das Modell antworten, und was geschieht, wenn die richtige Passage nicht vor ihm liegt. Diese Seite liefert die Antwort – in dem Detailgrad, den Sie beim Lesen der Implementierung erhalten würden.

Was Sie erhalten#

Jede Antwort, die der Leser sieht, wird aus Seitentext erstellt, den Docsbook für diese konkrete Frage in dieser Anfrage abgerufen hat. Der Leser kann den Vorgang verfolgen: Das Widget gibt Found N results sowie für jede geöffnete Seite eine Reading <page>-Zeile aus, die jeweils einen Link zur Seite selbst enthält. Unter der Antwort befindet sich eine Liste von Quellenangaben, und eine Quellenangabe bleibt nur erhalten, wenn das Modell den Pfad dieser Seite inline in seiner eigenen Antwort zitiert hat oder der Server diese Seite tatsächlich für diese Frage abgerufen hat. Ein vom Modell erfundener und nie zitierter Pfad kann nicht zu einer Quellenangabe werden.

Wenn beim Abruf nichts Relevantes gefunden wird, wird das Modell angewiesen zu sagen, dass die Dokumentation dies nicht abdeckt, statt etwas Plausibles zu formulieren. Diese Ablehnung wird aufgezeichnet, nicht verschluckt — sie wird zu einer Zeile in Ihrem Bericht zu unbeantworteten Fragen und zu einem chat.no_answer-Webhook, der Ihnen signalisiert, welche Seite Sie als Nächstes schreiben sollten.

Wie wird eine Antwort erstellt?#

Sieben Stufen, in dieser Reihenfolge. Jede unten aufgeführte Stufe ist ein tatsächlicher Zweig in der Anfrage, kein Diagramm.

1. Ihre Dokumentation wird in Einheiten aufgeteilt und anschließend eingebettet#

Die automatische Indexierung erfolgt auf Überschriftenebene: eine Einheit pro Abschnitt einer Seite. Der an das Einbettungsmodell gesendete Text besteht aus dem Breadcrumb der Abschnittsüberschrift, gefolgt vom Abschnittstext — Billing > Refunds vor dem Erstattungstext —, weil ein Abschnitt namens „Einschränkungen“ unter „Webhooks“ etwas anderes bedeutet als unter „KI-Chat“ und der Vektor diesen Unterschied enthalten muss. Jede Einheit ist auf 6.000 Zeichen begrenzt. Im Indexierer gibt es auch eine Granularität auf Seiten- und Zeilenebene; der automatische Pfad verwendet Überschriften.

Die Identität einer Einheit besteht aus ihrem Seitenpfad und ihrem Überschriftenanker. Anker wiederholen sich innerhalb einer Seite — ein Änderungsprotokoll kann vierzig ### Fixed-Überschriften enthalten —, daher erhält ein wiederholter Anker ein ordinales Suffix. Ohne dieses wäre jeder dieser Abschnitte dieselbe Einheit, und der Schreibvorgang würde kollidieren.

2. Einheiten werden zu Vektoren, und unveränderte Einheiten kosten nichts#

Embeddings sind openai/text-embedding-3-small, 1.536 Dimensionen und werden über OpenRouter in Stapeln von 96 Einheiten pro Aufruf angefordert. Die Speicherspalte ist ein vector(1536), und ein Modell, das eine andere Breite zurückgibt, wird direkt abgelehnt, anstatt gespeichert und später unbemerkt inkonsistent zu sein.

Jede Einheit enthält einen Inhaltshash von sha256(model + NUL + text). Bei einer Neuindizierung wird eine Einheit, deren Hash bereits gespeichert ist, übersprungen. Wenn Sie also eine Seite bearbeiten, kostet das nur die Embedding-Menge einer Seite und nicht des gesamten Korpus. Die Schätzung, die Ihnen vor einem Durchlauf angezeigt wird, enthält eine exakte Einheitenanzahl (der Splitter ist deterministisch und wurde bereits ausgeführt) sowie eine ungefähre Tokenanzahl von characters ÷ 4 — betrachten Sie diesen Wert als ±30 %, weshalb er als Schätzung und nicht als Preis angegeben wird.

3. Die Neuindexierung folgt Ihren Commits#

Jeder Commit an Ihrer Dokumentation reiht eine Neuindexierung ein. Ein eingereihter Lauf wird alle zwei Minuten von einem Hintergrundprozess aufgegriffen, nicht von einem an die bereits gesendete Antwort angehängten Callback — genau ein solcher Callback ist früher während der Ausführung abgebrochen und hat einen gestempelten, aber leeren Index hinterlassen. Aufeinanderfolgende Commits innerhalb von fünf Minuten werden zu einem Lauf zusammengefasst, da ein Veröffentlichungsablauf zunächst Inhalte, dann die Navigation und anschließend das Branding committet.

Ob die semantische Suche verwendet wird, entscheidet sich durch das Vorhandensein von Vektoren, niemals durch einen Zeitstempel der letzten Indexierung. Ein Zeitstempel ist eine Behauptung; eine Zeile ist ein Beweis, und genau darin liegt der gesamte Unterschied zwischen „semantische Suche ist aktiviert“ und „semantische Suche funktioniert“.

4. Der Abruf führt jedes Mal beide Retriever aus#

Die Vektorsuche ruft die 6 nächstgelegenen Zeilen anhand der Kosinusdistanz ab, wandelt sie in eine Ähnlichkeit von 1 − distance um, verwirft alles unter einem Ähnlichkeitsschwellenwert von 0.25, entfernt Duplikate nach Seite, bevor sie auf 3 gekürzt wird (sechs Treffer sind oft sechs Abschnitte derselben Seite), und behält ihre Prioritätsposition in der endgültigen Liste bei.

Die Volltextsuche ist hier kein Fallback. Sie wird bei jeder Frage ausgeführt, und ihre Seiten werden hinzugefügt, wobei die Anzahl so begrenzt wird, dass Vektor- und lexikalische Suche zusammen nie mehr als 5 Seiten liefern. Der Grund dafür ist anhand unseres eigenen Index messbar: Bei der Frage "Welches URL-Muster verwendet Docsbook, um meine Dokumentationswebsite bereitzustellen?" rangierte der am besten passende Chunk der richtigen Seite anhand der Kosinusähnlichkeit auf Platz 48 von 1.341 Chunks — 18 andere Seiten erzielten höhere Werte — während die lexikalische Suche ihn als obersten Treffer zurückgab, weil die Seite die Begriffe der Anfrage wörtlich enthält. Kein Wert von top-k behebt das; die Rangfolge selbst war für diese Anfrage falsch. Ein nicht leeres, aber falsches Vektorergebnis ist genau der Fehler, den diese Zusammenführung korrigieren soll, und eine Regel nach dem Muster „lexikalische Suche nur ausführen, wenn die Vektorsuche leer ist“ kann ihn nicht erkennen.

Die letzten beiden Zeilen der Tabelle gelten für Korpora ohne jeglichen Index. Die agentische Schleife stellt dem Modell ein search_docs-Tool zur Verfügung und ermöglicht es ihm, bis zu 4 Hin-und-Rückfragen lang bei Temperatur 0 mit anderen Formulierungen erneut zu suchen, bevor es sich auf höchstens zwei Seitenpfade festlegen muss — so, wie man nach dem ersten erfolglosen Versuch einen Codebestand mit grep durchsuchen würde.

5. Die Seiten werden abgerufen und vom Ende gekürzt#

Jede ausgewählte Seite wird aus deinem Repository über dessen Standard-Branch abgerufen und mit ihrem Pfad und Titel in einer Kopfzeile in den Prompt eingefügt. Eine Seite mit mehr als 12.000 Zeichen wird nicht am Anfang gekürzt: Die ersten 9.000 Zeichen und die letzten 3.000 bleiben erhalten, wobei die Auslassung dazwischen gekennzeichnet wird. Rückerstattungsrichtlinien, „Verwandte Inhalte“ und Abschnitte zur Fehlerbehebung befinden sich am Ende einer Seite. Durch das Kürzen am Anfang würde daher genau der Teil wegfallen, auf den sich eine Frage höchstwahrscheinlich bezieht. Die Seite, auf der sich der Leser gerade befindet, wird separat eingefügt und auf 8.000 Zeichen gekürzt.

6. Das Modell wird vor dem Schreiben eingeschränkt#

Das Standardmodell des Reader-Chats ist openai/gpt-4o-mini — ein Kontextfenster mit 128.000 Tokens und eine Ausgabebegrenzung von 16.384 Tokens laut der Modellreferenz von OpenAI. Du kannst pro Projekt ein anderes Modell auswählen; siehe KI-Chat.

Die Systemnachricht ist kurz und kann von dir ersetzt werden. Die Regeln zur Quellenbindung befinden sich im Anweisungsblock, der zusammen mit den Inhalten eintrifft, und sie sind spezifisch, weil jede einzelne Regel auf einem tatsächlich aufgetretenen Fehler beruht:

• Stütze dich ausschließlich auf die bereitgestellten Inhalte. Greife niemals auf vortrainiertes Wissen zurück, um einen Begriff zu definieren oder eine Lücke zu füllen, die in der Dokumentation nicht abgedeckt ist.
• Behaupte nicht, dass etwas fehlt, wenn die Information vorhanden ist. Lies die bereitgestellten Seiten erneut, bevor du sagst, dass etwas fehlt — auch dann, wenn sich die Information auf einer Seite befindet, die zugleich eine kostenpflichtige oder optionale Funktion behandelt.
• Halte kostenloses und kostenpflichtiges Verhalten getrennt. Vermische kein Detail von der kostenpflichtigen Seite mit der Beschreibung der Standardvariante.
• Die Seiten wurden durch eine Suche gefunden, nicht von einem Menschen geprüft. Prüfe jede Seite anhand der konkreten Frage und nicht anhand von Wortüberschneidungen. Eine Seite über Unterverzeichnisse für Lokalisierungen enthält zwar die Wörter „URL pattern“, beantwortet aber keine Frage zur Standard-URL.
• Achte auf die engere Fragestellung. Wenn eine Seite eine qualifizierte Version der Frage beantwortet (eine Sprache, einen Tarif oder ein Add-on), die Frage aber keine solche Einschränkung enthielt, beantwortet diese Seite etwas anderes.
• Einrichtungsfragen erfordern einen konkreten Satz. Suche bei „Wie richte ich X ein?“ nach dem Satz, der einen konkreten Menüpfad, eine Schaltfläche oder einen Schritt für X nennt. Gibt es keinen solchen Satz, sage, dass die Dokumentation keine integrierte X-Integration beschreibt — eine Erwähnung von X an anderer Stelle oder ein allgemeiner Mechanismus, der theoretisch mit X verbunden werden könnte, ist kein Einrichtungsablauf.
• Voraussetzungen sind zwingend und werden zweimal genannt. Durchsuche die gesamte Seite nach einem erforderlichen Tarif, einer Rolle, einem vorherigen Schritt, einer Version oder einem Kontingent — in der Dokumentation stehen diese Angaben am Anfang oft in einer kurzen fettgedruckten Zeile, die man auf dem Weg zu den nummerierten Schritten leicht überspringt. Eine abschließende Prüfung unmittelbar vor der Generierung liest den Anfang jeder Seite erneut, da eine Voraussetzung, die nur in der Einleitung einer Seite genannt wird, nichts Vergleichbarem in der Nähe gegenübersteht, sobald das Modell bis zum relevanten Unterabschnitt gelesen hat.

Die Antwort wird als striktes JSON angefordert — ein Markdown-Text und ein refs-Array — und mit einer Temperatur von 0,3 gestreamt.

7. Zitate werden vom Server angehängt, nicht dem Modell anvertraut#

Dies ist der Schritt, der entscheidet, ob ein Zitat überhaupt etwas bedeutet.

Die Ankerregel ist keine Pedanterie. Eine von Hand geschriebene Slug-Regel („Kleinbuchstaben, Leerzeichen in Bindestriche umwandeln, Sonderzeichen entfernen“) stimmt bei gewöhnlichen ASCII-Satzzeichen nicht mit dem Renderer überein — Edge cases & errors wird auf der Seite zu edge-cases--errors und in einer selbst erstellten Regel zu edge-cases-errors — und reduziert eine nichtlateinische Überschrift auf nichts als Bindestriche. Eine einzige Instanz berechnet diese Zeichenfolge; alle anderen fragen sie ab.

Was passiert, wenn nichts Relevantes gefunden wird#

Es wird nichts erfunden, um die Lücke zu füllen. Wenn jeder Retriever leer zurückkommt, werden keine Seiten angehängt, es erscheint keine Found N results-Zeile, und die Anweisung an das Modell lautet, schlicht zu sagen, dass der bereitgestellte Inhalt die Frage nicht beantwortet.

Die Verweigerung wird anschließend als Daten behandelt:

• Der Antworttext wird auf ein Muster für unbeantwortete Fragen geprüft; ein Treffer löst neben dem gewöhnlichen chat.question_asked-Ereignis einen chat.no_answer-Webhook aus.
• Die Frage erscheint unter Unbeantwortete Fragen, der gefilterten Ansicht aller protokollierten Chatfragen, deren Antwort diese Prüfung nicht bestanden hat.
• Leser können eine Antwort im Widget negativ bewerten; diese Bewertungen werden in Ihren Analysen als seitenbezogene Anzahl der Ablehnungen erfasst.

Eine Lücke in Ihrer Dokumentation ist als Berichtzeile wertvoller als als erfundener Absatz – genau dieser Abwägung ist diese gesamte Seite gewidmet.

Warum dies der richtige Weg ist (Belege)#

Was wir messen — und was wir nicht veröffentlichen#

Wir veröffentlichen keinen Genauigkeitsprozentsatz für den Docsbook-AI-Chat. Wir haben keinen gelabelten Benchmark über Kundenkorpora durchgeführt, und eine Zahl, die anhand unserer eigenen Dokumentation ermittelt wurde, würde Ihnen nichts über Ihre Dokumentation sagen. Eine solche Zahl zu nennen, würde gegen die Regel verstoßen, nach der der Rest dieser Dokumentation verfasst ist.

Stattdessen gibt es Folgendes:

Diese letzte Zeile ist beabsichtigt. „Die semantische Suche ist aktiviert“ lässt sich von außen nicht falsifizieren — genau so konnte ein abgestempelter, aber leerer Index einst monatelang als funktionierend gelten. Wenn der Retriever bei jeder Antwort genannt wird, kann jeder diese Aussage überprüfen, auch Sie.

Docsbook führt außerdem zwei interne Testsuiten aus — einen Golden Set mit 40 Fällen, der bewertet, nach welchem Tool das Modell bei Temperatur 0 zuerst greift, sowie eine Live-Szenario-Suite mit deterministischen Prüfungen und einem eng gefassten LLM-Evaluator. Beide decken den Admin-Assistenten in Ihrem Dashboard ab, nicht den Chat für Leser, und wir sagen das ausdrücklich, statt zuzulassen, dass ihre grünen Häkchen als Qualitätsaussage für das Thema dieser Seite verstanden werden.

Grenzen#

• Keine veröffentlichte Genauigkeitskennzahl. Siehe oben. Behandle jede einzelne Genauigkeitszahl eines Anbieters – auch unsere, falls wir jemals eine angeben – als unbrauchbar, bis sein Korpus, sein Fragenset und sein Grader veröffentlicht wurden.
• Retrieval kann mit voller Überzeugung falsch liegen. Der oben genannte Fall auf Platz 48 von 1.341 stammt von uns und basiert auf unserem eigenen Korpus. Das Zusammenführen des lexikalischen Retrievals korrigiert eine große Fehlerklasse; es beseitigt sie jedoch nicht vollständig. Retrieval ist außerdem genau dort am unzuverlässigsten, wo es am meisten darauf ankommt: Messungen zeigen, dass Retrieval bei weniger verbreiteten Fakten am meisten hilft, bei denen das Modell nichts Auswendig gelerntes als Rückgriffsmöglichkeit hat (Mallen et al., 2023).
• Die Ähnlichkeitsuntergrenze von 0.25 ist eine feste Konstante und wird nicht pro Korpus angepasst. Ein Korpus mit ungewöhnlichem Vokabular benötigt möglicherweise eine andere Untergrenze, und derzeit gibt es dafür keine projektbezogene Steuerung.
• Der Zitierfilter verwendet ODER, nicht UND. Eine Referenz bleibt erhalten, wenn der Pfad abgerufen wurde oder wenn das Modell ihn inline zitiert hat. Wenn beides erforderlich war, blieb refs bei fast jeder Antwort leer, weil Modelle das Array ausfüllen und den Marker überspringen. Die Folge ist, dass ein Pfad, den das Modell sowohl erfunden als auch inline zitiert hat, den Filter passieren würde; nur die abgerufene Hälfte ist konstruktionsbedingt fundiert. Solange die Inline-Hälfte nicht ebenfalls gegen das Korpus geprüft wird, bleibt dies eine offene Frage.
• Grounding ist kein Beweis für inhaltliche Treue. Der Server kann garantieren, dass eine zitierte Seite gelesen wurde; er kann jedoch nicht garantieren, dass jeder Satz der Antwort daraus folgt. Genau diesen verbleibenden Anteil misst RAGTruth, und er ist real.
• Der Detektor für unbeantwortbare Fragen ist ein englischer Musterabgleich. Eine in einer anderen Sprache formulierte Ablehnung wird nicht erkannt, sodass chat.no_answer und der Bericht zu unbeantworteten Fragen auf nicht englischsprachigen Websites zu niedrige Werte ausweisen. Solange wir keinen gemessenen Ersatz veröffentlichen, bleibt dies eine offene Frage.
• Sehr lange Seiten verlieren ihren Mittelteil. Eine Seite mit mehr als 12.000 Zeichen erreicht das Modell als Kopf- und Endabschnitt, wobei der Mittelteil als ausgelassen markiert ist. Eine Information, die ausschließlich im Mittelteil einer sehr langen Seite steht, kann übersehen werden. Die Aufteilung dieser Seite ist die Lösung und verbessert die Seite auch für Menschen.
• Das Modellverhalten ist versionsabhängig. Das standardmäßige Lesemodell, sein Kontextfenster und sein Ablehnungsverhalten können vom Anbieter geändert werden. Der Mechanismus auf dieser Seite stammt von uns; die Befolgung dieses Mechanismus durch das Modell nicht.
• Semantisches Retrieval benötigt Vektoren. Bis ein Indexlauf abgeschlossen ist, greift das Retrieval auf die Volltextsuche und den Dokumentgraphen zurück. Das ist ein funktionierender Chat, kein defekter – aber es ist nicht der in Stufe 4 beschriebene.

Verwandte Themen#

• KI-Chat — der Vertrag: was der Assistent tun kann und was nicht.
• Suche — der lexikalische Index, den diese Pipeline gemeinsam nutzt.
• Quellen — was der Assistent über Ihre Seiten hinaus lesen darf.
• Chat-Hooks — eine Frage blockieren oder dem Modell eine Tatsache übergeben, die nur Ihre Systeme kennen.
• Wie Docsbook seine Aussagen belegt — die Regel, nach der diese Seite verfasst ist.