103 lines
5.7 KiB
Markdown
103 lines
5.7 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", um beide je nach Bedarf zu verwenden.
|
|
> 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. **SDKs:** Stehen `google-genai` UND `google-generativeai` in der `requirements.txt`?
|
|
2. **Prompts:** Sind alle Prompts als `r"""...""".format()` angelegt?
|
|
3. **Grounding:** Wird vor dem KI-Call die Webseite der Firma gescrapt?
|
|
4. **Package.json:** Sind Build-Tools (`vite`, `typescript`) in `dependencies` (NICHT `devDependencies`)?
|
|
5. **Vite Config:** Ist `base: './'` gesetzt?
|
|
6. **DB-Datei:** Wurde die leere `.db`-Datei auf dem Host via `touch` erstellt?
|
|
|
|
---
|
|
|
|
## 1. Detaillierte Fehlerlösungen & Code-Vorlagen
|
|
|
|
Dieser Abschnitt enthält die aus der Git-Historie wiederhergestellten "Lessons Learned".
|
|
|
|
### 1.1 Python: Abhängigkeiten & SDKs (Häufigste Fehlerquelle)
|
|
|
|
**Problem 1: `ModuleNotFoundError` bei geteilten Bibliotheken**
|
|
- **Fehler:** Eine kleine App stürzt ab, weil sie `helpers.py` importiert, aber nicht alle darin verwendeten Bibliotheken (z.B. `gspread`, `pandas`) in ihrer eigenen `requirements.txt` hat.
|
|
- **Lösung (in `helpers.py`):** "Exotische" Importe optional machen.
|
|
```python
|
|
try:
|
|
import gspread
|
|
GSPREAD_AVAILABLE = True
|
|
except ImportError:
|
|
GSPREAD_AVAILABLE = False
|
|
gspread = None # Wichtig, damit Referenzen nicht fehlschlagen
|
|
```
|
|
- **Lösung (in `requirements.txt` der App):** Nur die **direkt** für die App benötigten Pakete auflisten. Nicht blind die globale `requirements.txt` kopieren. Für eine typische App sind das oft nur:
|
|
```text
|
|
google-generativeai
|
|
google-genai
|
|
Pillow
|
|
requests
|
|
beautifulsoup4
|
|
```
|
|
|
|
**Problem 2: `ImportError` für `Schema` oder `Content`**
|
|
- **Fehler:** `ImportError: cannot import name 'Schema' from 'google.generativeai.types'`
|
|
- **Ursache:** Der Code ist für eine neuere Version des `google-generativeai`-SDK geschrieben, aber im Projekt ist eine ältere Version (z.B. `0.3.0`) installiert, in der diese Klassen anders hießen oder nicht existierten.
|
|
- **Lösung (für Legacy SDKs):**
|
|
1. Entferne die direkten Importe für `Schema` und `Content`.
|
|
2. Übergebe Konfigurationen wie `generation_config` als einfaches Python-Dictionary. Das alte SDK ist damit zufrieden.
|
|
|
|
**Problem 3: `AttributeError: module 'google.generativeai' has no attribute 'Client'`**
|
|
- **Ursache:** Der Code verwendet eine veraltete API (`genai.Client`), die im SDK entfernt wurde.
|
|
- **Lösung:** Den Code auf die moderne `GenerativeModel`-API umstellen.
|
|
```python
|
|
genai.configure(api_key="YOUR_KEY")
|
|
model = genai.GenerativeModel('gemini-1.5-flash-latest')
|
|
response = model.generate_content(...)
|
|
```
|
|
|
|
### 1.2 Frontend: Build-Prozess & Server
|
|
|
|
**Problem 1: `npm run build` schlägt im Docker-Container fehl**
|
|
- **Ursache:** Wichtige Build-Tools (`vite`, `typescript` etc.) stehen fälschlicherweise in `devDependencies` in der `package.json`. Der Docker-Build installiert diese standardmäßig nicht.
|
|
- **Lösung:** **Alle** `devDependencies` in die `dependencies` verschieben.
|
|
|
|
**Problem 2: "White Screen" - App lädt nicht**
|
|
- **Ursache:** Die App wird unter einem Unterpfad (z.B. `/ce/`) bereitgestellt, aber Vite sucht die JS/CSS-Dateien im Root (`/`).
|
|
- **Lösung (in `vite.config.ts`):** Den Basispfad anpassen.
|
|
```typescript
|
|
export default defineConfig({
|
|
base: './', // Zwingt Vite, relative Pfade zu nutzen
|
|
});
|
|
```
|
|
### 1.3 Docker & Datenbank
|
|
|
|
**Problem 1: `OperationalError: no such table`**
|
|
- **Ursache:** Die `.db`-Datei wurde zwar mit `touch` erstellt, ist aber leer. Die Tabellen wurden nie initialisiert.
|
|
- **Lösung:** Die Datenbank-Initialisierung (z.B. `python3 db_manager.py init`) MUSS beim Start des `server.cjs` automatisch ausgeführt werden.
|
|
```javascript
|
|
// In server.cjs am Anfang
|
|
const { spawn } = require('child_process');
|
|
const dbScript = path.join(__dirname, 'gtm_db_manager.py'); // Pfad anpassen
|
|
spawn('python3', [dbScript, 'init']);
|
|
```
|
|
|
|
**Problem 2: Code-Änderungen werden nicht übernommen ("Geisterfehler")**
|
|
- **Ursache:** Ein Volume-Mount in `docker-compose.yml` überschreibt die neueren Dateien im Image mit alten, lokalen Dateien. Besonders tückisch, wenn `server.cjs` an die falsche Stelle gemountet wird.
|
|
- **Lösung:**
|
|
1. **Immer `git pull`** auf dem Host ausführen, bevor `docker-compose build` aufgerufen wird.
|
|
2. Mount-Pfade präzise setzen. Wenn das Dockerfile `server.cjs` in `/app/server.cjs` kopiert, muss der Mount genau dorthin zeigen:
|
|
```yaml
|
|
volumes:
|
|
- ./my-app-folder/server.cjs:/app/server.cjs # Korrekt
|
|
- ./my-app-folder/:/app/my-app-folder/ # Falsch
|
|
```
|
|
|
|
---
|
|
*Dokumentation wiederhergestellt und erweitert am 15.01.2026.* |