Python-SDK mit Unsloth verbinden

Anleitung zum Aufrufen der lokalen API von Unsloth aus Python mit den offiziellen OpenAI- oder Anthropic-SDKs, einschließlich Streaming, Vision, Funktionsaufrufen und den integrierten serverseitigen Tools von Unsloth.

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.

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.

🔑 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:

  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:

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:

pip install openai

2. Erstelle einen Client mit Verweis auf Unsloth:

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

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:

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:

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)

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“.

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:

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, bashund 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:

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.

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.

Modelle auflisten

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:

pip install anthropic

2. Erstelle einen Client mit Verweis auf Unsloth:

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
)

Einfache Nachricht

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:

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:

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:

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:

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.

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_choicemö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.

# 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.

# 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:8888gestartet, 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_tokensund stream können die Standardwerte für diese Anfrage weiterhin überschreiben.