local-llm-client
ローカル LLM ゲートウェイ(local-llm-server / OpenAI 互換)に繋ぐ高レベルクライアント。
- サーバー(ゲートウェイ)は別パッケージ。これは接続する側(エージェント共通のクライアント)。
- 各エージェントが openai のボイラープレート(メッセージ整形・画像入力・thinking 切替・ストリーム)を 再実装しなくて済む。
- 公式
openaiSDK を使用。CA ストアと HTTP・型処理などの間接依存にも、修正済みバージョンの下限を設定 (openai>=1.55.3,<4。3.x で HTTP 層が httpx → httpx2 に替わったが、 どちらでも動く。版の範囲はscripts/check-fresh-venv.shで空の venv に入れて確かめている)。
インストール
CPython の最小パッチ版は系列ごとに 3.11.18 / 3.12.16 / 3.13.18 / 3.14.10 / 3.15.2。 eMudhra 侵害鍵の標準 TLS での拒否を含む版が必要。開発・検証には 3.13.18 を使用する。 詳しい通信経路・更新結果・未確認範囲は TLS と実行環境 を参照。
uv add local-llm-client
このリポジトリの開発・実行
従来どおり、インストール済みの uv 0.13.6 以降とプロジェクトの .venv を使う。
Python は uv 標準の保存先で管理する。独自の起動スクリプトや .python-version は不要。
新しく環境を構築する場合は、次を実行する:
uv python install 3.13.18
uv sync --python 3.13.18 --locked
uv run examples/connect_and_generate.py
uv run pytest -q
uv run python scripts/check-tls.py --output .tools/validation/tls.json
CHECK_TLS=1 scripts/check-fresh-venv.sh
既存環境の Python を替える場合は、先に .venv を退避して保持してから構築する。
例はこのリポジトリの .venv と uv.lock を使う。重複していた独立スクリプト用の依存宣言は
削除した。ゲートウェイとモデルは別途起動・準備が必要。
VS Code のワークスペース既定も .venv に設定している。以前にインタープリタを手動選択した
ワークスペースでは、Python の選択表示が .venv/bin/python か確認する。
使い方
ゲートウェイ(local-llm-server)を起動しておき、公開ポートに繋ぐだけ。
from local_llm_client import LLMClient
llm = LLMClient(
model="mlx-community/Qwen3.6-27B-4bit",
base_url="http://127.0.0.1:8799/v1",
)
print(llm.respond("ローカル LLM の利点を3つ。"))
# 画像入力・ストリーム
print(llm.respond("これは何?", images=["photo.jpg"]))
for piece in llm.respond("長い説明を", stream=True):
print(piece, end="", flush=True)
# 動画入力(ゲートウェイが ffmpeg でフレーム抽出して画像として渡す。llama-cpp / mlx-vlm 共通)
print(llm.respond("この動画で何が起きている?", videos=["clip.mp4"]))
音声認識(STT)は transcribe()。ゲートウェイの whisper バックエンドへ音声を送る
(エージェント側に mlx-whisper は不要。model に whisper 系 ID を指定するだけ):
stt = LLMClient(model="mlx-community/whisper-large-v3-turbo",
base_url="http://127.0.0.1:8799/v1")
print(stt.transcribe("input.wav", language="ja")) # → 文字起こし(文字列)
print(stt.transcribe(audio_bytes, filename="clip.mp3")) # バイトでも可
print(stt.transcribe("speech.wav", translate=True)) # 英訳
seg = stt.transcribe("input.wav", response_format="verbose_json") # 区間・言語つき
STT を使うにはゲートウェイ側に ffmpeg CLI が必要(→ local-llm-server の 音声認識(STT / whisper))。
起動確認付きのワンライナー(未起動なら親切なエラー。サーバーは起動しない):
from local_llm_client import connect, ServerNotRunningError
try:
llm = connect(model="mlx-community/Qwen3.6-27B-4bit",
base_url="http://127.0.0.1:8799/v1")
except ServerNotRunningError:
print("先にゲートウェイ(local-llm-server)を起動してください")
高度な操作(embeddings / tool calling / 構造化出力 / async など)は、土台の openai クライアントに
llm.openai で直接アクセスできる。素の openai SDK で base_url を指してもよい。
タイムアウトと無応答(ハング)対策
timeout を指定しなくても、LLMClient は有限の既定タイムアウト(DEFAULT_TIMEOUT =
read 300 秒 / connect 10 秒)を使う。無指定でも 1 回の呼び出しがプロセスを無期限にブロック
しないようにするため。read タイムアウトは「次のトークンが届くまでの最大待ち時間」=無応答
(stall)検知として働き、超えると LLMTimeoutError を投げる。
from local_llm_client import LLMClient, LLMTimeoutError
llm = LLMClient(model="...", base_url="http://127.0.0.1:8799/v1")
try:
print(llm.respond("これは何?", images=["photo.jpg"]))
except LLMTimeoutError as e:
print("無応答:", e) # 原因の当たり(画像入り時は MTP×images の既知バグ)を添えたメッセージ
- 長く/無制限にしたいときは明示する(vision のプリフィルが長いモデル等):
import openai LLMClient(..., timeout=openai.Timeout(600.0, connect=10.0)) # read 10 分 LLMClient(..., timeout=openai.Timeout(None)) # 無制限(自己責任) LLMClient(..., timeout=240) # 数値なら全操作一律
openai.Timeoutは openai の HTTP 層(2.x までは httpx、3.x からは httpx2)の Timeout そのもの なので、どちらの版でもそのまま通る。httpxを直接 import すると openai 3.x の環境では入って いないことがあるので避ける。 - 生成の無応答として
LLMTimeoutErrorに翻訳する例外の型はlocal_llm_client.TIMEOUT_ERRORS(openai のAPITimeoutErrorと、ストリーム中に版によっては生で飛んでくる HTTP 層のTimeoutException)。llm.openaiを直接使って自前でタイムアウトを捕まえるときに使える。 - openai SDK は timeout エラーを既定で再試行する(
max_retries、既定 2)ため、実効の最悪 待ち時間は read × 試行回数になり得る。
注意: 画像入力(
images=)× MTP(投機的デコーディング)は要注意。 MTP を有効にしたモデルへ画像を送ると、ゲートウェイが依存するmlx_vlmの既知バグで エラーにならずハングすることがある。新しめのlocal-llm-serverゲートウェイはこの 組み合わせを HTTP 400 で即拒否するが、古いゲートウェイではLLMTimeoutError(上記の 有限タイムアウト)で打ち切られる。画像を扱うなら MTP 無しのモデルを使うか、そのモデルのdraft_model = "off"で MTP を切る(→ local-llm-server の MTP ドキュメント)。
別PC(ネットワーク越し)から繋ぐ
ゲートウェイを host = "0.0.0.0" + api_key で公開している場合は、base_url をそのPCのLAN IP、
api_key をそのキーに合わせる(chat も在席セッションも自動でキーが載る)。詳細は
docs/connecting.md。
llm = LLMClient(model="mlx-community/Qwen3.6-27B-4bit",
base_url="http://192.168.1.5:8799/v1", api_key="<キー>")
在席セッション(使い終わったら即メモリ解放)
LLMClient は既定で、ゲートウェイに「このモデルを使う」と登録し、定期ハートビートを送る。
クライアントを破棄(close() / with ブロック終了 / プロセス終了)すると利用終了を通知し、
そのモデルを使うエージェントが他に居なければ、ゲートウェイがそのモデルを即アンロードして
メモリを解放する(idle_timeout の20分を待たない)。GPU/RAM が逼迫する環境で、使い終わった
モデルをすぐ片付けたいときに効く。
確実に即解放させるには with で囲むか、使い終わりに close() を呼ぶ:
with LLMClient(model="mlx-community/Qwen3.6-27B-4bit",
base_url="http://127.0.0.1:8799/v1") as llm:
print(llm.respond("..."))
# ブロックを抜けた瞬間、他に同モデル利用者が居なければメモリが即解放される
- 明示しなくても安全:
close()を呼ばずに落ちても、ゲートウェイ側がハートビート途絶を 検出して回収する(gateway.tomlのsession_ttl、既定90秒)。with/close()はそれを 待たず即座に解放するための最短手段。 - オフにする:
LLMClient(..., session=False)で完全に無効化(従来どおりidle_timeoutまかせ)。ゲートウェイが未対応/未起動でも自動で無効化されるだけで、エラーにはならない。 - 任意指定:
agent_id(既定は自動採番)、heartbeat_interval(既定30秒)。
サーバー側の仕組みは local-llm-server の 在席ベースの即時アンロード を参照。
ライセンス
Apache-2.0
ツール呼び出しの生成中テキストを受け取る(on_tool_args、0.8.0)
LLMClient(stream_tool_calls=True)(0.9.0)でゲートウェイに頼むと、モデルが
ツール呼び出しを生成している最中の生テキスト(Qwen なら <tool_call><function=…> の形)が
ストリームの content として届く。頼んだクライアントのリクエストにだけヘッダー
X-Stream-Tool-Calls: 1 が付き、ゲートウェイ(local-llm-server 0.38.19+)がそのリクエストだけ流すので、
同じモデルを共有するほかのクライアントには影響しない(ゲートウェイ側でモデルの既定
stream_tool_calls = true にしても届く。その場合は全クライアントに流れる)。chat() はこれを本文(on_text)から剥がし、途中経過を
on_tool_args(raw_text, done) に渡す。最終的なツール呼び出し(.tool_calls)は従来どおり
最後の解析済みチャンクから作る。
from local_llm_client.tool_call_stream import parse_partial_tool_call
def on_tool_args(raw, done):
p = parse_partial_tool_call(raw) # {"name", "arguments", "partial", "arguments_text"}
if p["name"] == "write_file" and p["partial"] and p["partial"][0] == "content":
editor.show(p["arguments"].get("path"), p["partial"][1]) # 書きかけの本文を表示
llm = LLMClient(model="…", stream_tool_calls=True)
msg = llm.chat(messages, tools, on_text=print, on_tool_args=on_tool_args)
頼まないとき(既定)はマーカーが来ないので、挙動は従来と同じ。
思考(thinking)の本文を受け取る(on_reasoning、0.10.0)
LLMClient(enable_thinking=True) で思考が有効なモデルは、推論バックエンド(mlx-vlm 等)が思考を本文と
分けて reasoning_content(実装によっては reasoning)で返す。chat() に on_reasoning を渡すと、その
断片を受け取れる。本文(on_text)には流れない。渡さなければ従来どおり捨てる。
llm = LLMClient(model="…", enable_thinking=True)
msg = llm.chat(messages, tools, on_text=print, on_reasoning=lambda t: thinking_panel.append(t))
思考がバックエンドで分離されずに本文へ混ざってきた場合(<think>…</think> など)は、これまでどおり
本文から剥がして捨てる(on_reasoning には渡さない)。
Metadata
Release files for local-llm-client 0.10.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| local_llm_client-0.10.3.tar.gz | 51.9 kB | Without provenance | Details for local_llm_client-0.10.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| local_llm_client-0.10.3-py3-none-any.whl | Python 3 | none | any | Details for local_llm_client-0.10.3-py3-none-any.whl |
Total release size: 87.8 kB
Release files / local_llm_client-0.10.3.tar.gz
| Download URL | local_llm_client-0.10.3.tar.gz |
|---|---|
| Size | 51.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2f00b1fdb54fdf3b0b80f4d1039d5d053ffaf2d5149233be5949b30b9b1ff71f
|
|
BLAKE2b-256 checksum How to use checksums |
18c4aa05cbc172179996e9d6651449331a0807363789cad411ef4f5cb92de32b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / local_llm_client-0.10.3-py3-none-any.whl
| Download URL | local_llm_client-0.10.3-py3-none-any.whl |
|---|---|
| Size | 35.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d36bbbee4736aaf1ad076410a05f294ae35f1fc35395eadb2509f7ddc2310557
|
|
BLAKE2b-256 checksum How to use checksums |
dac151ba84f5ebf0a0b116c51d1d46905029e426bd410849d4f81e08147fdf28
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for local-llm-client 0.10.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.