> 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/jp/tong-he/python-sdkwounslothni.md). # Python SDKをUnslothに接続する Unsloth は同じベースURLで OpenAI 互換の3つの方言を提供します。Chat Completions、Responses、Anthropic Messages に対応しているため、主要な Python SDK はどれも利用できます。 \ \ 変更するのは `base_url` と `api_key` をクライアント側で設定するだけです。その他（ストリーミング、ツール呼び出し、ビジョン、構造化出力）はすべて SDK のドキュメントどおりに動作します。このページでは、多くの開発者が最初に使う2つの SDK、つまり公式の **OpenAI Python SDK** と公式の **Anthropic Python SDK**. {% hint style="info" %} どの URL / キー / モデル名を使えばよいかわからない場合は、まず API 概要を読んでください。起動方法、モデルのロード方法、そして `sk-unsloth-…` キー。 {% endhint %} ### 🔑 前提条件 以下のスニペットを実行する前に必要なもの: * **ローカルで動作している Unsloth** モデルがロードされた状態（ポートに注意: 通常は `8000` または `8888`). * **1 つの `sk-unsloth-…` API キー** から作成した **Settings → API**. * **モデル名。** Unsloth 内の GGUF モデル名（例: `qwen-local`, `unsloth/Qwen3.6-27B-GGUF`）。忘れた場合は、次を実行してください: ```bash curl http://localhost:8888/v1/models -H "Authorization: Bearer sk-unsloth-…" ``` そしてその `id` フィールド。 キーをコードに貼り付けなくて済むよう、環境変数として設定してください: ```bash export UNSLOTH_STUDIO_AUTH_TOKEN=sk-unsloth-xxxxxxxxxxxx ``` #### 🤖 OpenAI SDK Unsloth の `/v1/chat/completions` エンドポイントは OpenAI Python SDK にそのまま差し替えて使えます。クライアントは Unsloth を他の OpenAI 互換プロバイダーと同じように扱います。 **1. SDK をインストールします:** ```bash pip install openai ``` **2. クライアントを作成します** Unsloth を指すように設定して: ```python 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-… キー ) ``` #### 基本的なチャット補完 ```python response = client.chat.completions.create( model="default", # unsloth でモデルに付けた名前、または default messages=[ {"role": "user", "content": "パリについて2つの事実を教えて"} ], ) print(response.choices[0].message.content) ```
#### ストリーミング 設定として `stream=True` を指定し、返されたジェネレーターを反復処理します: ```python 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) ```
#### 画像（ビジョン） 画像を `image_url` コンテンツパートとして添付します。Unsloth は HTTP(S) URL または `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": "この画像には何が写っていますか？"}, ], } ], ) print(response.choices[0].message.content) ``` {% hint style="info" %} ロードされているモデルはマルチモーダルである必要があります。テキスト専用モデルをロードした場合、ビジョンリクエストは構造上は成功しますが、モデルは画像を「見る」ことができません。 {% endhint %}
#### 関数呼び出し（OpenAI tools） OpenAI 形式の `tools` と（任意で） `tool_choice` を渡すと、Unsloth はそれらをバックエンドに転送します。各ツール呼び出しを実行し、次のターンで結果を返す責任はクライアント側にあります: ```python 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": "今のパースの天気は？"}], 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**、そして **Web 検索** をサーバー側で実行し、その結果を自動的にストリームで返すことができます。利用するには `extra_body` パラメータを使い、フィールドがそのまま Unsloth に渡るようにします: ```python 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 カーネル）を保持できます。 {% hint style="info" %} `enabled_tools` は現在 `"python"`, `"bash"`、そして `"web_search"`をサポートしています。ツールの結果は `tool_result` イベントとしてストリームで返されるため、モデルは次のターンでそれらを見ることができます。 {% endhint %} **モデルの一覧表示** ```python models = client.models.list() for m in models.data: print(m.id) ```
#### 🧠 Anthropic SDK Unsloth の `/v1/messages` エンドポイントは Anthropic Python SDK にそのまま差し替えて使えます。 **1. SDK をインストールします:** ```bash pip install anthropic ``` **2. クライアントを作成します** Unsloth を指すように設定して: {% code overflow="wrap" %} ```python import os from anthropic import Anthropic client = Anthropic( base_url="http://localhost:8888", # あなたの unsloth のポート（ここでは /v1 は不要 - SDK が追加します） api_key="dummy", # 空でない任意の値 default_headers={"Authorization": f"Bearer {os.environ['UNSLOTH_STUDIO_AUTH_TOKEN']}"} # あなたの sk-unsloth-… キー ) ``` {% endcode %} #### 基本的なメッセージ ```python message = client.messages.create( model="default", max_tokens=1024, messages=[ {"role": "user", "content": "3つの言語でこんにちはと言って。"} ], ) print(message.content[0].text) ```
#### ストリーミング この SDK には、テキストの差分を返すコンテキストマネージャーがあります: ```python 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 データを使います: ```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": "この画像には何が写っていますか？"}, ], } ], ) print(message.content[0].text) ```
#### ツール呼び出し（Anthropic tools） Anthropic 形式の `tools` に `input_schema` を含めて渡すと、Unsloth はそれらをネイティブに転送します: ```python 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": "東京の天気は？"}], ) 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`: ```python 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 は OpenAI 形式の構造化出力を `response_format`でサポートしています。JSON Schema を渡すと、モデルはそれに一致する JSON を生成するよう制約されます。 ````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": "国を1つ選んでください: Japan、Egypt、または Peru。理由を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 # Gemma 4 が JSON の周りに付ける markdown フェンスを取り除いてから、パースします。 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("国:", parsed["country"]) print("理由 :", parsed["reason"]) ```` この `strict: True` フラグは、モデルが自力で従うことに頼るのではなく、デコード中に Unsloth がスキーマを強制することを示します。 `additionalProperties: False` と `required` は標準の JSON Schema と同じように機能します。 ターミナル出力はおおよそ次のようになります:
### 🧪 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_AUTH_TOKEN` 環境変数が設定されていないか、キーが間違っています。再度 export して、次で確認してください: `echo $UNSLOTH_STUDIO_AUTH_TOKEN`. **`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` コマンドを使ってサーバーのデフォルト動作を設定できます。 ```bash # カスタムデフォルトでサーバーを起動 unsloth run \ --model unsloth/Qwen3-1.7B-GGUF \ --reasoning off \ --temp 0.6 \ -p 8888 ``` 使用します `--reasoning off` で思考をオフにし、または `--reasoning on` で、reasoning をサポートするモデルでそれをオンにします。 ```bash # ローカルネットワークで 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` は、そのリクエストに対して引き続きデフォルトを上書きできます。 --- # 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/jp/tong-he/python-sdkwounslothni.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.