lightning-llm-gateway

Lightning AI LLM Gateway（Models API）

LLM ゲートウェイを使うと、複数のプロバイダーのモデルを1つの API と1つの請求先で利用できます。モデル名は provider/model 形式です（モデル名を確認するを参照）。LLM は lightning_sdk.llm からインポートしてください。パッケージのトップレベルからはエクスポートされていません。

セットアップと認証

export DEBUG=0 LIGHTNING_DEBUG=0   # an inherited DEBUG=1 logs the Authorization header; set this in every new shell
# Use the Lightning AI CLI from the current env; install or upgrade it there if it's missing or older than 2026.9.18
v=$(lightning --version 2>/dev/null | sed -n 's/^Lightning CLI version //p')
[ -n "$v" ] && [ "$(printf '%s\n' 2026.9.18 "$v" | sort -V | head -1)" = 2026.9.18 ] \
  || uv pip install -U lightning-sdk || python3 -m pip install -U lightning-sdk
lightning --version   # must print "Lightning CLI version …"; if not, see the table below
lightning login   # or headless: export LIGHTNING_USER_ID=... LIGHTNING_API_KEY=...

これはエージェントの現在の環境（プロジェクトの venv、conda 環境など）を使用し、必要に応じてそこにインストールします。その後は、どこでも通常の lightning … を呼び出してください。セットアップがうまくいかない場合は、次のように対処してください。

