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、特性开关、阶梯定价与自定义字段,支持新增/编辑复用同一表单。
- 一窗构建预览:单个界面内完成构建,大文本框预览生成的 JSON、小文本框展示构建日志,底部实时给出「新增 / 修改 / 移除 / 共计」与 Proxy 的对比概览,并一键导出;开启
- CI/CD 非交互导出:通过
litellmctl metadata-gen子命令直接生成定价 JSON,便于集成自动化流程。
安装
pip install litellm-controller
安装后即可通过 litellmctl 命令启动 TUI。
快捷键与操作
| 场景 | 快捷键 | 作用 |
|---|---|---|
| 全局 | Ctrl+Q |
任意界面退出程序 |
| 主菜单 | 1 / 2 / 3 / 4 |
直达模型管理 / 路由管理 / 设置 / 退出 |
Esc / Ctrl+C |
退出程序 | |
| 功能页 | Esc / Ctrl+C |
返回上一级(有未保存修改时先确认) |
Ctrl+R |
刷新当前页数据 | |
Home / End / PgUp / PgDn |
页面滚动 | |
| 列表页 | ↑ / ↓、回车 |
移动光标、执行所选行 |
| 鼠标 | 单击选中、双击执行(查看 / 编辑 / 启停);滚轮滚动 | |
/ |
聚焦搜索框(输入实时筛选;编辑态自动禁用 Ctrl+R) |
|
Ctrl+N |
新增条目(模型 / 路由组 / Upstream / 参数) | |
Ctrl+E / Ctrl+D |
设置页:编辑 / 删除 Upstream;脚本页:调优先级 | |
| 表单 / 模态 | Tab / Shift+Tab |
轮切字段 |
Enter |
提交(FormModal / InputModal;sheet 大表单用按钮提交) | |
Esc / Ctrl+C |
取消并关闭 | |
| 折叠菜单 ⋮ | 单击 菜单 ▾ / 点击外部 / Esc |
开合(低频操作:重置配置等) |
| 多选列表 | 空格 |
勾选 / 取消勾选 |
快速开始
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 字段,构建引擎会自动补全前缀后再合并,确保不会因前缀缺失产生重复条目:
| 脚本输出 | litellm_provider | 归一结果 |
|---|---|---|
~deepseek/deepseek-flash-latest |
openrouter | → openrouter/~deepseek/deepseek-flash-latest |
deepseek-chat |
deepseek | → deepseek/deepseek-chat |
openrouter/deepseek/deepseek-chat |
openrouter | 不触发(已有前缀) |
开发
本项目遵循 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
Metadata
Release files for litellm-controller 0.2.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| litellm_controller-0.2.5.tar.gz | 78.8 kB | Without provenance | Details for litellm_controller-0.2.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| litellm_controller-0.2.5-py3-none-any.whl | Python 3 | none | any | Details for litellm_controller-0.2.5-py3-none-any.whl |
Total release size: 166.3 kB
Release files / litellm_controller-0.2.5.tar.gz
| Download URL | litellm_controller-0.2.5.tar.gz |
|---|---|
| Size | 78.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f4a93739a1025e66f600e531a7bdd451ac4fbb74365c2057db3d3397e16258bb
|
|
BLAKE2b-256 checksum How to use checksums |
cb6021bd977d19d61fa8cba893141b865a672d43a163c6c7255e473ad16e9570
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Release files / litellm_controller-0.2.5-py3-none-any.whl
| Download URL | litellm_controller-0.2.5-py3-none-any.whl |
|---|---|
| Size | 87.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4db67004f2910b04f5c5c9ea011baa774a42797e4451d45762a5380e0adbc025
|
|
BLAKE2b-256 checksum How to use checksums |
7513260e73604a026e357a32e0e3ca7973f1462e3415d83b4a9e6d023bb91802
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Security for litellm-controller 0.2.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.