lightning-deployments

Lightning AI デプロイメント

デプロイメントは、自動スケーリングに対応した HTTPS エンドポイントの背後で、コンテナ（または HuggingFace モデル用に自動ビルドされた vLLM サーバー）を実行します。ソースは相互に排他的です。--image（Docker）、--model（HuggingFace ID、GPU が必要）、または --studio（Studio の環境をデプロイ）を指定します。

セットアップと認証

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                     # browser flow; or headless:
export LIGHTNING_API_KEY=... LIGHTNING_USER_ID=...   # USER_ID optional: with it Basic auth, without it the key is a Bearer token

これはエージェントの現在の環境（プロジェクトの venv、conda env など）を使用し、必要に応じてそこにインストールします。その後は、どこでも通常の 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 のみが失敗する場合、それらはサンドボックスプロキシを経由しません。そのコマンドだけをサンドボックスの外で実行します。バックグラウンドのポーラーも同じ理由で、エラーを表示せずに失敗します

上記のインストールにより、その環境で lightning_sdk もインポート可能になるため、Python のスニペットはその環境の python で実行できます。CLI が uv tool または uvx のフォールバックから提供されている場合は、単発のスクリプトを uv run --with lightning-sdk python script.py で実行します。ユーザーのプロジェクトに残るコードの場合は、先に確認してから、プロジェクト独自のツール（uv add、poetry add）で lightning-sdk を依存関係として宣言します。

組織とチームスペースの解決（最初に実施）

デプロイメントは、組織またはユーザーが所有するチームスペースに作成されます。決して推測しないでください。 明示的な --teamspace owner/teamspace（Python では teamspace="owner/teamspace"。個別の org=/user= 引数は非推奨です）、環境変数 LIGHTNING_ORG / LIGHTNING_TEAMSPACE、または設定のデフォルト（lightning config get teamspace）を使用します。いずれも設定されていない場合は、選択肢を一覧表示し、どの組織/チームスペースを使用するかユーザーに確認します：

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

選択内容を保存します：lightning config set teamspace <owner>/<teamspace>。

スコープ付き API キーを使う場合（ユーザーに確認できないエージェントの場合）：--teamspace には所有者の slug が必要ですが、/v1/memberships で取得できるのは所有者の ID のみです。また、同じチームスペースが 2 回（同じ projectId を持つ organization 行と user 行として）表示される場合があります。チームスペースが 1 つだけ一覧表示されている場合に限り続行し、組織の行を優先して、ownerType を使って所有者を解決します（jq が必要です）：

M=$(lightning api /v1/memberships)
if [ "$(printf "%s" "$M" | jq '[.memberships[].projectId] | unique | length')" != 1 ]; then
  echo "several teamspaces: ask the user which one" >&2
else
  ROW=$(printf "%s" "$M" | jq -c '(.memberships | map(select(.ownerType=="organization"))) + .memberships | .[0]')
  TS=$(printf "%s" "$ROW" | jq -r .name); OID=$(printf "%s" "$ROW" | jq -r .ownerId)
  if [ "$(printf "%s" "$ROW" | jq -r .ownerType)" = organization ]; then
    OWNER=$(lightning api "/v1/orgs/$OID" | jq -r .name)
  else   # a personal teamspace; the search is fuzzy, so match the id exactly
    OWNER=$(lightning api /v1/users/search -X GET -f "query=$OID" \
      | jq -r --arg id "$OID" '.users[] | select(.id==$id) | .username')
  fi
  lightning config set teamspace "$OWNER/$TS"   # or pass --teamspace "$OWNER/$TS" each time
fi

CLI リファレンス

サブコマンド：create、list、inspect、update、delete、logs（および logs download）、reload-weights、env / secret（稼働中のデプロイに対する list / set / delete）。stop はありません。update --min-replicas 0 --max-replicas 0 でレプリカ数をゼロにしてください。

# container deployment (a --port is required for non-model deployments)
lightning deployment create my-api --teamspace owner/teamspace \
  --image nginx:latest --machine CPU --port 80 --replicas 1 --api-key-auth

