pi-provider-litellm

LiteLLM 代理原生 Provider 扩展，适用于 Pi。需要 Pi 0.81.0 或更高版本。

从自托管的 LiteLLM 代理中发现模型，并将其注册到 Pi 提供商下。默认提供商为 litellm；可选的别名可以注册具有独立凭据的额外 LiteLLM 提供商。支持 /login litellm、LiteLLM MCP 工具、LiteLLM Skills Gateway 提示注入以及 Google ADC 令牌认证。首先尝试 /model/info（具有丰富元数据的管理员端点），在遇到 401/403/404 时回退到 /v1/models（OpenAI 兼容），然后针对较旧的 LiteLLM 代理尝试 /health 以及每个端点的 /model/info。

安装

pi install npm:pi-provider-litellm

Pi 从 npm 获取该包并对其进行注册。添加 -l 可将其安装到项目设置（.pi/settings.json）中，而非全局安装。

如需在不安装的情况下试用（一次性，仅限当前运行）：

pi -e npm:pi-provider-litellm

git clone https://github.com/balcsida/pi-provider-litellm.git ~/.pi/agent/extensions/pi-provider-litellm
cd ~/.pi/agent/extensions/pi-provider-litellm
npm ci
npm run clean && npm run build

配置

选项 A — 交互式登录

在 pi 内部：

/login litellm

要配置 API 密钥，请运行 /login，选择 Sign in with an API key，然后选择 LiteLLM API key。使用 /login litellm，直接选择 Sign in with an API key。

系统将提示您输入基础 URL 和 API 密钥。凭据将持久化到 ~/.pi/agent/auth.json。

企业 SSO 登录

如果你的 LiteLLM 代理需要 SSO/OAuth 认证（企业部署），你可以通过浏览器 SSO 流程进行认证，并可选择将生成的 JWT 与一个稳定的虚拟密钥配对：

