docs: Dokumentation aktualisieren – Multi-Provider-System, Gemini, Modell-Caching

2026-03-12 09:06:55 +01:00
1 parent ed6e78de56
commit 982aa60376
@@ -1,6 +1,6 @@
 # ARCHITECTURE.md – Gott

-**Gott** ist eine selbst-gehostete AI-Chat-Plattform, gebaut auf **.NET 10** und der **Anthropic Claude API**. Sie bietet Multi-User-Support, persistente Agent-Memory, Datei-/Shell-Tools, Telegram-Integration, Cronjobs und eine Krea-Bildgenerierung – alles über ein Vanilla-JavaScript-Frontend gesteuert.
+**Gott** ist eine selbst-gehostete AI-Chat-Plattform, gebaut auf **.NET 10** mit **Anthropic Claude API** als Haupt-Provider sowie **OpenAI-kompatiblen Providern** (Nvidia, Pollinations, Gemini). Sie bietet Multi-User-Support, persistente Agent-Memory, Datei-/Shell-Tools, Telegram-Integration, Cronjobs und eine Krea-Bildgenerierung – alles über ein Vanilla-JavaScript-Frontend gesteuert.

 ---

@@ -18,28 +18,29 @@
   - [Models](#models)
   - [Templates](#templates)
 6. [Frontend-Architektur](#frontend-architektur)
-7. [Chat-Pipeline](#chat-pipeline)
-8. [Tool-System](#tool-system)
-9. [Agent-System](#agent-system)
-10. [System-Prompt-Aufbau](#system-prompt-aufbau)
-11. [Memory-System](#memory-system)
-12. [Skill-System](#skill-system)
-13. [Telegram-Integration](#telegram-integration)
-14. [Cronjob-System](#cronjob-system)
-15. [Krea-Bildgenerierung](#krea-bildgenerierung)
-16. [Auth & Multi-User](#auth--multi-user)
-17. [Admin-Benutzerverwaltung](#admin-benutzerverwaltung)
-18. [Multi-Agent System (Preparer + Review + Finalizer)](#multi-agent-system-preparer--review--finalizer)
-19. [Interaktive Rückfragen (ask_user_choice)](#interaktive-rückfragen-ask_user_choice)
-20. [Plan-Modus](#plan-modus)
-21. [Nachrichten teilen (Shared Messages)](#nachrichten-teilen-shared-messages)
-22. [Workspace & File-Explorer](#workspace--file-explorer)
-23. [Avatar-System](#avatar-system)
-24. [LaTeX/Math-Rendering](#latexmath-rendering)
-25. [Windows Desktop App](#windows-desktop-app)
-26. [Deployment](#deployment)
-27. [Konfiguration](#konfiguration)
-28. [Datenbank-Migrationen](#datenbank-migrationen)
+7. [Multi-Provider-System (OpenAI-kompatibel)](#multi-provider-system-openai-kompatibel)
+8. [Chat-Pipeline](#chat-pipeline)
+9. [Tool-System](#tool-system)
+10. [Agent-System](#agent-system)
+11. [System-Prompt-Aufbau](#system-prompt-aufbau)
+12. [Memory-System](#memory-system)
+13. [Skill-System](#skill-system)
+14. [Telegram-Integration](#telegram-integration)
+15. [Cronjob-System](#cronjob-system)
+16. [Krea-Bildgenerierung](#krea-bildgenerierung)
+17. [Auth & Multi-User](#auth--multi-user)
+18. [Admin-Benutzerverwaltung](#admin-benutzerverwaltung)
+19. [Multi-Agent System (Preparer + Review + Finalizer)](#multi-agent-system-preparer--review--finalizer)
+20. [Interaktive Rückfragen (ask_user_choice)](#interaktive-rückfragen-ask_user_choice)
+21. [Plan-Modus](#plan-modus)
+22. [Nachrichten teilen (Shared Messages)](#nachrichten-teilen-shared-messages)
+23. [Workspace & File-Explorer](#workspace--file-explorer)
+24. [Avatar-System](#avatar-system)
+25. [LaTeX/Math-Rendering](#latexmath-rendering)
+26. [Windows Desktop App](#windows-desktop-app)
+27. [Deployment](#deployment)
+28. [Konfiguration](#konfiguration)
+29. [Datenbank-Migrationen](#datenbank-migrationen)

 ---

@@ -57,7 +58,7 @@
 │      │  SSE │      │      │      │ gram │ jobs │ Img  │ in │
 ├──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┴────┤
 │              Services Layer                                 │
-│  AnthropicService · ChatService · ToolService               │
+│  AnthropicService · OpenAiService · ChatService · ToolService│
 │  DatabaseService · MemoryService · SkillService             │
 │  TelegramService · CronjobService · KreaService             │
 ├─────────────────────────────────────────────────────────────┤
@@ -65,6 +66,7 @@
 │              Filesystem (data/agents/, data/skills/)        │
 ├─────────────────────────────────────────────────────────────┤
 │              Anthropic Claude API (claude-sonnet/opus/haiku) │
+│              OpenAI-kompatible APIs (Nvidia, Pollinations, Gemini) │
 │              Krea API (Bildgenerierung)                     │
 │              Telegram Bot API                               │
 └─────────────────────────────────────────────────────────────┘
@@ -79,7 +81,7 @@
 | **Runtime**   | .NET 10 (ohne Nullable, ohne Implicit Usings)             |
 | **Web**       | ASP.NET Minimal API, Kestrel                              |
 | **Datenbank** | SQLite via Microsoft.Data.Sqlite + Dapper                 |
-| **AI**        | Anthropic Claude API (Streaming SSE + Non-Streaming)      |
+| **AI**        | Anthropic Claude API (Streaming SSE + Non-Streaming), OpenAI-kompatible APIs (Nvidia, Pollinations, Gemini) |
 | **Images**    | SixLabors.ImageSharp (Resize, Thumbnails)                 |
 | **Cron**      | Cronos (Cron-Expression-Parsing)                          |
 | **Frontend**  | Vanilla JavaScript SPA (kein Framework)                   |
@@ -120,6 +122,7 @@ gott/
 │   ├── AuthService.cs            # Token-basierte Authentifizierung
 │   ├── ChatService.cs            # Kontext-Aufbau, History-Builder
 │   ├── AnthropicService.cs       # Claude API (Streaming + Non-Streaming)
+│   ├── OpenAiService.cs          # OpenAI-kompatible Provider (Nvidia, Pollinations, Gemini)
 │   ├── ToolService.cs            # Tool-Definitionen + Ausführung
 │   ├── SystemPromptBuilder.cs    # Modularer System-Prompt aus Blöcken
 │   ├── MemoryService.cs          # Agent-Gedächtnis (Dateisystem)
@@ -143,6 +146,7 @@ gott/
 │   ├── CronjobEndpoint.cs        # CRUD + Toggle, Manual Run
 │   ├── KreaEndpoint.cs           # Generate, List, File-Serve
 │   ├── SkillEndpoint.cs          # List, Agent-Skill-Mapping, Output-Files
+│   ├── ModelsEndpoint.cs         # Provider-Modelle (nvidia, pollinations, gemini, refresh)
 │   ├── SharedEndpoint.cs         # Nachrichten teilen (öffentliche Links)
 │   ├── AdminEndpoint.cs          # Admin: User-CRUD, Impersonate (Admin-only)
 │   ├── ServerSettingsEndpoint.cs  # Admin: Server-Settings lesen/schreiben (Admin-only)
@@ -254,6 +258,7 @@ gott/
        │       ├── PROMPT.md
        │       └── output/
        ├── images/               # Krea-generierte Bilder
+        ├── models_cache.json     # Gecachte Provider-Modelle (Nvidia, Pollinations, Gemini)
        ├── logs/                 # Payload-Logs (optional)
        └── backup/               # Backup-Archive
 ```
@@ -289,10 +294,10 @@ TelegramBot (1) ─── (*) Session  (via telegram_bot_id)
 |-------------------|-----------------------------------------------------|
 | `users`           | Benutzer (username, password_hash, display_name, is_admin, persona, settings, default_path) |
 | `tokens`          | Auth-Tokens (token → user_id)                       |
-| `agents`          | AI-Agenten (model, custom_commands, auto_commit, use_soul/identity/user_info/memory, use_web_search, web_search_version, allow_user_choice, task_instruction, avatar_scale/offset, avatar_small, is_public) |
+| `agents`          | AI-Agenten (model – z.B. `claude-sonnet-4-6` oder `nvidia:deepseek-ai/deepseek-r1`, custom_commands, auto_commit, use_soul/identity/user_info/memory, use_web_search, web_search_version, allow_user_choice, task_instruction, avatar_scale/offset, avatar_small, is_public) |
 | `sessions`        | Chat-Sessions (description, image, image_small, workspace, context, custom_commands, telegram_bot_id, telegram_chat_id, avatar_scale/offset, preparer_agent_id, review_agent_id, max_review_iterations, finalizer_agent_id) |
 | `chains`          | Request-Chains (model, tokens, iterations, timing, tool_choice, tool_names, stream_error_info, plan_mode, archive_id) |
-| `messages`        | Einzelne Nachrichten (text, tool_use, tool_result, error, web_search_result), Tag für Sub-Agent-Markierung oder Import-Herkunft (`openclaw-import`), SortKey für korrekte Reihenfolge |
+| `messages`        | Einzelne Nachrichten (text, tool_use, tool_result, error, web_search_result), Tag für Sub-Agent-Markierung oder Import-Herkunft (`openclaw-import`), SortKey für korrekte Reihenfolge, thought_signature (Gemini) |
 | `attachments`     | Datei-Anhänge (base64, image/document)              |
 | `archives`        | Archivierte Chain-Gruppen                           |
 | `agent_skills`    | Agent ↔ Skill Zuordnung                             |
@@ -306,7 +311,7 @@ TelegramBot (1) ─── (*) Session  (via telegram_bot_id)
 - `ChainId` – Eindeutige ID
 - `SessionId` – Zugehörige Session
 - `AgentId` – Zugehöriger Agent
- `Model` – Verwendetes Claude-Modell (z.B. `claude-sonnet-4-6`)
+- `Model` – Verwendetes Modell (z.B. `claude-sonnet-4-6`, `nvidia:deepseek-ai/deepseek-r1`, `gemini:gemini-2.5-flash`)
 - `SystemPrompt` – Der vollständige System-Prompt (gespeichert für Nachvollziehbarkeit)
 - `InputTokens`, `OutputTokens`, `CacheCreationTokens`, `CacheReadTokens` – Token-Verbrauch
 - `Iterations` – Anzahl der Tool-Loop-Durchläufe
@@ -329,6 +334,7 @@ TelegramBot (1) ─── (*) Session  (via telegram_bot_id)
 - `AttachmentNames` – JSON-Array mit Dateinamen
 - `Tag` – Markierung (`null` = normal, `"preparer"/"review"/"finalizer"` = Sub-Agent-Message (wird aus API-History gefiltert), `"openclaw-import"` = importierte Nachricht (wird immer in History einbezogen))
 - `IsMarked` – Als wichtig markierte Nachricht (wird in System-Prompt aufgenommen)
+- `ThoughtSignature` – Gemini thought_signature (für Gemini-Tool-Calls, wird im nächsten Request zurückgesendet)
 - `DeletedOn` – Soft-Delete Zeitstempel

 **SessionWithStats** – Erweitertes Session-Objekt für Listen-Endpunkt:
@@ -361,7 +367,7 @@ Initialisierungsreihenfolge:
 AuthService → DatabaseService → EnsureDefaultUser
 → ImageService, StreamingTracker, MemoryService, SkillService
 → ToolService → ChatService
-→ AnthropicService → TelegramService → KreaService
+→ AnthropicService → OpenAiService (+ LoadModelsAsync) → TelegramService → KreaService
 → CronjobService (BackgroundService)
 ```

@@ -373,6 +379,7 @@ AuthService → DatabaseService → EnsureDefaultUser
 | `AuthService`          | Singleton    | Token-Erzeugung/-Validierung, Passwort-Hashing (SHA256)         |
 | `ChatService`          | Singleton    | Chat-Kontext aufbauen, History aus DB rekonstruieren             |
 | `AnthropicService`     | Singleton    | Claude API Kommunikation (Streaming SSE + Non-Streaming)         |
+| `OpenAiService`        | Singleton    | OpenAI-kompatible Provider (Nvidia, Pollinations, Gemini) mit Tool-Calling, Streaming, Modell-Caching |
 | `ToolService`          | Singleton    | Tool-Definitionen bereitstellen, Tool-Aufrufe ausführen          |
 | `WorkspaceHelper`      | Static       | Workspace-Pfad-Auflösung (relativ → absolut), Path-Traversal-Schutz |
 | `SystemPromptBuilder`  | Static       | Modularer System-Prompt aus konfigurierbaren Blöcken + Reminder-Generierung |
@@ -406,6 +413,7 @@ Alle Endpoints folgen dem **Minimal API**-Pattern mit Extension Methods (`MapXxx
 | **Settings**  | `/api/settings`            | `GET`, `PUT`                                |
 | **Backup**    | `/api/backup`              | `POST` (Admin only, tar.gz Download)        |
 | **Shared**    | `/api/shared/`, `/api/messages/{id}/share` | Share erstellen, öffentlich abrufen, auflisten, löschen |
+| **Models**    | `/api/models/`             | `GET nvidia`, `GET pollinations`, `GET gemini`, `POST refresh` |
 | **Info**      | `/api/info`                | `GET` (Build-Zeitstempel)                   |
 | **ServerSettings** | `/api/admin/server-settings` | `GET`, `PUT` (Admin-only, liest/schreibt `appsettings.Production.json`) |

@@ -515,6 +523,41 @@ CSS ist in modulare Dateien aufgeteilt mit CSS Custom Properties für Theming:

 ---

+## Multi-Provider-System (OpenAI-kompatibel)
+
+Neben Anthropic Claude unterstützt Gott drei **OpenAI-kompatible Provider**. Der Agent-Model-String bestimmt den Provider:
+
+| Prefix | Provider | Base-URL | API-Key |
+|--------|----------|----------|---------|
+| (kein) | Anthropic Claude | `api.anthropic.com` | `AnthropicToken` |
+| `nvidia:` | Nvidia (g4f.space Proxy) | `g4f.space/api/nvidia/v1` | keiner |
+| `pollinations:` | Pollinations | `text.pollinations.ai/openai` | keiner |
+| `gemini:` | Google Gemini | `generativelanguage.googleapis.com/v1beta/openai` | `GeminiApiKey` |
+
+### Model-String-Format
+
+`provider:model-id` – z.B. `nvidia:deepseek-ai/deepseek-r1`, `gemini:gemini-2.5-flash`, `pollinations:openai-fast`
+
+### Modell-Caching
+
+Beim Server-Start werden verfügbare Modelle von den Provider-APIs geladen und in `data/models_cache.json` gecacht. Bei nachfolgenden Starts wird der Cache verwendet (kein API-Call). Manueller Refresh via `POST /api/models/refresh`.
+
+### OpenAiService
+
+`OpenAiService` implementiert:
+- **Streaming via SSE** (OpenAI-Format: `choices[0].delta`)
+- **Tool-Calling** (identische Tools wie AnthropicService)
+- **Agentic Loop** (Tool-Results → nächste Iteration)
+- **Gemini thought_signature** – wird aus `extra_content.google.thought_signature` gelesen, in DB persistiert (`MessageRecord.ThoughtSignature`), und beim History-Rebuild in `extra_content.google.thought_signature` zurückgesendet
+
+### Routing
+
+`ChatService.ResolveModelId()` prüft den Model-String:
+- Enthält `:` mit bekanntem Provider-Prefix → `OpenAiService.StreamChat()`
+- Sonst → `AnthropicService.StreamChat()`
+
+---
+
 ## Chat-Pipeline

 Der Chat-Flow von User-Input bis zur gerenderten Antwort:
@@ -528,9 +571,9 @@ Der Chat-Flow von User-Input bis zur gerenderten Antwort:
   a) User-Message + Attachments in DB speichern
   b) ChatService.PrepareContext() → Agent, Model, System-Prompt, Chain
   c) ChatService.BuildHistoryFromDb() → vollständige Message-History
-   d) AnthropicService.StreamChat() starten
+   d) Model-Routing: Anthropic → AnthropicService.StreamChat(), OpenAI-Provider (nvidia:/pollinations:/gemini:) → OpenAiService.StreamChat()
   ↓
-4. AnthropicService (Agentic Loop):
+4. Agentic Loop (AnthropicService oder OpenAiService):
   ┌─────────────────────────────────────────┐
   │  while (iterations < maxIterations)      │
   │    → Claude API Request (SSE)            │
@@ -1602,7 +1645,8 @@ Die Anwendung ist als systemd-Service konfiguriert und läuft standardmäßig au
  "PayloadLogging": false,      // API-Payloads loggen (Debug)
  "PayloadLoggingGzip": false,  // Payload-Logs als .gz komprimieren
  "KreaToken": "",               // Krea API Token (optional)
-  "KreaApiKey": ""               // API-Key für Krea-Endpoints ohne User-Auth (optional)
+  "KreaApiKey": "",               // API-Key für Krea-Endpoints ohne User-Auth (optional)
+  "GeminiApiKey": ""              // Google Gemini API Key (kostenlos via aistudio.google.com/apikey)
 }
 ```