Ubuntu MATE 24.04 + systemd 部署 LiteLLM + Open WebUI

Delta-delta2026-09-17 9:57

目录

  • [§1 系统准备](#§1 系统准备)
  • [§2 部署 LiteLLM + Open WebUI](#§2 部署 LiteLLM + Open WebUI)
  • [§3 接 MiniMax-M3 API](#§3 接 MiniMax-M3 API)
  • [§4 后续添加更多模型](#§4 后续添加更多模型)
  • [附录 排障速查](#附录 排障速查)

§1 系统准备

项 值
OS Ubuntu MATE 24.04
Python 3.12
服务端口 LiteLLM 4000 / Open WebUI 8080
用户 普通用户（非 root）
bash 复制代码 
sudo apt update
sudo apt install -y python3-venv

Python 的 pip 由 venv 自带，不需要额外装。

§2 部署

2.1 工作目录 + 双 .env

LiteLLM 的 .env 持有上游真 Key；Open WebUI 的 .env 持有给 LiteLLM master key 校验用的 dummy。两份隔离防止密钥混用。

bash 复制代码 
mkdir -p ~/ai-workspace && cd ~/ai-workspace

# LiteLLM 拿上游真 Key
cat > .litellm.env <<EOF
MINIMAX_API_KEY=eyJ你的MiniMax控制台Key
LITELLM_MASTER_KEY=sk-litellm-dummy-key
EOF
chmod 600 .litellm.env

# Open WebUI 拿 dummy（OPENAI_API_* 是 Open WebUI 内部约定的变量名，不能改）
WEBUI_SECRET=$(python3 -c 'import secrets; print(secrets.token_hex(32))')
cat > .webui.env <<EOF
OPENAI_API_BASE_URL=http://127.0.0.1:4000/v1
OPENAI_API_KEY=sk-litellm-dummy-key
WEBUI_SECRET_KEY=${WEBUI_SECRET}
EOF
chmod 600 .webui.env

这两个 Key 分别是：

变量 用途 用在哪儿 泄漏后果
MINIMAX_API_KEY=eyJ... MiniMax 账户的 API Key，控制台申请 LiteLLM 把请求转给 MiniMax 时带这个 MiniMax 账户被盗用产生 API 费用
LITELLM_MASTER_KEY=sk-litellm-dummy-key LiteLLM proxy 的入站校验密钥 客户端（Open WebUI / curl / SDK）调 LiteLLM 时必须带 Authorization: Bearer <master_key>，否则 401 别人能调你的 LiteLLM proxy，但拿不到 MiniMax 账户权限（看不到 MINIMAX_API_KEY）

为什么 master_key 是个固定 dummy 值而不是随机？ LiteLLM 1.51+ 默认每次启动会自动生成随机 master key 并打到日志。如果不显式锁成固定值，每次 sudo systemctl restart litellm 后 Open WebUI 缓存的旧 token 全部失效，需要重新登录一次。sk-litellm-dummy-key 是 LiteLLM 团队在 dev 文档里也用的示例值，公开但固定、可控。

部署前自检占位符是否已替换：

.litellm.env 写完后，跑下面这条命令确认 eyJ你的MiniMax控制台Key 这段占位符确实被替换了：

bash 复制代码 
grep '你的MiniMax' ~/ai-workspace/.litellm.env && echo "占位符没替换！" || echo "OK"

期望输出 OK（grep 没匹配就 OK）。任何残留占位符都会让 LiteLLM 启动后第一笔 请求 401，并且错误信息只会说 Invalid API Key，排障时不容易想到是占位符没换。

MINIMAX_API_KEY 怎么填：

  • 整段（包括 eyJ）替换成你 MiniMax 控制台的真实 key。真实 key 大概长这样：

    复制代码 
    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.abc...

  • 如果只替换后半段（比如只替换 你的MiniMax控制台Key 留 eyJ 不动），LiteLLM 不会报错，但 MiniMax 会返回 key 格式错误。

  • LITELLM_MASTER_KEY 不要改 ------和 .webui.env 里 OPENAI_API_KEY=sk-litellm-dummy-key 故意保持一致。

2.2 双 venv 安装

bash 复制代码 
cd ~/ai-workspace

# LiteLLM
python3 -m venv litellm_env
source litellm_env/bin/activate
pip install --upgrade pip 'litellm[proxy]>=1.80.15'
deactivate

# Open WebUI
python3 -m venv openwebui_env
source openwebui_env/bin/activate
pip install --upgrade pip 'open-webui>=0.6.30'
deactivate

为什么加版本约束：

  • LiteLLM 的 minimax/ provider 官方 Supported Models 当前不含 MiniMax-M3（只到 M2.1 / M2.1-lightning / M2）。所以主配置走 openai/ 前缀 + api_base，不依赖 minimax provider 收录 ------>=1.80.15 的下限只是因为该版本开始 LiteLLM 普遍稳定可用，未来升级只是拿到 patch。
  • Open WebUI >=0.6.30 因为 open-webui serve 子命令和"添加供应商"功能在更早的 0.4 / 0.5 系列里行为不同。
  • 用 >= 而不是 == 是允许 minor 升级（用 stability 换一致性）。要严格锁版本（如生产环境可重复构建），把 >= 改成 ==。

2.3 LiteLLM 配置

~/ai-workspace/config.yaml：

yaml 复制代码 
model_list:
  - model_name: MiniMax-M3
    litellm_params:
      model: openai/MiniMax-M3
      api_base: https://api.minimax.cn/v1
      api_key: os.environ/MINIMAX_API_KEY

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

litellm_settings:
  drop_params: true

字段详解：

字段 类型 含义
model_list array 客户端可见的模型定义列表，每项是一个模型。LiteLLM 用它对外暴露"我支持哪些模型"
model_list[].model_name string LiteLLM 暴露给客户端的名字。Open WebUI 下拉菜单看到的就是它
model_list[].litellm_params object 上游真实调用参数。名字带 litellm_ 前缀，意思是"这一层是给 LiteLLM 自己看的"
litellm_params.model string 上游真实模型 ID，格式 <provider>/<model>。本配置用 openai/MiniMax-M3 前缀------OpenAI 兼容协议
litellm_params.api_base string 当 model 用 openai/ 前缀时必填。LiteLLM 以 OpenAI 协议把请求发到这个 base URL
litellm_params.api_key string 鉴权 Key。os.environ/<NAME> 从进程环境读（systemd 的 EnvironmentFile= 或 shell export）
general_settings object 全局行为配置（影响整个 proxy）
general_settings.master_key string LiteLLM 主密钥。客户端调用时必须带 Authorization: Bearer <master_key>，否则 401。必须设成固定值，否则 LiteLLM 每次重启自动生成新的，Open WebUI 缓存的旧 token 全失效
litellm_settings object LiteLLM 内部行为参数
litellm_settings.drop_params bool 自动剥离上游不支持的参数（如 temperature=2.5 超过 MiniMax 接受范围）。true 推荐；false 严格，遇到不识别的参数直接 400

两个细节：

  1. <provider>/<model> 命名约定 ：前缀决定 LiteLLM 用哪种协议打上游。常见的有 openai/（OpenAI 兼容协议）、anthropic/（Anthropic 协议）、minimax/（LiteLLM 内置 minimax provider）、bedrock/、azure/、vertex_ai/、ollama_chat/、hosted_vllm/ 等。前缀错了 LiteLLM 不会报错，但会用错协议发请求------比如用 openai/ 配 api.minimax.cn/anthropic 路径，会用 OpenAI 协议打 Anthropic 接口，上游直接返回协议错误。

    本配置为什么用 openai/MiniMax-M3 而不是 minimax/MiniMax-M3？ LiteLLM 官方 minimax provider 的 Supported Models 当前只到 M2.1 / M2.1-lightning / M2，不含 M3 。所以必须用 openai/ 前缀 + api_base 把请求按 OpenAI 兼容协议打给 https://api.minimax.cn/v1，这部分 MiniMax 公开支持。

    代价：失去 LiteLLM minimax provider 可能存在的 MiniMax 特定适配（具体做了什么 LiteLLM 文档没公开列，无法对比）。在我们这个 Open WebUI → LiteLLM → MiniMax 的链路里，两种写法网络行为等价 ------客户端发 OpenAI 协议，LiteLLM 转发 OpenAI 协议给 MiniMax 的 /v1 端点，没有协议转换层介入。好处：1) 不依赖 LiteLLM 对 MiniMax-M3 模型 ID 的收录；2) 跨 LiteLLM 版本都 work；3) 假如 LiteLLM minimax provider 后续有 bug 或行为变更，影响不到你。

  2. api_key 三种写法：

    • os.environ/MINIMAX_API_KEY ------ 从环境变量读（推荐）
    • 明文 eyJxxx / sk-xxx ------ 直接写在 yaml 里，不推荐（密钥进文件，git 历史 / 备份都会泄漏）
    • 不支持 ${MINIMAX_API_KEY} 这种 shell 变量插值（LiteLLM 不解析 shell 语法）

model_name 是客户端（下拉菜单）看到的名字；litellm_params.model 是上游真实模型 ID。两者都可以是 MiniMax-M3，不冲突。

2.4 systemd 双服务

把下面两段里的 yourname 替换为你机器上的 Ubuntu 用户名。

/etc/systemd/system/litellm.service：

ini 复制代码 
[Unit]
Description=LiteLLM Proxy
After=network-online.target

[Service]
Type=simple
User=yourname
WorkingDirectory=/home/yourname/ai-workspace
EnvironmentFile=/home/yourname/ai-workspace/.litellm.env
ExecStart=/home/yourname/ai-workspace/litellm_env/bin/litellm \
    --config /home/yourname/ai-workspace/config.yaml \
    --host 127.0.0.1 --port 4000
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target

/etc/systemd/system/open-webui.service：

ini 复制代码 
[Unit]
Description=Open WebUI
After=network-online.target litellm.service
Requires=litellm.service

[Service]
Type=simple
User=yourname
WorkingDirectory=/home/yourname/ai-workspace
EnvironmentFile=/home/yourname/ai-workspace/.webui.env
ExecStart=/home/yourname/ai-workspace/openwebui_env/bin/open-webui serve \
    --host 127.0.0.1 --port 8080
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target

启用：

bash 复制代码 
sudo systemctl daemon-reload
sudo systemctl enable --now litellm open-webui
sudo systemctl status litellm open-webui --no-pager

期望两个服务都是 active (running)。

端口冲突时（如 ROS/Isaac Sim 占了 8080），同时改 systemd 里的 --port 和 .webui.env 里的 OPENAI_API_BASE_URL。

§3 接 MiniMax-M3 API

3.1 MiniMax API 速识

项 值
Base URL（OpenAI 兼容） https://api.minimax.cn/v1
Base URL（Anthropic 兼容，官方推荐） https://api.minimax.cn/anthropic
模型名 MiniMax-M3
鉴权 header Authorization: Bearer <MINIMAX_API_KEY>
Key 格式 eyJ... 开头 JWT（控制台申请）

本文档为什么选 OpenAI 兼容端点而不是 MiniMax 官方推荐的 Anthropic 端点？ 因为 LiteLLM 的 openai/ 前缀可以零配置对接 OpenAI 兼容端点（配 api_base 即可），无需走 minimax/ provider 或 Anthropic SDK 路径。Anthropic 端点的优势（Interleaved Thinking / Computer Use / Prompt Caching 等高级能力）主要给直接用 Anthropic SDK 的客户端------比如 Claude Code、Cursor 等。LiteLLM 场景下这些高级能力通过代理链会有损耗，所以本教程统一用 OpenAI 兼容端点保持最简。如果你要用 Claude Code 直连 MiniMax 不走 LiteLLM，那 Anthropic 端点确实更合适。

3.2 直接调（不走 LiteLLM）

bash 复制代码 
curl -sS https://api.minimax.cn/v1/chat/completions \
  -H "Authorization: Bearer ${MINIMAX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-M3",
    "messages": [{"role":"user","content":"你好"}]
  }'

OpenAI SDK：

python 复制代码 
from openai import OpenAI

client = OpenAI(
    base_url="https://api.minimax.cn/v1",
    api_key="<MINIMAX_API_KEY>",
)

resp = client.chat.completions.create(
    model="MiniMax-M3",
    messages=[{"role":"user","content":"你好"}],
)
print(resp.choices[0].message.content)

Anthropic SDK：

python 复制代码 
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.minimax.cn/anthropic",
    api_key="<MINIMAX_API_KEY>",
)