症状	対処方法
有効な環境がない、externally-managed-environment が表示される、またはプロジェクト独自のバージョン固定と競合する	単独でインストールします：uv tool install lightning-sdk（または pipx install lightning-sdk）。PATH に含まれていない場合は "$(uv tool dir --bin)/lightning" を呼び出してください
インストール後も Lightning CLI version の行が表示されない	別の lightning（PyTorch Lightning のもの）または無効な環境が先に見つかっています：command -v lightning を確認し、環境を有効にするか、その環境の bin/lightning を呼び出してください
No such command、No such option、または unexpected extra argument が表示される	CLI が古すぎます：command -v lightning で示される場所でアップグレードしてください（uv pip install -U lightning-sdk または uv tool upgrade lightning-sdk）
インストールがブロックされる（読み取り専用の環境やホームディレクトリ、エージェントのサンドボックス）	各コマンドを UV_CACHE_DIR="${TMPDIR:-/tmp}/uv" UV_TOOL_DIR="${TMPDIR:-/tmp}/uv-tools" uvx lightning-sdk … として実行してください
エージェントのサンドボックス内でのみ、lightning --version も含め、すべての呼び出しで SSL/CA エラーが発生する	**/*.pem の読み取り拒否ルールにより、certifi の cacert.pem が隠されています。そのパスだけを許可してください。サンドボックスを無効にしないでください
エージェントのサンドボックス内でのみ NameResolutionError が発生する	lightning api も失敗する場合は、ユーザーに lightning.ai と *.lightning.ai（/sandbox）を許可するよう依頼してください。studio／job コマンドまたは SDK だけが失敗する場合、それらはサンドボックスのプロキシを経由しません。その処理だけをサンドボックス外で実行してください。バックグラウンドのポーラーも同じ理由で、何も表示せずに失敗します

LLM クラスは Python のものです。上記のインストールにより、その環境で lightning_sdk もインポート可能になるため、コード例はその環境の python で実行できます。CLI が uv ツールまたは uvx のフォールバック経由でインストールされた場合は、単発のスクリプトを uv run --with lightning-sdk python script.py で実行してください。ユーザーのプロジェクト内で継続して使うコードの場合は、ユーザーに確認してから、プロジェクト独自のツール（uv add、poetry add）で lightning-sdk を依存関係に追加してください。

推論はチームスペースに請求されます。LLM クラスはチームスペースなしでは実行できません。解決方法は、明示的な teamspace= 引数（"owner/teamspace"、またはその組織の最初のチームスペースを使用する場合は組織名のみ）→ LIGHTNING_TEAMSPACE と LIGHTNING_CLOUD_PROJECT_ID の環境変数（両方とも Studio 内で設定されます。名前のみの場合は Teamspace ID is missing が発生します）→ ユーザーのデフォルトのチームスペースの順です。ユーザーが複数の組織／チームスペースに所属しており、どれも設定されていない場合は、どこに請求するかをユーザーに確認してください。

lightning api /v1/memberships | jq -r '.memberships[] | [.ownerType, .name] | @tsv'

Python SDK

from lightning_sdk.llm import LLM

llm = LLM("openai/gpt-4o", teamspace="my-org/my-teamspace")

# single-shot
print(llm.chat("Summarize this...", system_prompt="Be terse", max_completion_tokens=500))

# streaming
for chunk in llm.chat("Tell a story", stream=True):
    print(chunk, end="")

# multi-turn: reuse the same conversation name across calls. History persists server-side
# under that name; set LIGHTNING_EPHEMERAL=true to persist nothing
llm.chat("What is CUDA?", conversation="cuda-help")
llm.chat("Show an example", conversation="cuda-help")
print(llm.get_history("cuda-help"))        # [{"role": "user"|"assistant", "content": ...}]
llm.reset_conversation("cuda-help")
llm.list_conversations()

# images (local paths are base64-encoded automatically; URLs passed through)
llm.chat("What's in this image?", images=["./photo.png"])

# knobs
llm.chat("...", reasoning_effort="high")   # none|low|medium|high
# there is no temperature/top_p: extra **kwargs are silently dropped, not sent to the model

# model info & pricing: every chat() call is billed to the resolved teamspace
print(llm.context_length)
m = llm.metadata                            # prompt_price, completion_price, max_completion_tokens,
                                            # capabilities, throughput, time_to_first_token

非同期：LLM("...", enable_async=True) を設定すると、chat() が await 可能になります（ストリーミング時は非同期ジェネレーターになります）。非同期の処理経路では、tools と reasoning_effort は無視されます。

モデル名を確認する

llm.list_models() はありません。現在のカタログは lightning.ai の Model APIs ページで確認してください。 SDK は、既知の公開モデルを静的にまとめたマップも lightning_sdk/llm/public_assistants.py に保持しています。このマップは LIGHTNING_CLOUD_URL が https://lightning.ai の場合（実際には Studio 内の場合）にのみ使用されます。それ以外では SDK がサーバーに問い合わせるため、マップにないモデルも解決できます。

モデル名の例（対象は変更されます）：openai/gpt-4o、anthropic/claude-3-5-sonnet-20240620、google/gemini-2.5-pro、lightning-ai/gpt-oss-120b。

• 不明な provider/model は、インスタンスの作成時にエラーになります。
• それ以外のプレフィックス（myorg/my-assistant）は、カスタムの組織／ユーザーアシスタントとして解決されます。

ワークフローの例

このスキルで対応できるプロンプト：「lightning 経由で gpt-4o を使ってこのファイルを要約して」、「このプロンプトに対する Claude と Gemini の回答を比較して」、「このタスクで最も安価なゲートウェイモデルはどれ？」、「このチェックポイントをモデルレジストリにプッシュして」。

シェルからの単発推論：

uv run --with lightning-sdk python -c "
from lightning_sdk.llm import LLM
llm = LLM('openai/gpt-4o', teamspace='my-org/my-teamspace')
print(llm.chat('Explain CUDA streams in two sentences.'))"

同じプロンプトでモデルを比較（価格を考慮）：

from lightning_sdk.llm import LLM
prompt = "Extract the action items from this meeting transcript: ..."
for model in ["openai/gpt-4o", "anthropic/claude-3-5-sonnet-20240620", "google/gemini-2.5-flash"]:
    llm = LLM(model, teamspace="my-org/my-teamspace")
    m = llm.metadata
    print(f"--- {model} (in ${m.prompt_price}/tok, out ${m.completion_price}/tok)")
    print(llm.chat(prompt, max_completion_tokens=300))

メモリを備えた長時間実行アシスタント： Python SDK のブロックにある複数ターンの conversation= 呼び出しを使い、完了したら reset_conversation() を実行します。

直接 REST アクセス用 API キー

SDK の外部からパブリック推論エンドポイントを呼び出す場合（Authorization: Bearer <key>）：

lightning api-key get [--org NAME]        # get-or-create the default model-API key, prints raw key
lightning api-key create --org NAME --name my-key
lightning api-key list; lightning api-key delete <KEY_ID>

ユーザーが複数の組織に所属している場合は、--org を渡すか LIGHTNING_ORG を設定してください。そうしないと、キーが誤った組織に紐付けられる可能性があります。OpenAI 互換の正確なベース URL は lightning.ai の Model APIs ページに記載されています（SDK にはハードコードされていません）。一方、SDK 独自の LLM.chat() は Lightning のアシスタントエンドポイント（POST /v1/agents/{assistant_id}/conversations）を使用します。

認証方式を混同しないでください。プラットフォームの SDK／REST 呼び出しでは、LIGHTNING_USER_ID と LIGHTNING_API_KEY の両方が設定されている場合は Basic 認証（user_id:api_key）を使用し、それ以外の場合はキーを Bearer として単独で送信します。モデル API エンドポイントでは、lightning api-key get で取得したキーを Bearer として指定します。

モデルチェックポイントレジストリ（別の概念）

lightning model は、ゲートウェイ推論とは無関係なチームスペースストア内のバイナリモデルアーティファクトを管理します。名前の形式は org/teamspace/model[:version] です。

lightning model upload   my-org/my-teamspace/my-model ./checkpoints          # PATH is positional; only option is --cloud-account
lightning model download my-org/my-teamspace/my-model:v2 --download-dir ./out

from lightning_sdk.models import upload_model, download_model, delete_model, list_model_versions
info = upload_model("my-org/my-teamspace/my-model", path="./ckpt")   # auto-versions vX
paths = download_model("my-org/my-teamspace/my-model")

注意点

• プロセス内で最初に作成された LLM(...) によって、それ以降のすべてのインスタンスのチームスペース／認証情報の解決が固定されるため、最初のインスタンスで teamspace= を設定してください。 キャッシュはクラスレベルです。
• 個人用チームスペース（teamspace="<user>/<teamspace>"）は Studio の外では失敗することがあるため、組織所有のチームスペースを使うか、課金対象にしたいチームスペースの Studio 内で実行してください。 エラーは Teamspace ID is missing from the resolved authentication information. です（SDK のバグ）。Studio 内では、エラーなしに Studio 自身のチームスペースに課金されます。
• 推論モデル（openai/gpt-5*）は max_completion_tokens の上限が小さいと空の応答を返すため、1000 以上を指定するか、上限を省略してください。 まず内部推論に予算を消費します。100 以下では、クライアント側のデシリアライズで断続的に TypeError が発生することもあります。