lightning-llm-gateway

Lightning AI LLM Gateway（Models API）

LLM 网关通过一个 API 和一张账单，提供来自多个供应商的模型。模型名称格式为 provider/model（参见查找模型名称）。从 lightning_sdk.llm 导入 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=...

这会使用 Agent 当前的环境（项目 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）
安装受阻（环境或主目录只读、Agent 沙盒）	将每条命令写成 UV_CACHE_DIR="${TMPDIR:-/tmp}/uv" UV_TOOL_DIR="${TMPDIR:-/tmp}/uv-tools" uvx lightning-sdk … 来运行
每次调用都出现 SSL/CA 错误，即使是 lightning --version 也如此，且仅发生在 Agent 沙盒中	**/*.pem 读取拒绝规则隐藏了 certifi 的 cacert.pem：允许访问该路径；不要禁用沙盒
NameResolutionError，且仅发生在 Agent 沙盒中	如果 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 声明为依赖项。

推理费用由 teamspace 承担——没有 teamspace 时，LLM 类会拒绝运行。解析顺序：显式的 teamspace= 参数（"owner/teamspace"，或使用该组织第一个 teamspace 的组织名称）→ LIGHTNING_TEAMSPACE + LIGHTNING_CLOUD_PROJECT_ID 环境变量（在 Studio 中会同时设置；只提供名称会报错 Teamspace ID is missing）→ 用户的默认 teamspace。如果用户属于多个组织或 teamspace，且均未配置，请询问应由哪个 teamspace 承担费用：

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() 可等待（流式传输时为异步生成器）。异步路径会静默忽略 tools 和 reasoning_effort。

查找模型名称

没有 llm.list_models()；请从 lightning.ai 的 Model APIs 页面获取当前模型目录。 SDK 还会在 lightning_sdk/llm/public_assistants.py 中维护已知公开模型的静态映射。只有当 LIGHTNING_CLOUD_URL 为 https://lightning.ai 时（实际上是在 Studios 中），才会使用该映射。在其他地方，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 对此提示词的回答”、“对于此任务，哪个网关模型最便宜？”、“将此检查点推送到模型注册表”。

从 Shell 进行一次性推理：

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）。

不要混淆身份验证方案：当同时设置 LIGHTNING_USER_ID 和 LIGHTNING_API_KEY 时，平台 SDK/REST 调用使用 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。