VergeOS OpenAI-kompatible API

Dokumentation für den OpenAI-kompatiblen API-Endpunkt von VergeOS, der Anwendungen ermöglicht, mit lokal gehosteten LLMs im standardmäßigen OpenAI-API-Format mit Python, JavaScript und cURL zu interagieren.

Übersicht

VergeOS bietet einen OpenAI-kompatiblen API-Endpunkt, der Anwendungen die Interaktion mit lokal gehosteten großen Sprachmodellen (LLMs) im standardmäßigen OpenAI-API-Format ermöglicht. So können Sie vertraute Tools und Bibliotheken verwenden, während die Modelle vollständig innerhalb Ihrer VergeOS-Umgebung ausgeführt werden.

Die API leitet Anfragen automatisch an Ihre konfigurierten Assistenten und deren zugrunde liegende Modelle weiter und bietet so eine einheitliche Schnittstelle für KI-Interaktionen.

Voraussetzungen

Bevor Sie die OpenAI-kompatible API verwenden, stellen Sie sicher, dass die folgenden Komponenten ausgeführt werden:

1. AI-Helper-Worker: Dieser Worker verarbeitet API-Anfragen und muss ausgeführt werden. Er startet automatisch, wenn der KI-Dienst aktiviert ist.
2. Mindestens ein Assistent mit einem Online-Modell: Ein Assistent muss konfiguriert sein und sein zugrunde liegendes Modell muss sich im Status „Online“ befinden.

Um diese Voraussetzungen zu überprüfen:

1. Navigieren Sie zu KI → Worker anzeigen um zu bestätigen, dass der AI-Helper-Worker ausgeführt wird
2. Navigieren Sie zu KI → Assistenten um zu bestätigen, dass mindestens ein Assistent den Status „Online“ anzeigt

API-Endpunkte

Die OpenAI-kompatible API ist verfügbar unter:

https://<your-vergeos-url>/v1

Unterstützte Endpunkte

Endpunkt	Beschreibung
/v1/models	Verfügbare Modelle auflisten (gibt konfigurierte Assistenten zurück)
/v1/chat/completions	Chat-Vervollständigungen generieren

Authentifizierung

API-Anfragen erfordern eine Authentifizierung mit einem Bearer-Token:

Authorization: Bearer <your-api-key>

Einen API-Schlüssel erstellen

1. Navigieren Sie zu System → Benutzer
2. Wählen Sie den Benutzer aus, dem der API-Schlüssel gehören soll (oder erstellen Sie einen neuen Benutzer)
3. Klicken Sie auf Neuer API-Schlüssel im linken Menü
4. Konfigurieren Sie die Schlüsseleinstellungen:

   • Namen: Ein aussagekräftiger Name für den Schlüssel (z. B. my-app-key)
   • Beschreibung (optional): Zusätzliche Details zum Verwendungszweck des Schlüssels
   • Ablaufart: Wählen Sie „Datum festlegen“ oder „Nie“
   • Läuft ab: Wenn Sie „Datum festlegen“ verwenden, wählen Sie das Ablaufdatum/die -uhrzeit
5. Speichern Sie den Schlüssel und kopieren Sie das generierte Token

Sicherheit

Der API-Schlüssel wird bei der Erstellung nur einmal angezeigt. Bewahren Sie ihn sicher auf, da er später nicht wiederhergestellt werden kann.

API-Schlüssel übernehmen die Berechtigungen ihres zugehörigen Benutzers. Für den Produktiveinsatz sollten Sie einen dedizierten API-Benutzer mit entsprechenden Berechtigungen anlegen.

Grundlegende Verwendung

Python-Beispiel

from openai import OpenAI

client = OpenAI(
    base_url="https://your-vergeos-instance.com/v1",
    api_key="your-api-key"
)

response = client.chat.completions.create(
    model="qwen3-coder-14B",  # Verwenden Sie den Assistentennamen
    messages=[
        {"role": "user", "content": "Schreibe eine Hello-World-Funktion in Python"}
    ],
    max_tokens=1024,
    temperature=0.7
)

print(response.choices[0].message.content)

cURL-Beispiel

curl https://your-vergeos-instance.com/v1/chat/completions \\
  -H "Authorization: Bearer your-api-key" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen3-coder-14B",
    "messages": [{"role": "user", "content": "Hallo!"}],
    "max_tokens": 100
  }'

Verfügbare Modelle auflisten

curl https://your-vergeos-instance.com/v1/models \\
  -H "Authorization: Bearer your-api-key"

Modellnamen

Verwenden Sie in API-Anfragen den Assistentennamen (z. B. qwen3-coder-14B) als den model Parameter, nicht den Namen des zugrunde liegenden Modells (z. B. Qwen3-14B-Q6_K).

Antwortformat

Antworten folgen dem standardmäßigen OpenAI-Format mit zusätzlichen Zeitinformationen:

{
  "id": "unique-completion-id",
  "object": "chat.completion",
  "created": 1768822431,
  "model": "assistant-name",
  "system_fingerprint": "assistant-name",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Antwortinhalt hier"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 100,
    "total_tokens": 132
  },
  "timings": {
    "prompt_n": 12,
    "prompt_ms": 365.388,
    "prompt_per_token_ms": 30.449,
    "prompt_per_second": 32.84,
    "predicted_n": 100,
    "predicted_ms": 1620.788,
    "predicted_per_token_ms": 16.21,
    "predicted_per_second": 61.70
  }
}

