> 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
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 bedient drei OpenAI-kompatible Dialekte unter derselben Basis-URL. Chat Completions, Responses und Anthropic Messages, sodass jeder gängige Python-SDK damit funktioniert. \
\
Sie ändern nur die `base_url` und `api_key` auf dem Client; alles andere (Streaming, Tool-Aufrufe, Vision, strukturierte Ausgabe) 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" %}
Falls Sie sich nicht sicher sind, welche URL / welcher Schlüssel / welcher Modellname verwendet werden soll, lesen Sie zuerst die API-Übersicht. Dort werden Sie durch das Starten, Laden eines Modells und das Erstellen eines `sk-unsloth-…` Schlüssels.
{% endhint %}
### 🔑 Voraussetzungen
Bevor Sie einen der folgenden Snippets ausführen, benötigen Sie:
* **lokal ausgeführtes Unsloth** mit einem geladenen Modell (beachten Sie den Port: typischerweise `8000` oder `8888`).
* **Eine `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 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:
```bash
export UNSLOTH_STUDIO_AUTH_TOKEN=sk-unsloth-xxxxxxxxxxxx
```
#### 🤖 OpenAI-SDK
Unslooths `/v1/chat/completions` Der Endpoint ist ein Drop-in-Ersatz für das OpenAI Python SDK. Der Client behandelt Unsloth wie jeden anderen 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": "Gib mir zwei Fakten über Paris"}
],
)
print(response.choices[0].message.content)
```
#### Streaming
Setzen Sie `stream=True` und über den zurückgegebenen Generator iterieren:
```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ängen Sie ein Bild als `image_url` Content-Teil 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 Sie ein reines Textmodell laden, wird die Vision-Anfrage strukturell erfolgreich sein, aber das Modell wird das Bild nicht erkennen können.
{% endhint %}
#### Funktionsaufrufe (OpenAI-Tools)
Übergeben Sie OpenAI-typische `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 Turn 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-seitige Tools (Kurzform)
Zusätzlich zu OpenAI-typischen clientseitigen Tools kann Unsloth **Python**, **bash**, und **Websuche** serverseitig ausführen und die Ergebnisse automatisch zurückstreamen. Aktivieren Sie dies über das `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)
```
Der `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, sodass das Modell sie in seinem nächsten Durchgang sehen kann.
{% endhint %}
**Modelle auflisten**
```python
models = client.models.list()
for m in models.data:
print(m.id)
```
#### 🧠 Anthropic-SDK
Unslooths `/v1/messages` Endpoint ist ein Drop-in-Ersatz 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 es 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 Kontextmanager bereit, der Text-Deltas liefert:
```python
with client.messages.stream(
model="default",
max_tokens=1024,
messages=[{"role": "user", "content": "Erklären Sie LoRA in zwei Sätzen."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
```
#### Bilder (Vision)
Anthropic-ähnlicher 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)
Übergeben Sie Anthropic-typische `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 Tokio?"}],
)
for block in message.content:
if block.type == "tool_use":
print(block.name, block.input)
```
#### Unsloth-Server-seitige Tools (Kurzform)
Dasselbe `enable_tools` / `enabled_tools` / `session_id` Kurzform funktioniert auch mit `/v1/messages` dem Durchreichen `extra_body`:
```python
with client.messages.stream(
model="default",
max_tokens=1024,
messages=[{"role": "user", "content": "Suche nach Python-3.13-Funktionen 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 Event-Stream durch.
#### JSON-Dekodierung (`response_format`)
Unsloth unterstützt OpenAI-typische strukturierte Ausgaben ü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ählen Sie ein Land: Japan, Ägypten oder Peru. Erklären Sie 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-Fence, den Gemma 4 um das JSON legt, und parsen Sie es 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"])
````
Der `strict: True` Kennzeichen weist Unsloth an, das Schema während des Decodings 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:
### 🧪 Auswahl eines SDK
Beide SDKs funktionieren mit Unsloth. Die richtige Wahl hängt vom übrigen Stack ab:
* Verwenden Sie das **OpenAI SDK** wenn Ihr Code bereits vom OpenAI-Python-Paket abhängt, Sie OpenAI-typische `Tools` / `tool_choice`oder Sie planen, die Responses-API aufzurufen.
* Verwenden Sie das **Anthropic-SDK** wenn Ihr Code bereits vom Anthropic-Paket abhängt, Sie Anthropics `input_schema` Tool-Format bevorzugen oder die Anthropic-nativen Streaming-Ereignistypen verwenden möchten.
Sie können beide im selben Projekt verwenden. Unsloth stellt sie auf demselben Port bereit, sodass ein einziger `sk-unsloth-…` Schlüssel beide authentifiziert.
### ❔ Fehlerbehebung
**`401 Nicht autorisiert`** Der `UNSLOTH_STUDIO_AUTH_TOKEN` Die Umgebungsvariable ist nicht gesetzt oder der Schlüssel ist falsch. Exportieren Sie sie erneut und prüfen Sie mit `echo $UNSLOTH_STUDIO_AUTH_TOKEN`.
**`404 Nicht gefunden` aus dem OpenAI-SDK** Prüfen Sie, dass `base_url` endet mit `/v1`. Das OpenAI-SDK hängt Endpunktpfade unverändert an die Basis-URL an.
**`404 Nicht gefunden` aus dem Anthropic-SDK** Prüfen Sie, dass `base_url` tut das **nicht** endet mit `/v1`. Das Anthropic-SDK fügt `/v1/messages` selbst hinzu.
**`extra_body` Felder erreichen Unsloth nicht** Stellen Sie sicher, dass Sie eine aktuelle `openai` / `anthropic` SDK-Version verwenden. Ältere Versionen verwerfen unbekannte Felder stillschweigend. Aktualisieren Sie mit `pip install -U openai anthropic`.
**Streaming „hängt“ und gibt dann alles auf einmal aus** Alles, was Ihre Ausgabe umhüllt, puffert. In einem Skript, `print(..., flush=True)`; in einem Notebook ist es meist in Ordnung; hinter einem Proxy deaktivieren Sie das Antwort-Puffern auf dem Proxy.
Bei Problemen auf Endpunktebene (falscher Port, Modell lädt nicht, Verbindung verloren usw.) siehe die API-Übersichtsseite.
### Optional: Server-Standardwerte setzen
Sie können das Standardverhalten des Servers konfigurieren, bevor Sie sich mit dem Python-SDK verbinden, wenn Sie die `unsloth run` Befehl zu verbinden.
```bash
# Starten Sie den Server mit benutzerdefinierten Standardwerten
unsloth run \
--model unsloth/Qwen3-1.7B-GGUF \\
--reasoning off \
--temp 0.6 \
-p 8888
```
Verwenden Sie `--reasoning off` um das Denken auszuschalten, oder `--reasoning on` um es für Modelle einzuschalten, die Reasoning unterstützen.
```bash
# Die API im lokalen Netzwerk bereitstellen
unsloth run \
--model unsloth/Qwen3-1.7B-GGUF \\
-H 0.0.0.0 \
-p 8888
```
Dies startet den Server auf `0.0.0.0:8888`, sodass sich andere Geräte in Ihrem lokalen Netzwerk verbinden können.
Diese Einstellungen werden zu den Server-Standardwerten, wenn Anfragen keine eigenen Generierungsparameter angeben.
Anfragebezogene Werte wie `Temperatur`, `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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.