# HuggingFace model via vLLM (GPU machine required; port defaults to 8000)
lightning deployment create llama --teamspace owner/teamspace \
  --model meta-llama/Llama-3.1-8B-Instruct --machine L40S \
  [--hf-token-secret <secret-name>] [--tensor-parallel-size 2] [--max-model-len 8192] \
  [--quantization fp8] [--dtype bfloat16] [--dry-run] [--force]

# cloud account — if you pass none, the SDK picks one (config `cloud-account`, then
# LIGHTNING_CLUSTER_ID, then the teamspace's default binding) and prints which on stderr.
# Other deployments in the same teamspace may sit on a different account, which
# `deployment list` shows in its last column; match it with --cloud when relevant.
lightning deployment create ... --cloud gcp-lightning-public-prod

# autoscaling / env / secrets
lightning deployment create ... \
  --min-replicas 0 --max-replicas 4 --autoscale-metric GPU --autoscale-threshold 90 \
  -e KEY=VALUE --secret MY_LIGHTNING_SECRET --interruptible   # check the spot price first (below)

# endpoint auth: mutually exclusive; OMITTING ALL THREE MAKES THE ENDPOINT PUBLIC (confirm that's intended)
  --api-key-auth                    # require a Lightning USER API key (Bearer)
  --basic-auth USER:PASS
  --token-auth TOKEN                # any bearer string you choose

# operate
lightning deployment list --teamspace owner/teamspace [--all] [--sort-by state]
lightning deployment inspect my-api --teamspace owner/teamspace     # full JSON incl. endpoint URLs
lightning deployment logs my-api --teamspace owner/teamspace [-f] [--tail 100] [--timestamps]
lightning deployment logs my-api --teamspace owner/teamspace --query timeout --severity error   # filter server-side
lightning deployment logs my-api --teamspace owner/teamspace --since 30m --until 5m             # window (replicas merged + labelled)
lightning deployment update my-api --teamspace owner/teamspace --max-replicas 8
lightning deployment update my-api --teamspace owner/teamspace --min-replicas 0 --max-replicas 0   # "stop"
lightning deployment update my-api --teamspace owner/teamspace --image myimg:v2 [--max-surge 1] [--max-unavailable 0]  # new release, rolling update
lightning deployment reload-weights llama --teamspace owner/teamspace   # hot-reload BYOM weights
lightning deployment delete my-api --teamspace owner/teamspace --yes

• lightning auth whoami の結果に応じて認証フラグを選択してください。呼び出し元が user の場合は --api-key-auth、scoped-api-key の場合は --token-auth を使います。 --api-key-auth が受け付けるのは Lightning の user キーのみです（userApiKey: true としてシリアライズされます）。scoped-key の呼び出し元は、レプリカが稼働して課金が発生している間、すべてのリクエストで 401 を受け取ります。scoped key、CI ジョブ、エージェントからエンドポイントを呼び出す場合は、--token-auth <token> を使用してください。各自の Lightning ログインを使う人間が呼び出す場合は、--api-key-auth を使用してください。
• --interruptible を使っても必ず安くなるとは限らないため、指定する前に価格を確認してください。 SKU やクラウドによっては、スポットのほうがオンデマンドより高く、作成時にも警告されません。アクセラレーターカタログから両方の料金を取得し（lightning-cost-estimation スキルを参照）、min(cost, spotPrice) を選択してください。
• イメージ、コマンド、env、エントリーポイント、パスマッピング、ヘルスチェック、クラウドアカウント、スポット設定、数量、最大実行時間を変更すると新しいリリースが作成されます。マシンのみを切り替えた場合は作成されません。 CLI はローリングアップデートを自動的に追加します。SDK では、リリース戦略が渡されておらず、保存済みの戦略もない場合、RuntimeError が発生します。

Python SDK

from lightning_sdk import Deployment, Machine
from lightning_sdk.api.deployment_api import (
    ApiKeyAuth, BasicAuth, TokenAuth, AutoScaleConfig, Env, Secret,
    RollingUpdateReleaseStrategy, HttpHealthCheck,
)

