> 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/fr/integrations/connecter-le-sdk-python-a-unsloth.md).

# Connecter le SDK Python à Unsloth

Guide pour appeler l'API locale d'Unsloth depuis Python à l'aide des 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 : tous les SDK Python courants sont donc compatibles. \
\
Vous ne modifiez que le `base_url` et le `api_key`  du client ; tout le reste (streaming, appels d’outils, vision, sorties structurées) fonctionne comme indiqué dans la documentation du SDK. Cette page présente les deux SDK que la plupart des développeurs choisissent en premier : le SDK officiel **OpenAI Python SDK** et le SDK officiel **Anthropic Python SDK**.

{% hint style="info" %}
Si vous ne savez pas quelle URL, quelle clé ou quel nom de modèle utiliser, consultez d’abord la présentation de l’API. Elle vous guide pour démarrer, charger un modèle et créer une clé `sk-unsloth-…` .
{% endhint %}

### 🔑 Prérequis

Avant d’exécuter les exemples ci-dessous, vous aurez besoin de :

* **Unsloth lancé localement** avec un modèle chargé (notez le port : généralement `8000` ou `8888`).
* **Une `sk-unsloth-…` clé API** créée depuis **Paramètres → API**.
* **Un nom de modèle.** Le nom du modèle GGUF dans Unsloth (par exemple `qwen-local`, `unsloth/Qwen3.6-27B-GGUF`). Si vous l’avez oublié, exécutez :

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

  et copiez le champ `id` .

Définissez la clé comme variable d’environnement pour ne jamais avoir à la coller dans votre code :

```bash
export UNSLOTH_STUDIO_AUTH_TOKEN=sk-unsloth-xxxxxxxxxxxx
```

#### 🤖 SDK OpenAI

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

**1. Installez le SDK :**

```bash
pip install openai
```

**2. Créez un client** configuré pour utiliser Unsloth :

