652 lines
23 KiB
Markdown
652 lines
23 KiB
Markdown
# RetrieX v1.6.0 – Konfigurationsanleitung `config/retriex/genre.yaml`
|
||
|
||
Stand: Version **1.6.0** auf Basis des aktuellen `rag-inprogress.zip`.
|
||
|
||
Diese Anleitung beschreibt, welche fachlichen Werte in `config/retriex/genre.yaml` gepflegt werden, wie sie in der Runtime wirken und welche Prüfungen nach Änderungen ausgeführt werden müssen.
|
||
|
||
`genre.yaml` ist in RetrieX v1.6.0 die zentrale Fachkonfiguration für die aktive Domäne. Im aktuellen Paket ist genau ein Genre aktiv:
|
||
|
||
```yaml
|
||
id: water_analysis
|
||
label: Water analysis / measurement devices
|
||
mode: single_installation_single_genre
|
||
```
|
||
|
||
Wichtig: RetrieX v1.6.0 ist keine Multi-Tenant- oder Multi-Genre-Plattform. Eine Installation steht für ein fachliches Genre. Domainnahe Begriffe, Produktrollen, Query-Guards, Promptregeln, Shop-Matching-Wörter und Regression-Guardrails gehören deshalb hierher, nicht zurück in hart codierte PHP-Listen.
|
||
|
||
---
|
||
|
||
## 1. Rolle von `genre.yaml` im System
|
||
|
||
`genre.yaml` ergänzt die technischen YAML-Dateien unter `config/retriex` um eine fachliche Source-of-Truth-Schicht.
|
||
|
||
In `genre.yaml` gehören insbesondere:
|
||
|
||
- Hauptprodukt-, Zubehör- und Verbrauchsmaterialrollen
|
||
- Produktattribute, Messparameter, Größen-, Farb- oder Längenbegriffe
|
||
- Marken, Kanonisierungen, Schreibvarianten und Synonyme
|
||
- Commerce-/Shop-Suchbegriffe und positive Tokenfilter
|
||
- Referenzauflösung für Follow-ups aus dem Chatverlauf
|
||
- Produktlisten- und Produktlink-Follow-ups
|
||
- exakte Zubehör-/Indikatorcode-Guards
|
||
- technische Prompt- und Antwortprioritäten
|
||
- Measurement-Evidence-Guards
|
||
- Search-Repair-Kandidaten und Direct-Attribute-Lookups
|
||
- Governance-, Source-of-Truth- und Regression-Anker
|
||
|
||
Nicht in `genre.yaml` gehören:
|
||
|
||
- Datenbankzugangsdaten
|
||
- Shopware-Zugangsdaten
|
||
- LLM-Endpunkt
|
||
- Python-/Vector-Service-Pfade
|
||
- Cache-, Lock-, Log- oder Infrastrukturparameter
|
||
- konkrete Modell-Samplingwerte wie Temperature oder Top-P
|
||
|
||
Diese Werte bleiben in `.env`, `services.yaml`, `model.yaml`, `vector.yaml`, `runtime.yaml` oder in der Datenbankkonfiguration.
|
||
|
||
---
|
||
|
||
## 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 Metadaten
|
||
|
||
| Feld | Bedeutung | Anpassung |
|
||
| --- | --- | --- |
|
||
| `id` | technischer Genre-Identifier | Nur ändern, wenn die Installation fachlich umgewidmet wird. |
|
||
| `label` | lesbarer Name | Frei sprechend halten. |
|
||
| `mode` | Betriebsmodell | In v1.6.0 bei `single_installation_single_genre` belassen. |
|
||
| `description` | Kurzbeschreibung | Bei Umwidmung aktualisieren. |
|
||
|
||
### 2.2 `adaptation_surface`
|
||
|
||
`adaptation_surface` ist die Landkarte der fachlichen Anpassungsflächen. Sie dokumentiert, welche Runtime-Pfade durch `genre.yaml` fachlich überlagert oder gespeist werden.
|
||
|
||
Auswirkung:
|
||
|
||
- dient Audit, Review und Migration
|
||
- ändert normalerweise nicht direkt das Antwortverhalten
|
||
- muss zu `configuration_values` passen
|
||
- soll keine fachliche Payload enthalten
|
||
|
||
Ändern nur dann, wenn neue genreabhängige Runtime-Pfade hinzukommen, wegfallen oder umbenannt werden.
|
||
|
||
### 2.3 `configuration_values`
|
||
|
||
`configuration_values` enthält die eigentlichen fachlichen Werte. Änderungen hier können Retrieval, Shop-Suche, Commerce-Routing, Promptbau, Search Repair, Follow-up-Auflösung und Regression-Guards unmittelbar beeinflussen.
|
||
|
||
Grundregel:
|
||
|
||
- Fachwerte immer hier pflegen.
|
||
- Bestehende Gruppenstruktur beibehalten.
|
||
- `source_paths` nicht entfernen.
|
||
- Nach Änderungen immer Validate, Source-Audit, Pattern-Audit und Regression ausführen.
|
||
|
||
### 2.4 `source_paths`
|
||
|
||
`source_paths` verknüpfen Genre-Werte mit den alten oder effektiven technischen Config-Pfaden.
|
||
|
||
Sie sind wichtig für:
|
||
|
||
- Nachvollziehbarkeit
|
||
- Source-of-Truth-Guardrails
|
||
- Migrationssicherheit
|
||
- Audit-Ausgaben
|
||
|
||
Sie liefern nicht selbst den Runtime-Wert. Bei reinen Fachwertänderungen bleiben sie normalerweise unverändert.
|
||
|
||
---
|
||
|
||
## 3. Runtime-Lesemodell in v1.6.0
|
||
|
||
Die folgenden Runtime-Klassen lesen fachliche Werte bevorzugt über `GenreConfig` bzw. genregebundene Konfigurationsviews:
|
||
|
||
| Klasse / Bereich | Typische Genre-Werte | Wirkung |
|
||
| --- | --- | --- |
|
||
| `DomainVocabularyConfig` | Produktrollen, Views, Rollenbegriffe | Geräte-/Zubehörtrennung, Prompt- und Shop-Begriffe |
|
||
| `CommerceQueryParserConfig` | Marken, Canonical Terms, Korrekturen | Shopquery-Normalisierung und Token-Erhalt |
|
||
| `QueryEnricherConfig` | Query-Enrichment-Regeln | Erweiterung oder Fokussierung von Suchanfragen |
|
||
| `CommerceIntentConfig` | Commerce-Signale, Produkt-/Preis-/Shopmuster | Erkennung von Kauf-, Preis- und Shop-Intents |
|
||
| `SalesIntentConfig` | Sales-, Vergleichs-, ROI-Signale | Vertriebsnahe Intent-Erkennung |
|
||
| `AgentRunnerConfig` | Follow-ups, Shopquery-Cleanup, Direct Answer, RAG-Anker | Chatverlauf, Shop-Fallbacks und Antwortsteuerung |
|
||
| `PromptBuilderConfig` | Antwortpriorität, Fact-Grounding, Output-Regeln | Finale Antwortqualität und Grenzen |
|
||
| `SearchRepairConfig` | Repair-Kandidaten, Attribut-Lookup, Zubehörcodes | Reparatur schwacher oder referenzieller Shopanfragen |
|
||
| `NdjsonHybridRetrieverConfig` | Exact Selection, Tabellen-/Indikatormuster | Präzision bei RAG-Fakten und Tabellenextraktion |
|
||
| `LanguageCleanupConfig` | Protected Terms und Cleanup-Profile | Schutz fachlicher Tokens vor Sprachbereinigung |
|
||
| `GovernanceConfig` | Regression- und Audit-Guardrails | Schutz vor Rückfällen in hardcodierte Fachlogik |
|
||
|
||
Legacy-YAMLs bleiben als technische Verarbeitungsschicht relevant, sind aber nicht mehr der bevorzugte Pflegeort für neue fachliche Domänenwerte.
|
||
|
||
---
|
||
|
||
## 4. Gruppen in `configuration_values`
|
||
|
||
### 4.1 `product_roles`
|
||
|
||
Zweck: definiert, welche Begriffe als Hauptprodukt, Zubehör, Verbrauchsmaterial oder rollenbezogene Prompt-/Shop-Begriffe gelten.
|
||
|
||
Wichtige Knoten:
|
||
|
||
- `primary_product_terms`
|
||
- `accessory_product_terms`
|
||
- `requested_accessory_code_terms`
|
||
- `shop_views`
|
||
- `prompt_views`
|
||
- `no_llm_fallback_terms`
|
||
|
||
Auswirkung:
|
||
|
||
- trennt Geräte/Hauptprodukte von Zubehör und Verbrauchsmaterialien
|
||
- beeinflusst Shop-Matching, Promptregeln und No-LLM-Fallbacks
|
||
- verhindert, dass Zubehörfragen als Gerätefragen beantwortet werden
|
||
- schützt Flows wie Indikator/Reagenz/Zubehör gegen falsche Produktrollen
|
||
|
||
Anpassung:
|
||
|
||
- Für ein neues Genre zuerst diese Gruppe überarbeiten.
|
||
- Hauptprodukt- und Zubehörbegriffe getrennt halten.
|
||
- Realistische Nutzerbegriffe, Umlaute und ASCII-Varianten aufnehmen.
|
||
- Keine zu generischen Wörter wie `produkt`, `artikel` oder `teil` als starke Rollenbegriffe verwenden.
|
||
|
||
Beispiel Wasseranalyse:
|
||
|
||
```yaml
|
||
primary_product_terms:
|
||
terms:
|
||
- messgerät
|
||
- analysegerät
|
||
- testomat
|
||
accessory_product_terms:
|
||
terms:
|
||
- indikator
|
||
- reagenz
|
||
- zubehör
|
||
```
|
||
|
||
### 4.2 `product_attributes`
|
||
|
||
Zweck: definiert fachliche Attribute, Constraints und Vergleichsmuster.
|
||
|
||
Wichtige Knoten:
|
||
|
||
- `direct_attribute_cleanup.product_type_terms`
|
||
- `direct_attribute_cleanup.stop_terms`
|
||
- `direct_attribute_cleanup.comparative_constraint_patterns`
|
||
- `size_and_color_terms`
|
||
- `numeric_length_constraints`
|
||
|
||
Auswirkung:
|
||
|
||
- ermöglicht direkte Attributfragen wie „Anschlusskabel länger 20 m“
|
||
- steuert Cleanup vor Search Repair
|
||
- unterstützt Sortier-/Filterlogik für numerische Längen oder Größen
|
||
- kann für andere Genres auf Größe, Farbe, Material, Spannung, Gewinde, Kompatibilität usw. umgewidmet werden
|
||
|
||
Anpassung:
|
||
|
||
- Fachliche Produktartbegriffe austauschen, nicht nur ergänzen.
|
||
- Stop-Terme nur für Bedienwörter verwenden.
|
||
- Regex-Muster vorsichtig ändern und mit echten Prompts testen.
|
||
|
||
### 4.3 `brands_and_canonical_terms`
|
||
|
||
Zweck: pflegt Marken, Kanonisierungen, Schreibweisen und semantische Synonyme.
|
||
|
||
Wichtige Knoten:
|
||
|
||
- `known_brands`
|
||
- `canonical_terms`
|
||
- `query_enrichment_rules`
|
||
- `accessory_focus_variants`
|
||
- `rag_evidence_synonyms`
|
||
|
||
Auswirkung:
|
||
|
||
- schützt Markennamen und Modellfamilien in Shopqueries
|
||
- normalisiert Tippfehler oder Schreibvarianten
|
||
- hält direkte Produktnamen wie `chlor select sensor` oder Modellkürzel wie `testomat lab cl` stabil
|
||
- unterstützt RAG-Evidence-Abgleich über Synonyme
|
||
|
||
Anpassung:
|
||
|
||
- Nur etablierte Synonyme und klare Korrekturen eintragen.
|
||
- Keine aggressiven Kanonisierungen, die Varianten zusammenwerfen.
|
||
- Kürzel wie `CL`, `TH`, `SIO2`, `LAB CL` immer gegen Regression testen.
|
||
|
||
### 4.4 `intent_and_routing`
|
||
|
||
Zweck: enthält fachliche Werte für Commerce-, Sales- und Routing-Erkennung.
|
||
|
||
Wichtige Knoten:
|
||
|
||
- `fuzzy_routing_terms`
|
||
- `commerce_intent`
|
||
- `sales_intent`
|
||
|
||
Auswirkung:
|
||
|
||
- erkennt Preis-, Shop-, Produkt-, Beratungs- und Vergleichsfragen
|
||
- trennt technische Wissensfragen von Produkt-/Kaufintents
|
||
- verhindert, dass reine Fachfragen unnötig zu Shop-Suchen werden
|
||
|
||
Anpassung:
|
||
|
||
- Starke Shopbegriffe und Beratungssignale sauber trennen.
|
||
- Branchen- oder Anwendungskontexte nicht automatisch als Produktbeweis behandeln.
|
||
- Für neue Genres typische Kauf-/Vergleichs-/Beratungswörter ergänzen.
|
||
|
||
### 4.5 `context_resolution`
|
||
|
||
Zweck: löst referenzielle Folgefragen aus Chatverlauf und sichtbaren Antworten auf.
|
||
|
||
Wichtige Knoten:
|
||
|
||
- `commercial_table_follow_up`
|
||
- `referential_terms`
|
||
- `history_anchor_enrichment`
|
||
- `product_list_followup`
|
||
- `meta_query_guard`
|
||
- `rag_anchor_enrichment`
|
||
|
||
Auswirkung in v1.6.0:
|
||
|
||
- Folgefragen wie „was kostet der indikator“ können den letzten Geräte-/Indikatoranker nutzen.
|
||
- Produktlisten-Follow-ups wie „gib mir Links zu den Produkten“ können sichtbare Produktnamen extrahieren.
|
||
- Mehrprodukt-Follow-ups werden auf einzelne Produktanker vorbereitet.
|
||
- Schwache Shopfragen wie „suche im Shop nach der Information“ können auf konkrete History-Anker zurückfallen.
|
||
- RAG-Anker wie Messwerte und Produkttitel helfen, Folgefragen fachlich zu fokussieren.
|
||
|
||
Anpassung:
|
||
|
||
- `referential_terms` sind Pronomen/Füllwörter, keine Produktbegriffe.
|
||
- `product_list_followup.anchor_patterns` müssen konkrete Produktidentitäten erfassen.
|
||
- `meta_query_guard` sollte Bedien-/Meta-Wörter enthalten, die nicht als Suchinhalt dominieren dürfen.
|
||
- Bei neuen Produktfamilien entsprechende `canonical_family_terms` und Startmuster ergänzen.
|
||
|
||
### 4.6 `shop_query_runtime`
|
||
|
||
Zweck: steuert, welche Tokens in Shopqueries erhalten, entfernt, positiv gefiltert oder zu konkreten Produktankern repariert werden.
|
||
|
||
Wichtige Knoten:
|
||
|
||
- `current_input_preservation_terms`
|
||
- `stopword_cleanup`
|
||
- `positive_token_filter`
|
||
- `generic_device_anchor`
|
||
- `compound_prefix_match`
|
||
- `primary_identity_repair`
|
||
- `semantic_shop_search_tokens`
|
||
- `direct_answer`
|
||
|
||
Auswirkung in v1.6.0:
|
||
|
||
- Relationsrauschen wie „erreicht“, „gemessen“, „beim“ oder reine Bedienwörter wird entfernt.
|
||
- Korrigierte Tokens aus der Commerce-Konfiguration bleiben in der finalen Query erhalten.
|
||
- Modellkürzel wie `LAB CL`, `THCL`, `CLT`, `SIO2` werden über positive Filter und Nachbarschaftsregeln geschützt.
|
||
- Generische Gerätefragen können auf konkrete YAML-konfigurierte Geräteanker wie `testomat 808 sio2` geführt werden.
|
||
- Self-Loops bei identischen Folgeaktionsqueries können unterdrückt werden.
|
||
|
||
Anpassung:
|
||
|
||
- `allowed_terms` und `blocked_terms` immer zusammen prüfen.
|
||
- `adjacent_variant_terms` nur für echte Modell-/Variantentokens verwenden.
|
||
- `generic_device_anchor.anchor_rules` ist der richtige Ort für domainnahe Gerät-Parameter-Anker, nicht PHP-Core.
|
||
- Stopwords niemals so breit wählen, dass Produktnamen oder Messparameter verloren gehen.
|
||
|
||
### 4.7 `result_identity_and_answer_policy`
|
||
|
||
Zweck: definiert Antwortregeln, Prompt-Prioritäten, Evidence Guards und Ergebnisidentität.
|
||
|
||
Wichtige Knoten:
|
||
|
||
- `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`
|
||
- `measurement_evidence_guard_terms`
|
||
- `measurement_evidence_maps`
|
||
|
||
Auswirkung:
|
||
|
||
- technische Fakten werden exakt und quellennahe beantwortet
|
||
- niedrigste/höchste Grenzwerte bleiben auf den Primärfakt fokussiert
|
||
- Indikator-/Reagenzfragen werden nicht mit anderen Varianten vermischt
|
||
- Produktselektion mit Shopdaten bleibt an Produktidentität, Produktnummer und explizite Evidence gebunden
|
||
- nicht belegte Informationen sollen als „Nicht bekannt.“ formuliert werden
|
||
|
||
Anpassung:
|
||
|
||
- Promptregeln kurz, eindeutig und testbar halten.
|
||
- Keine Vertriebsversprechen aufnehmen, die aus Quellen nicht belegbar sind.
|
||
- Bei neuen Messparametern `measurement_evidence_maps` erweitern.
|
||
- Exakte Code- und Variantenregeln immer mit Zubehör-/Preisflows testen.
|
||
|
||
### 4.8 `search_repair`
|
||
|
||
Zweck: repariert schwache Shopqueries und direkte Attributsuchen.
|
||
|
||
Wichtige Knoten:
|
||
|
||
- `direct_product_attribute_lookup`
|
||
- `requested_accessory_code_terms`
|
||
- `candidate_patterns`
|
||
- `candidate_terms`
|
||
|
||
Auswirkung:
|
||
|
||
- erkennt spezifische Modell-/Zubehörkandidaten
|
||
- hält exakte Zubehörcodes wie `300` getrennt von Varianten wie `300 S`
|
||
- unterstützt reparierte Queries bei fehlenden oder schwachen Primärtreffern
|
||
- hilft bei Follow-ups, die nur „Preis“, „Shop“ oder „Information“ enthalten
|
||
|
||
Anpassung:
|
||
|
||
- Regexe nicht auf einzelne Produkte hart verdrahten.
|
||
- Code-Muster so definieren, dass Varianten nur bei expliziter Nutzereingabe gematcht werden.
|
||
- Generische Kandidatentokens knapp halten, sonst entstehen breite Shoptreffer.
|
||
|
||
### 4.9 `retrieval_and_language`
|
||
|
||
Zweck: verbindet Genre-Werte mit Retrieval- und Sprachbereinigung.
|
||
|
||
Wichtige Knoten:
|
||
|
||
- `protected_terms`
|
||
- `cleanup_profiles`
|
||
- `retrieval_vocabulary_views`
|
||
- `exact_selection`
|
||
|
||
Auswirkung:
|
||
|
||
- schützt kurze technische Tokens vor Stopword-Cleanup
|
||
- sichert RAG-Evidence- und Retrieval-Referenz-Cleanup
|
||
- unterstützt exakte Auswahl bei Tabellen, Grenzwerten und Indikatormappings
|
||
|
||
Anpassung:
|
||
|
||
- Kurze Modell-/Messparameter-Tokens in Protected-Term-Listen absichern.
|
||
- Cleanup-Profile nicht durch alte Legacy-Stopword-Listen ersetzen.
|
||
- Exact-Selection-Regeln bei Tabellenfragen mit Regression testen.
|
||
|
||
### 4.10 `shop_data_mapping`
|
||
|
||
Zweck: beschreibt fachliche Shopdaten-Zuordnung und Shop-Matching-Rollen.
|
||
|
||
Wichtige Knoten:
|
||
|
||
- `custom_fields`
|
||
- `text`
|
||
- `role_guard`
|
||
- `commerce_connection`
|
||
|
||
Auswirkung:
|
||
|
||
- mappt Shopware-Custom-Fields auf Antwortfelder
|
||
- steuert Geräte-/Zubehörfilterung im Shop-Matching
|
||
- entscheidet, wann Shopdaten als kommerzielle Felder priorisiert werden
|
||
|
||
Anpassung:
|
||
|
||
- Feldnamen an den realen Shopware-Datenbestand anpassen.
|
||
- Rollenfilter nicht so hart setzen, dass Zubehör-/Bundle-Treffer verschwinden.
|
||
- Shopdaten dürfen technische Eignung nur belegen, wenn der Produktdatensatz sie explizit nennt.
|
||
|
||
### 4.11 `governance_and_regression`
|
||
|
||
Zweck: hält Regression- und Audit-Anker für stabile Flows.
|
||
|
||
Wichtige Knoten:
|
||
|
||
- `regression_baseline`
|
||
- `vocabulary_guardrails`
|
||
- `core_pattern_audit`
|
||
|
||
Auswirkung:
|
||
|
||
- schützt zentrale 1.4.x/1.5.x/1.6.0-Flows
|
||
- bewahrt kurze Modell-/Parameter-Tokens
|
||
- verhindert Rückfälle in neue fachliche PHP-Hardcodings
|
||
- macht verdächtige Pattern-/Token-Nutzung im Core reviewbar
|
||
|
||
Anpassung:
|
||
|
||
- Neue stabile Kunden-/Testflows als Regression-Anker ergänzen.
|
||
- Domain Marker Terms aktuell halten.
|
||
- Audit-Ausnahmen nur für technische Parserlogik zulassen, nicht für fachliche Sonderfälle.
|
||
|
||
---
|
||
|
||
## 5. Wichtige v1.6.0-Guardrails
|
||
|
||
### 5.1 Exakte Zubehör- und Indikatorcodes
|
||
|
||
Ein konkreter Code wie `300` darf nicht automatisch Varianten wie `300 S`, `301` oder `302` einschließen. Varianten sind nur erlaubt, wenn die Nutzerfrage sie explizit nennt oder die Quelle denselben Produktdatensatz eindeutig damit verbindet.
|
||
|
||
Relevant sind insbesondere:
|
||
|
||
- `product_roles.requested_accessory_code_terms`
|
||
- `search_repair.requested_accessory_code_terms`
|
||
- `search_repair.candidate_patterns`
|
||
- `result_identity_and_answer_policy.prompt_rules`
|
||
|
||
### 5.2 Geräteanker bei referenziellen Shopfragen
|
||
|
||
Bei Follow-ups wie „was kostet der indikator“ muss der konkrete Verlaufskontext erhalten bleiben, z. B. Gerät + Indikatortyp. `indikatortyp` ist Kontextsignal, darf aber nicht allein die Shopquery dominieren.
|
||
|
||
Relevant sind:
|
||
|
||
- `context_resolution.history_anchor_enrichment`
|
||
- `context_resolution.commercial_table_follow_up`
|
||
- `shop_query_runtime.positive_token_filter`
|
||
- `shop_query_runtime.stopword_cleanup`
|
||
|
||
### 5.3 Produktlisten- und Link-Follow-ups
|
||
|
||
Bei Fragen wie „gib mir Links zu den Produkten“ soll RetrieX sichtbare Produktanker aus der vorherigen Antwort verwenden und Mehrproduktlisten in Einzelqueries aufteilen.
|
||
|
||
Relevant sind:
|
||
|
||
- `context_resolution.product_list_followup.enabled`
|
||
- `context_resolution.product_list_followup.anchor_patterns`
|
||
- `context_resolution.product_list_followup.max_anchors`
|
||
- `context_resolution.product_list_followup.template`
|
||
|
||
### 5.4 Schwache History-/Meta-Fragen
|
||
|
||
Meta-Fragen wie „suche im Shop nach der Information“ enthalten kaum Produktsubstanz. v1.6.0 darf dann auf den letzten konkreten Produktanker aus der History zurückfallen, statt `information` als Shopquery zu senden.
|
||
|
||
Relevant sind:
|
||
|
||
- `context_resolution.meta_query_guard`
|
||
- `context_resolution.product_list_followup.noise_terms`
|
||
- `shop_query_runtime.stopword_cleanup`
|
||
|
||
### 5.5 Generische Device-Parameter-Anker
|
||
|
||
Fragen wie „Gerät für Silikatüberwachung“ können auf konkrete konfigurierbare Anker wie `testomat 808 sio2` geführt werden. Diese Abbildung gehört in YAML, nicht als Sonderlogik in PHP.
|
||
|
||
Relevant ist:
|
||
|
||
- `shop_query_runtime.generic_device_anchor.anchor_rules`
|
||
|
||
---
|
||
|
||
## 6. Sichere Änderungsreihenfolge
|
||
|
||
### Kleine Wertänderung
|
||
|
||
1. Passenden Knoten in `configuration_values` suchen.
|
||
2. Wert ändern oder ergänzen.
|
||
3. `source_paths` unverändert lassen.
|
||
4. Config und Regression prüfen.
|
||
|
||
### Neues Synonym oder neue Marke
|
||
|
||
1. `brands_and_canonical_terms` prüfen.
|
||
2. Falls Shopquery-relevant: `shop_query_runtime.positive_token_filter.allowed_terms` prüfen.
|
||
3. Falls Retrieval-/Prompt-relevant: `retrieval_and_language.protected_terms` oder passende Vocabulary-Views prüfen.
|
||
4. Gegen echte Prompts testen.
|
||
|
||
### Neues Zubehör oder Verbrauchsmaterial
|
||
|
||
1. `product_roles.accessory_product_terms` ergänzen.
|
||
2. `product_roles.requested_accessory_code_terms` prüfen.
|
||
3. `result_identity_and_answer_policy.response_format_accessory` prüfen.
|
||
4. Shopquery- und Preis-Follow-up testen.
|
||
|
||
### Neues Geräte-/Parameter-Mapping
|
||
|
||
1. `shop_query_runtime.generic_device_anchor.anchor_rules` ergänzen.
|
||
2. `brands_and_canonical_terms.canonical_terms` prüfen.
|
||
3. `result_identity_and_answer_policy.measurement_evidence_maps` ergänzen, falls technische Evidence betroffen ist.
|
||
4. `mto:agent:test:shop-search` und `mto:agent:retrieval:test` ausführen.
|
||
|
||
### Umwidmung auf neues Genre
|
||
|
||
1. `id`, `label`, `description` ändern.
|
||
2. `product_roles` vollständig ersetzen.
|
||
3. Attribute, Marken, Synonyme und Intents ersetzen.
|
||
4. Shopquery-Runtime und Search Repair neu fachlich definieren.
|
||
5. Promptregeln neutralisieren und danach genrebezogen ergänzen.
|
||
6. Regression-Baseline für das neue Genre aufbauen.
|
||
7. Alte Wasseranalyse-Tokens aus Guardrails entfernen, sofern nicht mehr gültig.
|
||
|
||
---
|
||
|
||
## 7. Pflichtchecks nach Änderungen
|
||
|
||
Nach jeder fachlichen Änderung an `genre.yaml` mindestens ausführen:
|
||
|
||
```bash
|
||
php bin/console mto:agent:config:validate
|
||
php bin/console mto:agent:config:audit-source --details
|
||
php bin/console mto:agent:config:audit-patterns --details
|
||
php bin/console mto:agent:regression:test
|
||
```
|
||
|
||
Für Review/CI zusätzlich möglich:
|
||
|
||
```bash
|
||
php bin/console mto:agent:config:dump-effective --summary
|
||
php bin/console mto:agent:config:validate --json
|
||
php bin/console mto:agent:regression:test --json
|
||
```
|
||
|
||
Für praktische Query-Tests:
|
||
|
||
```bash
|
||
php bin/console mto:agent:retrieval:test "niedrigster Grenzwert Wasserhärte"
|
||
php bin/console mto:agent:test:shop-search "testomat 808 300 indikator" --repair
|
||
php bin/console mto:agent:chat cli-debug
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Typische Fehlerbilder
|
||
|
||
| Änderung | Möglicher Fehler |
|
||
| --- | --- |
|
||
| Fachbegriff nur in PHP ergänzt | Audit findet neue hardcodierte Semantik oder spätere Updates verlieren den Wert. |
|
||
| `blocked_terms` zu breit | Produkt-/Parameter-Tokens verschwinden aus Shopqueries. |
|
||
| `allowed_terms` zu eng | Modellkürzel wie `LAB CL` oder `SIO2` fallen auf generische Begriffe zurück. |
|
||
| Zubehörbegriff als Hauptprodukt gepflegt | Zubehörfragen werden als Gerätefragen beantwortet. |
|
||
| Exakte Code-Regel zu weich | `300` zieht Varianten wie `300 S` oder andere Codes in die Antwort. |
|
||
| Product-list Patterns zu breit | Follow-ups erzeugen falsche oder kombinierte Produktqueries. |
|
||
| Promptregel zu allgemein | Antworten werden sales-lastig oder enthalten nicht belegte Details. |
|
||
| Regression-Baseline nicht angepasst | stabile Flows können unbemerkt brechen. |
|
||
|
||
---
|
||
|
||
## 9. Entscheidungsregeln
|
||
|
||
| Wertart | Richtiger Ort |
|
||
| --- | --- |
|
||
| Geräte-/Zubehörwort | `product_roles` |
|
||
| Messparameter oder Attribut | `product_attributes` oder `measurement_evidence_maps` |
|
||
| Markenname / Produktfamilie | `brands_and_canonical_terms.known_brands` |
|
||
| Schreibvariante / Tippfehler | `brands_and_canonical_terms.canonical_terms` oder Commerce-Korrektur |
|
||
| Shopquery-Stopword | `shop_query_runtime.stopword_cleanup` |
|
||
| erhaltenswertes Shop-Token | `shop_query_runtime.positive_token_filter.allowed_terms` |
|
||
| verbotener Shop-Noise | `shop_query_runtime.positive_token_filter.blocked_terms` |
|
||
| generische Gerätefrage zu konkretem Produktanker | `shop_query_runtime.generic_device_anchor.anchor_rules` |
|
||
| Follow-up aus Verlauf | `context_resolution` |
|
||
| Antwort-/Promptgrenze | `result_identity_and_answer_policy.prompt_rules` |
|
||
| Search-Repair-Muster | `search_repair` |
|
||
| Regression-Schutz | `governance_and_regression` |
|
||
|
||
---
|
||
|
||
## 10. Minimalbeispiele
|
||
|
||
### 10.1 Neues Zubehör-Synonym ergänzen
|
||
|
||
```yaml
|
||
configuration_values:
|
||
product_roles:
|
||
accessory_product_terms:
|
||
terms:
|
||
- indikator
|
||
- reagenz
|
||
- kalibrierpuffer
|
||
```
|
||
|
||
Danach testen:
|
||
|
||
```bash
|
||
php bin/console mto:agent:config:validate
|
||
php bin/console mto:agent:regression:test
|
||
```
|
||
|
||
### 10.2 Neues Modellkürzel schützen
|
||
|
||
```yaml
|
||
configuration_values:
|
||
shop_query_runtime:
|
||
positive_token_filter:
|
||
adjacent_variant_terms:
|
||
- lab
|
||
- cl
|
||
- sio2
|
||
```
|
||
|
||
Zusätzlich prüfen, ob das Kürzel auch in `retrieval_and_language.protected_terms` oder Governance-Guardrails geschützt werden muss.
|
||
|
||
### 10.3 Neue generische Geräteanker-Regel
|
||
|
||
```yaml
|
||
configuration_values:
|
||
shop_query_runtime:
|
||
generic_device_anchor:
|
||
anchor_rules:
|
||
- anchor: example device xy
|
||
template: "{anchor}"
|
||
match_terms:
|
||
- beispielparameter
|
||
- beispielüberwachung
|
||
```
|
||
|
||
Danach praktische Shop- und Retrievaltests ausführen.
|
||
|
||
---
|
||
|
||
## 11. Kurzfazit
|
||
|
||
`genre.yaml` ist in RetrieX v1.6.0 die zentrale fachliche Steuerdatei. Sie hält die Domänenlogik aus dem PHP-Core heraus und macht Produktrollen, Query-Verhalten, Follow-up-Auflösung, Shop-Matching, Promptgrenzen und Regression-Guards reviewbar.
|
||
|
||
Neue fachliche Werte sollen hier oder in den angebundenen YAML-Views gepflegt werden. Nach jeder Änderung müssen Config-Validierung, Source-Audit, Pattern-Audit und Regressionstest grün bleiben.
|