dep = Deployment("my-api", teamspace="my-org/my-teamspace")   # owner/teamspace, same as the CLI
dep.start(
    image="nginx:latest",
    machine=Machine.CPU,
    ports=[80],                                 # REQUIRED for non-model deployments; a LIST, not an int
    autoscale=AutoScaleConfig(min_replicas=0, max_replicas=4, metric="CPU", threshold=90),
    env=[Env("MODE", "prod"), Secret("HF_TOKEN")],   # or a plain dict for env vars
    auth=ApiKeyAuth(),                          # None => PUBLIC endpoint
    health_check=HttpHealthCheck(path="/health", port=80),
    spot=False,                                 # True = interruptible replicas
)

print(dep.urls)                                 # endpoint URL(s); no .status property — use replica counts
print(dep.running_replicas, dep.pending_replicas, dep.failing_replicas)
r = dep.get(path="/health")                     # convenience HTTP; auto-auths only for ApiKeyAuth

# a new release needs a release strategy (see the release rule under CLI reference)
dep.update(image="nginx:1.27", release_strategy=RollingUpdateReleaseStrategy(max_surge=1, max_unavailable=0))
dep.update(min_replicas=1, max_replicas=8)      # scaling: no new release, no strategy needed
dep.stop()                                      # scales to 0; blocks until replicas reach 0

SDK を使用した HuggingFace モデルのサービング：dep.start(model="meta-llama/...", machine=Machine.L40S, ports=[8000], hf_token_secret="...")。image / studio は None である必要があります。それでも ports は指定してください。

dep.delete() はデプロイを削除しません。 dep.get() / dep.post() と同様に、これは HTTP ヘルパーであり、デプロイされたサービスのエンドポイントに HTTP DELETE リクエストを送信します。デプロイのリソースを削除するには、lightning deployment delete NAME --yes または未加工の API を使用してください。

プライベートコンテナーイメージ

レジストリ認証情報が必要なイメージを使うデプロイでは、V1JobSpec.image_secret_ref に、teamspace 内の SECRET_TYPE_DOCKER_REGISTRY シークレットの名前を設定する必要があります。CLI も Deployment.start() も image_secret_ref を公開しておらず、これがないとサーバーは不透明な 500 エラーでイメージを拒否します。 エラーにはイメージ名も不足している認証情報も表示されません： Exception: The jobs_service_create_deployment_with_http_info request failed to reach the server, response: 500.

SDK でサポートされるまでは、作成リクエストにこのフィールドをパッチしてください：

from lightning_sdk.lightning_cloud.openapi.api import jobs_service_api

_create = jobs_service_api.JobsServiceApi.jobs_service_create_deployment_with_http_info

def _with_image_secret(self, body, project_id, **kwargs):
    if getattr(body, "spec", None) is not None:
        body.spec.image_secret_ref = "MY_REGISTRY_SECRET"
    return _create(self, body, project_id, **kwargs)

jobs_service_api.JobsServiceApi.jobs_service_create_deployment_with_http_info = _with_image_secret

teamspace のシークレットとその種類を一覧表示するには、次を実行してください：

PROJECT_ID=$(lightning api /v1/memberships | jq -r '.memberships[] | select(.name=="<teamspace>") | .projectId')
lightning api "/v1/projects/${PROJECT_ID}/secrets" | jq -r '.secrets[] | "\(.name) \(.type)"'

この 500 の原因を診断するには、ほかの引数は同一のまま、公開イメージ（nginx:latest）で再試行してください。 その作成が成功する場合、変数はイメージであり、マシン、ポート、レプリカ数、クラウドアカウントではありません。

ワークフローの例

このスキルが対応するプロンプト：「この docker イメージを API の背後でデプロイして」、「lightning で Llama 3.1 8B をサーブして」、「夜間にデプロイのスケールを下げて」、「新しいイメージバージョンをロールアウトして」。

コンテナーをデプロイし、応答を確認してから、クリーンアップします。 確認には、ソースの Studio 内のアプリではなく、deployment inspect から取得したエンドポイント URL を使用してください。Studio で確認できるのはイメージです。サービスを確認できるのはエンドポイントだけです。