Die Das Feld liefert Leistungsmetriken, die in der standardmäßigen OpenAI-API nicht verfügbar sind.

Assistenten konfigurieren

Assistenten legen fest, wie die API mit den zugrunde liegenden Modellen interagiert. Der Assistent Namen wird als model Parameter in API-Anfragen verwendet.

Detaillierte Anweisungen zum Erstellen und Konfigurieren von Assistenten finden Sie im KI-Konfigurationshandbuch.

Wichtige Einstellungen für die API-Nutzung

• Namen: Dies wird zum model Parameter in API-Aufrufen
• Denken deaktivieren: Aktivieren Sie dies für Modelle mit Denkfunktionen, um Inhalte über die API zurückzugeben
• System-Prompt: Wird automatisch auf jede API-Anfrage angewendet

Worker

Das KI-System verwendet zwei Arten von Workern:

• AI-Helper-Worker: Verarbeitet API-Anfragen und leitet sie an Modelle weiter. Startet automatisch und ist für die Funktionsfähigkeit der API erforderlich.
• Modell-Worker: Übernehmen die Inferenz für jedes laufende Modell. Werden automatisch erstellt, wenn ein Modell startet.

Worker-Status anzeigen unter KI → Worker anzeigen.

Mehrturn-Dialoge

Die API unterstützt Mehrturn-Dialoge, indem der Nachrichtenverlauf einbezogen wird:

response = client.chat.completions.create(
    model="qwen3-coder-14B",
    messages=[
        {"role": "user", "content": "Was ist Python?"},
        {"role": "assistant", "content": "Python ist eine Programmiersprache..."},
        {"role": "user", "content": "Zeigen Sie mir ein einfaches Beispiel"}
    ]
)

Wenn Chat-Verlauf auf dem Assistenten aktiviert ist, kann das System den Kontext auch über separate API-Aufrufe innerhalb einer Sitzung hinweg beibehalten.

Arbeiten mit denkenden Modellen

Einige Modelle (wie Qwen3) verfügen über "Denk"-Funktionen, bei denen sie Probleme intern durchdenken, bevor sie antworten.

Wenn Sie ein solches Modell über die API verwenden und leere Antworten erhalten, gibt das Modell möglicherweise Denk-Tokens aus, die aus der Antwort herausgefiltert werden. Um den tatsächlichen Antwortinhalt zu erhalten:

1. Navigieren Sie zu KI → Assistenten
2. Klicken Sie auf Ihren Assistenten
3. Klicken Sie auf Assistent bearbeiten
4. Aktivieren Sie den Denken deaktivieren Schalter
5. Klicken Sie auf Absenden

Dadurch wird der Denkprozess unterdrückt und nur die endgültige Antwort zurückgegeben.

Integrationsbeispiele

IDE-Integration

Viele IDEs unterstützen benutzerdefinierte OpenAI-kompatible Endpunkte. Konfigurieren Sie Ihre IDE mit:

• API-Basis-URL: https://your-vergeos-instance.com/v1
• API-Schlüssel: Ihr VergeOS-API-Schlüssel
• Modell: Ihr Assistentenname (z. B. qwen3-coder-14B)

Anwendungsintegration

Verwenden Sie eine beliebige OpenAI-Client-Bibliothek:

Python

from openai import OpenAI
client = OpenAI(base_url="https://your-vergeos-instance.com/v1", api_key="your-key")

JavaScript

import OpenAI from 'openai';
const client = new OpenAI({
  baseURL: 'https://your-vergeos-instance.com/v1',
  apiKey: 'your-key'
});

cURL

curl https://your-vergeos-instance.com/v1/chat/completions \\
  -H "Authorization: Bearer your-key" \\
  -H "Content-Type: application/json" \\
  -d '{"model": "assistant-name", "messages": [...]}'

Fehlerbehebung

Fehler „Anmeldung erforderlich“

{"err":"Login required"}

Ursache: Fehlender oder ungültiger API-Schlüssel.

Lösung: Fügen Sie im Authorization-Header einen gültigen API-Schlüssel ein.

Leerer Antwortinhalt

Ursache: Das Modell verwendet Denk-Tokens, die aus der Ausgabe gefiltert werden.

Lösung: Aktivieren Sie "Denken deaktivieren" in den Assistenteneinstellungen.

Modell nicht gefunden

Ursache: Der angegebene Modellname stimmt mit keinem Assistenten überein.

Lösung:

• Verwenden Sie den exakten Assistentennamen (Groß-/Kleinschreibung beachten)
• Überprüfen Sie, ob der Assistent unter KI → Assistenten
• Stellen Sie sicher, dass das Modell des Assistenten Online ist

Verbindung abgelehnt

Ursache: Der AI-Helper-Worker wird nicht ausgeführt.

Lösung:

• Prüfen Sie KI → Worker anzeigen um den Status des AI-Helper-Workers zu überprüfen
• Starten Sie bei Bedarf den KI-Dienst neu

Langsame Antworten

Ursache: Das Modell wird geladen oder ist stark ausgelastet.

Lösung:

• Überprüfen Sie die Ressourcennutzung des Workers unter KI → Worker anzeigen
• Erwägen Sie, dem Modell mehr CPU-Kerne oder RAM zuzuweisen
• Verwenden Sie ein kleineres Modell für schnellere Antworten

---

Versionskompatibilität: Diese Funktion ist in VergeOS 26.0 und höher verfügbar.