Connecter le SDK Python à Unsloth

Guide pour appeler l’API locale d’Unsloth depuis Python en utilisant les SDK officiels OpenAI ou Anthropic, y compris le streaming, la vision, l’appel de fonctions et les outils côté serveur intégrés d’Unsloth.

Unsloth propose trois dialectes compatibles avec OpenAI à la même URL de base. Chat Completions, Responses et Anthropic Messages, donc tout SDK Python grand public fonctionne avec lui. Vous ne modifiez que le base_url et api_key dans le client ; tout le reste (streaming, appel d'outils, vision, sortie structurée) se comporte comme le documente le SDK. Cette page couvre les deux SDK que la plupart des développeurs utilisent d'abord : le SDK Python officiel SDK Python OpenAI et le SDK officiel SDK Python Anthropic.

Si vous n'êtes pas sûr de l'URL / clé / nom du modèle à utiliser, lisez d'abord la présentation de l'API. Elle vous guide pour démarrer, charger un modèle et créer une sk-unsloth-… clé.

🔑 Prérequis

Avant d'exécuter l'un des extraits ci-dessous, vous aurez besoin de :

• Unsloth en cours d'exécution en local avec un modèle chargé (notez le port : généralement 8000 ou 8888).

• Un sk-unsloth-… clé API créée depuis Paramètres → API.

• Un nom de modèle. Le nom du modèle GGUF dans Unsloth (par ex. qwen-local, unsloth/Qwen3.6-27B-GGUF). Si vous l'oubliez, exécutez :

  curl http://localhost:8888/v1/models -H "Authorization: Bearer sk-unsloth-…"

  et copiez le id champ.

Définissez la clé comme variable d'environnement afin de ne jamais la coller dans le code :

export UNSLOTH_STUDIO_AUTH_TOKEN=sk-unsloth-xxxxxxxxxxxx

🤖 SDK OpenAI

Le /v1/chat/completions point de terminaison d'Unsloth est un remplacement direct pour le SDK Python OpenAI. Le client traite Unsloth comme n'importe quel autre fournisseur compatible avec OpenAI.

1. Installez le SDK :

pip install openai

2. Créez un client pointant vers Unsloth :

import os
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8888/v1",              # votre port unsloth + /v1
    api_key=os.environ["UNSLOTH_STUDIO_AUTH_TOKEN"],     # votre clé sk-unsloth-…
)

Complétion de chat de base

response = client.chat.completions.create(
    model="default",                               # le nom que vous avez donné au modèle dans unsloth ou default
    messages=[
        {"role": "user", "content": "Give me two facts about Paris"}
    ],
)
print(response.choices[0].message.content)

Flux continu

Définissez stream=True et itérez sur le générateur renvoyé :

stream = client.chat.completions.create(
    model="qwen-local",
    messages=[{"role": "user", "content": "Write a haiku about locally-run LLMs."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices:
        delta = chunk.choices[0].delta.content
        if delta:
            print(delta, end="", flush=True)

Images (vision)

Joignez une image comme image_url partie de contenu. Unsloth accepte soit une URL HTTP(S), soit une URI data : base64 :

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": "What's in this image?"},
            ],
        }
    ],
)
print(response.choices[0].message.content)

Le modèle chargé doit être multimodal. Si vous chargez un modèle texte uniquement, la requête de vision réussira sur le plan structurel mais le modèle ne pourra pas « voir » l'image.

Appel de fonctions (outils OpenAI)

Passez des tools et, facultativement, tool_choice et Unsloth les transmet au backend. Votre client est responsable d'exécuter chaque appel d'outil et de renvoyer le résultat au tour suivant :

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Obtenir la météo actuelle d'une ville",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "Nom de la ville, par ex. 'Paris'"},
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "What's the weather in Perth right now?"}],
    tools=tools,
    tool_choice="auto",
)

tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.function.name, tool_call.function.arguments)

Outils côté serveur Unsloth (raccourci)

En plus des outils côté client au format OpenAI, Unsloth peut exécuter Python, bash, et recherche web côté serveur et renvoyer automatiquement les résultats en flux. Activez cela via le extra_body paramètre afin que les champs soient transmis directement à Unsloth :

stream = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "What is 123 * 456? Use Python to compute it."}],
    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)

Le session_id est facultatif. Utilisez-le pour conserver l'état de l'outil (par ex. un noyau Python) entre les appels.

enabled_tools prend actuellement en charge "python", "bash", et "web_search". Les résultats des outils sont renvoyés en flux sous forme d'événements tool_result afin que le modèle puisse les voir à son tour suivant.

Liste des modèles

models = client.models.list()
for m in models.data:
    print(m.id)

🧠 SDK Anthropic

Le /v1/messages point de terminaison est un remplacement direct pour le SDK Python Anthropic.

1. Installez le SDK :

pip install anthropic

2. Créez un client pointant vers Unsloth :

import os
from anthropic import Anthropic

client = Anthropic(
    base_url="http://localhost:8888", # votre port unsloth (pas de /v1 ici - le SDK l'ajoute)
    api_key="dummy", # une valeur aléatoire non vide
    default_headers={"Authorization": f"Bearer {os.environ['UNSLOTH_STUDIO_AUTH_TOKEN']}"} # votre clé sk-unsloth-…
)