lightning auth whoami    # pick the auth flag from this (see the auth rule under CLI reference)
lightning deployment create hello-api --teamspace my-org/my-teamspace \
  --image nginx:latest --machine CPU --port 80 --min-replicas 0 --max-replicas 1 --api-key-auth
lightning deployment inspect hello-api --teamspace my-org/my-teamspace   # JSON: status, endpoint URL
URL=<endpoint URL from the inspect output above>
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $LIGHTNING_API_KEY" "$URL/"   # verify the ENDPOINT, not the Studio

from lightning_sdk import Deployment
dep = Deployment("hello-api", teamspace="my-org/my-teamspace")
print(dep.urls)                       # e.g. ['https://80-dep-<id>-d.cloudspaces.litng.ai'] — available even while scaled to zero
print(dep.get(path="/").status_code)  # sends the caller's Lightning API key for ApiKeyAuth

lightning deployment delete hello-api --teamspace my-org/my-teamspace --yes

オープンウェイトの LLM をサーブします（vLLM、サーバー側でビルドするため Dockerfile は不要）：

lightning deployment create qwen-served --teamspace my-org/my-teamspace \
  --model Qwen/Qwen2.5-7B-Instruct --machine L40S --min-replicas 0 --max-replicas 1 --api-key-auth --dry-run
# review the model spec it prints, then re-run without --dry-run; if the real create reports
# unacknowledged warnings, re-run with --ack <code> (repeatable) or --force
lightning deployment logs qwen-served --teamspace my-org/my-teamspace -f   # watch it come up

エンドポイントはポート 8000 で OpenAI 互換 API を提供します。任意の OpenAI クライアントの base_url を dep.urls[0] に設定してください。

運用：スケール、更新、ロールバック、トラフィックコストの管理：

lightning deployment update hello-api --teamspace my-org/my-teamspace --min-replicas 1 --max-replicas 4   # keep warm
lightning deployment update hello-api --teamspace my-org/my-teamspace --min-replicas 0 --max-replicas 0   # stop (scale to zero)
lightning deployment update hello-api --teamspace my-org/my-teamspace --image nginx:1.27                  # new release, rolling by default

未加工 API の代替手段

PROJECT_ID=$(lightning api /v1/memberships | jq -r '.memberships[] | select(.name=="<teamspace>") | .projectId' | head -1)
lightning api "/v1/projects/${PROJECT_ID}/deployments" -q '.deployments[].name'   # plain GET; -f/-F without -X would send a POST
lightning api "/v1/projects/${PROJECT_ID}/deployments/${DEPLOYMENT_ID}"
lightning api "/v1/projects/${PROJECT_ID}/deployments/${DEPLOYMENT_ID}" -X DELETE

注意点

