> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/de/integrationen/python-sdk-mit-unsloth-verbinden.md). # Python SDK mit Unsloth verbinden Unsloth stellt unter derselben Basis-URL drei mit OpenAI kompatible Dialekte bereit: Chat Completions, Responses und Anthropic Messages, sodass jedes gängige Python-SDK damit funktioniert. \ \ Sie ändern nur das `Basis-URL` und `api_key` auf dem Client; alles andere (Streaming, Tool-Aufrufe, Vision, strukturierte Ausgaben) verhält sich so, wie es die SDK-Dokumentation beschreibt. Diese Seite behandelt die beiden SDKs, zu denen die meisten Entwickler zuerst greifen: das offizielle **OpenAI Python SDK** und das offizielle **Anthropic Python SDK**. {% hint style="info" %} Wenn Sie sich nicht sicher sind, welche URL / welchen Schlüssel / welchen Modellnamen Sie verwenden sollen, lesen Sie zuerst die API-Übersicht. Dort werden Sie durch das Starten, Laden eines Modells und das Erstellen eines `sk-unsloth-…` Schlüssels geführt. {% endhint %} ### 🔑 Voraussetzungen Bevor Sie eines der folgenden Codebeispiele ausführen, benötigen Sie: * **Unsloth lokal ausgeführt** mit geladenem Modell (beachten Sie den Port: typischerweise `8000` oder `8888`). * **Ein `sk-unsloth-…` API-Schlüssel** erstellt aus **Einstellungen → API**. * **Ein Modellname.** Der Name des GGUF-Modells in Unsloth (z. B. `qwen-local`, `unsloth/Qwen3.6-27B-GGUF`). Wenn Sie ihn vergessen, führen Sie aus: ```bash curl http://localhost:8888/v1/models -H "Authorization: Bearer sk-unsloth-…" ``` und kopieren Sie das `id` Feld. Setzen Sie den Schlüssel als Umgebungsvariable, damit Sie ihn nie in Code einfügen müssen: ```bash export UNSLOTH_STUDIO_AUTH_TOKEN=sk-unsloth-xxxxxxxxxxxx ``` #### 🤖 OpenAI-SDK Unsloths `/v1/chat/completions` Endpunkt ist ein Drop-in für das OpenAI-Python-SDK. Der Client behandelt Unsloth wie jeden anderen mit OpenAI kompatiblen Anbieter. **1. Installieren Sie das SDK:** ```bash pip install openai ``` **2. Erstellen Sie einen Client** der auf Unsloth zeigt: ```python import os from openai import OpenAI client = OpenAI( base_url="http://localhost:8888/v1", # Ihr Unsloth-Port + /v1 api_key=os.environ["UNSLOTH_STUDIO_AUTH_TOKEN"], # Ihr sk-unsloth-…-Schlüssel ) ``` #### Einfache Chat-Vervollständigung ```python response = client.chat.completions.create( model="default", # der Name, den Sie dem Modell in Unsloth gegeben haben, oder default messages=[ {"role": "user", "content": "Nenne mir zwei Fakten über Paris"} ], ) print(response.choices[0].message.content) ```
#### Streaming Setzen Sie `stream=True` und iterieren Sie über den zurückgegebenen Generator: ```python stream = client.chat.completions.create( model="qwen-local", messages=[{"role": "user", "content": "Schreibe ein Haiku über lokal ausgeführte LLMs."}], stream=True, ) for chunk in stream: if chunk.choices: delta = chunk.choices[0].delta.content if delta: print(delta, end="", flush=True) ```
#### Bilder (Vision) Hänge ein Bild als `image_url` Inhaltsteil. Unsloth akzeptiert entweder eine HTTP(S)-URL oder eine `data:` Base64-URI: ```python import base64 from pathlib import Path img_b64 = base64.b64encode(Path("test.jpg").read_bytes()).decode() response = client.chat.completions.create( model="default", messages=[ { "role": "user", "content": [ { "type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{img_b64}"}, }, {"type": "text", "text": "Was ist auf diesem Bild?"}, ], } ], ) print(response.choices[0].message.content) ``` {% hint style="info" %} Das geladene Modell muss multimodal sein. Wenn Sie ein reines Textmodell laden, wird die Vision-Anfrage strukturell erfolgreich sein, aber das Modell wird das Bild nicht „sehen“ können. {% endhint %}
#### Funktionsaufrufe (OpenAI-Tools) Übergebe OpenAI-stilistische `tools` und (optional) `tool_choice` und Unsloth leitet sie an das Backend weiter. Ihr Client ist dafür verantwortlich, jeden Tool-Aufruf auszuführen und das Ergebnis im nächsten Durchlauf zurückzugeben: ```python tools = [ { "type": "function", "function": { "name": "get_weather", "description": "Get the current weather for a city", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "Name der Stadt, z. B. 'Paris'"}, }, "required": ["city"], }, }, } ] response = client.chat.completions.create( model="default", messages=[{"role": "user", "content": "Wie ist das Wetter in Perth gerade?"}], tools=tools, tool_choice="auto", ) tool_call = response.choices[0].message.tool_calls[0] print(tool_call.function.name, tool_call.function.arguments) ```
#### Unsloth-Servertools (Kurzform) Zusätzlich zu clientseitigen Tools im OpenAI-Stil kann Unsloth **Python**, **bash**und **Websuche** sie serverseitig ausführen und die Ergebnisse automatisch zurückstreamen. Aktivieren Sie dies über den `extra_body` Parameter, sodass die Felder direkt an Unsloth durchgereicht werden: ```python stream = client.chat.completions.create( model="default", messages=[{"role": "user", "content": "Wie viel ist 123 * 456? Verwenden Sie Python, um es zu berechnen."}], stream=True, extra_body={ "enable_tools": True, "enabled_tools": ["python", "web_search"], "session_id": "my-session", }, ) for chunk in stream: if chunk.choices: delta = chunk.choices[0].delta.content if delta: print(delta, end="", flush=True) ```
Das `session_id` ist optional. Verwenden Sie ihn, um den Tool-Zustand (z. B. einen Python-Kernel) über Aufrufe hinweg beizubehalten. {% hint style="info" %} `enabled_tools` unterstützt derzeit `"python"`, `"bash"`und `"web_search"`. Tool-Ergebnisse werden als `tool_result` Ereignisse zurückgestreamt, damit das Modell sie in seinem nächsten Durchlauf sehen kann. {% endhint %} **Modelle auflisten** ```python models = client.models.list() for m in models.data: print(m.id) ```
#### 🧠 Anthropic-SDK Unsloths `/v1/messages` Der Endpunkt ist ein Drop-in für das Anthropic-Python-SDK. **1. Installieren Sie das SDK:** ```bash pip install anthropic ``` **2. Erstellen Sie einen Client** der auf Unsloth zeigt: {% code overflow="wrap" %} ```python import os from anthropic import Anthropic client = Anthropic( base_url="http://localhost:8888", # Ihr Unsloth-Port (hier kein /v1 - das SDK fügt ihn hinzu) api_key="dummy", # ein beliebiger, nicht leerer Wert default_headers={"Authorization": f"Bearer {os.environ['UNSLOTH_STUDIO_AUTH_TOKEN']}"} # Ihr sk-unsloth-…-Schlüssel ) ``` {% endcode %} #### Einfache Nachricht ```python message = client.messages.create( model="default", max_tokens=1024, messages=[ {"role": "user", "content": "Sag Hallo in drei Sprachen."} ], ) print(message.content[0].text) ```
#### Streaming Das SDK stellt einen Context Manager bereit, der Text-Deltas liefert: ```python with client.messages.stream( model="default", max_tokens=1024, messages=[{"role": "user", "content": "Erkläre LoRA in zwei Sätzen."}], ) as stream: for text in stream.text_stream: print(text, end="", flush=True) ``` #### Bilder (Vision) Anthropic-artiger Bildinhalt verwendet einen `source` Block mit Base64-Daten: ```python import base64 from pathlib import Path img_b64 = base64.standard_b64encode(Path("photo.jpg").read_bytes()).decode() message = client.messages.create( model="default", max_tokens=1024, messages=[ { "role": "user", "content": [ { "type": "image", "source": { "type": "base64", "media_type": "image/jpeg", "data": img_b64, }, }, {"type": "text", "text": "Was ist auf diesem Bild?"}, ], } ], ) print(message.content[0].text) ```
#### Tool-Aufrufe (Anthropic-Tools) Übergeben Sie Anthropic-Stil `tools` mit einem `input_schema` und Unsloth leitet sie nativ weiter: ```python tools = [ { "name": "get_weather", "description": "Get the current weather for a city", "input_schema": { "type": "object", "properties": { "city": {"type": "string", "description": "Name der Stadt, z. B. 'Tokio'"}, }, "required": ["city"], }, } ] message = client.messages.create( model="default", max_tokens=1024, tools=tools, tool_choice={"type": "auto"}, messages=[{"role": "user", "content": "Wie ist das Wetter in Tokio?"}], ) for block in message.content: if block.type == "tool_use": print(block.name, block.input) ```
#### Unsloth-Servertools (Kurzform) Dasselbe `enable_tools` / `enabled_tools` / `session_id` Kurzform funktioniert auch mit `/v1/messages` leiten Sie es weiter `extra_body`: ```python with client.messages.stream( model="default", max_tokens=1024, messages=[{"role": "user", "content": "Suche nach Funktionen von Python 3.13 und fasse sie zusammen."}], extra_body={ "enable_tools": True, "enabled_tools": ["web_search", "python"], "session_id": "my-session", }, ) as stream: for text in stream.text_stream: print(text, end="", flush=True) ```
Unsloth sendet benutzerdefinierte `tool_result` SSE-Ereignisse für die Sicht des Modells auf die Ausgabe jedes Tool-Aufrufs. Das Anthropic-SDK leitet diese unverändert über seinen Event-Stream weiter. #### JSON-Dekodierung (`response_format`) Unsloth unterstützt strukturierte Ausgaben im OpenAI-Stil über `response_format`. Übergeben Sie ein JSON-Schema, und das Modell wird darauf beschränkt, JSON zu erzeugen, das diesem entspricht. ````python import json import os import re from openai import OpenAI client = OpenAI( base_url="http://localhost:8888/v1", api_key=os.environ["UNSLOTH_STUDIO_AUTH_TOKEN"], ) response = client.chat.completions.create( model="default", stream=False, temperature=0.0, max_tokens=1024, messages=[ { "role": "user", "content": "Wähle ein Land: Japan, Ägypten oder Peru. Erkläre in einem Satz warum.", }, ], response_format={ "type": "json_schema", "json_schema": { "name": "country_pick", "schema": { "type": "object", "properties": { "country": {"type": "string", "enum": ["Japan", "Ägypten", "Peru"]}, "reason": {"type": "string"}, }, "required": ["country", "reason"], "additionalProperties": False, }, "strict": True, }, }, ) raw = response.choices[0].message.content # Entfernen Sie den Markdown-Blockrahmen, den Gemma 4 um das JSON legt, und parsen Sie ihn dann. cleaned = re.sub(r"^```(?:json)?\s*", "", raw) cleaned = re.sub(r"\s*```$", "", cleaned) parsed = json.loads(cleaned) print(json.dumps(parsed, indent=2)) print() print("country:", parsed["country"]) print("reason :", parsed["reason"]) ```` Das `strict: True` Das Flag weist Unsloth an, das Schema während der Dekodierung durchzusetzen, anstatt sich darauf zu verlassen, dass das Modell sich von selbst daran hält. `additionalProperties: False` und `required` funktionieren wie im standardmäßigen JSON-Schema. Die Terminalausgabe sollte ungefähr so aussehen:
### 🧪 Die Wahl eines SDKs Beide SDKs funktionieren mit Unsloth. Die richtige Wahl hängt vom Rest Ihres Stacks ab: * Verwende das **OpenAI-SDK** wenn Ihr Code bereits vom OpenAI-Python-Paket abhängt, bevorzugen Sie OpenAI-Stil `tools` / `tool_choice`oder Sie planen, die Responses-API aufzurufen. * Verwende das **Anthropic-SDK** wenn Ihr Code bereits vom Anthropic-Paket abhängt, bevorzugen Sie Anthropic's `input_schema` Tool-Format, oder Sie möchten die nativen Anthropic-Streaming-Ereignistypen. Sie können beide im selben Projekt verwenden. Unsloth stellt sie auf demselben Port bereit, sodass ein einzelner `sk-unsloth-…` Schlüssel beide authentifiziert. ### ❔ Fehlerbehebung **`401 Nicht autorisiert`** Das `UNSLOTH_STUDIO_AUTH_TOKEN` Umgebungsvariable nicht gesetzt ist oder der Schlüssel falsch ist. Exportieren Sie sie erneut und bestätigen Sie mit `echo $UNSLOTH_STUDIO_AUTH_TOKEN`. **`404 Nicht gefunden` im OpenAI-SDK** Prüfen Sie, ob `Basis-URL` endet auf `/v1`. Das OpenAI-SDK hängt Endpunktpfade unverändert an die Basis-URL an. **`404 Nicht gefunden` im Anthropic-SDK** Prüfen Sie, ob `Basis-URL` tut **nicht** endet auf `/v1`. Das Anthropic-SDK fügt `/v1/messages` es selbst hinzu. **`extra_body` Felder erreichen Unsloth nicht** Vergewissern Sie sich, dass Sie eine aktuelle `openai` / `anthropic` SDK verwenden. Ältere Versionen verwerfen unbekannte Felder stillschweigend. Aktualisieren Sie mit `pip install -U openai anthropic`. **Das Streaming „hängt“ und gibt dann alles auf einmal aus** Alles, was Ihre Ausgabe umschließt, puffert. In einem Skript, `print(..., flush=True)`; in einem Notebook ist es normalerweise in Ordnung; hinter einem Proxy deaktivieren Sie das Response-Buffering am Proxy. Bei Problemen auf Endpunktebene (falscher Port, Modell wird nicht geladen, Verbindungsverlust usw.) siehe die API-Übersichtsseite. ### Optional: Server-Standardeinstellungen festlegen Sie können das Standardverhalten des Servers vor der Verbindung mit dem Python-SDK konfigurieren, wenn Sie den `unsloth run` Befehl hinzu. ```bash # Server mit benutzerdefinierten Standardeinstellungen starten unsloth run \ --model unsloth/Qwen3-1.7B-GGUF \ --reasoning off \ --temp 0.6 \ -p 8888 ``` Verwende `--reasoning off` um das Denken auszuschalten, oder `--reasoning on` um es für Modelle einzuschalten, die Reasoning unterstützen. ```bash # API im lokalen Netzwerk freigeben unsloth run \ --model unsloth/Qwen3-1.7B-GGUF \ -H 0.0.0.0 \ -p 8888 ``` Dadurch startet der Server auf `0.0.0.0:8888`, sodass andere Geräte in deinem lokalen Netzwerk verbinden können. Diese Einstellungen werden zu den Server-Standardeinstellungen, wenn Anfragen keine eigenen Generierungsparameter angeben. Anfragebezogene Werte wie `temperature`, `top_p`, `max_tokens`und `stream` kann die Standardwerte für diese Anfrage dennoch überschreiben. --- # 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: ``` GET https://unsloth.ai/docs/de/integrationen/python-sdk-mit-unsloth-verbinden.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.