Installation & Setup

Diese Anleitung beschreibt die Installation und Konfiguration der KIVA KI-Plattform Komponenten.

Voraussetzungen

Für lokale Entwicklung

• Python 3.10, 3.11 oder 3.12
• Poetry für Dependency Management
• PostgreSQL 15+ (lokal oder via Docker)
• Node.js 18+ & npm (für Web-Dashboard)
• Docker & Docker Compose (optional, empfohlen)

Für Produktivbetrieb

• Kubernetes Cluster (v1.25+)
• Helm 3.x
• kubectl mit Cluster-Zugriff
• PostgreSQL (managed oder self-hosted)
• GPU Nodes (für vLLM Inference, optional)

---

Lokale Entwicklungsumgebung

1. LLM Gateway Setup

Repository klonen

git clone https://gitlab.opencode.de/baden-wuerttemberg/innenministerium/kiva.platform/kiva-llm-gateway
cd kiva-llm-gateway

Python Environment einrichten

# Virtual Environment erstellen
python -m venv .venv

# Aktivieren
# Linux/macOS:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

# Dependencies installieren
make install-proxy-dev

# Prisma Client generieren
poetry run prisma generate

Datenbank starten

Option A: Docker Compose (empfohlen)

# PostgreSQL Container starten
docker-compose up -d db

# Schema erstellen
poetry run prisma migrate dev --name init

Option B: Lokale PostgreSQL

# Datenbank erstellen
createdb litellm

# Schema migrieren
poetry run prisma migrate dev --name init

Konfiguration

Erstellen Sie eine .env Datei:

cp .env.example .env

Minimale Konfiguration:

# Master Key für Admin-Zugriff
LITELLM_MASTER_KEY=sk-your-secure-master-key-here

# Datenbank
DATABASE_URL=postgresql://llmproxy:dbpassword9090@localhost:5432/litellm
STORE_MODEL_IN_DB=True

# LLM Provider (Beispiel: lokales vLLM)
OPENAI_API_KEY=sk-dummy-key
OPENAI_BASE_URL=http://localhost:8000

Services starten

Backend:

poetry run uvicorn litellm.proxy.proxy_server:app --host localhost --port 4000 --reload

Web-Dashboard:

cd ui/litellm-dashboard
npm install
npm run dev

Zugriff:

• Backend API: http://localhost:4000
• Web Dashboard: http://localhost:3000
• API Docs: http://localhost:4000/docs

2. vLLM Inference Engine (Optional)

Für lokale Modell-Inferenz:

# Mit Docker
docker run --gpus all -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:latest \
  --model meta-llama/Llama-3.2-1B-Instruct \
  --dtype auto \
  --api-key sk-dummy-key

# Oder mit pip
pip install vllm
vllm serve meta-llama/Llama-3.2-1B-Instruct \
  --dtype auto \
  --api-key sk-dummy-key

---

Produktivbetrieb auf Kubernetes

1. Helm Repository einrichten

# Helm Repository hinzufügen (Beispiel)
helm repo add kiva https://registry.example.com/helm

# Oder OCI Registry
helm registry login registry.example.com

2. PostgreSQL Setup

Option A: Managed Database

# Azure Database for PostgreSQL
az postgres flexible-server create \
  --name kiva-db \
  --resource-group kiva-rg \
  --location westeurope \
  --admin-user kivaadmin \
  --admin-password <secure-password> \
  --sku-name Standard_B2s \
  --version 15

Option B: Kubernetes Operator

# CloudNativePG Operator
helm install cnpg cloudnative-pg/cloudnative-pg -n cnpg-system --create-namespace

# PostgreSQL Cluster
kubectl apply -f - <<EOF
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: kiva-postgres
spec:
  instances: 3
  storage:
    size: 100Gi
EOF

3. LLM Gateway Deployment

Erstellen Sie eine values.yaml:

# values-prod.yaml
replicaCount: 3

env:
  LITELLM_MASTER_KEY: "sk-prod-master-key"
  DATABASE_URL: "postgresql://user:pass@kiva-postgres:5432/litellm"
  STORE_MODEL_IN_DB: "True"

resources:
  requests:
    memory: "2Gi"
    cpu: "1000m"
  limits:
    memory: "4Gi"
    cpu: "2000m"

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: llm-gateway.kiva.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: llm-gateway-tls
      hosts:
        - llm-gateway.kiva.example.com

Deployment:

# Mit Helm direkt
helm install kiva-llm-gateway kiva/llm-gateway \
  -f values-prod.yaml \
  -n kiva \
  --create-namespace

# Oder mit ArgoCD
kubectl apply -f - <<EOF
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: kiva-llm-gateway
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://registry.example.com/helm
    chart: llm-gateway
    targetRevision: "1.0.0"
    helm:
      valueFiles:
        - values-prod.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: kiva
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
EOF

4. vLLM Inference Deployment

# values-vllm.yaml
image:
  repository: vllm/vllm-openai
  tag: "v0.6.0"

model:
  name: "meta-llama/Llama-3.2-3B-Instruct"
  quantization: "awq"  # Optional: awq, gptq

resources:
  requests:
    nvidia.com/gpu: 1
    memory: "16Gi"
  limits:
    nvidia.com/gpu: 1
    memory: "32Gi"

nodeSelector:
  workload: gpu

service:
  type: ClusterIP
  port: 8000

helm install kiva-vllm kiva/vllm \
  -f values-vllm.yaml \
  -n kiva

---

Verifizierung

Lokale Installation

# Gateway Health Check
curl http://localhost:4000/health

# Modell-Liste abrufen
curl http://localhost:4000/v1/models \
  -H "Authorization: Bearer sk-your-secure-master-key-here"

# Test Chat Completion
curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-secure-master-key-here" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Kubernetes Deployment

# Pod Status prüfen
kubectl get pods -n kiva

# Logs anzeigen
kubectl logs -n kiva deployment/kiva-llm-gateway -f

# Service Endpoints testen
kubectl run -it --rm debug --image=curlimages/curl --restart=Never -- \
  curl http://kiva-llm-gateway.kiva.svc.cluster.local:4000/health

---

Nächste Schritte

• Sicherheit: Best Practices für Produktivbetrieb

Für Integrationsmöglichkeiten siehe den Abschnitt Integration.