resp = client.messages.create(
    model="MiniMax-M3",
    max_tokens=1024,
    messages=[{"role":"user","content":"你好"}],
)
print(resp.content[0].text)

3.3 通过 LiteLLM 调

验证 LiteLLM 已加载模型：

bash 复制代码 
curl -sS http://127.0.0.1:4000/v1/models \
  -H "Authorization: Bearer sk-litellm-dummy-key" | jq '.data[].id'

应看到 MiniMax-M3。

浏览器访问 http://127.0.0.1:8080，首次注册管理员账号，下拉选 MiniMax-M3 即可对话。

程序化调用（任一 OpenAI 兼容客户端）：

python 复制代码 
from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:4000/v1",   # 打 LiteLLM，不是 MiniMax
    api_key="sk-litellm-dummy-key",         # LiteLLM master key，不是 MiniMax
)

resp = client.chat.completions.create(
    model="MiniMax-M3",                     # config.yaml 里定义的 model_name
    messages=[{"role":"user","content":"你好"}],
)
print(resp.choices[0].message.content)

3.4 Open WebUI 基本使用

首次访问： 浏览器打开 http://127.0.0.1:8080，注册管理员账号（数据存本地 SQLite）。

发起对话：

  1. 左上角模型下拉菜单 → 选 MiniMax-M3
  2. 输入框打字 → 回车发送

