Python SDKをUnslothに接続

ストリーミング、ビジョン、関数呼び出し、Unslothのサーバーサイド組み込みツールを含む、公式OpenAIまたはAnthropic SDKを使ってPythonからUnslothのローカルAPIを呼び出すためのガイド。

Unslothは、同じベースURLでOpenAI互換の3つの方言を提供します。Chat Completions、Responses、Anthropic Messagesのすべてに対応するので、主要なPython SDKはすべてそのまま使えます。\n\n変更するのは base_url と api_key をクライアント側で設定するだけです。ほかのすべて（ストリーミング、ツール呼び出し、ビジョン、構造化出力）はSDKのドキュメントどおりに動作します。このページでは、ほとんどの開発者が最初に使う2つのSDK、公式の OpenAI Python SDK と公式の Anthropic Python SDK.

URL / キー / モデル名のどれを使えばよいかわからない場合は、まずAPIの概要を読んでください。そこでは、起動、モデルの読み込み、そして sk-unsloth-… キー。

🔑 前提条件

以下のスニペットを実行する前に、次のものが必要です：

• モデルを読み込んだ状態でローカルで動作しているUnsloth （ポートに注意：通常は 8000 または 8888).

• 次のもの： sk-unsloth-… APIキー から作成された 設定 → API.

• モデル名。 Unsloth内のGGUFモデル名（例： qwen-local, unsloth/Qwen3.6-27B-GGUF）。忘れた場合は、次を実行します：

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

  をコピーしてください id フィールド。

キーは環境変数として設定して、コードに貼り付けないようにします：

export UNSLOTH_STUDIO_AUTH_TOKEN=sk-unsloth-xxxxxxxxxxxx

🤖 OpenAI SDK

Unslothの /v1/chat/completions エンドポイントはOpenAI Python SDKにそのまま差し替えて使えます。クライアントからは、Unslothは他のOpenAI互換プロバイダと同じように扱われます。

1. SDKをインストールします：

pip install openai

2. クライアントを作成します Unslothを指定して：

import os
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8888/v1",              # あなたのUnslothポート + /v1
    api_key=os.environ["UNSLOTH_STUDIO_AUTH_TOKEN"],     # あなたのsk-unsloth-…キー
)

基本的なチャット補完

response = client.chat.completions.create(
    model="default",                               # Unslothでモデルに付けた名前、またはdefault
    messages=[
        {"role": "user", "content": "パリについて2つの事実を教えて"}
    ],
)
print(response.choices[0].message.content)

ストリーミング

設定して stream=True を有効にし、返されたジェネレータを反復処理します：

stream = client.chat.completions.create(
    model="qwen-local",
    messages=[{"role": "user", "content": "ローカルで実行されるLLMについて俳句を書いてください。"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices:
        delta = chunk.choices[0].delta.content
        if delta:
            print(delta, end="", flush=True)

画像（ビジョン）

画像を1つの image_url コンテンツパートとして添付します。UnslothはHTTP(S) URLか 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": "この画像には何が写っていますか？"},
            ],
        }
    ],
)
print(response.choices[0].message.content)

読み込まれたモデルはマルチモーダルでなければなりません。テキスト専用モデルを読み込むと、ビジョン要求は構造上は成功しますが、モデルは画像を「見る」ことはできません。

関数呼び出し（OpenAIツール）

OpenAI形式の tools と（必要に応じて） tool_choice を渡すと、Unslothがバックエンドに転送します。各ツール呼び出しを実行し、その結果を次のターンで返すのはクライアントの役割です：

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "都市の現在の天気を取得する",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "都市名、例：'Paris'"},
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "Perthの今の天気は？"}],
    tools=tools,
    tool_choice="auto",
)

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

Unslothサーバー側ツール（ショートハンド）

OpenAI形式のクライアント側ツールに加えて、Unslothは Python, bash、そして ウェブ検索 をサーバー側で実行し、結果を自動的にストリーミングで返すことができます。 extra_body パラメータ経由で有効化すると、フィールドはそのままUnslothに渡されます：

stream = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "123 * 456は？ Pythonを使って計算してください。"}],
    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)

この session_id は省略可能です。呼び出しをまたいでツールの状態（例：Pythonカーネル）を保持するために使います。

enabled_tools は現在次をサポートしています "python", "bash"、そして "web_search"。ツール結果は tool_result イベントとしてストリーミングで返されるので、モデルは次のターンでそれらを見ることができます。

モデル一覧

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

🧠 Anthropic SDK

Unslothの /v1/messages エンドポイントはAnthropic Python SDKにそのまま差し替えて使えます。

1. SDKをインストールします：

pip install anthropic

2. クライアントを作成します Unslothを指定して：

import os
from anthropic import Anthropic

client = Anthropic(
    base_url="http://localhost:8888",                 # あなたのUnslothポート（ここでは /v1 を付けない - SDKが付加します）
    api_key="dummy",                                  # ランダムな空でない値
    default_headers={"Authorization": "Bearer {os.environ['UNSLOTH_STUDIO_AUTH_TOKEN']}"} # あなたのsk-unsloth-…キー
)

基本メッセージ