1. Run /login litellm inside pi and select Sign in with LiteLLM SSO
2. Enter the proxy URL
3. Your default browser opens the LiteLLM SSO login URL (e.g. https://litellm.your-domain.com/sso/key/generate) automatically — the URL is also displayed in case it can't be opened. Authenticate via SSO
4. Copy your token from the LiteLLM UI and paste it at the prompt (copying a full Bearer ... header value is fine — the prefix is stripped automatically)
5. When prompted to generate a virtual key, press Enter to accept (recommended) or enter n to use the JWT directly

当您生成虚拟密钥时，生成的 sk-... 密钥将作为您的凭证存储，并用于所有 API 请求。如果代理的密钥策略为生成的密钥附加了过期时间，Pi 将在其临近过期时提示您重新进行身份验证；否则，该密钥将被视为永久有效，直到在 LiteLLM 中被吊销。

直接使用时，扩展程序会读取其 exp 声明，当令牌即将过期时，Pi 会提示您重新进行身份验证。再次运行 /login litellm 以刷新。

选项 B — 环境变量

export LITELLM_BASE_URL="https://litellm.your-domain.com"
export LITELLM_API_KEY="sk-..."

存储的 litellm pi 凭据优先于 LITELLM_API_KEY；当不存在已保存的凭据时，使用环境变量密钥。当不存在已保存的登录基础 URL 时，使用 LITELLM_BASE_URL。

多个 LiteLLM 提供商别名

在 ~/.pi/agent/settings.json 的 litellm.providers 下添加别名提供商。每个别名都注册为独立的 Pi 提供商名称，因此模型显示为 litellm/model-id 和 litellm-anthropic/model-id。

{
  "litellm": {
    "providers": {
      "litellm-anthropic": {
        "baseUrl": "https://litellm.your-domain.com",
        "apiKey": "$LITELLM_CLAUDE_KEY",
        "headers": "$LITELLM_HEADERS"
      }
    }
  }
}

你还可以通过相同的结构覆盖默认提供商：

{
  "litellm": {
    "providers": {
      "litellm": {
        "baseUrl": "https://litellm.your-domain.com",
        "apiKey": "$LITELLM_API_KEY",
        "headers": "$LITELLM_HEADERS"
      },
      "litellm-anthropic": {
        "baseUrl": "https://litellm.your-domain.com",
        "apiKey": "$LITELLM_CLAUDE_KEY",
        "headers": "$LITELLM_HEADERS"
      }
    }
  }
}

Provider 字段：

/login litellm 和 Google ADC 令牌认证仍然限定于默认 litellm Provider。别名使用其配置的 apiKey 或手动存储的与别名名称匹配的认证条目。

可选的 LiteLLM 功能

LiteLLM Skills 和 MCP 集成默认启用。在 ~/.pi/agent/settings.json 中全局禁用任一功能：

{
  "litellm": {
    "skills": {
      "enabled": false
    },
    "mcp": {
      "enabled": false
    }
  }
}

将 skills.enabled 设置为 false 会禁用 Skills Gateway 管理工具、技能获取和系统提示注入。将 mcp.enabled 设置为 false 会禁用 LiteLLM MCP 发现和工具注册。更改这些设置后，请重启 Pi，以移除先前注册的工具。

使用

/model

可选环境变量

LITELLM_DISCOVERY_TIMEOUT_MS=0 禁用自动和显式的刷新模型发现。当您未使用 /login litellm 时，它不会替换发送请求所需的 base URL 或 API key 设置。

Models.dev 元数据在 Pi agent 目录下的 litellm-models-dev.json 中缓存 28 天。新鲜数据可避免公共请求；过期数据会立即使用，同时一个后台刷新会更新缓存。当您的 LiteLLM 元数据是权威的且不需要外部增强时，请设置 LITELLM_MODELS_DEV=0。

Google ADC token auth

当您的 LiteLLM 代理接受 Google OAuth 访问令牌时，您可以让扩展从 Application Default Credentials 刷新令牌：

gcloud auth application-default login
export LITELLM_BASE_URL="https://litellm.your-domain.com"
export LITELLM_GCLOUD_TOKEN_AUTH=1

仅支持 authorized_user ADC 文件。服务账号 JSON 文件会被拒绝并给出警告。令牌在内存中缓存 50 分钟，且注册的提供程序密钥是一个 Pi !command，因此当 Pi 发送模型请求时，请求时的身份验证会解析出一个新的令牌。

LiteLLM MCP 工具

如果你的 LiteLLM 代理公开了 MCP REST 端点，此扩展程序将从以下位置发现工具：

• GET /mcp-rest/tools/list
• POST /mcp-rest/tools/call

每个发现的工具都注册为名为 mcp_<server>_<tool> 的原生 Pi 工具，其简单的 JSON Schema 参数映射到 Pi/TypeBox 参数。复杂模式回退为单个 args 对象。MCP 发现运行于 Pi 刷新 LiteLLM 模型之后或 /login litellm 之后；扩展激活从不等待其完成。MCP 工具在 Pi 的并行工具模式下运行，并对瞬时失败重试一次。

LiteLLM Skill Hub

如果您的 LiteLLM 代理暴露了 /claude-code/marketplace.json，则启用的技能会在每个智能体回合之前获取，并作为 litellm_skills 部分附加到系统提示中。当 Skill Hub 不可用时，扩展回退到传统的 /v1/skills Skills Gateway 路径。它还注册了用于基本技能管理的 Pi 工具：

• litellm_skill_list
• litellm_skill_create
• litellm_skill_delete

Mocked LiteLLM 冒烟工作流

LiteLLM Smoke GitHub Actions 工作流在 runner 上启动 VidaiMock 和一个真实的 LiteLLM 代理。LiteLLM 暴露 OpenAI 兼容和 Anthropic 路由，其上游由 VidaiMock 提供，然后此扩展的冒烟运行器通过 LiteLLM 发现这些模型，并通过代理发送 /v1/chat/completions 请求。

这保持了 LiteLLM 集成路径处于测试状态，但不会调用真实的 LLM API。不需要提供商 API 密钥或 GitHub Models 权限。冒烟运行器还断言发现来自 /model/info（LITELLM_SMOKE_EXPECT_SOURCE），因此静默回退到 /v1/models 会导致运行失败。该工作流还运行身份验证检查，以及当为虚拟密钥和管理路由行为配置 LITELLM_LICENSE 时可选的基于 Postgres 的身份验证检查，然后使用 --list-models 和 -p 针对 OpenAI 兼容和 Anthropic 支持的路径运行非交互式 Pi CLI 冒烟测试，从而在不打开 TUI 的情况下覆盖扩展加载、模型发现和真实补全路径。它还运行一个交互式 Pi TUI 冒烟测试，涵盖 /login litellm 和 Pi 的原生 /model 刷新。

开发

此包需要 Node.js >=22.19.0。CI 目前使用 Node 26.5.0。

npm ci
npm run check
npm run clean && npm run build

npm run check 运行 Biome、类型检查和 Vitest 测试套件。由于扩展入口点是 ./dist/index.js，在本地 Pi 冒烟检查之前必须构建运行时更改。

在更改包内容或依赖策略之前，还请运行：

npm run supply-chain:guard
npm pack --dry-run

已发布的 npm 包应仅包含 dist、README.md 和 LICENSE。

发布

发布由名为 v*.*.* 的 semver 标签驱动。GitHub 发布工作流从 lockfile 安装，运行检查，构建 dist，验证包 tarball，以 provenance 发布到 npm，并创建 GitHub 发布。

在标记发布之前，请保持 package.json 和 package-lock.json 版本同步，并验证 dry-run 包内容。

模型目录

动态目录由 Pi 持久化在 ~/.pi/agent/models-store.json 中。凭据保留在 ~/.pi/agent/auth.json 中。旧版 litellm-models*.json 文件将被忽略且不会被删除。

打开 /model 会在后台使用 Pi 的原生模型生命周期刷新已配置的提供商目录。

故障排除

License

MIT — 参见 LICENSE.