```python
import os
from openai import OpenAI

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

#### Complétion de chat simple

```python
response = client.chat.completions.create(
    model="default",                               # the name you gave the model in unsloth or default
    messages=[
        {"role": "user", "content": "Give me two facts about Paris"}
    ],
)
print(response.choices[0].message.content)
```

<figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FZkxVYS7fcvwXZ8AxvaBF%2FScreenshot%202026-04-22%20at%202.38.44%E2%80%AFAM.png?alt=media&amp;token=06dece4e-dade-4c2d-bcdb-7c946cdd1290" alt=""><figcaption></figcaption></figure>

#### Diffusion en continu

Définissez `stream=True` et parcourez le générateur renvoyé :

```python
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)
```

<figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F0eItNT5zanSB8rXY4QHn%2Fopenai_streaming.png?alt=media&amp;token=2922bbf3-69da-409f-b954-76b6259233f8" alt=""><figcaption></figcaption></figure>

#### Images (vision)

Ajoutez une image comme élément de contenu `image_url` . Unsloth accepte une URL HTTP(S) ou un URI `data:` en base64 :

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

{% hint style="info" %}
Le modèle chargé doit être multimodal. Si vous chargez un modèle uniquement textuel, la requête de vision fonctionnera sur le plan structurel, mais le modèle ne pourra pas « voir » l’image.
{% endhint %}

<figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FTNCX4qEMj8zFSAsOJw2Y%2Fopenai_sdk_vision_test.png?alt=media&amp;token=caa22501-66fc-4e3c-b4a0-636ebe5af4bf" alt=""><figcaption></figcaption></figure>

#### Appel de fonctions (outils OpenAI)

Transmettez des `tools` et, éventuellement, `tool_choice` au format OpenAI ; Unsloth les transmet au backend. Il vous incombe d’exécuter chaque appel d’outil et de renvoyer le résultat au tour suivant :

```python
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "City name, e.g. '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)
```

<figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F8nzgxHsN8J23B6duQ3Zv%2Fopenai_sdk_function_calling.png?alt=media&amp;token=3551592d-31b2-4fa6-94a9-6a9f0974c21a" alt=""><figcaption></figcaption></figure>

#### Outils côté serveur Unsloth (raccourci)

En plus des outils côté client compatibles avec le format OpenAI, Unsloth peut exécuter **Python**, **un terminal** (des commandes shell) et **une recherche Web** côté serveur et renvoyer automatiquement les résultats en continu. Activez cette fonctionnalité avec le paramètre `extra_body` pour transmettre directement les champs à Unsloth :

```python
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)
```

<figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FvdZuLwIh7LT0C8y7AWaR%2FScreenshot%202026-04-22%20at%203.01.06%E2%80%AFAM.png?alt=media&amp;token=35ff3039-d941-406b-b3fc-5e1e564c7651" alt=""><figcaption></figcaption></figure>

<figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FnW60ezYCOJQmTjd52bnu%2FScreenshot%202026-04-22%20at%203.05.23%E2%80%AFAM.png?alt=media&amp;token=f7125db4-cb94-46f7-974d-abe58ec348a7" alt=""><figcaption></figcaption></figure>

Le paramètre `session_id` est facultatif. Utilisez-le pour conserver l’état des outils (par exemple, un noyau Python) d’un appel à l’autre.

{% hint style="info" %}
`enabled_tools` prend actuellement en charge `"python"`, `"terminal"`et `"web_search"`. Les résultats des outils sont renvoyés en continu sous forme d’événements `tool_result` afin que le modèle puisse les consulter au tour suivant.
{% endhint %}

**Lister les modèles**

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

<figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F6GKdrximwyplotWu3u5s%2FScreenshot%202026-04-22%20at%203.06.57%E2%80%AFAM.png?alt=media&amp;token=48d17278-e4b0-4437-a426-5f12c0c45b1e" alt=""><figcaption></figcaption></figure>

#### 🧠 SDK Anthropic

Le point de terminaison `/v1/messages` d’Unsloth est directement compatible avec le SDK Python d’Anthropic.

**1. Installez le SDK :**

```bash
pip install anthropic
```

**2. Créez un client** configuré pour utiliser Unsloth :

{% code overflow="wrap" %}

```python
import os
from anthropic import Anthropic

client = Anthropic(
    base_url="http://localhost:8888", # your unsloth port (no /v1 here - the SDK adds it)
    api_key="dummy", # a random none empty value
    default_headers={"Authorization": f"Bearer {os.environ['UNSLOTH_STUDIO_AUTH_TOKEN']}"} # your sk-unsloth-… key
)
```

{% endcode %}

#### Message simple

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

<figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2Fc4yQCiRHjebKomV4H2Eh%2FScreenshot%202026-04-22%20at%202.29.04%E2%80%AFAM.png?alt=media&amp;token=4ad983da-83fd-48c0-8fa8-1fbe92fcfd40" alt=""><figcaption></figcaption></figure>

#### Diffusion en continu

Le SDK propose un gestionnaire de contexte qui renvoie les fragments de texte au fur et à mesure :

```python
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 bloc `source` contenant des données base64 :

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

<figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FKI75sgbWxmo8BNXQEP6s%2Fanthropic_sdk_vision_test.png?alt=media&amp;token=f72c2dd6-b811-41a7-82bb-a2a6f30513ac" alt=""><figcaption></figcaption></figure>

#### Appels d’outils (outils Anthropic)

Transmettez des outils au format Anthropic `tools` avec un schéma `input_schema` et Unsloth les transmet nativement :

```python
tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name, e.g. '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)
```

<figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FWnWPZdZOtV2o1o5FIzlD%2Fanthropic_tool_use_get_weather_tokyo.png?alt=media&amp;token=39587916-f4c0-45cf-8e59-11245b3432b8" alt=""><figcaption></figcaption></figure>

#### Outils côté serveur Unsloth (raccourci)

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

```python
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)
```

<figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2F2wA6aleUHPJN1gAB3ClL%2Fserver_side_tool_call_backend.png?alt=media&amp;token=7440befb-d517-473a-a431-c6b4cb413ca5" alt=""><figcaption></figcaption></figure>

<figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FwcIerVboFjEZPkI2vU0L%2Fserver_side_tool_call_output.png?alt=media&amp;token=33800495-70d1-4a5f-9173-cde144abecb3" alt=""><figcaption></figcaption></figure>

Unsloth émet des événements SSE personnalisés `tool_result` pour représenter, du point de vue du modèle, la sortie de chaque appel d’outil. Le SDK Anthropic les transmet tels quels dans son flux d’événements.

#### Décodage JSON (`response_format`)

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

````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": "Pick a country: Japan, Egypt, or Peru. Explain why in one sentence.",
        },
    ],
    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
# Strip the markdown fence Gemma 4 wraps around the JSON, then parse.
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` indicateur indique à Unsloth d'appliquer 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 à ceci :

<figure><img src="https://550366147-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FmhPxaVA6sxkyF3nFf51f%2FScreenshot%202026-05-05%20at%201.46.44%E2%80%AFPM.png?alt=media&amp;token=50b1600d-9e5a-4d22-819a-274c6bfbf8f7" alt=""><figcaption></figcaption></figure>

### 🧪 Choisir un SDK

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

* Utilisez le **SDK OpenAI** si votre code dépend déjà du package Python OpenAI, si vous souhaitez utiliser les `tools` / `tool_choice`au format OpenAI, 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 d'outil `input_schema` d'Anthropic ou si vous souhaitez utiliser les types d'événements de streaming natifs d'Anthropic.

Vous pouvez utiliser les deux dans le même projet. Unsloth les sert sur le même port ; une seule `sk-unsloth-…` clé permet de s'authentifier auprès des deux.

### ❔ Dépannage

**`401 Unauthorized`**  La `UNSLOTH_STUDIO_AUTH_TOKEN` variable d'environnement n'est pas définie ou la clé est incorrecte. Exportez-la de nouveau et vérifiez avec `echo $UNSLOTH_STUDIO_AUTH_TOKEN`.

**`404 Not Found` depuis le SDK OpenAI** Vérifiez que `base_url` se termine par `/v1`. Le SDK OpenAI ajoute les chemins des points de terminaison à l’URL de base telle quelle.

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

**`Les champs extra_body` ne parviennent pas à Unsloth** Vérifiez que vous utilisez une version récente du SDK `openai` / `anthropic` ou du SDK. Les anciennes versions ignorent silencieusement les champs inconnus. Mettez-les à jour avec `pip install -U openai anthropic`.

**Le streaming « se bloque », puis affiche tout d’un coup** Le composant qui traite votre sortie la met en mémoire tampon. Dans un script, utilisez `print(..., flush=True)` ; dans un notebook, cela ne pose généralement pas de problème ; derrière un proxy, désactivez la mise en mémoire tampon des réponses sur celui-ci.

Pour les problèmes liés aux points de terminaison (port incorrect, modèle qui ne se charge pas, connexion perdue, etc.), consultez la page de présentation de l’API.

### Facultatif : définir les paramètres par défaut du serveur

Vous pouvez configurer le comportement par défaut du serveur avant de vous connecter avec le SDK Python, à l’aide de la commande `unsloth run` .

```bash
# Démarrer le serveur avec des paramètres par défaut personnalisés
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 sur les modèles qui prennent en charge le raisonnement.

```bash
# Exposer l’API sur votre réseau local
unsloth run \
  --model unsloth/Qwen3-1.7B-GGUF \
  -H 0.0.0.0 \
  -p 8888
```

Le serveur démarre ainsi sur `0.0.0.0:8888`, ce qui permet aux autres appareils de votre réseau local de s’y connecter.

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

Les valeurs définies 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.


---

# 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/fr/integrations/connecter-le-sdk-python-a-unsloth.md?ask=<question>&goal=<user_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.