message = client.messages.create(
    model="default",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "3つの言語で挨拶してください。"}
    ],
)
print(message.content[0].text)

ストリーミング

SDKは、テキストの差分を返すコンテキストマネージャーを提供します：

with client.messages.stream(
    model="default",
    max_tokens=1024,
    messages=[{"role": "user", "content": "LoRAを2文で説明してください。"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

画像（ビジョン）

Anthropic形式の画像コンテンツでは source ブロックに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": "この画像には何が写っていますか？"},
            ],
        }
    ],
)
print(message.content[0].text)

ツール呼び出し（Anthropicツール）

Anthropic形式の tools を input_schema 付きで渡すと、Unslothがネイティブに転送します：

tools = [
    {
        "name": "get_weather",
        "description": "都市の現在の天気を取得する",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "都市名、例：'Tokyo'"},
            },
            "required": ["city"],
        },
    }
]

message = client.messages.create(
    model="default",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto"},
    messages=[{"role": "user", "content": "Tokyoの今の天気は？"}],
)

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

Unslothサーバー側ツール（ショートハンド）

同じ enable_tools / enabled_tools / session_id のショートハンドは /v1/messages をそのまま渡せば extra_body:

with client.messages.stream(
    model="default",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Python 3.13の機能を検索して要約してください。"}],
    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は独自の tool_result 各ツール呼び出しの出力に対するモデルの閲覧用に、SSEイベントを出力します。Anthropic SDKはこれらを変更せずにイベントストリームへ通します。

JSONデコード（response_format)

Unslothは response_formatを介してOpenAI形式の構造化出力をサポートします。JSON Schemaを渡すと、モデルはそれに一致するJSONを生成するよう制約されます。

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": "国を1つ選んでください：日本、エジプト、ペルー。1文で理由を説明してください。",
        },
    ],
    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
# JSONを囲むGemma 4のマークダウンのフェンスを取り除き、解析します。
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"])

この strict: True フラグは、モデル自身が従うことに頼るのではなく、デコード時にUnslothにスキーマを強制させます。 additionalProperties: False と required は標準のJSON Schemaと同じように動作します。

ターミナルの出力はおおむね次のようになります：

JSONを囲むGemma 4のマークダウンのフェンスを取り除き、解析します。

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"])

🧪 SDKの選択

どちらのSDKもUnslothで動作します。適切な選択は、既存のスタックの残り次第です：

• 次を使います： OpenAI SDK もしコードがすでにOpenAI Pythonパッケージに依存しているなら、OpenAI形式の tools / tool_choiceを使いたい場合、またはResponses APIを呼び出す予定なら。

• 次を使います： Anthropic SDK もしコードがすでにAnthropicパッケージに依存しているなら、Anthropicの input_schema ツール形式を好む場合、またはAnthropicネイティブのストリーミングイベント型を使いたい場合。

同じプロジェクトで両方を使えます。Unslothは同じポートで両方を提供するので、1つの sk-unsloth-… キーで両方を認証できます。

❔ トラブルシューティング

401 Unauthorized この UNSLOTH_STUDIO_API_KEY の環境変数が設定されていないか、キーが正しくありません。再度エクスポートして次で確認してください echo $UNSLOTH_STUDIO_API_KEY.

404 Not Found OpenAI SDKから 確認してください base_url が /v1で終わっていることを。OpenAI SDKはエンドポイントのパスをベースURLにそのまま付加します。

404 Not Found Anthropic SDKでは 確認してください base_url し ません で終わらない /v1。Anthropic SDKは /v1/messages を自動で付けます。

extra_body フィールドがUnslothに届いていません 最近の openai / anthropic SDKを使っていることを確認してください。古いバージョンは未知のフィールドを黙って捨てます。次でアップグレードしてください pip install -U openai anthropic.

ストリーミングが「止まった」あと、一度に全部吐き出す 出力をラップしている何かがバッファリングしています。スクリプトでは print(..., flush=True)；ノートブックでは通常問題ありません；プロキシの背後では、プロキシ側のレスポンスバッファリングを無効にしてください。

エンドポイントレベルの問題（ポート違い、モデルの読み込み失敗、接続喪失など）については、API概要ページを参照してください。

任意：サーバーのデフォルトを設定

Python SDKで接続する前に、 unsloth run コマンドを使用する場合に、サーバーの既定動作を設定できます。

# カスタムの既定値でサーバーを起動
unsloth run \\
  --model unsloth/Qwen3-1.7B-GGUF \\
  --reasoning off \\
  --temp 0.6 \\
  -p 8888

使用します --reasoning off を使って思考をオフにするか、 --reasoning on を使って、推論に対応したモデルで思考をオンにします。

# ローカルネットワーク上にAPIを公開する
unsloth run \\
  --model unsloth/Qwen3-1.7B-GGUF \\
  -H 0.0.0.0 \\
  -p 8888

これでサーバーは 0.0.0.0:8888で起動し、ローカルネットワーク上の他のデバイスが接続できるようになります。

これらの設定は、リクエスト側で独自の生成パラメータが指定されていない場合のサーバー既定値になります。

次のようなリクエストレベルの値： temperature, top_p, max_tokens、そして stream は、そのリクエストのデフォルトを引き続き上書きできます。