左侧栏主要入口：

项 用途
New Chat 开始新会话
Workspaces 工作区 / 团队共享
Documents 上传文档做 RAG（检索增强）
Models 增删/管理模型（你应该会在 "External" 区看到 MiniMax-M3）
Settings 个人偏好、默认模型、主题、API Keys

几个常用快捷键：

快捷键 功能
Enter 发送消息
Shift + Enter 换行（不发送）
/ 弹出命令面板（可切换模型、清空等）

数据存储： Open WebUI 的 SQLite 在 ~/.open-webui/data/webui.db，含账号 / 聊天历史 / 文档索引。备份这个文件即可。

§4 后续添加更多模型

所有模型定义都在 ~/ai-workspace/config.yaml 的 model_list 数组里。LiteLLM 不监听配置文件变化------改完必须重启才生效：

bash 复制代码 
sudo systemctl restart litellm

然后浏览器 Ctrl+Shift+R 强刷，下拉菜单出现新模型。

4.1 加 OpenAI gpt-4o-mini

config.yaml 在 model_list 数组末尾加：

yaml 复制代码 
  - model_name: gpt-4o-mini                    # Open WebUI 下拉菜单显示名
    litellm_params:
      model: openai/gpt-4o-mini                # 上游真实模型 ID
      api_key: os.environ/OPENAI_API_KEY       # 从 .litellm.env 读

