LiteLLM Controller (litellmctl)

LiteLLM Controller 是基于 Textual 的现代化终端用户界面（TUI）管理工具，专为 LiteLLM Proxy 设计，用于高效管理模型、路由组配置以及模型元数据（定价与上下文窗口）。

核心特性

• 现代 TUI 界面：基于 Textual 8.x 响应式框架，统一页面骨架（顶栏 / 内容区 / 底部提示栏 / ⋮ 折叠菜单）、全键盘导航 + 单击即执行鼠标操作、三段式模态、实时模糊筛选、状态栏与非阻塞异步更新。
• 合一式模型表单：添加、查看（只读）、编辑复用同一页面，单窗口内完成 Provider 选择、模型映射（支持从 LiteLLM 价格表 / Upstream 一键拉取并按勾选替换）、Credential 绑定与高级选项（阶梯价格、order/weight、自定义 JSON），无需多步向导。
• 合一式路由组表单：创建、查看、编辑同样复用单页；组名 / 路由策略 / 成员模型实时筛选勾选，支持一键清理失效成员。
• 脚本驱动的元数据管理：
  • 一窗构建预览：单个界面内完成构建，大文本框预览生成的 JSON、小文本框展示构建日志，底部实时给出「新增 / 修改 / 移除 / 共计」与 Proxy 的对比概览，并一键导出；开启 model_metadata.auto_push 后导出成功即自动把价格数据推送到 Proxy。
  • 优先级合并：支持多个 Python 脚本共同生成 model_prices_and_context_window.json，通过优先级（Priority）实现多源配置覆盖；脚本管理为「一窗设置」：单击脚本行弹出表单统一维护名称、描述、优先级、启用开关与脚本内容，支持搜索、排序与新建。
  • 可视化编辑：default.py 完整可视化编辑器，单窗口内配置价格、上下文、Mode、特性开关、阶梯定价与自定义字段，支持新增/编辑复用同一表单。
• CI/CD 非交互导出：通过 litellmctl metadata-gen 子命令直接生成定价 JSON，便于集成自动化流程。

安装

pip install litellm-controller

安装后即可通过 litellmctl 命令启动 TUI。

快捷键与操作

与 aliyunctl / clashctl 共享同一套界面规范（见 AGENTS.md 第一部分）。

快速开始

1. 初始化配置

首次启动时，向导会自动引导配置 LiteLLM Proxy 的 Endpoint、Master Key 以及可选的 Upstream。

2. 交互式使用

litellmctl              # 使用默认配置 ~/.config/litellm-controller
litellmctl -D /path/dir # 指定配置文件目录

3. 非交互式构建（CLI 模式）

若只想在脚本中静默更新定价文件：

litellmctl metadata-gen [output_directory]

若在导出后自动把价格数据推送到 Proxy（UI 导出与本子命令共用同一开关），在 config.yaml 中开启：

model_metadata:
  auto_push: true

推送按 deployment 匹配构建结果（litellm_params.model → litellm_model → 公开名），仅提交有差异的数值字段（价格 / tier / max_tokens 等，经 PATCH /model/{id}/update 写入 model_info，即时生效、无需重启）。注意 Proxy 无整体上传 cost map 的 API；个别高级字段在部分版本会被静默丢弃（不影响其他字段生效），config.yaml 定义的模型不可编辑会记为失败项。

元数据脚本规范

每个脚本位于 $CONFIG_DIR/model_metadata/ 下，需包含以下头部配置：

# --- LITELLMCTL CONFIG ---
NAME = "我的自定义配置"
DESCRIPTION = "描述文本"
PRIORITY = 50
ENABLED = True
# -------------------------

脚本需将模型字典以 JSON 格式打印至 stdout，日志信息打印至 stderr。

Key 前缀归一

脚本输出的模型 key 应遵循 provider/model_id 格式（如 openrouter/deepseek/deepseek-chat）。若 key 缺少 provider 前缀但条目包含 litellm_provider 字段，构建引擎会自动补全前缀后再合并，确保不会因前缀缺失产生重复条目：

开发

本项目遵循 Python 3.10+ 规范。

git clone https://github.com/Moha-Master/LiteLLM-Controller.git
cd LiteLLM-Controller
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pytest

许可证

MIT