Zum Inhalt

F13 Integration

1. Einführung

1.1 Überblick

F13 ist ein modulares, auf Mikroservices basierendes KI-System, entwickelt vom Land Baden-Württemberg. Das System nutzt KIVA LLM Gateway als zentralen LLM Gateway, um mit verschiedenen Large Language Model (LLM) Backends zu kommunizieren.

Diese Dokumentation beschreibt die Integration über das KIVA Gateway als zentrale Proxy-Schicht zwischen F13 und verschiedenen LLM-Backends.

Zielgruppe

Diese Dokumentation richtet sich an Entwickler und DevOps-Teams, die F13 mit KIVA LLM Gateway betreiben möchten.

Wichtig: Diese Dokumentation bezieht sich auf den KIVA LLM Gateway Fork (basierend auf LiteLLM v1.74.4), nicht auf das Standard-LiteLLM.

1.2 Was ist KIVA LLM Gateway?

KIVA LLM Gateway ist eine vollständig souveräne und modell-agnostische KI-Gateway-Lösung, die:

  • ✅ Auf eigener Infrastruktur betrieben werden kann
  • ✅ Eine einheitliche OpenAI-kompatible API bereitstellt
  • ✅ Als Proxy-Layer zwischen F13 und verschiedenen Model-Backends fungiert
  • ✅ Load Balancing, Fallbacks und Rate Limiting ermöglicht
  • ✅ Vollständige Datenhoheit und DSGVO-Konformität gewährleistet

Technische Basis:

  • Basiert auf: LiteLLM v1.74.4 (MIT-Lizenz)
  • Enterprise Features: Entfernt (fokussiert auf Grundfunktionalitäten)
  • Entwicklung: Land Baden-Württemberg / KIVA KI Plattform
  • Lizenz: MIT
  • Telemetrie: Standardmäßig deaktiviert

1.3 Architektur-Übersicht