.litellm.env 加：

复制代码 
OPENAI_API_KEY=sk-你的OpenAI_Key

4.2 加 MiniMax 另一个模型

yaml 复制代码 
  - model_name: MiniMax-另一个                # Open WebUI 下拉名
    litellm_params:
      model: openai/<控制台代号>               # 与 §2.3 同模式：openai/ + api_base
      api_base: https://api.minimax.cn/v1
      api_key: os.environ/MINIMAX_API_KEY

具体模型代号以 MiniMax 控制台 https://api.minimax.cn/v1/models 实测列表为准，不要用未核实的代号。

4.3 删模型

从 model_list 数组里删那条，restart 即可。下次启动 LiteLLM 不再认识这个 model_name，Open WebUI 下拉自动消失。

4.4 重启验证

bash 复制代码 
sudo systemctl restart litellm
curl -sS http://127.0.0.1:4000/v1/models \
  -H "Authorization: Bearer sk-litellm-dummy-key" | jq '.data[].id'

期望在返回的 data[] 数组里同时看到旧模型 + 新加的模型。

附录 排障速查

症状 处理
curl /v1/models 返回 401 .webui.env 与 .litellm.env 里 dummy key 不一致
Open WebUI 下拉没有 MiniMax-M3 systemctl restart litellm 后浏览器 Ctrl+Shift+R 强刷
首次调用 MiniMax-M3 报 404 / BadRequest（LiteLLM 启动时不会自动验证模型，要到第一笔请求才会暴露配置错误） 确认 api_base: https://api.minimax.cn/v1 拼写正确（/v1 结尾），以及 MINIMAX_API_KEY 已替换占位符
直连 MiniMax API 测试 401 控制台核对 Key 是否启用 MiniMax-M3 权限；重新生成 Key
端口 4000 / 8080 被占 改 systemd 里的 --port，同步改 .webui.env 的 OPENAI_API_BASE_URL
MiniMax API 返回 401/403 控制台核对 Key 是否启用 MiniMax-M3 权限
两次 source 同一个 shell 里的两份 .env，同名变量被覆盖 用两个独立终端分别跑 LiteLLM 和 Open WebUI，不要共用 shell
相关推荐
金融大 k1 小时前
A股实时行情 API 接入指南：Python 覆盖行情、复权、基本面与 WebSocket
python·websocket·行情数据·行情 api
生信大杂烩1 小时前
Xenium H&E空间原位可视化——细胞轮廓、基因表达与转录本可视化
python·算法·数据分析
东莞市云毅网络有限公司1 小时前
用标准库做网页正文抽取：从 HTML 到结构化字段的轻量实现
python·sqlite·自动化运维·geo·数据监测
高级程序源1 小时前
django校企合作实习基地管理系统82506-计算机课程设计、毕业设计
vue.js·后端·python·mysql·django·课程设计·pygame
东方芷兰1 小时前
Agent 技术摘要 02 —— 区块链、比特币、挖矿、ETF、比特币疯涨事件、以太坊、以太币、显卡荒事件
人工智能·笔记·python
贝猫说python1 小时前
阿里云部署qwen 大模型从0-1，第2步：阿里云平台创建ubuntu实例
python
峥嵘life1 小时前
2026华为AI码道 CodeArts 使用分享：Windows端 + 服务器CLI 实战总结
android·大数据·开发语言·python
贝猫说python1 小时前
阿里云部署qwen 大模型从0-1，第3步：阿里云服务器上部署大模型
python
少陽君2 小时前
服务器服务检查报告
python
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02数学公理体系大全:第六章 选择公理的等价形式及证明03历年考研数学一、数学二、数学三真题试卷及答案PDF04GitHub 镜像站点05微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新06蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接07人工智能（AI）发展史：详细里程碑082026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？09ZCode 周末送额度活动开启：3 亿 Token 免费领取10【一等奖版】2026 国赛 A题 药材的烘干问题