Baue ein System, das hochgeladene Dokumente einliest und für KI-Agenten durchsuchbar macht

## Benenne Zweige einheitlich und trenne API-, Worker- und gemeinsamen Code Machen Sie Zuständigkeiten vor Codeänderungen sichtbar, damit jedes Verhalten in der Ebene bleibt, die es testen und warten kann. ### Nachverfolgbare Zweige verwenden - Benennen Sie Zweige nach dem Muster `type/user/description pattern`. - Schreiben Sie `type` klein und wählen Sie eine anerkannte Änderungsklasse wie `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `perf`, `ci`, `build` oder `revert`. - Verwenden Sie für `user` die für die Arbeit verantwortliche Person; ersetzen Sie sie niemals durch einen allgemeinen Agenten- oder Werkzeugnamen. - Halten Sie `description` kurz, klein geschrieben und im Format mit Bindestrichen. ### Zuständigkeiten zur Laufzeit trennen - Halten Sie synchrone API-Verarbeitung, asynchrone Dokumentenarbeit, gemeinsam genutzte Modelle und Dienste sowie Bereitstellungsbelange in getrennten Paketen. - Ordnen Sie Endpunktsteuerung, Geschäftsregeln, Persistenz, Analyse, Informationsabruf und allgemeine Hilfsfunktionen Modulen mit eindeutiger Zuständigkeit zu; behandeln Sie unabhängig vertriebene SDKs als eigene Produkte. - Wenn ein Verhalten mehrere Pakete betrifft, definieren Sie zuerst den gemeinsamen Vertrag und testen Sie jede zuständige Implementierung. ## Leite jede hochgeladene Datei an einen Parser für ihr Format Verwenden Sie eine gestufte Verarbeitungskette, damit jedes Dokument einen sichtbaren Weg vom Hochladen bis zu zitierbaren Abrufbelegen durchläuft. 1. Nehmen Sie die hochgeladene Datei an, erstellen Sie einen Auftrag, speichern Sie das Quellobjekt dauerhaft und stellen Sie die asynchrone Verarbeitung in die Warteschlange. 2. Analysieren Sie das Dokumentprofil einmalig und leiten Sie das Dokument anhand von Dateityp und Strukturbelegen an einen Parser weiter. 3. Überführen Sie die Parserausgabe in einen einheitlichen typisierten Tabellenvertrag. 4. Überführen Sie Zeilen in typisierte Segmentdatensätze. 5. Stellen Sie Dokument-, Abschnitts-, Segment- und Graphzustand vor dem Abruf bereit. ### Parsersteuerung ausdrücklich festlegen - Verwenden Sie für alle Formate einen typisierten Parser-Einstiegspunkt und geben Sie auftragslokale Artefaktpfade zurück. - Leiten Sie PDF-, DOCX-, PPTX-, Tabellenkalkulations-, Markdown-, Text-, Bild- und Rohsegmenteingaben über formatspezifische Strategien; konvertieren Sie ältere Bürodateiformate vor dem modernen Parser. - Trennen Sie bei PDFs die offene semantische Klassifikation von reinen Steuerungskategorien wie Atlas, Scandokument, Foliensatz und allgemeines Dokument. - Führen Sie die Strukturanalyse für übergroße Dokumente einmal am Einstiegspunkt aus und geben Sie den daraus entstehenden Aufteilungsplan an nachgelagerte Schritte weiter. - Entfernen Sie nach der Analyse Bilder ohne Verweis und wenden Sie eine deterministische Bildkomprimierung an. ## Erkenne die Überschriftenhierarchie und behalte Tabellen und Bilder bei der Umwandlung Bestimmen Sie die Struktur anhand der stärksten verfügbaren Belege und bewahren Sie bei der Konvertierung Tabellen, Bilder und Beziehungen zwischen Überschriften. ### Überschriften in Belegreihenfolge bestimmen 1. Verwenden Sie ein eingebettetes Inhaltsverzeichnis als verbindliche Grundlage, sofern es vorhanden ist. 2. Gleichen Sie ausdrückliche Nummerierungsmuster und sprachspezifische Kapitelmarkierungen ab. 3. Verwenden Sie ein LLM-Hierarchiemodell nur für noch ungeklärte Überschriftenkandidaten. 4. Bündeln Sie bei layoutreichen PDFs die Schriftgeometrie in eine begrenzte Zahl von Überschriftenebenen. ### Formatspezifisches Verhalten bewahren - Durchlaufen Sie DOCX-Textelemente in Quellreihenfolge, einschließlich Absätzen, Tabellen, Bildern und Inhaltsverzeichnisbereichen. - Führen Sie einen Überschriftenstapel, der untergeordnete Ebenen schließt, wenn eine neue Überschrift auf eine übergeordnete Ebene zurückkehrt. - Konvertieren Sie Tabellen mit korrekten `rowspan`- und `colspan`-Werten in HTML und entfernen Sie Bildduplikate mithilfe eines perzeptuellen Hashes. - Leiten Sie Standard-PDFs durch Extraktion und Markdown-Analyse; leiten Sie atlasähnliche oder übergroße Dokumente über ihre jeweiligen Spezialpfade. - Verwenden Sie für Zusammenfassung, Hierarchieerkennung, Bildbeschreibung, OCR und Grobklassifikation jeweils eigene Modellkonfigurationsschlüssel. ## Speichere Chunks, Navigation und Manifest in festem Format Behandeln Sie den dauerhaft gespeicherten Korpus als maßgebend; zwischenzeitliche DataFrames sind flüchtige Implementierungsdetails. ### Korpus- und Dokumentzustand speichern - Speichern Sie korpusweite Graphmetadaten und Statistiken zu Abrufzugriffen neben je einem Verzeichnis pro aufgenommenem Dokument. - Speichern Sie geordnete Segmente, hierarchische Navigation, Analysemetadaten, den vollständigen Überschriftenbaum, archivierte Quellressourcen, extrahierte Bilder und Tabellen sowie Diagnoseausgaben dauerhaft. - Verwenden Sie genau drei grundlegende Segmenttypen: `text`, `image` und `table`. - Geben Sie jedem Segment eine deterministische `chunk_id`, typisierte Inhalte, einen Hierarchiepfad sowie Metadaten zu Länge, Zusammenfassungen, Seitenzahlen, Token, Schlüsselwörtern, Dateipfaden und segmentübergreifenden Verweisen. ### Verweise und Navigation bewahren - Stellen Sie eingebettete Beziehungen durch `connect_to`-Einträge dar, die `target`, `relation`, `ref` und die als Zeichenversatz angegebene `position` enthalten. - Verwenden Sie `embeds` für eingebettete Ressourcen und `related` für nicht eingebettete Verknüpfungen. - Erstellen Sie `doc_nav.json` als Abschnittsbaum mit Zusammenfassungen, der Anzahl der Segmente, untergeordneten Elementen und Bild- oder Tabellenressourcen. - Erstellen Sie `manifest.json` mit Quellmetadaten, Statistiken und einer verschachtelten `HIERARCHY`. - Wandeln Sie flüchtige Parserzeilen in typisierte Segmentnutzdaten um, bevor Sie `chunks.json` schreiben. ## Stelle Datenbankeinträge, Suchindizes und Graphverbindungen gemeinsam bereit Stellen Sie einen konsistenten Revisionsstand bereit, damit relationale Datensätze, Suchkanäle und Graphkanten dieselbe Segmentmenge beschreiben. ### Zuständigkeit für relationale Daten wahren - Speichern Sie Dokumentidentität, Eigentümer, Namensraum, Status, aktive Revision und Quelldateinamen auf Dokumentebene. - Speichern Sie übergeordnete Verknüpfungen, Pfade, Titel, Ebenen, Zusammenfassungen und Sortierreihenfolge in einem revisionsbezogenen Abschnittsbaum. - Speichern Sie Inhaltshashes, Segmenttypen, durchsuchbaren Text, Quellpfade, Ressourcenpfade, Metadaten und Sortierreihenfolge je Segment. - Begrenzen Sie Graphknoten auf das jeweilige Dokument und verwenden Sie ungerichtete Graphkanten, wenn diese symmetrische Beziehungen darstellen. ### In einer festen Reihenfolge bereitstellen 1. Entfernen Sie Segmentduplikate dokumentübergreifend anhand eines deterministischen Inhaltshashes. 2. Erstellen Sie übergeordnete Abschnitte aus Segmentpfaden von oben nach unten. 3. Erzeugen Sie für jedes Segment getrennte Inhalts-, Pfad- und Rohbegriffssuchkanäle. 4. Erstellen Sie Dokumentgraphknoten und Kanten für Schlüsselwortüberschneidungen nur, wenn mindestens 3 Schlüsselwörter übereinstimmen und die Bewertung mindestens 0.8 beträgt. Verwenden Sie tokenisierte Inhalte mit Zusammenfassungen für die Inhaltssuche, tokenisierte Dateinamen und Abschnittspfade für die Pfadsuche sowie Rohinhalte mit Pfaden für die Teilzeichenfolgensuche. ## Biete klassische Suche mit Ranking und Agentensuche innerhalb eines Budgets Trennen Sie Anfrageformung, lexikalische Suche, Nachladen von Inhalten, Graphzugriff, Zugriffstatistik, Arbeitsablaufausführung, Navigation und Belegdarstellung nach Zuständigkeit. ### Beide Abrufarten bewahren - Kombinieren Sie im klassischen Modus Pfad-, Inhalts- und Begriffskanäle mit reziproker Rangfusion. - Verwenden Sie die Standardgewichte der Kanäle `path=1.0`, `content=2.0` und `term=1.5` mit `score = weight / (k + rank + 1)` und `k=60`. - Lassen Sie im agentenbasierten Modus einen Planer komplexe Anfragen in einen DAG aus Abrufschritten zerlegen; planen Sie keine Schritte zur Antwortsynthese innerhalb des Abrufs. - Erzwingen Sie ein gemeinsames Tokenbudget für den gesamten DAG. Halten Sie bei dessen Ausschöpfung sicher an und geben Sie die bis dahin besten gesammelten Belege zurück. - Führen Sie Ermittlung, beschränkte Abschnittsnavigation nach dem Breitensuchverfahren und Belegdarstellung als getrennte Phasen aus. - Geben Sie `evidence_text` als primäre Antwort aus und behalten Sie das veraltete `answer_text` nur als leeres Kompatibilitätsfeld bei. ### Inhalte gezielt nachladen und einstufen - Stellen Sie ungeöffnete Abschnitte als Gliederungen aus Titel und Zusammenfassung dar und laden Sie rohe `text`-, `image`- und `table`-Segmente nur für ausgewählte Blätter nach. - Lösen Sie verbundene Ressourcen systemnah auf und betten Sie sie direkt ein, ohne anfällige Platzhalter auf Grundlage von Zeichenkettenersetzungen. - Ordnen Sie Agentenergebnisse zuerst nach `agent_score`, dann nach `discovery_score`; verschieben Sie Zeilen mit `agent_score=0` in eine Ausweichmenge. - Schließen Sie vor dem Zusammenstellen die angegebenen Dokumente und Abschnitte aus und beschränken Sie das Ergebnis auf erlaubte Segmenttypen. - Fügen Sie Quellenangaben mit `document_id`, `chunk_id`, `source_file_name` und `section_path` an. ## Halte Chunk-IDs stabil und speichere nur erfolgreiche Ergebnisse im Cache Legen Sie Schnellpfade, Kennungen, Änderungsreihenfolge und Telemetrie ausdrücklich fest, damit Optimierungen die Abrufsemantik nicht verändern. ### Reproduzierbare Ergebnisse sicherstellen - Leiten Sie Segmentkennungen ausschließlich aus einem stabilen Hash des Textinhalts ab und schließen Sie Bild- und Tabellenverweise aus, damit identische Inhalte über mehrere Hochladevorgänge hinweg zusammengeführt werden. - Planen Sie DOM-Änderungen zuerst und wenden Sie sie danach in umgekehrter Reihenfolge an, um Indexverschiebungen zu vermeiden. - Entfernen Sie identische Bilder innerhalb eines Dokuments mithilfe eines perzeptuellen Hashes und verwenden Sie zwischengespeicherte Metadaten erneut. - Geben Sie wiederholten Bildern an unterschiedlichen Positionen deterministische, aber eindeutige Kennungen und überspringen Sie bei der Suche nach nahem Textkontext binäre Kennungen. ### Schnellpfade und Zwischenspeicher begrenzen - Wenn `total_chunks <= top_k` gilt, geben Sie alle Segmente direkt über einen ausdrücklichen Pfad für kleine Korpora zurück. - Speichern Sie nach Benutzer, Namensraum, Anfrage, `top_k` und Filtern zwischen; prüfen Sie die Zwischenspeicherversion vor der Ausführung und schreiben Sie erst nach erfolgreichem Abschluss. - Erfassen Sie Zugriffe je Segment und Dokument für Rangverbesserungen, ohne den Quellinhalt zu verändern. - Führen Sie für Agentenaktionen, Eingaben, Ausgaben, Latenz und Tokenverbrauch Ausführungs- und Schrittdatensätze, die nur durch Anhängen erweitert werden können. ## Beachte Eigenheiten der LLM-API und prüfe lokal, bevor du fertig meldest Legen Sie Modellbeschränkungen und lokale Prüfbefehle ausdrücklich fest, damit Fehler diagnostizierbar bleiben. ### Modellanbindungen absichern - Fügen Sie das Wort `json` ein, wenn Sie den DeepSeek-Modus `json_object` anfordern. - Verketten Sie während der Datenstromverarbeitung `delta.content` nur, wenn es nicht `None` ist. - Wechseln Sie API-Zugriffstoken innerhalb der Ratenbegrenzung jedes Tokens, wenden Sie Wartezeiten an und wiederholen Sie den Vorgang sofort mit dem nächsten verfügbaren Token. - Beschränken Sie den Abruf auf Belege; nachgelagerte Agenten entscheiden, ob die Belege ausreichen, und synthetisieren Antworten außerhalb des Abrufdienstes. ### Das System lokal prüfen - Installieren Sie aus dem fest versionierten Arbeitsbereich, kopieren Sie Umgebungsvorlagen lokal und starten Sie die erforderlichen Datenbank-, Zwischenspeicher-, Objektspeicher-, API- und Verarbeitungsdienste. - Stellen Sie gezielte durchgängige Prüfbefehle für Parser, Dokumentenprofiler, Hierarchie und agentenbasierte Abläufe bereit; führen Sie anschließend Codequalitätsprüfungen, sichere automatische Korrekturen und Typprüfungen über API-, Verarbeitungs- und gemeinsam genutzte Pakete hinweg aus. - Prüfen Sie die lokale API-Dokumentation und die Endpunkte der unterstützenden Dienste, bevor Sie Fehler auf höheren Ebenen der Verarbeitungskette diagnostizieren. - Melden Sie den Abschluss erst, wenn für den betroffenen Parser, den Bereitstellungspfad, die Abrufart und die Qualitätsprüfungen direkte Ergebnisse vorliegen.