> 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 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**. {% hint style="info" %} 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é. {% endhint %} ### 🔑 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 : ```bash 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 : ```bash 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 :** ```bash pip install openai ``` **2. Créez un client** pointant vers Unsloth : ```python 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 ```python 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é : ```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) ```
#### Images (vision) Joignez une image comme `image_url` partie de contenu. Unsloth accepte soit une URL HTTP(S), soit une `URI data :` 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 texte uniquement, la requête de vision réussira sur le plan structurel mais le modèle ne pourra pas « voir » l'image. {% endhint %}
#### 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 : ```python 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 : ```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) ```
Le `session_id` est facultatif. Utilisez-le pour conserver l'état de l'outil (par ex. un noyau Python) entre les appels. {% hint style="info" %} `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. {% endhint %} **Liste des modèles** ```python 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 :** ```bash pip install anthropic ``` **2. Créez un client** pointant vers Unsloth : {% code overflow="wrap" %} ```python 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-… ) ``` {% endcode %} #### Message de base ```python 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 : ```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 `source` bloc avec 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) ```
#### Appel d'outils (outils Anthropic) Passez des `tools` avec un `input_schema` et Unsloth les transmet nativement : ```python 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`: ```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) ```
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. ````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": "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. ```bash # 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. ```bash # 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. --- # 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/fr/integrations/connecter-le-sdk-python-a-unsloth.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.