graph TB subgraph F13["F13 System"] Core["Core"] Chat["Chat"] RAG["RAG"] Core --> API["OpenAI-kompatible API"] Chat --> API RAG --> API end API --> Gateway["KIVA LLM Gateway
(Proxy Layer – Port 4000)
Fork von LiteLLM v1.74.4"] Gateway --> vLLM["vLLM
(lokal)"] Gateway --> Ollama["Ollama
(lokal)"] Gateway --> OpenAI["OpenAI
(API)"] Gateway --> Azure["Azure
OpenAI"] style F13 fill:#e1f5ff,stroke:#01579b,stroke-width:2px style Gateway fill:#fff3e0,stroke:#e65100,stroke-width:2px style vLLM fill:#f3e5f5,stroke:#4a148c,stroke-width:1px style Ollama fill:#f3e5f5,stroke:#4a148c,stroke-width:1px style OpenAI fill:#e8f5e9,stroke:#1b5e20,stroke-width:1px style Azure fill:#e8f5e9,stroke:#1b5e20,stroke-width:1px

Wichtig:

  • F13 kommuniziert nur mit KIVA LLM Gateway
  • Die Backends (vLLM, Ollama, OpenAI, etc.) werden von KIVA Gateway verwaltet
  • Standard-Port: 4000

1.4 Vorteile dieser Architektur

Vorteil Beschreibung
Einheitliche Schnittstelle F13 nutzt immer die gleiche API, unabhängig vom Backend
Souveränität Vollständige Kontrolle über Daten und Infrastruktur
Flexibilität Backends können gewechselt werden ohne Änderungen in F13
Zentrales Management Load Balancing und Monitoring am Gateway
Einfache Integration F13 nutzt Standard OpenAI Python Client
DSGVO-konform Keine externen Datenübertragungen, keine Telemetrie

2. F13 Systemarchitektur

2.1 Mikroservice-Übersicht

F13 besteht aus folgenden Hauptkomponenten:

graph TB Frontend["Frontend
(Svelte, Port 9999)"] Frontend --> Core["Core Service
(Orchestrierung, Business Logic)"] Core --> Chat["Chat"] Core --> RAG["RAG"] Core --> Parser["Parser"] Core --> Summary["Summary"] Core --> ES["Elasticsearch"] Chat --> Gateway["KIVA LLM Gateway"] RAG --> Gateway Summary --> Gateway style Frontend fill:#e3f2fd,stroke:#1565c0,stroke-width:2px style Core fill:#fff3e0,stroke:#e65100,stroke-width:2px style Chat fill:#f3e5f5,stroke:#4a148c,stroke-width:1px style RAG fill:#f3e5f5,stroke:#4a148c,stroke-width:1px style Parser fill:#f3e5f5,stroke:#4a148c,stroke-width:1px style Summary fill:#f3e5f5,stroke:#4a148c,stroke-width:1px style ES fill:#f3e5f5,stroke:#4a148c,stroke-width:1px style Gateway fill:#fff9c4,stroke:#f57f17,stroke-width:2px

2.2 Chat-Mikroservice

Der Chat-Mikroservice ist die primäre Komponente für LLM-Interaktion:

Verantwortlichkeiten:

  • Entgegennahme von Chat-Anfragen vom Core-Service
  • Anwendung von System-, User- und Assistant-Prompts
  • Kommunikation mit KIVA Gateway über OpenAI-kompatible API
  • Response-Streaming (optional)
  • Fehlerbehandlung und Logging

Technische Implementierung:

# Kern-Komponenten des Chat-Service
from openai import AsyncOpenAI

class OpenAIChatCompletion:
    def __init__(self, llm: LLM):
        self.llm = llm
        self.llm_client = AsyncOpenAI(
            api_key=" ",  # API Key aus Secret-Datei
            base_url=str(self.llm.api.url),  # KIVA Gateway URL
            timeout=60,
            max_retries=3
        )

    async def run_chat_completion(self, chat_input):
        response = await self.llm_client.chat.completions.create(
            model=self.llm.model,  # Model name in KIVA Gateway
            messages=messages,
            temperature=self.llm.inference.temperature,
            max_tokens=self.llm.inference.max_new_tokens
        )
        return response

2.3 Konfigurationsstruktur

F13 nutzt drei YAML-Konfigurationsdateien unter dem Verzeichnis configs/:

configs/
├── general.yml          # Aktivierte Modelle, Log-Level
├── llm_models.yml       # LLM-Definitionen und API-Endpunkte
└── prompt_maps.yml      # Prompt-Templates pro Modell

Wichtig: Siehe Abschnitt 4 für detaillierte Konfigurationsbeispiele.

3. KIVA LLM Gateway als LLM Gateway

3.1 Rolle von KIVA LLM Gateway

KIVA LLM Gateway fungiert als LLM Gateway (Abstraktionsschicht) zwischen F13 und verschiedenen LLM-Backends:

Aus F13-Perspektive:

  • F13 sendet Anfragen an einen einzigen Endpunkt (KIVA Gateway)
  • F13 nutzt immer die gleiche API (OpenAI-kompatibel)
  • F13 weiß nicht, welches Backend verwendet wird
  • Einziger Endpunkt: http://kiva-gateway:4000/v1

Aus Backend-Perspektive:

  • KIVA Gateway kann mit beliebigen Backends kommunizieren:
    • Lokale Modelle: vLLM, Ollama, LocalAI
    • Cloud APIs: OpenAI, Anthropic, Azure OpenAI, Google Gemini
    • Enterprise: AWS Bedrock, Azure ML, Hugging Face Inference
  • KIVA Gateway übersetzt zwischen verschiedenen API-Formaten
  • KIVA Gateway verwaltet Load Balancing und Fallbacks

3.2 Unterstützte Backends

KIVA LLM Gateway unterstützt über 100 Anbieter. Häufig verwendete Backends sind:

Backend Typ Verwendung
vLLM Lokal Hochperformante lokale Inferenz mit GPU
Ollama Lokal Einfaches lokales Model-Hosting
OpenAI Cloud GPT-4, GPT-3.5-turbo
Anthropic Cloud Claude 3 Modelle
Azure OpenAI Cloud Enterprise OpenAI Integration
AWS Bedrock Cloud AWS-native LLM-Zugriff

Hinweis: Die Konfiguration dieser Backends erfolgt in KIVA Gateway, nicht in F13.

3.3 OpenAI-kompatible API

F13 nutzt die OpenAI Python Client Library für die Kommunikation:

from openai import AsyncOpenAI

# F13 Chat-Service erstellt einen Client
client = AsyncOpenAI(
    base_url="http://kiva-gateway:4000/v1",  # KIVA Gateway Endpoint
    api_key="your-key"                        # KIVA Gateway API Key
)

# Standard OpenAI API Call
response = await client.chat.completions.create(
    model="gpt-4",  # Model name configured in KIVA Gateway
    messages=[
        {"role": "system", "content": "Du bist F13."},
        {"role": "user", "content": "Hallo!"}
    ]
)

Wichtig:

  • base_url zeigt auf KIVA Gateway (Port 4000), nicht auf das Backend
  • model entspricht einem in KIVA Gateway konfigurierten Modellnamen
  • KIVA Gateway routet die Anfrage zum entsprechenden Backend

3.4 Unterschiede zu Standard-LiteLLM

Aspekt Standard LiteLLM KIVA LLM Gateway
Version Latest (rolling) v1.74.4 (festgefroren)
Port 8000 4000
Enterprise Features Verfügbar Entfernt (MIT-Lizenz)
Telemetrie Optional Standardmäßig deaktiviert
Branding LiteLLM Baden-Württemberg / KIVA
Dokumentation Englisch Deutsch
Fokus Allgemein Souveränität & Verwaltung

4. F13 Konfiguration für KIVA Gateway

4.1 Konfigurationsdateien-Übersicht

4.1.1 general.yml

Definiert, welche Modelle aktiv sind:

# SPDX-FileCopyrightText: 2025 Land Baden-Württemberg <InnoLab@stm.bwl.de>
# SPDX-License-Identifier: MPL-2.0

active_llms:
  chat: 
    - "gpt4_kiva"
    - "claude_opus_kiva"
    - "llama2_local_kiva"

log_level: INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL

Felder:

  • active_llms.chat: Liste der Modell-IDs, die in F13 verfügbar sein sollen
  • log_level: Logging-Level für F13-Services

4.1.2 llm_models.yml

Definiert die Verbindung zu KIVA Gateway:

# SPDX-FileCopyrightText: 2025 Land Baden-Württemberg <InnoLab@stm.bwl.de>
# SPDX-License-Identifier: MPL-2.0

chat:
  gpt4_kiva:
    # Label für die Benutzeroberfläche
    label: "GPT-4 (via KIVA Gateway)"

    # Modellname wie in KIVA Gateway konfiguriert
    model: "gpt-4"

    # Prompt-Map (Referenz zu prompt_maps.yml)
    prompt_map: "base_assistant"

    # Ist das Modell extern gehostet?
    is_remote: true  # true für Cloud-APIs, false für lokale

    # API-Konfiguration
    api:
      # KIVA Gateway Endpoint (Port 4000!)
      url: "http://kiva-gateway:4000/v1"

      # Health Check Endpoint
      health_check: "/health/liveliness"

      # Authentifizierung
      auth:
        type: "token"  # oder "basic_auth"
        secret_path: "/core/secrets/kiva_gateway_api.secret"

    # Inferenz-Parameter
    inference:
      temperature: 0.7        # 0.0 - 2.0 (höher = kreativer)
      top_p: 0.9              # 0.0 - 1.0 (Nucleus sampling)
      max_new_tokens: 2048    # Maximale Antwortlänge

Wichtige Felder:

Feld Beschreibung Beispiel
label Anzeigename in der UI "GPT-4 (via KIVA Gateway)"
model Model name in KIVA Gateway "gpt-4"
prompt_map Prompt-Template "base_assistant"
is_remote Cloud API? true/false
api.url KIVA Gateway Endpoint "http://kiva-gateway:4000/v1"
api.health_check Health Check Path "/health/liveliness"
api.auth.type Auth-Typ "token" oder "basic_auth"
inference.temperature Kreativität 0.0 - 2.0
inference.max_new_tokens Max. Antwortlänge z.B. 2048

4.1.3 prompt_maps.yml

Definiert System-Prompts für verschiedene Anwendungsfälle:

# SPDX-FileCopyrightText: 2025 Land Baden-Württemberg <InnoLab@stm.bwl.de>
# SPDX-License-Identifier: MPL-2.0

chat:
  base_assistant:
    system:
      generate: |
        Anweisung: Du bist ein Chatbot, der immer auf Deutsch antwortet, 
        wenn er auf Deutsch angesprochen wird. Dein Name lautet F13. 
        Antworte hilfreich und direkt und verzichte auf eine direkte Anrede. 
        Wenn du zu einer Frage keine ausreichende Information hast, gib dies 
        ehrlich an und gebe an, dass du dazu keine Auskunft geben kannst.

  administration_expert:
    system:
      generate: |
        Du bist ein fortschrittlicher KI-basierter Assistent, der F13 heißt 
        und dafür entwickelt wurde, Mitarbeitenden der Verwaltung bei einer 
        Vielzahl von Aufgaben zu helfen. Deine Rolle besteht darin, hilfreiche, 
        höfliche und informative Gespräche zu führen.

        Richtlinien:
        1. Klarheit und Genauigkeit: Priorisiere klare, korrekte Informationen
        2. Nutzerzentriert: Achte auf die Bedürfnisse des Nutzers
        3. Empathie und Neutralität: Zeige Empathie, bleibe neutral

4.2 Konfigurationsbeispiele

Beispiel 1: Cloud-Modell via KIVA Gateway

chat:
  gpt4_kiva:
    label: "GPT-4"
    model: "gpt-4"
    prompt_map: "base_assistant"
    is_remote: true
    api:
      url: "http://kiva-gateway:4000/v1"
      health_check: "/health/liveliness"
      auth:
        type: "token"
        secret_path: "/core/secrets/kiva_gateway_api.secret"
    inference:
      temperature: 0.7
      top_p: 0.9
      max_new_tokens: 4096

Beispiel 2: Lokales Modell (vLLM) via KIVA Gateway

chat:
  llama2_local:
    label: "Llama 2 7B Chat (Lokal)"
    model: "llama-2-7b-chat"  # Name in KIVA Gateway config
    prompt_map: "base_assistant"
    is_remote: false  # Lokal gehostet
    api:
      url: "http://kiva-gateway:4000/v1"
      health_check: "/health/liveliness"
      # Keine auth nötig für interne KIVA Gateway-Instanz
    inference:
      temperature: 0.7
      top_p: 0.9
      max_new_tokens: 2048

Beispiel 3: Mehrere Modelle

chat:
  # Schnelles Modell für einfache Anfragen
  gpt35_fast:
    label: "GPT-3.5 Turbo (Schnell)"
    model: "gpt-3.5-turbo"
    prompt_map: "base_assistant"
    is_remote: true
    api:
      url: "http://kiva-gateway:4000/v1"
      auth:
        type: "token"
        secret_path: "/core/secrets/kiva_gateway_api.secret"
    inference:
      temperature: 0.7
      max_new_tokens: 1024

  # Leistungsstarkes Modell für komplexe Aufgaben
  gpt4_advanced:
    label: "GPT-4 (Erweitert)"
    model: "gpt-4"
    prompt_map: "administration_expert"
    is_remote: true
    api:
      url: "http://kiva-gateway:4000/v1"
      auth:
        type: "token"
        secret_path: "/core/secrets/kiva_gateway_api.secret"
    inference:
      temperature: 0.6
      max_new_tokens: 4096

  # Lokales Modell für datenschutzsensible Anfragen
  mistral_local:
    label: "Mistral 7B (Lokal, DSGVO)"
    model: "mistral-7b-instruct"
    prompt_map: "base_assistant"
    is_remote: false
    api:
      url: "http://kiva-gateway:4000/v1"
    inference:
      temperature: 0.7
      max_new_tokens: 2048