WindowsでLM StudioのPython SDKを使う｜接続とモデル管理

先に結論：既存のロード済みLLMをSDKから選ぶ

LM Studio Python SDKは、PythonからLM Studioのネイティブなモデルhandleを扱うパッケージです。ここではPython環境とSDK、LM Studioがすでに使え、ローカルLLMがロード済みの状態から、確認したloopback接続先を設定し、その一覧から明示的に選んで短い応答を返します。記事のコードはモデルをダウンロードしたり、新しくロードしたりしません。

REST APIを使う手順やendpointごとの違いは、このSDK例とは別の入口です。まずPythonで既存のロード済みモデルを扱いたい場合に、以下の手順へ進みます。

• ローカルAI API入門 - LM Studio・Ollama・JanのHTTP APIを比較する
• LM Studioのlms CLI - 端末からserverやロード状態を確認する
• LM Studio Embedding API - ベクトル化やRAGのembedding処理へ進む

接続前にPython・アプリ・host:portを確認する

対象は、利用するPython環境へ互換性のある`lmstudio` SDKが入り、LM Studioとdaemonが利用でき、対象のローカルLLMをアプリでロード済みの状態です。Python環境が複数ある場合、SDKを入れた環境と実行する`py` / `python`が同じか確認します。現在のupstream mainのpyprojectはPython 3.10以上を指定していますが、mainやpre-releaseの条件をインストール済みstable版へそのまま当てはめず、使う版の公式案内を見てください。

1. Pythonの実行環境と、そこから見える`lmstudio` SDKの版を確認する。
2. LM StudioでローカルLLMをロードし、アプリ上で対象モデルが使える状態を確認する。
3. アプリのDeveloper表示などから、実際のloopback API hostとportを確認する。
4. 接続文字列は`127.0.0.1:1234`のような`host:port`形式にする。`http://.../v1`のREST base URLとは混ぜない。

公式project setupでは、convenience clientの初回利用より前に`configure_default_client()`を呼ぶ例が示されています。この関数はSDK 1.3から利用でき、SDK 1.5.0では任意のHTTP REST API serverを有効にしなくてもSDKを使える変更があります。古いSDKは要件が異なるため、自分の版を境界に含めます。

• LM Studio Python project setup - host:portとSDK版ごとの接続要件を確認する
• LM Studioの認証・プライバシー - 認証情報とローカル履歴の扱いを確認する

ロード済みLLMを一覧から明示的に選ぶ

次の例は、Developer表示などで確認したloopback host:portへ最初に接続先を設定し、ロード済みLLMだけを一覧します。0件ならそこで停止します。複数件の場合も同じ一覧に出したhandleを表示し、そのsnapshotから自分で選んだ番号を範囲確認して使います。新しい実行では一覧を取り直してください。番号は永続するmodel IDではありません。

import lmstudio as lms

# LM Studioの表示で確認したloopback host:portへ置き換える
SERVER_API_HOST = "127.0.0.1:1234"
lms.configure_default_client(SERVER_API_HOST)

models = lms.list_loaded_models("llm")
if not models:
    raise RuntimeError("ロード済みLLMがありません。LM Studio側の状態を確認してください。")

for index, handle in enumerate(models):
    print(f"[{index}] {handle}")

selected_index = int(input("使うhandleの番号を入力してください: "))
if not 0 <= selected_index < len(models):
    raise IndexError("一覧にある番号を選んでください。")

model = models[selected_index]
result = model.respond(
    "ローカルAIを使うときに確認することを一つ、短く教えてください。",
    config={"maxTokens": 50},
)
print(result)

表示されたhandleが使いたいモデルと一致するか、LM Studioの画面や`lms ps`と照らしてから番号を入力します。入力が整数でない場合や範囲外ならエラーが見えるので、先頭のモデルを自動選択する動きにはなりません。`list_loaded_models("llm")`はダウンロード済みファイルの一覧ではなく、現在ロード済みのLLM handleを返します。

