775 lines
27 KiB
Markdown
775 lines
27 KiB
Markdown
# Konfigurationsanleitung `config/retriex/genre.yaml`
|
|
|
|
Stand: aktueller Arbeitsstand aus `rag-inprogress.zip`.
|
|
|
|
Diese Anleitung beschreibt, welche Bereiche in `genre.yaml` gepflegt werden, welche Auswirkungen Änderungen haben und wie eine Anpassung sicher durchgeführt wird.
|
|
|
|
---
|
|
|
|
## 1. Zweck der Datei
|
|
|
|
`config/retriex/genre.yaml` ist die zentrale fachliche Konfigurationsfläche für eine RetrieX-Installation mit genau einem aktiven Genre.
|
|
|
|
Aktuell ist das Genre:
|
|
|
|
```yaml
|
|
id: water_analysis
|
|
label: Water analysis / measurement devices
|
|
mode: single_installation_single_genre
|
|
```
|
|
|
|
Wichtig:
|
|
|
|
- Eine Installation steht für ein Genre.
|
|
- Es gibt keine Multi-Tenant-, Multi-Shop-, Host-, API-Key- oder Request-basierte Genre-Umschaltung.
|
|
- Fachliche Listen, Begriffe, Muster, Produktrollen, Antwortregeln und genreabhängige Guardrails gehören in `genre.yaml`.
|
|
- Technische Einstellungen wie Modell, Vector-Index, Chunking, Cache, LLM-Parameter, Store-API-Credentials oder allgemeine Infrastruktur bleiben außerhalb von `genre.yaml`.
|
|
- Die alten YAML-Dateien bleiben als technische Verarbeitungsschicht, leere Fallbacks oder eingefrorene Legacy-Pfade erhalten. Neue fachliche Werte sollen dort nicht wieder eingeführt werden.
|
|
|
|
---
|
|
|
|
## 2. Grundstruktur
|
|
|
|
Die Datei hängt am Symfony-Parameter:
|
|
|
|
```yaml
|
|
parameters:
|
|
retriex.genre.config:
|
|
id: water_analysis
|
|
label: Water analysis / measurement devices
|
|
mode: single_installation_single_genre
|
|
description: ...
|
|
adaptation_surface: ...
|
|
configuration_values: ...
|
|
```
|
|
|
|
### 2.1 `id`, `label`, `mode`, `description`
|
|
|
|
| Feld | Bedeutung | Auswirkung | Anpassung |
|
|
|---|---|---|---|
|
|
| `id` | Technischer Genre-Identifier | Metadaten, Diagnose, zukünftige Dokumentation | Bei Umwidmung ändern, z. B. `fashion`, `spare_parts`, `electronics` |
|
|
| `label` | Lesbarer Name | Audit-/Debug-/Dokumentationswert | Frei sprechend halten |
|
|
| `mode` | Betriebsmodell | Beschreibt bewusst `single_installation_single_genre` | Nicht auf Multi-Genre ändern, solange keine Architektur dafür existiert |
|
|
| `description` | Kurzbeschreibung | Dokumentation | An neues Genre anpassen |
|
|
|
|
### 2.2 `adaptation_surface`
|
|
|
|
`adaptation_surface` ist die Landkarte. Sie gruppiert alle Konfigurationsbereiche, die bei einer Umwidmung des Systems überprüft werden müssen.
|
|
|
|
Sie enthält Beschreibungen und `paths` auf alte/effective Runtime-Konfigurationspfade.
|
|
|
|
Auswirkung:
|
|
|
|
- Ändert normalerweise nicht direkt das Antwort- oder Suchverhalten.
|
|
- Wird für Validierung, Audit und Nachvollziehbarkeit genutzt.
|
|
- Muss synchron zu `configuration_values` bleiben.
|
|
- Jede Gruppe in `adaptation_surface` braucht eine entsprechende Gruppe in `configuration_values`.
|
|
|
|
Anpassen:
|
|
|
|
- Nur ändern, wenn ein neuer genreabhängiger Runtime-Pfad hinzukommt, wegfällt oder umbenannt wird.
|
|
- Keine fachlichen Werte dort pflegen.
|
|
- `paths` müssen gültige Pfade sein; falsche Pfade werden durch Validate/Audit sichtbar.
|
|
|
|
### 2.3 `configuration_values`
|
|
|
|
`configuration_values` ist die eigentliche zentrale Wertefläche.
|
|
|
|
Auswirkung:
|
|
|
|
- Die Runtime-Konfigurationsklassen lesen diese Werte bevorzugt über `GenreConfig`.
|
|
- Änderungen hier beeinflussen Retrieval, Shop-Suche, Commerce-Routing, Search Repair, Antwortregeln, Follow-up-Auflösung, Produktrollentrennung und Regression-Guardrails.
|
|
- Die alten Pfade sollen leer oder eingefroren bleiben.
|
|
|
|
Anpassen:
|
|
|
|
- Fachliche Änderungen immer hier vornehmen.
|
|
- Die bestehende Gruppenstruktur beibehalten.
|
|
- `source_paths` nicht entfernen.
|
|
- Nach Änderungen immer Validate, Regression und Audits ausführen.
|
|
|
|
### 2.4 `source_paths`
|
|
|
|
`source_paths` verknüpft einen Wertknoten in `configuration_values` mit seinen alten/effective Config-Pfaden.
|
|
|
|
Auswirkung:
|
|
|
|
- Dient Audit, Source-of-Truth-Guard und Migrationsnachvollziehbarkeit.
|
|
- Liefert nicht selbst den Runtime-Wert.
|
|
- Falsche oder unbekannte Pfade erzeugen Validate-/Audit-Probleme.
|
|
|
|
Anpassen:
|
|
|
|
- Bei reinen Wertänderungen normalerweise unverändert lassen.
|
|
- Nur ändern, wenn die technische Verdrahtung oder ein Legacy-Pfad wirklich geändert wurde.
|
|
- Wenn ein Wertknoten direkte Payload enthält, muss er selbst oder ein Parent-Knoten `source_paths` deklarieren.
|
|
- Doppelte oder leere `source_paths` sind nicht zulässig.
|
|
|
|
---
|
|
|
|
## 3. Runtime-Lesemodell
|
|
|
|
Die wichtigsten Klassen erhalten `GenreConfig` per Dependency Injection und lesen fachliche Werte bevorzugt aus `genre.yaml`:
|
|
|
|
| Klasse | Liest aus `genre.yaml` | Typische Wirkung |
|
|
|---|---|---|
|
|
| `DomainVocabularyConfig` | Produktrollen, Vocabulary-Views, Prompt-/Shop-/Retrieval-Views, Maps | Grundvokabular, Shop-/Prompt-Rollen, Evidence-Begriffe |
|
|
| `CommerceQueryParserConfig` | Marken, Canonical-Terms | Query-Normalisierung für Shop-Suche |
|
|
| `QueryEnricherConfig` | Query-Enrichment-Regeln | Erweiterung/Umformung von Suchanfragen |
|
|
| `CommerceIntentConfig` | Commerce-Signale, Größen-/Farb-/Produktmuster | Erkennung von Kauf-, Preis-, Shop- und Beratungsabsicht |
|
|
| `SalesIntentConfig` | Sales-/Vergleichs-/ROI-Signale | Sales-orientierte Intent-Erkennung |
|
|
| `AgentRunnerConfig` | Follow-ups, Shop-Query-Cleanup, Direct Answer, Längenfilter, RAG-Anker | Gesprächskontext, Shop-Fallbacks, direkte Shopantworten |
|
|
| `PromptBuilderConfig` | Antwortpriorität, Formatregeln, Fact-Grounding, Evidence Guards | Qualität und Grenzen der finalen Antwort |
|
|
| `SearchRepairConfig` | Direct-Attribute-Lookup, Kandidatenmuster, Repair-Tokens | Reparatur schwacher Shop-Suchen |
|
|
| `NdjsonHybridRetrieverConfig` | Exact Selection, Indicator-/Tabellenmuster | Präzision bei RAG-Fakten und Tabellenextraktion |
|
|
| `LanguageCleanupConfig` | Protected Terms | Schutz wichtiger Tokens vor Cleanup |
|
|
| `GovernanceConfig` | Regression-/Audit-Guardrails | Schutz vor Regressions- und Core-Listen-Rückfällen |
|
|
|
|
Die Legacy-YAMLs sind weiterhin wichtig, aber nicht mehr der primäre Pflegeort für genreabhängige Fachwerte.
|
|
|
|
---
|
|
|
|
## 4. Gruppenübersicht mit Auswirkungen
|
|
|
|
### 4.1 `product_roles`
|
|
|
|
Zweck: Definiert, welche Begriffe als Hauptprodukt, Zubehör, Verbrauchsmaterial oder produktrollenbezogene Prompt-/Shop-Begriffe gelten.
|
|
|
|
Wichtige Werte:
|
|
|
|
- `primary_product_terms.terms`
|
|
- `accessory_product_terms.terms`
|
|
- `requested_accessory_code_terms.terms`
|
|
- `shop_views.*`
|
|
- `prompt_views.*`
|
|
- `no_llm_fallback_terms.*`
|
|
|
|
Auswirkung:
|
|
|
|
- Entscheidet, ob eine Anfrage eher Gerät/Hauptprodukt oder Zubehör meint.
|
|
- Beeinflusst Shop-Query-Aufbau, Produktrollentrennung und Antwortformat.
|
|
- Verhindert z. B., dass Zubehör als Gerät oder Geräte als Zubehör beantwortet werden.
|
|
- Steuert No-LLM-Fallbacks bei einfachen oder schwach belegten Anfragen.
|
|
|
|
Anpassung:
|
|
|
|
- Für ein neues Genre zuerst diese Gruppe anpassen.
|
|
- Hauptproduktbegriffe vollständig ersetzen, nicht nur ergänzen.
|
|
- Zubehör- und Verbrauchsmaterialbegriffe getrennt halten.
|
|
- Synonyme, Umlaute und ASCII-Varianten aufnehmen, wenn Nutzer sie realistisch verwenden.
|
|
- Keine zu allgemeinen Wörter wie `produkt`, `artikel`, `teil` allein als starke Rollenbegriffe verwenden, sonst steigt Fehlrouting.
|
|
|
|
Beispiel Wasseranalyse:
|
|
|
|
```yaml
|
|
primary_product_terms:
|
|
terms:
|
|
- messgerät
|
|
- analysegerät
|
|
- testomat
|
|
accessory_product_terms:
|
|
terms:
|
|
- indikator
|
|
- reagenz
|
|
- zubehör
|
|
```
|
|
|
|
Beispiel Umwidmung Fashion:
|
|
|
|
```yaml
|
|
primary_product_terms:
|
|
terms:
|
|
- shirt
|
|
- hose
|
|
- jacke
|
|
- schuh
|
|
accessory_product_terms:
|
|
terms:
|
|
- gürtel
|
|
- tasche
|
|
- pflegeset
|
|
```
|
|
|
|
---
|
|
|
|
### 4.2 `product_attributes`
|
|
|
|
Zweck: Definiert genreabhängige Attribute und Constraints, z. B. Kabellänge, Messgröße, Größe, Farbe oder Material.
|
|
|
|
Wichtige Werte:
|
|
|
|
- `direct_attribute_cleanup.product_type_terms`
|
|
- `direct_attribute_cleanup.stop_terms`
|
|
- `direct_attribute_cleanup.comparative_constraint_patterns`
|
|
- `size_and_color_terms.*`
|
|
- `numeric_length_constraints.length_sort.*`
|
|
- `numeric_length_constraints.length_filter.*`
|
|
|
|
Auswirkung:
|
|
|
|
- Beeinflusst direkte Produktattribut-Suchen wie „Anschlusskabel länger 20m“.
|
|
- Steuert, welche Wörter nach Cleanup übrig bleiben müssen, damit Search Repair greift.
|
|
- Aktiviert Sortierung oder Filterung nach numerischen Längen-/Größenwerten.
|
|
- Commerce-Intent erkennt Größe/Farbe/Varianten besser oder schlechter abhängig von diesen Listen.
|
|
|
|
Anpassung:
|
|
|
|
- Produktartbegriffe an das Genre anpassen, z. B. `anschlusskabel` durch `sneaker`, `sofa`, `akku`, `ersatzfilter` ersetzen.
|
|
- Stop-Terme nur für Bedienwörter verwenden, nicht für fachliche Kernbegriffe.
|
|
- Regex-Patterns vorsichtig ändern und mit realen Anfragen testen.
|
|
- Für Fashion Größen/Farben ausbauen; für Ersatzteile eher Maße, Kompatibilität, Seriennummern, Gewinde, Spannung usw. pflegen.
|
|
|
|
Achtung:
|
|
|
|
- `nicht`, `kein`, Modellkürzel und fachliche Kurzbegriffe dürfen nicht versehentlich als Stopword entfernt werden.
|
|
- Numerische Patterns müssen Einheiten passend zum Genre abbilden. Bei Fashion wäre `cm`, `inch`, `EU`, `UK`; bei Kabeln `m`, `meter`.
|
|
|
|
---
|
|
|
|
### 4.3 `brands_and_canonical_terms`
|
|
|
|
Zweck: Pflegt Marken, Token-Normalisierung, Synonyme und Query-Enrichment.
|
|
|
|
Wichtige Werte:
|
|
|
|
- `known_brands.terms`
|
|
- `canonical_terms.map`
|
|
- `query_enrichment_rules.rules`
|
|
- `accessory_focus_variants.map`
|
|
- `rag_evidence_synonyms.map`
|
|
|
|
Auswirkung:
|
|
|
|
- Marken werden in Shop-Queries und Query-Parsing besser erkannt.
|
|
- Plural-/Sprachvarianten werden auf kanonische Suchbegriffe zurückgeführt.
|
|
- Query-Enrichment ergänzt fachlich sinnvolle verwandte Suchbegriffe.
|
|
- Evidence-Guards verstehen Synonyme besser.
|
|
|
|
Anpassung:
|
|
|
|
- Markenliste shop- und genrebezogen pflegen.
|
|
- Canonical Map nur für eindeutige Äquivalenzen verwenden.
|
|
- Query-Enrichment nicht als Ranking-Hack missbrauchen; nur semantisch nahe Begriffe ergänzen.
|
|
- Synonyme nicht mit Nicht-Äquivalenten mischen.
|
|
|
|
Beispiel:
|
|
|
|
```yaml
|
|
canonical_terms:
|
|
map:
|
|
reagenzien: reagenz
|
|
indicators: indikator
|
|
```
|
|
|
|
Für Fashion:
|
|
|
|
```yaml
|
|
canonical_terms:
|
|
map:
|
|
sneakers: sneaker
|
|
shirts: shirt
|
|
t-shirts: tshirt
|
|
```
|
|
|
|
---
|
|
|
|
### 4.4 `intent_and_routing`
|
|
|
|
Zweck: Steuert, ob eine Anfrage als Shop-, Preis-, Beratungs-, Produktwahl-, Vergleichs- oder Sales-Anfrage erkannt wird.
|
|
|
|
Wichtige Werte:
|
|
|
|
- `fuzzy_routing_terms.terms`
|
|
- `commerce_intent.strong_signals`
|
|
- `commerce_intent.advisory_signals`
|
|
- `commerce_intent.advisory_product_selection_patterns`
|
|
- `commerce_intent.explicit_commerce_intent_patterns`
|
|
- `commerce_intent.model_like_product_pattern`
|
|
- `sales_intent.*`
|
|
|
|
Auswirkung:
|
|
|
|
- Entscheidet, ob Shop-Suche gestartet wird.
|
|
- Erkennt Follow-ups wie „suche im shop“ oder „was kostet das“.
|
|
- Unterscheidet Beratung von reiner Wissensfrage.
|
|
- Beeinflusst, wann Produktlisten, Preise oder Produktempfehlungen erzeugt werden.
|
|
|
|
Anpassung:
|
|
|
|
- Shop-/Preis-/Kaufbegriffe meist generisch belassen.
|
|
- Produktwahlmuster genrebezogen anpassen, z. B. `mit welchem testomat` durch `welche jacke`, `welcher akku`, `welches ersatzteil` ersetzen.
|
|
- `model_like_product_pattern` nur ändern, wenn Modell-/SKU-Struktur im neuen Genre anders ist.
|
|
- Sales-Signale nur anpassen, wenn die Installation tatsächlich Sales-/B2B-Beratung leisten soll.
|
|
|
|
Risiko:
|
|
|
|
- Zu breite starke Commerce-Signale führen dazu, dass Wissensfragen fälschlich als Shop-Anfragen behandelt werden.
|
|
- Zu enge Muster verhindern gewünschte Shop-Follow-ups.
|
|
|
|
---
|
|
|
|
### 4.5 `context_resolution`
|
|
|
|
Zweck: Löst referenzielle Folgefragen und baut aus dem Verlauf sinnvolle Shop-Queries.
|
|
|
|
Wichtige Werte:
|
|
|
|
- `commercial_table_follow_up.*`
|
|
- `referential_terms.terms`
|
|
- `history_anchor_enrichment.*`
|
|
- `meta_query_guard.*`
|
|
- `rag_anchor_enrichment.*`
|
|
|
|
Auswirkung:
|
|
|
|
- „Was kostet der Indikator?“ kann aus vorherigem Kontext `Indikatortyp 300` ableiten.
|
|
- „Suche im Shop“ kann aus einer vorherigen Produktempfehlung eine konkrete Shop-Suche erzeugen.
|
|
- Meta-only-Anfragen wie `shop`, `preis`, `kosten` werden nicht verworfen, wenn brauchbarer Verlaufskontext existiert.
|
|
- Numerische RAG-Anker wie `0,02 °dH` können mit Produktankern kombiniert werden.
|
|
|
|
Anpassung:
|
|
|
|
- `history_anchor_patterns` und `anchor_patterns` an typische Modell-, Zubehör- oder Variantenanker des Genres anpassen.
|
|
- `query_template_with_model` und `query_template_without_model` nur ändern, wenn Referenzauflösung anders formuliert werden soll.
|
|
- `meta_only_terms` generisch halten, aber `context_fallback_filter_terms` genrebezogen prüfen.
|
|
- `rag_anchor_enrichment.subject_terms` an fachliche Kernthemen des Genres anpassen.
|
|
|
|
Beispiel Wasseranalyse:
|
|
|
|
```yaml
|
|
query_template_with_model: '{model} indikator'
|
|
query_template_without_model: 'indikator'
|
|
```
|
|
|
|
Für Ersatzteile könnte es z. B. werden:
|
|
|
|
```yaml
|
|
query_template_with_model: '{model} ersatzteil'
|
|
query_template_without_model: 'ersatzteil'
|
|
```
|
|
|
|
---
|
|
|
|
### 4.6 `shop_query_runtime`
|
|
|
|
Zweck: Steuert Shop-Query-Cleanup, direkte Shopantworten, semantische Suchbegriffe und Ergebnisidentität.
|
|
|
|
Wichtige Werte:
|
|
|
|
- `current_input_preservation_terms.terms`
|
|
- `semantic_shop_search_tokens.terms`
|
|
- `stopword_cleanup.terms`
|
|
- `compound_prefix_match.terms`
|
|
- `primary_identity_repair.stop_terms`
|
|
- `direct_answer.*`
|
|
|
|
Auswirkung:
|
|
|
|
- Bestimmte kurze Begriffe wie `pH`, `rx`, `orp` bleiben in Shop-Queries erhalten.
|
|
- Semantische Shop-Suchbegriffe verbessern Query-Erweiterung.
|
|
- Stopword-Cleanup entfernt Bedienwörter aus Shop-Queries.
|
|
- Direct Answer bestimmt, wie Shop-Ergebnisse direkt textlich ausgegeben werden.
|
|
|
|
Anpassung:
|
|
|
|
- Für jedes neue Genre kurze geschützte Produkt-/Attributtokens eintragen, z. B. `xl`, `usb-c`, `m8`, `a4`, sofern relevant.
|
|
- Stopwords nicht mit Produktkürzeln vermischen.
|
|
- Direct-Answer-Texte an Tonalität und Produktdomäne anpassen.
|
|
- `max_results` so wählen, dass Antworten nicht überladen werden.
|
|
|
|
Achtung:
|
|
|
|
- Wenn ein wichtiger kurzer Begriff nicht geschützt ist, kann er beim Cleanup verschwinden.
|
|
- Wenn zu viele allgemeine Begriffe geschützt sind, werden Shop-Queries unscharf.
|
|
|
|
---
|
|
|
|
### 4.7 `result_identity_and_answer_policy`
|
|
|
|
Zweck: Definiert Prompt-Regeln, Antwortpriorität, Produktrollen-Trennung und Evidence-Guards.
|
|
|
|
Wichtige Werte:
|
|
|
|
- `prompt_rules.output_priority_technical`
|
|
- `prompt_rules.response_format_technical`
|
|
- `prompt_rules.response_format_accessory`
|
|
- `prompt_rules.fact_grounding_technical`
|
|
- `prompt_rules.fact_grounding_with_shop`
|
|
- `prompt_keyword_views.technical_product_keywords`
|
|
- `measurement_evidence_guard_terms.*`
|
|
- `measurement_evidence_maps.*`
|
|
|
|
Auswirkung:
|
|
|
|
- Bestimmt, welche Fakten in technischen Antworten priorisiert werden.
|
|
- Verhindert, dass Eigenschaften eines Produkts einem anderen Produkt zugeschrieben werden.
|
|
- Steuert die Trennung zwischen Gerät/Hauptprodukt und Zubehör/Verbrauchsmaterial.
|
|
- Sichert, dass Messfähigkeit, Zubehörbezug oder Attributbelege nur beantwortet werden, wenn sie belegt sind.
|
|
|
|
Anpassung:
|
|
|
|
- Antwortregeln domänenspezifisch, aber knapp und testbar formulieren.
|
|
- Evidence-Maps für echte fachliche Mess-/Attributdimensionen pflegen.
|
|
- Nicht-Äquivalenzen explizit halten, z. B. `freies Chlor` ist nicht automatisch `Gesamtchlor`.
|
|
- Für ein anderes Genre positive und negative Kontextbegriffe neu definieren.
|
|
|
|
Beispiel:
|
|
|
|
```yaml
|
|
measurement_evidence_maps:
|
|
request_terms:
|
|
redox:
|
|
- redox
|
|
- orp
|
|
non_equivalent_terms:
|
|
free_chlorine:
|
|
- Gesamtchlor
|
|
```
|
|
|
|
Für Fashion könnte eine analoge Struktur z. B. Größen-/Material-/Passform-Evidence absichern.
|
|
|
|
---
|
|
|
|
### 4.8 `search_repair`
|
|
|
|
Zweck: Repariert schwache oder zu kurze Shop-Suchen und extrahiert Modell-/Zubehör-/Spezifitätskandidaten.
|
|
|
|
Wichtige Werte:
|
|
|
|
- `direct_product_attribute_lookup.*`
|
|
- `candidate_patterns.specific_model_candidate_patterns`
|
|
- `candidate_patterns.patterns.*`
|
|
- `candidate_terms.*`
|
|
|
|
Auswirkung:
|
|
|
|
- Verbessert Suche, wenn die primäre Shop-Suche zu wenig oder falsche Ergebnisse liefert.
|
|
- Erkennt Modellkandidaten, Zubehörcodes, Bundle-/Accessory-Begriffe und Spezifitätsanker.
|
|
- Hilft bei Fällen wie direkten Produktattributfragen oder unvollständigen Shop-Follow-ups.
|
|
|
|
Anpassung:
|
|
|
|
- Candidate-Terms an das Genre anpassen.
|
|
- Regex nur ändern, wenn Modell-/SKU-/Zubehörcode-Struktur wirklich anders ist.
|
|
- `min_query_tokens_after_cleanup` nicht zu niedrig setzen, sonst repariert das System sehr unspezifische Anfragen.
|
|
- Accessory-Code-Muster für neue Domänen neu modellieren, z. B. Ersatzteilnummern, DIN-/Normteile, SKU-Formate.
|
|
|
|
Regex-Hinweis:
|
|
|
|
- Patterns sind Strings wie `'/.../iu'`.
|
|
- YAML-Quoting beibehalten.
|
|
- Nach Änderung immer Syntax und Regression testen.
|
|
|
|
---
|
|
|
|
### 4.9 `retrieval_and_language`
|
|
|
|
Zweck: Schützt wichtige Sprache-/Fachbegriffe und steuert genreabhängige Retrieval-Hilfen.
|
|
|
|
Wichtige Werte:
|
|
|
|
- `protected_terms.terms`
|
|
- `cleanup_profiles.*`
|
|
- `retrieval_vocabulary_views.*`
|
|
- `exact_selection.*`
|
|
|
|
Auswirkung:
|
|
|
|
- Protected Terms verhindern, dass wichtige Wörter beim Cleanup entfernt werden.
|
|
- Retrieval-Vocabulary hilft, Dokumenttypen, Geräte, Reagenzien/Zubehör oder Produkttexte zu erkennen.
|
|
- Exact Selection verbessert gezielte Tabellen-/Faktauswahl, z. B. Indikatortabellen.
|
|
- Falsche Werte hier können RAG-Fakten, Follow-up-Präzision und Tabellenextraktion deutlich verschlechtern.
|
|
|
|
Anpassung:
|
|
|
|
- Protected Terms mit kurzen, wichtigen Tokens des Genres füllen.
|
|
- Cleanup-Profile nur vorsichtig ändern; allgemeine Sprachbereinigung gehört weiter in `language.yaml`, fachlicher Schutz in `genre.yaml`.
|
|
- `looks_like_*`-Listen an Dokument- und Produkttypen des neuen Genres anpassen.
|
|
- Exact-Selection-Bereiche nur verwenden, wenn das Genre ähnliche strukturierte Tabellen-/Faktmuster hat.
|
|
|
|
Achtung:
|
|
|
|
- Negationen wie `nicht`, `kein`, `keine` schützen.
|
|
- Kurze Modell- oder Fachkürzel schützen, z. B. `pH`, `rx`, `th`; in anderen Genres z. B. `XL`, `USB`, `M8`.
|
|
|
|
---
|
|
|
|
### 4.10 `shop_data_mapping`
|
|
|
|
Zweck: Beschreibt, wie Shopware-Felder und Produkttexte für diese Installation interpretiert werden.
|
|
|
|
Wichtige Werte:
|
|
|
|
- `custom_fields.primary`
|
|
- `custom_fields.secondary`
|
|
- `custom_fields.use_cases`
|
|
- `custom_fields.languages`
|
|
- `text.*`
|
|
- `role_guard.*`
|
|
- `commerce_connection.*`
|
|
|
|
Auswirkung:
|
|
|
|
- Bestimmt, welche Shopware-Custom-Fields für Produktbeschreibung, Attribute, Einsatzgebiete oder Sprache genutzt werden.
|
|
- Textlabels beeinflussen die Darstellung/Interpretation von Shopdaten.
|
|
- Role Guard filtert Zubehör bei Geräteanfragen bzw. hält ambige Produkte bei Geräteanfragen.
|
|
- Store-API-URL und max results sind runtime-/env-aufgelöste Pfade und im Guard explizit erlaubt.
|
|
|
|
Anpassung:
|
|
|
|
- Bei anderem Shopdatenmodell zuerst `custom_fields` prüfen.
|
|
- Labels an Shopdaten anpassen, aber nicht mit Prompt-Regeln verwechseln.
|
|
- Role Guard nur ändern, wenn die Produktdaten sauber zwischen Hauptprodukt und Zubehör unterscheiden.
|
|
- Credentials und technische Verbindungswerte nicht hart in `genre.yaml` eintragen; ENV-Referenzen beibehalten.
|
|
|
|
---
|
|
|
|
### 4.11 `governance_and_regression`
|
|
|
|
Zweck: Schützt das aktive Genre durch Regression-Baselines und Audit-Regeln.
|
|
|
|
Wichtige Werte:
|
|
|
|
- `regression_baseline.*`
|
|
- `vocabulary_guardrails`
|
|
- `core_pattern_audit.*`
|
|
|
|
Auswirkung:
|
|
|
|
- Regressionstests wissen, welche Kurzmodelle, Messwerte, fachlichen Keywords und Shop-Query-Fälle geschützt sind.
|
|
- Pattern-Audit erkennt, wenn wieder harte Fachlisten in PHP-Code oder falsche Config-Pfade wandern.
|
|
- Verhindert Rückfälle in Core-Keywordlisten.
|
|
|
|
Anpassung:
|
|
|
|
- Bei Genre-Umwidmung Regression-Baseline konsequent austauschen.
|
|
- Keine alten Wasseranalyse-Werte stehen lassen, wenn sie für das neue Genre nicht gelten.
|
|
- `core_pattern_audit.domain_marker_terms` mit neuen Fachmarkern füllen, damit Audit Rückfälle erkennt.
|
|
- Technische Audit-Ausnahmen nur erweitern, wenn wirklich nötig und mit Begründung.
|
|
|
|
---
|
|
|
|
## 5. Source-of-Truth-Guard
|
|
|
|
Der Guard wird über `config/retriex/governance.yaml` gesteuert:
|
|
|
|
```yaml
|
|
genre_source_of_truth:
|
|
enabled: true
|
|
source: genre.yaml
|
|
legacy_mode: frozen_or_empty_fallback
|
|
```
|
|
|
|
Er prüft:
|
|
|
|
1. `genre.configuration_values` ist vorhanden und nicht leer.
|
|
2. Jede `adaptation_surface`-Gruppe hat eine passende `configuration_values`-Gruppe.
|
|
3. Jeder relevante Wertknoten ist durch `source_paths` abgedeckt.
|
|
4. Alle `source_paths` zeigen auf bekannte Config-Pfade.
|
|
5. Alte Legacy-Pfade sind entweder leer, runtime-aufgelöst erlaubt oder per SHA-256-Hash eingefroren.
|
|
6. Wenn ein eingefrorener Legacy-Wert geändert wird, schlägt Validate/Audit fehl.
|
|
|
|
Bedeutung für die Pflege:
|
|
|
|
- Fachliche Werte in `genre.yaml` ändern.
|
|
- Legacy-Werte nicht parallel ändern.
|
|
- Wenn ein Legacy-Pfad absichtlich nicht leer bleiben muss, braucht er einen bewussten Hash-Eintrag in `governance.yaml`.
|
|
- Wenn ein neuer Runtime-Pfad genreabhängig wird, muss er in `adaptation_surface`, `configuration_values.source_paths` und ggf. in die Guard-Logik aufgenommen werden.
|
|
|
|
---
|
|
|
|
## 6. Sichere Änderungsreihenfolge
|
|
|
|
### Kleine Wertänderung innerhalb des aktuellen Genres
|
|
|
|
1. Passende Gruppe in `configuration_values` finden.
|
|
2. Nur dort Werte ändern.
|
|
3. `source_paths` unverändert lassen.
|
|
4. YAML-Syntax prüfen.
|
|
5. Pflichtchecks ausführen.
|
|
6. Relevante manuelle Regression mit realen Beispielanfragen testen.
|
|
|
|
### Neues Synonym oder neue Marke
|
|
|
|
1. Prüfen, ob es ein Rollenbegriff, Attribut, Canonical Term oder Query-Enrichment ist.
|
|
2. In der passenden Gruppe ergänzen:
|
|
- Marke: `brands_and_canonical_terms.known_brands.terms`
|
|
- Synonym mit echter Gleichwertigkeit: `canonical_terms.map`
|
|
- Query-Erweiterung: `query_enrichment_rules.rules`
|
|
- Evidence-Synonym: `rag_evidence_synonyms.map`
|
|
3. Keine Duplikate in Legacy-YAMLs eintragen.
|
|
4. Shop- und RAG-Testfälle ausführen.
|
|
|
|
### Neues Attribut oder Constraint
|
|
|
|
1. Produkt-/Attributbegriff in `product_attributes.direct_attribute_cleanup.product_type_terms` aufnehmen.
|
|
2. Wenn nötig Cleanup-Stopterms prüfen.
|
|
3. Vergleichs-/Filterpattern nur ergänzen, wenn echte Nutzerformulierungen vorliegen.
|
|
4. Wenn das Attribut in Antworten belegt werden muss, zusätzlich `result_identity_and_answer_policy` prüfen.
|
|
5. Tests mit positiver und negativer Anfrage ausführen.
|
|
|
|
### Umwidmung auf ein neues Genre
|
|
|
|
Empfohlene Reihenfolge:
|
|
|
|
1. `id`, `label`, `description` ändern.
|
|
2. `product_roles` vollständig neu definieren.
|
|
3. `product_attributes` neu definieren.
|
|
4. `brands_and_canonical_terms` austauschen.
|
|
5. `intent_and_routing` auf neue Produktsprache anpassen.
|
|
6. `context_resolution` auf neue Verlaufanker umstellen.
|
|
7. `shop_query_runtime` und geschützte Kurzbegriffe anpassen.
|
|
8. `result_identity_and_answer_policy` neu formulieren.
|
|
9. `search_repair` für neue Modell-/SKU-/Zubehörmuster anpassen.
|
|
10. `retrieval_and_language` auf neue Dokument-/Produktbegriffe umstellen.
|
|
11. `shop_data_mapping` an Shopware-Felder prüfen.
|
|
12. `governance_and_regression` komplett neu setzen.
|
|
13. Tests und Audits ausführen.
|
|
|
|
Wichtig: Nicht nur neue Werte ergänzen, sondern alte Wasseranalyse-spezifische Werte entfernen, wenn sie im neuen Genre keine Bedeutung haben. Sonst bleiben falsche Anker aktiv.
|
|
|
|
---
|
|
|
|
## 7. Pflichtchecks nach Änderungen
|
|
|
|
Im Projekt mit installiertem `vendor/` ausführen:
|
|
|
|
```bash
|
|
bin/console cache:clear
|
|
bin/console mto:agent:config:validate
|
|
bin/console mto:agent:regression:test
|
|
bin/console mto:agent:config:audit-source --details
|
|
bin/console mto:agent:config:audit-patterns --details
|
|
```
|
|
|
|
Zusätzlich sinnvoll:
|
|
|
|
```bash
|
|
php -l src/Config/GenreConfig.php
|
|
python3 - <<'PY'
|
|
import yaml
|
|
from pathlib import Path
|
|
for path in Path('config/retriex').glob('*.yaml'):
|
|
yaml.safe_load(path.read_text())
|
|
print('YAML parse OK')
|
|
PY
|
|
```
|
|
|
|
Hinweis: In der entpackten ZIP liegt kein `vendor/`, deshalb sind die `bin/console`-Checks dort nicht lokal ausführbar. Sie müssen im echten Projektstand mit Dependencies laufen.
|
|
|
|
---
|
|
|
|
## 8. Typische Fehler und Auswirkungen
|
|
|
|
| Fehler | Auswirkung | Korrektur |
|
|
|---|---|---|
|
|
| Fachliche Werte in Legacy-YAML ergänzt | Source-of-Truth-Guard kann brechen; doppelte Pflege kehrt zurück | Wert nach `genre.yaml` verschieben, Legacy leer/eingefroren lassen |
|
|
| `source_paths` entfernt | Validate/Audit meldet fehlende Abdeckung | `source_paths` am Wertknoten oder Parent wiederherstellen |
|
|
| Allgemeines Wort als starkes Rollenwort | Falsches Routing, unscharfe Shop-Suche | Nur fachlich trennscharfe Begriffe verwenden |
|
|
| Wichtiges Kürzel nicht geschützt | Query-Cleanup entfernt es; Shop/RAG verliert Präzision | In `protected_terms` oder `current_input_preservation_terms` aufnehmen |
|
|
| Regex falsch escaped | Runtime-/Validate-Fehler oder keine Treffer | YAML-Quoting und Regex-Syntax prüfen |
|
|
| Alte Genrebegriffe bei Umwidmung behalten | Antworten/Shopqueries driften ins alte Genre | Alte Listen aktiv bereinigen |
|
|
| Negationen als Stopwords entfernt | Antworten können semantisch falsch werden | `nicht`, `kein`, `keine` schützen |
|
|
| Query-Enrichment zu breit | Shop-Suche findet falsche Produkte | Nur echte fachliche Nähe ergänzen |
|
|
| Evidence-Synonyme zu breit | Eigenschaften werden falsch übertragen | Synonyme und Nicht-Äquivalenzen sauber trennen |
|
|
|
|
---
|
|
|
|
## 9. Entscheidungsregeln: Wohin gehört welcher Wert?
|
|
|
|
| Wertart | Gehört nach `genre.yaml`? | Zielgruppe |
|
|
|---|---:|---|
|
|
| Produktrollen, Zubehörrollen, Verbrauchsmaterialrollen | Ja | `product_roles` |
|
|
| Marken und eindeutige Synonyme | Ja | `brands_and_canonical_terms` |
|
|
| Shop-/Kauf-/Preis-Signale mit Genrebezug | Ja | `intent_and_routing` |
|
|
| Nutzer-Stopwords ohne Fachbezug | Eher nein | `language.yaml`, falls allgemeine Sprachschicht |
|
|
| Geschützte Fachkürzel | Ja | `retrieval_and_language.protected_terms` oder `shop_query_runtime.current_input_preservation_terms` |
|
|
| Prompt-Antwortregeln mit Fachbezug | Ja | `result_identity_and_answer_policy` |
|
|
| Technische Prompt-Struktur ohne Fachbezug | Nein | `prompt.yaml` |
|
|
| Modellparameter, Temperatur, Top-K | Nein | Model-/Runtime-Konfiguration |
|
|
| Shopware-Credentials | Nein | ENV / technische Config |
|
|
| Shopware-Custom-Field-Mapping | Ja, wenn installations-/genreabhängig | `shop_data_mapping` |
|
|
| Regression-Fachwerte | Ja | `governance_and_regression` |
|
|
| Audit-Source-Roots und technische Pfadausnahmen | Eher nein bzw. nur Governance | `governance.yaml` / `governance_and_regression.core_pattern_audit` je nach bestehender Struktur |
|
|
|
|
---
|
|
|
|
## 10. Minimalbeispiel: neues Zubehör-Synonym ergänzen
|
|
|
|
Ziel: Nutzer sagen künftig auch „Chemiesatz“ für Reagenz-/Indikator-Zubehör.
|
|
|
|
Prüfen, ob es Rolle, Canonical Term oder Evidence-Synonym ist:
|
|
|
|
- Als Zubehörrolle relevant: ja.
|
|
- Als Suchnormalisierung relevant: eventuell.
|
|
- Als Evidence-Synonym relevant: nur wenn fachlich gleichwertig belegt.
|
|
|
|
Mögliche Änderung:
|
|
|
|
```yaml
|
|
configuration_values:
|
|
product_roles:
|
|
accessory_product_terms:
|
|
terms:
|
|
- indikator
|
|
- reagenz
|
|
- chemiesatz
|
|
```
|
|
|
|
Optional zusätzlich:
|
|
|
|
```yaml
|
|
configuration_values:
|
|
brands_and_canonical_terms:
|
|
canonical_terms:
|
|
map:
|
|
chemiesatz: reagenz
|
|
```
|
|
|
|
Danach testen:
|
|
|
|
- „welcher chemiesatz passt zu ...“
|
|
- „suche chemiesatz im shop“
|
|
- Negativtest: Gerät darf dadurch nicht als Zubehör klassifiziert werden.
|
|
|
|
---
|
|
|
|
## 11. Minimalbeispiel: neues kurzes Attribut schützen
|
|
|
|
Ziel: Im neuen Genre ist `M8` ein wichtiger Anschluss-/Gewindetyp und darf nicht aus Shop-Queries verschwinden.
|
|
|
|
Mögliche Änderung:
|
|
|
|
```yaml
|
|
configuration_values:
|
|
retrieval_and_language:
|
|
protected_terms:
|
|
terms:
|
|
- m8
|
|
shop_query_runtime:
|
|
current_input_preservation_terms:
|
|
terms:
|
|
- m8
|
|
```
|
|
|
|
Danach testen:
|
|
|
|
- „zeige mir kabel m8 länger 5m“
|
|
- „suche im shop nach m8“
|
|
- „was kostet das m8 kabel“ nach vorherigem Kontext
|
|
|
|
---
|
|
|
|
## 12. Kurzfazit
|
|
|
|
`genre.yaml` ist die fachliche Source of Truth für eine Single-Genre-RetrieX-Installation.
|
|
|
|
Bei Anpassungen gilt:
|
|
|
|
1. Fachwerte in `configuration_values` ändern.
|
|
2. `adaptation_surface` nur als Inventar pflegen.
|
|
3. `source_paths` als Audit-Verknüpfung erhalten.
|
|
4. Legacy-YAMLs nicht wieder mit Fachwerten füllen.
|
|
5. Nach jeder Änderung Validate, Regression und Audits ausführen.
|
|
6. Bei Genre-Umwidmung alte Fachbegriffe bewusst entfernen, nicht nur neue ergänzen.
|