> 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-sdkwounslothnisuru.md).
# Python SDKをUnslothに接続する
公式の OpenAI または Anthropic SDK を使って、ストリーミング、ビジョン、関数呼び出し、Unsloth の組み込みサーバーサイドツールを含め、Python から Unsloth のローカル API を呼び出すためのガイド。
Unsloth は、同じベース URL で 3 つの OpenAI 互換方言を提供します。Chat Completions、Responses、Anthropic Messages の3つで、主要な 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`).
* **ある `sk-unsloth-…` API キー** から作成された **設定 → 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 のツール）
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 search** サーバー側で実行し、結果を自動でストリームバックできます。 `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": "Say hello in three languages."}
],
)
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 形式の画像コンテンツは `ソースからビルドする` 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 のツール）
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 は `response_format`を通じて OpenAI 形式の構造化出力をサポートします。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つ選んでください: 日本、エジプト、ペルー。理由を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 の 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("country:", parsed["country"])
print("reason :", 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` 環境変数が設定されていないか、キーが間違っています。再エクスポートして次で確認してください `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 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/jp/tong-he/python-sdkwounslothnisuru.md?ask=&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.