Message de base

message = client.messages.create(
    model="default",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Say hello in three languages."}
    ],
)
print(message.content[0].text)

Flux continu

Le SDK expose un gestionnaire de contexte qui produit des incréments de texte :

with client.messages.stream(
    model="default",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain LoRA in two sentences."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Images (vision)

Le contenu d'image au format Anthropic utilise un source bloc avec des données base64 :

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": "What's in this image?"},
            ],
        }
    ],
)
print(message.content[0].text)

Appel d'outils (outils Anthropic)

Passez des tools avec un input_schema et Unsloth les transmet nativement :

tools = [
    {
        "name": "get_weather",
        "description": "Obtenir la météo actuelle d'une ville",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "Nom de la ville, par ex. 'Tokyo'"},
            },
            "required": ["city"],
        },
    }
]

message = client.messages.create(
    model="default",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto"},
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
)

for block in message.content:
    if block.type == "tool_use":
        print(block.name, block.input)

Outils côté serveur Unsloth (raccourci)

Le même enable_tools / enabled_tools / session_id raccourci fonctionne avec /v1/messages transmettez-le extra_body:

with client.messages.stream(
    model="default",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Search for Python 3.13 features and summarize."}],
    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 émet des tool_result événements SSE personnalisés pour la vue qu'a le modèle de la sortie de chaque appel d'outil. Le SDK Anthropic les transmet tels quels via son flux d'événements.

Décodage JSON (response_format)

Unsloth prend en charge les sorties structurées au format OpenAI via response_format. Passez un schéma JSON et le modèle est contraint de produire un JSON qui y correspond.

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": "Choisissez un pays : Japon, Égypte ou Pérou. Expliquez pourquoi en une phrase.",
        },
    ],
    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
# Retirez la clôture Markdown que Gemma 4 entoure autour du JSON, puis parsez-le.
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"])

Le strict: True indique à Unsloth d'imposer le schéma lors du décodage plutôt que de compter sur le modèle pour le respecter de lui-même. additionalProperties: False et required fonctionnent comme dans le schéma JSON standard.

La sortie du terminal devrait ressembler approximativement à ceci :

🧪 Choix d'un SDK

Les deux SDK fonctionnent avec Unsloth. Le bon choix dépend du reste de votre pile :

• Utilisez le SDK OpenAI si votre code dépend déjà du package Python OpenAI, si vous voulez le format OpenAI tools / tool_choice, ou si vous prévoyez d'appeler l'API Responses.

• Utilisez le SDK Anthropic si votre code dépend déjà du package Anthropic, si vous préférez le format input_schema d'outils d'Anthropic, ou si vous voulez les types d'événements de flux natifs d'Anthropic.

Vous pouvez utiliser les deux dans le même projet. Unsloth les sert sur le même port, donc une seule sk-unsloth-… clé authentifie les deux.

❔ Dépannage

401 Unauthorized Le UNSLOTH_STUDIO_AUTH_TOKEN variable d'env n'est pas définie, ou la clé est incorrecte. Réexportez-la et vérifiez avec echo $UNSLOTH_STUDIO_AUTH_TOKEN.

404 Not Found du SDK OpenAI Vérifiez que base_url se termine par /v1. Le SDK OpenAI ajoute les chemins de point de terminaison à l'URL de base tels quels.

404 Not Found du SDK Anthropic Vérifiez que base_url se termine pas se termine par /v1. Le SDK Anthropic ajoute /v1/messages lui-même.

extra_body les champs n'atteignent pas Unsloth Assurez-vous d'utiliser une version récente de openai / anthropic SDK. Les anciennes versions ignorent silencieusement les champs inconnus. Mettez à niveau avec pip install -U openai anthropic.

Le flux « se bloque » puis affiche tout d'un coup Tout ce qui enveloppe votre sortie la met en tampon. Dans un script, print(..., flush=True); dans un notebook, c'est généralement correct ; derrière un proxy, désactivez la mise en tampon des réponses sur le proxy.

Pour les problèmes au niveau du point de terminaison (port incorrect, modèle non chargé, connexion perdue, etc.), consultez la page de présentation de l'API.

Facultatif : définir les valeurs par défaut du serveur

Vous pouvez configurer le comportement par défaut du serveur avant de vous connecter avec le SDK Python, lorsque vous utilisez la unsloth run commande.

# Démarrez le serveur avec des valeurs par défaut personnalisées
unsloth run \
  --model unsloth/Qwen3-1.7B-GGUF \
  --reasoning off \
  --temp 0.6 \
  -p 8888

Utilisez --reasoning off pour désactiver la réflexion, ou --reasoning on pour l'activer pour les modèles qui prennent en charge le raisonnement.

# Exposez l'API sur votre réseau local
unsloth run \
  --model unsloth/Qwen3-1.7B-GGUF \
  -H 0.0.0.0 \
  -p 8888

Cela démarre le serveur sur 0.0.0.0:8888, ce qui permet aux autres appareils de votre réseau local de se connecter.

Ces paramètres deviennent les valeurs par défaut du serveur lorsque les requêtes ne spécifient pas leurs propres paramètres de génération.

Les valeurs au niveau de la requête comme temperature, top_p, max_tokens, et stream peuvent toujours remplacer les valeurs par défaut pour cette requête.