• デプロイメントはレプリカが起動している間、課金されます。作成前に必ずユーザーに費用を確認してください。 GPU マシンを使う場合、--min-replicas >= 1（継続的に課金されます）を設定する場合、また請求額の上限を決める --max-replicas を引き上げる場合は、事前に明確な許可を得てください。まず lightning-cost-estimation スキルでマシンの料金を確認してください。
• デプロイメントの検証には、ソース Studio 内のアプリではなく、deployment inspect で確認できる公開 URL を使ってください。 Studio で確認できるのはイメージだけです。サービスを確認できるのはエンドポイントのみです。レプリカが正常と表示され、通常どおり課金されていても、デプロイメントがすべてのリクエストに 401 を返すことがあります。
• min_replicas=0 ならレプリカ数がゼロの間は課金されず、次のリクエストは失敗せずにコールドスタートを待ちます。 エッジはレプリカの準備が整うまで接続を維持し（GPU イメージでは約 6 分）、その後、通常の 200 を返します。503 を返したり接続を拒否したりすることはないため、タイムアウトが短く設定されていないクライアントは待ち続けます。min_replicas >= 1 は継続的に課金されるため、この費用をユーザーに伝えてください。
• スケール・トゥ・ゼロのアイドル時間とヘルスチェックは SDK でのみ設定できます。 AutoScaleConfig(idle_threshold_seconds=...) と HttpHealthCheck(path=..., port=...) に対応する deployment create／update フラグはありません（--health-check-path／--readiness-probe はありません）。CLI ではデフォルトのアイドル時間が適用され、起動中でも準備が整っていないレプリカにトラフィックが届くのを防ぐ手段はありません。
• 既存のデプロイメントに対する Deployment.start() は、エラーにならずに更新／再起動として処理されます。 名前の競合があってもエラーは発生しません。
• ポートの指定が誤っていても、どのポートかはエラーに表示されません。 モデル以外のデプロイメントでポートが指定されていない場合は ValueError が発生します。SDK で ports に int を指定すると、SDK 内部から TypeError: 'int' object is not iterable が発生しますが、エラーには ports への言及がありません。
• metric を指定せずに AutoScaleConfig を使うと、start() の時点で後からエラーが発生します。 ValueError: The autoscaling metric is required. Currently supported metrics are ['GPU', 'CPU', 'RPM'] が発生し、トレースバックが示すのは設定オブジェクトではなく start() です。必ず metric= を渡してください。
• deployment inspect で Secret("NAME") の name が空でも、バグではありません。 {"from_secret": "NAME", "name": "", "value": ""} と表示されます。プラットフォームが参照先を解決し、シークレット名を環境変数名として設定します。
• デプロイメントのログはチームスペースへのアクセス権を持つ人なら誰でも読めるため、起動時に実際のシークレットを出力しないでください。 環境変数を出力するコンテナは、シークレットの値を deployment logs に漏えいさせます。
• Deployment deleted と表示されても、デプロイメントが「消えた」とは限りません。 最大約 2.5 分間、デプロイメントの一覧に残ることがあります。deployment list（および list --all）に、古いレプリカ数と deletedAt: None を伴って PENDING と表示される場合があります。削除失敗と判断したり、削除完了の確認のために list を繰り返し実行したりしないでください。数分経過してもまだ残っている場合に限り、delete を再実行してください。削除は取り消せない操作であり、--yes を指定しない限り CLI で確認が求められるため、事前にユーザーの許可を得てください。
• -f を付けない deployment logs は、出力がないままハングして戻らないことがあります。 スクリプトで上限付きの読み取り（--tail 25、--follow なし）を行う場合は、個別にタイムアウトを設定してください。-f は動作します。
• deployment inspect の total_cost はデプロイメントの存続期間中ずっと 0.0 のままです。チームスペースのクレジット残高で費用を確認してください。 ジョブとは異なり、課金／使用量エンドポイントを使ってもデプロイメントの費用は確認できません。実行前後のクレジット残高の差を確認してください。このフィールドは連続する呼び出し間で、浮動小数点の完全な精度と小数第 2 位への丸めの間で変化するため、丸め誤差が無視できる程度になる長さの期間を取ってください。
• --dry-run はサーバーを呼び出さないため、未確認の警告に関するエラーは表示されません。 実際の --model による作成では、Deployment has unacknowledged warnings: ... Re-run with --ack <code> (repeatable) or --force. というエラーが発生することがあります。ドライランで表示されるのは、設定したモデル仕様（served_model_name、weight_source、および指定した vLLM フラグ）のみで、マシン、イメージの種類、レプリカ設定は表示されません。
• --model で不透明な 403 が返された場合は、アカウントでこの機能が制限されているため、--image に切り替えてください。 エラーは Exception: The jobs_service_create_deployment_with_http_info request failed to reach the server, response: 403. で、サーバーからのメッセージはありません。LIGHTNING_DEBUG=1 を設定するとトレースバックは追加されますが、理由は表示されません。これは引数の誤りではなく利用資格の問題なので、モデル ID やフラグのデバッグは不要です。利用資格が不要な vLLM コンテナイメージを直接デプロイしてください（--image）。
• teamspace="owner/teamspace" と org=／user= の両方を渡すと ValueError が発生します。 org=／user= のみを渡すと DeprecationWarning が表示されます。2026.7.31 より古い SDK では、両方を指定すると "Teamspace owner/name does not exist" というエラーが発生していました。指定を分けずにアップグレードしてください。