• LM Studio公式REPL例 - handleの列挙と選択の公式例を見る
• LM Studio Python loaded models - ロード済みLLMとembeddingのfilterを確認する
• LM Studio CLIの`lms ps` - 画面外からロード状態を確認する

ロードと再利用を区別し、共有中のモデルを勝手に外さない

ダウンロード済みモデルとメモリ上にロードされたhandleは別です。`list_downloaded_models()`と`list_loaded_models()`は対象が異なり、ファイル名や画面の表示名がそのままロード済みinstanceの識別子だとは限りません。この記事の最小例は既存handleを使うため、モデルの検索・取得・ロードを追加しません。

scoped clientを閉じる操作は接続の後片付けであり、共有中のモデルを必ずアンロードするという説明には置き換えられません。ロード・再利用・アンロードの対象と影響は、使うSDK版の公式説明で確認します。

• LM Studio Python model loading - model()とload_new_instanceの違いを見る
• ロードやメモリ不足を切り分ける - PCメモリとモデルサイズの判断へ進む

streamで文字を順に受け取り、最後に結果を見る

`respond_stream()`は逐次届くfragmentを順に扱う入口です。次の部分は、直前の例の`result = model.respond(...)`から`print(result)`までを置き換えるためのものです。両方を続けて書くと別々の応答を2回送ることになるため、必要な方だけ使います。

stream = model.respond_stream(
    "ローカルAIの接続確認で見る項目を一つ教えてください。",
    config={"maxTokens": 50},
)
for fragment in stream:
    print(fragment.content, end="", flush=True)

# 全fragmentを読み終えてから最終結果・statsへアクセスする
result = stream.result()
print()
print("stop_reason:", result.stats.stop_reason)
print("predicted_tokens_count:", result.stats.predicted_tokens_count)

ストリームを最後まで反復する前に`result()`を呼ぶと、完了前の結果を求めて例外になる場合があります。`wait_for_result()`は内部で完了を待つ別の呼び方で、結果を読むだけの`result()`とは動きが異なります。途中で止めたい場合は`cancel()`を明示し、単にループを`break`することをキャンセルと同一視しません。

• LM Studio Python chat completion - respond・stream・最終statsを確認する
• LM Studio Python cancellation - streamを止める場合の仕様を見る

接続・モデル・認証でつまずいたら一つずつ分ける

複数の設定を同時に変えず、Python環境、アプリ状態、host:port、loaded handle、SDK版、応答段階を分けて記録します。同期処理の待機timeoutはSDK 1.5の説明では応答やeventに60秒間進展がない場合のものです。すべての処理が合計60秒で終わるという意味ではなく、標準の対処としてtimeoutを無効にする案内もしません。

公式認証案内のアプリ条件だけで、インストール済みSDKのtoken対応まで決まるわけではありません。アプリ0.4.0以上に加え互換SDKが必要です。SDK 1.6.0b1のrelease noteにはAPI token supportが記載されていますが、pre-releaseです。SDK 1.5.0を含むすべてのstable版が`LM_API_TOKEN`や`api_token`に対応すると仮定せず、betaの導入、認証の無効化、tokenの表示は手順にしません。

• LM Studio Python authentication - アプリとSDK両方の認証条件を確認する
• SDK 1.6.0b1 release note - pre-releaseとtoken supportの記載を見る
• ローカルAIの履歴とプライバシー - 入力・履歴・接続先の境界を確認する

次に読む場所を目的で選ぶ

Pythonから既存LLMのrespondやstreamを扱う基本が分かったら、用途に合わせてHTTP API、端末操作、embeddingへ進みます。SDK例のloopback接続だけで、モデルや周辺providerへの全通信が常にローカルであると証明できるわけではありません。個人情報や秘密を含まない短い入力から始め、選んだモデルとアプリ側の設定を確認してください。

• ローカルAI API入門 - HTTP APIのpath・provider・接続全体を確認する
• LM Studioのlms CLI - モデルやserverの状態をコマンドで見る
• LM Studio Embedding API - RAG用vectorの生成へ進む