> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/automate-protect-and-extend/de/private-ki/open-ai-router.md). # VergeOS OpenAI-kompatible API ## Ü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:///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 ``` ### 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 {% hint style="warning" %} **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. {% endhint %} 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 ```python 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 ```bash 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 ```bash curl https://your-vergeos-instance.com/v1/models \\ -H "Authorization: Bearer your-api-key" ``` {% hint style="info" %} **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`). {% endhint %} ## Antwortformat Antworten folgen dem standardmäßigen OpenAI-Format mit zusätzlichen Zeitinformationen: ```json { "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](/automate-protect-and-extend/de/private-ki/configuration.md#ai-assistant-management). {% hint style="success" %} **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 {% endhint %} ## 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: ```python 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: {% tabs %} {% tab title="Python" %} ```python from openai import OpenAI client = OpenAI(base_url="https://your-vergeos-instance.com/v1", api_key="your-key") ``` {% endtab %} {% tab title="JavaScript" %} ```javascript import OpenAI from 'openai'; const client = new OpenAI({ baseURL: 'https://your-vergeos-instance.com/v1', apiKey: 'your-key' }); ``` {% endtab %} {% tab title="cURL" %} ```bash curl https://your-vergeos-instance.com/v1/chat/completions \\ -H "Authorization: Bearer your-key" \\ -H "Content-Type: application/json" \\ -d '{"model": "assistant-name", "messages": [...]}' ``` {% endtab %} {% endtabs %} ## Fehlerbehebung ### Fehler „Anmeldung erforderlich“ ```json {"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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verge.io/automate-protect-and-extend/de/private-ki/open-ai-router.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.