52 lines
2.5 KiB
Markdown
52 lines
2.5 KiB
Markdown
# Migration Guide: Google AI Builder Apps -> Local Docker Stack
|
|
|
|
> **CRITICAL WARNINGS & BEST PRACTICES (READ BEFORE MIGRATION):**
|
|
>
|
|
> 1. **DIE GOLDENE REGEL DER STRINGS:** Nutze **NIEMALS** `f"""..."""` für komplexe Prompts oder Listen-Operationen mit verschachtelten Keys. Es führt unweigerlich zu `SyntaxError: unterminated string literal`. Nutze **AUSSCHLIESSLICH Triple Raw Quotes (`r"""..."""`)** und die **`.format()`** Methode.
|
|
> 2. **SDK WAHL (DUAL SDK):** Das moderne `google-genai` ist gut, aber das Legacy `google-generativeai` ist oft stabiler für reinen Text (`gemini-2.0-flash`). Nutze die "Dual SDK Strategy" aus `helpers.py`.
|
|
> 3. **GROUNDED TRUTH (MUSS):** Verlasse dich niemals auf das Wissen des Modells allein. Implementiere **immer** Web-Scraping (Homepage + Unterseiten) und SerpAPI-Suchen, um das Modell mit Fakten zu füttern.
|
|
> 4. **DOCKER VOLUMES:** Mounte **nur spezifische Dateien**, niemals den `dist`-Ordner überschreiben. Bei Syntax-Fehlern, die trotz Korrektur bleiben: `docker-compose build --no-cache`.
|
|
|
|
---
|
|
|
|
## 0. Der "Quick-Start" Checkliste (5-Minuten-Plan)
|
|
|
|
1. **SDK:** Stehen beide SDKs in der `requirements.txt`?
|
|
2. **Prompts:** Sind alle Prompts als `r"""...""".format()` angelegt?
|
|
3. **Grounding:** Werden Produkt- und Branchenseiten gescrapt?
|
|
4. **Package.json:** Sind Build-Tools in `dependencies`?
|
|
5. **Vite Config:** Ist `base: './'` gesetzt?
|
|
|
|
---
|
|
|
|
## 1. Vorbereitung & Abhängigkeiten (Common Pitfalls)
|
|
|
|
Bevor Code kopiert wird, müssen die Grundlagen stimmen.
|
|
|
|
### 1.1 Package.json Check (Frontend Build-Falle)
|
|
Build-Tools wie `vite`, `@vitejs/plugin-react` oder `typescript` müssen in den `dependencies` stehen, nicht in `devDependencies`. Der multi-stage Docker-Build installiert standardmäßig keine dev-dependencies.
|
|
|
|
### 1.2 Python Syntax & F-Strings (Der Prompt-Albtraum)
|
|
Verschachtelte Anführungszeichen in F-Strings sprengen den Python-Parser in vielen Umgebungen.
|
|
**RICHTIG:**
|
|
```python
|
|
prompt = r"""
|
|
Analysiere "{name}". Antworte JSON: {{"key": "value"}}
|
|
""".format(name=item['name'])
|
|
```
|
|
|
|
### 1.3 Volume Mounts & Datei-Synchronisierung
|
|
Einzeldatei-Mounts (`- ./file.py:/app/file.py`) sind oft unzuverlässig bei schnellen Code-Änderungen. Im Zweifel das Image neu bauen.
|
|
|
|
---
|
|
|
|
## 2. Die AI Engine (Standard)
|
|
|
|
Nutze für alle Services die Logik aus `gtm_architect_orchestrator.py`:
|
|
1. **Dual SDK Support** (Legacy + Modern).
|
|
2. **Modell-Fallback** (Versuche 2.0-flash, dann 1.5-flash).
|
|
3. **Grounded Scraping** vor jedem KI-Aufruf.
|
|
|
|
---
|
|
*Dokumentation finalisiert am 10.01.2026 nach der Competitor-Analysis Odyssee.*
|