> 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 drei OpenAI-kompatible Dialekte unter derselben Basis-URL bereit. Chat Completions, Responses und Anthropic Messages, sodass jedes gängige Python-SDK damit funktioniert. \ \ Du änderst nur die `base_url` und `api_key` am Client; alles andere (Streaming, Tool-Aufrufe, Vision, strukturierte Ausgabe) verhält sich so, wie es die SDK-Dokumentation beschreibt. Diese Seite behandelt die zwei SDKs, zu denen die meisten Entwickler zuerst greifen: das offizielle **OpenAI Python SDK** und das offizielle **Anthropic Python SDK**. {% hint style="info" %} Wenn du dir nicht sicher bist, welche URL / welcher Schlüssel / welcher Modellname zu verwenden ist, lies zuerst die API-Übersicht. Dort wirst du durch das Starten, Laden eines Modells und das Erstellen eines `sk-unsloth-…` Schlüssels geführt. {% endhint %} ### 🔑 Voraussetzungen Bevor du die folgenden Snippets ausführst, benötigst du: * **Unsloth lokal ausgeführt** mit geladenem Modell (achte auf den Port: typischerweise `8000` oder `8888`). * **Einen `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`). Falls du ihn vergessen hast, führe Folgendes aus: ```bash curl http://localhost:8888/v1/models -H "Authorization: Bearer sk-unsloth-…" ``` und kopiere das `id` Feld. Setze den Schlüssel als Umgebungsvariable, damit du ihn nie in Code einfügst: ```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 OpenAI-kompatiblen Anbieter. **1. Installiere das SDK:** ```bash pip install openai ``` **2. Erstelle einen Client** mit Verweis auf Unsloth: ```python import os from openai import OpenAI client = OpenAI( base_url="http://localhost:8888/v1", # dein unsloth-Port + /v1 api_key=os.environ["UNSLOTH_STUDIO_AUTH_TOKEN"], # dein sk-unsloth-…-Schlüssel ) ``` #### Einfache Chat Completion ```python response = client.chat.completions.create( model="default", # der Name, den du dem Modell in unsloth gegeben hast, oder default messages=[ {"role": "user", "content": "Gib mir zwei Fakten über Paris"} ], ) print(response.choices[0].message.content) ```
#### Streaming Setze `stream=True` und iteriere ü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 an. 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 zu sehen?"}, ], } ], ) print(response.choices[0].message.content) ``` {% hint style="info" %} Das geladene Modell muss multimodal sein. Wenn du ein rein textbasiertes Modell lädst, wird die Vision-Anfrage strukturell erfolgreich sein, aber das Modell kann das Bild nicht „sehen“. {% endhint %}
#### Funktionsaufrufe (OpenAI-Tools) Übergib OpenAI-ähnliche `tools` und (optional) `tool_choice` und Unsloth leitet sie an das Backend weiter. Dein 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": "Die aktuelle Wetterlage für eine Stadt abrufen", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "Stadtname, 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-Server-Tools (Kurzform) Zusätzlich zu OpenAI-artigen Tools auf Client-Seite kann Unsloth **Python**, **bash**und **Websuche** serverseitig ausführen und die Ergebnisse automatisch zurückstreamen. Aktiviere dies über den `extra_body` Parameter, damit die Felder direkt an Unsloth durchgereicht werden: ```python stream = client.chat.completions.create( model="default", messages=[{"role": "user", "content": "Was ist 123 * 456? Verwende 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) ```
Die `session_id` ist optional. Verwende sie, um den Tool-Status (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, sodass 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` Endpunkt ist ein Drop-in für das Anthropic Python SDK. **1. Installiere das SDK:** ```bash pip install anthropic ``` **2. Erstelle einen Client** mit Verweis auf Unsloth: {% code overflow="wrap" %} ```python import os from anthropic import Anthropic client = Anthropic( base_url="http://localhost:8888", # dein unsloth-Port (hier kein /v1 - das SDK fügt es hinzu) api_key="dummy", # ein beliebiger nicht leerer Wert default_headers={"Authorization": f"Bearer {os.environ['UNSLOTH_STUDIO_AUTH_TOKEN']}"} # dein 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 Kontextmanager 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 zu sehen?"}, ], } ], ) print(message.content[0].text) ```
#### Tool-Aufrufe (Anthropic-Tools) Übergib Anthropic-ähnliche `tools` mit einem `input_schema` und Unsloth leitet sie nativ weiter: ```python tools = [ { "name": "get_weather", "description": "Die aktuelle Wetterlage für eine Stadt abrufen", "input_schema": { "type": "object", "properties": { "city": {"type": "string", "description": "Stadtname, z. B. 'Tokyo'"}, }, "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 Tokyo?"}], ) for block in message.content: if block.type == "tool_use": print(block.name, block.input) ```
#### Unsloth-Server-Tools (Kurzform) Die gleiche `enable_tools` / `enabled_tools` / `session_id` Kurzform funktioniert auch bei `/v1/messages` gib es einfach 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 gibt benutzerdefinierte `tool_result` SSE-Ereignisse für die Sicht des Modells auf die Ausgabe jedes Tool-Aufrufs aus. Das Anthropic SDK reicht diese unverändert über seinen Ereignisstrom weiter. #### JSON-Dekodierung (`response_format`) Unsloth unterstützt OpenAI-artige strukturierte Ausgaben über `response_format`. Übergib ein JSON-Schema, und das Modell wird darauf beschränkt, JSON auszugeben, 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", "Egypt", "Peru"]}, "reason": {"type": "string"}, }, "required": ["country", "reason"], "additionalProperties": False, }, "strict": True, }, }, ) raw = response.choices[0].message.content # Entferne den Markdown-Codeblock, den Gemma 4 um das JSON legt, und parse 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"]) ```` Die `strict: True` Flag weist Unsloth an, das Schema während der Dekodierung durchzusetzen, statt sich darauf zu verlassen, dass das Modell sich von selbst daran hält. `additionalProperties: False` und `required` funktionieren wie in standardmäßigem JSON Schema. Die Terminalausgabe sollte ungefähr so aussehen:
### 🧪 Ein SDK auswählen Beide SDKs funktionieren mit Unsloth. Die richtige Wahl hängt von deinem restlichen Stack ab: * Verwende das **OpenAI SDK** wenn dein Code bereits vom OpenAI-Python-Paket abhängt, du OpenAI-ähnliche `tools` / `tool_choice`möchtest oder du die Responses API aufrufen willst. * Verwende das **Anthropic SDK** wenn dein Code bereits vom Anthropic-Paket abhängt, du Anthropics `input_schema` Tool-Format bevorzugst oder du die nativen Streaming-Ereignistypen von Anthropic möchtest. Du kannst beide im selben Projekt verwenden. Unsloth stellt sie über denselben Port bereit, sodass ein einzelner `sk-unsloth-…` Schlüssel beide authentifiziert. ### ❔ Fehlerbehebung **`401 Unauthorized`** Die `UNSLOTH_STUDIO_AUTH_TOKEN` Umgebungsvariable ist nicht gesetzt oder der Schlüssel ist falsch. Setze sie erneut und prüfe mit `echo $UNSLOTH_STUDIO_AUTH_TOKEN`. **`404 Not Found` aus dem OpenAI SDK** Prüfe, dass `base_url` endet mit `/v1`. Das OpenAI SDK hängt Endpunktpfade unverändert an die Basis-URL an. **`404 Not Found` aus dem Anthropic SDK** Prüfe, dass `base_url` endet **nicht** mit `/v1`. Das Anthropic SDK fügt `/v1/messages` selbst hinzu. **`extra_body` Felder gelangen nicht zu Unsloth** Stelle sicher, dass du eine aktuelle `openai` / `anthropic` SDK-Version verwendest. Ältere Versionen verwerfen unbekannte Felder stillschweigend. Aktualisiere mit `pip install -U openai anthropic`. **Streaming „hängt“ und gibt dann alles auf einmal aus** Alles, was deine Ausgabe umhüllt, puffert. In einem Skript `print(..., flush=True)`; in einem Notebook ist es normalerweise in Ordnung; hinter einem Proxy musst du das Response-Buffering auf dem Proxy deaktivieren. Bei Problemen auf Endpunkt-Ebene (falscher Port, Modell wird nicht geladen, Verbindung verloren usw.) siehe die API-Übersichtsseite. ### Optional: Server-Standardwerte setzen Du kannst das Standardverhalten des Servers vor der Verbindung mit dem Python SDK konfigurieren, wenn du den `unsloth run` Befehl verwendest. ```bash # Server mit benutzerdefinierten Standardwerten 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 zu aktivieren, die Reasoning unterstützen. ```bash # Die API im lokalen Netzwerk freigeben unsloth run \ --model unsloth/Qwen3-1.7B-GGUF \ -H 0.0.0.0 \ -p 8888 ``` Dadurch wird der Server auf `0.0.0.0:8888`gestartet, sodass andere Geräte in deinem lokalen Netzwerk sich verbinden können. Diese Einstellungen werden zu den Server-Standardeinstellungen, wenn Anfragen keine eigenen Generierungsparameter angeben. Werte auf Anfrageebene wie `temperature`, `top_p`, `max_tokens`und `stream` können die Standardwerte für diese Anfrage weiterhin ü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, and the optional `goal` query parameter: ``` GET https://unsloth.ai/docs/de/integrationen/python-sdk-mit-unsloth-verbinden.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.