Quickstart

In 4 Schritten zum KI-Avatar

Integriert in weniger als 30 Minuten.

LiveKit Agent erstellen

Wir empfehlen den Voice AI quickstart Guide von LiveKit um deinen ersten LiveKit Agent mit Python>=3.11 aufzusetzen. (NodeJS Agenten werden nicht unterstützt.) Falls du bereits einen LiveKit-Agenten in Python>=3.11 hast kannst du auch diesen verwenden.

Voice AI quickstart Guide

Bitte stelle auf jeden Fall sicher, dass du mit deinem LiveKit Agenten verbal im LiveKit Playground kommunizieren kannst bevor du fortfährst und den Avatar anbindest.

LiveKit Playground öffnen

Avaluma Plugin installieren

Installiere das Avaluma LiveKit Plugin im Python-Environment deines Agenten.

Das agent-starter-python Repository von LiveKit verwendet uv.

pip install git+https://github.com/avaluma-ai/avaluma-livekit-plugin.git

Avatar zum Agenten hinzufügen

Füge den folgenden Import oben in der Pythondatei des LiveKit Agents hinzu. Im LiveKit agent-starter-python Repo von LiveKit heißt die Datei agent.py.

Import hinzufügen

from avaluma_livekit_plugin import AvatarSession

Suche in der selben Datei nach await session.start und füge direkt davor den folgenden Avatar-Setup-Block hinzu:

# Avatar
avatar = AvatarSession(
    license_key="YOUR_AVALUMA_KEY",
    avatar_id="260218-Avaluma_Avatar_Kadda_v5",  # Avatar identifier without .hvia ("string" -> test stream)
    avatar_server_url="https://api.avaluma.ai",
)
# Start the avatar and wait for it to join
await avatar.start(room=ctx.room, agent_session=session)

Passe zum Schluss noch die Argumente von AvatarSession an. Insbesondere den license_key.

Der License-Key kann im Login Bereich erstellt werden.

Key erstellen →

Avatar & Agent im LiveKit Playground testen

Starte deinen Agenten wie bisher und teste ihn direkt im LiveKit Agents Playground. Dies ist der einfachste und schnellste Weg, um Agent und Avatar in Aktion zu sehen.

LiveKit Playground öffnen

Für die Integration in Web- und Mobile Apps bietet LiveKit entsprechende SDKs und Beispielprojekte – von React und JavaScript über Swift bis hin zu Android.

LiveKit Frontend SDKs & Beispiele für Web, iOS, Android und mehr.

LiveKit Frontend Docs →

Self-Hosting (optional)

Du kannst den Avaluma Avatar Server auch selbst mit Docker hosten – vollständig on-prem, ohne Abhängigkeit von api.avaluma.ai.

Voraussetzungen:

Linux GPU Instanz mit CUDA 12, OpenGL Unterstützung und NVIDIA Treibern (inklusive Grafik Treibern) mit mindestens 6GB VRAM. Jeder Avatar braucht 2.5GB VRAM, ein Avatar kann jedoch in mehreren Sessions gleichzeitig erscheinen. Wir haben Ampere, Ada Lovelace und Blackwell Architekturen getestet.
Docker mit Nvidia-Container-Toolkit

Nach der Installation des Nvidia-Container-Toolkits muss Docker neu gestartet werden.

Nvidia Container Toolkit installieren →

1. .hvia-Datei vorbereiten

Lege deine .hvia-Datei in einen lokalen assets/avatar-Ordner. Dieser Ordner wird in den Container gemountet.

Die .hvia-Datei enthält dein Avatar-Modell und kann via dev@avaluma.ai angefragt werden.

2. Docker Compose starten

services:
  avaluma-avatar:
    image: ghcr.io/avaluma-ai/avaluma-avatar-server:latest
    ports:
      - "8080:8080"
    environment:
      - API_UTILS_PWD="CHANGE_THIS"
    volumes:
      - ./assets/avatars:/app/assets/avatars # folder for .hvia-files
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu, compute, utility, graphics]

3. avatar_server_url in agent.py anpassen

Stelle sicher, dass avatar_server_url auf deinen Container zeigt – nicht mehr auf api.avaluma.ai.

avatar = AvatarSession(
    license_key="YOUR_AVALUMA_KEY",
    avatar_id="your-avatar-name",  # Dateiname ohne .hvia
    avatar_server_url="http://localhost:8080",  # zeigt auf deinen Container
)

Brauchst du Hilfe?

Schreib uns oder schau in die Dokumentation.

dev@avaluma.ai Examples Repo