在 Olares 上部署 LiteLLM 统一 AI 模型网关：安装、配置与接入 Open WebUI 实战指南

• 云原生
• 后端
• 运维

LiteLLM 是一个 AI 网关，它把 OpenAI、Anthropic、Google 以及 Ollama、vLLM 等本地推理引擎的异构 API 统一收敛到一个 OpenAI 兼容接口后面，客户端只需一个 API 端点即可调用全部已配置模型。本文基于 Olares 的 LiteLLM 应用（应用版本 1.0.8），完整演示从 Market 安装 LiteLLM、配置 OpenAI 兼容的本地 Qwen 模型、用内置 Playground 验证连接、生成虚拟密钥并接入 Open WebUI，以及通过使用统计与日志监控调用链路的全过程。读完本文，你将掌握一套"模型引擎 + LiteLLM 网关 + 客户端应用"的可复用接入方案，并理解 Olares 平台层面对应用间调用的身份与网络支撑机制。

认识 LiteLLM 网关

LiteLLM 位于你的应用和模型提供商之间，充当代理层，主要承担三项职责：

• 统一接口：LiteLLM 将来自 OpenAI、Anthropic、Google 以及本地引擎（Ollama、vLLM）的不同 API 格式，规范化为单一的 OpenAI 兼容标准。客户端不必为每家提供商分别适配一套 API。
• 自动格式转换：当你使用标准参数发送请求时，LiteLLM 会把它们翻译成目标提供商期望的特定参数名称与数据结构，保证请求能正确被后端解析。
• 请求路由：根据请求中的模型名称，LiteLLM 决定将其转发到远程云提供商，还是本地模型服务器。

由于这一统一层的存在，你的客户端应用只需要一个 API 端点即可访问所有已配置的模型，并能在远程与本地提供商之间自由切换。在 Olares 上运行 LiteLLM，意味着你拥有了一个集中管理全部模型配置的枢纽：模型在 Olares 本地引擎上推理，LiteLLM 对外暴露单一端点，其他应用（如 Open WebUI）无需感知模型后端的网络细节。

版本说明：本文档对应的 Olares 连接方式基于模型控制台直连方式（对应 Olares 1.12.6 及此前版本的ai-service-connections-1.12.6.md复用内容）；Olares 1.12.7 及以后版本引入 Router 统一网关后，连接信息也可通过 Router 的连接示例 获取，两种方式在 LiteLLM 中的配置思路一致。

前置条件

开始之前，你需要具备：

• Olares 管理员权限：安装应用、查看应用入口（Entrances）等操作都需要管理员身份。

• 一个本地聊天模型，推荐使用以下组合：

  模型类型	模型	获取方式
  聊天	Qwen3.6-27B (llama.cpp)	从 Market 安装

  安装完成后，模型应用会作为独立服务运行，为后续 LiteLLM 接入提供模型名与 Base URL。如果你希望使用其他模型，也可以从 Market 安装其他预构建模型应用，或参考 使用引擎基座应用托管本地大语言模型 克隆引擎基座来部署自己的模型实例。

安装 LiteLLM

1. 打开 Olares 的Market，搜索 "LiteLLM"。

2. 点击获取，然后点击安装。

3. 出现提示时，设置两个环境变量：

   • UI_USERNAME：指定管理员账户的用户名。这是 LiteLLM 管理后台的登录用户名。
   • UI_PASSWORD：指定管理员账户的密码。建议使用强度足够的独立密码，不要与其他账户共用。

4. 点击确认并等待安装完成。

安装完成后，LiteLLM 会出现在 Olares 的 Launchpad 中。首次使用需要以安装时设置的管理员凭据登录，后续所有模型管理、密钥签发与用量查看都在这套凭据下进行。

添加 OpenAI 兼容的本地模型

要让 LiteLLM 代理本地模型，需要先拿到模型的精确连接信息，再把它注册到 LiteLLM 中。整个过程分两步。

从模型控制台获取连接信息

在 Olares 上，独立模型以独立服务的方式与客户端应用分开运行。要连接它们，客户端需要与 API 格式匹配的精确Model name和Base URL，这两个值都可以从模型的模型控制台获取。

以 Qwen3.6-27B (llama.cpp) 为例，LiteLLM 使用 OpenAI 兼容 API 格式，具体步骤如下：

1. 从 Launchpad 打开模型应用，其模型控制台（Model Console）会自动打开。
2. 等待Model显示READY、Engine显示RUNNING，确保推理引擎已就绪。
3. 在Model区域，按原样复制Model name。本示例中为unsloth/Qwen3.6-27B-GGUF:Q4_K_M。
4. 在Engine区域：
   • Connection source：选择Apps in Olares（面向 Olares 内应用的服务端调用）。
   • API format：选择OpenAI-Compatible。
   • 复制提供的Base URL，请按显示内容原样使用，不要改动路径与协议。

说明：如果模型控制台提供的是 Anthropic 兼容格式或其他格式（如 Ollama 原生格式），则对应选择相应的 API format；本文以 OpenAI-Compatible 为例，因为它是 LiteLLM 接入本地模型最常用的格式。关于 Olares 内应用请求来源与连接方式的一般性原理，可参考 如何将 AI 应用连接到 Olares 模型。

将模型添加到 LiteLLM

拿到 Model name 和 Base URL 后，在 LiteLLM 中完成注册：

1. 从 Launchpad 打开 LiteLLM，使用安装时设置的管理员凭据登录。

2. 从左侧边栏选择Models + Endpoints，然后点击Add Model标签页。

3. 配置以下设置：

   配置项	取值	说明
   Provider	OpenAI	LiteLLM 使用 OpenAI 提供方适配器对接 OpenAI 兼容端点。
   LiteLLM Model Name(s)	unsloth/Qwen3.6-27B-GGUF:Q4_K_M	输入从模型控制台复制的准确 Model name，LiteLLM 将以此作为内部路由标识。
   Public Model Name	qwen3.6-27b	容易识别的对外别名，客户端在模型列表中看到的就是这个名字。
   API Base	粘贴从模型控制台复制的 Base URL	模型后端的实际服务地址，请原样使用。
   API Key	local	本地模型通常不校验密钥，输入占位值即可；若后端有真实密钥要求，请填入对应密钥。

4. 点击页面底部的Test Connect，LiteLLM 会向模型后端发起一次连通性探测。

5. 当Connection Test Results窗口显示连接成功消息时，关闭窗口。

6. 点击Test Connect旁边的Add Model完成注册。你现在可以在All Models标签页中查看新添加的模型。

从平台实现看，LiteLLM 作为 Olares 上的共享应用，其到模型服务的调用走的是 Olares 平台的应用间网络（mesh-in）通道：平台通过shared-caller决策机制解析应用依赖并注入调用边（见 decide.go 中Decide的实现），测试用例中也以SettingSharedAppDeps: "ollama,litellm"这类共享依赖声明为例（见 decide_test.go）。这正是 Olares 内应用调用本地模型"无需真实 API 密钥"的底层原因——平台网络层已经完成调用方身份与可达性管理。

使用 Playground 测试模型

注册完成后，先在内置 Playground 中验证模型连接与响应质量，再接入其他客户端。

1. 从左侧边栏选择Playground。

2. 在聊天标签页上，配置以下设置：

   • 虚拟密钥来源（Virtual Key Source）：保持默认的当前 UI 会话（Current UI Session）。这会让测试请求直接使用当前管理会话，无需额外签发密钥。
   • 自定义代理基础地址（Custom Proxy Base URL）：留空。填写它会导致错误。
   • 端点类型（Endpoint Type）：选择与你的模型匹配的模式。对于聊天模型，选择v1/chat/completions。
   • Select Model：选择刚刚添加的模型，本示例中为qwen3.6-27b。

3. 在测试密钥（Test Key）面板中，向聊天框发送提示词以评估模型性能。例如：

   写一个关于机器人发现被遗忘图书馆的 3 段科幻故事

   你可以在这里直接查看首 token 时间（TTFT，Time to First Token）、总延迟以及输入/输出 token 数等指标，用来判断模型响应速度与上下文消耗。

4. 若要检查模型支持的功能和参数，从左侧边栏选择AI Hub，然后在模型中心（Model Hub）标签页上点击详情，即可在模型概览页面上查看模型能力与参数说明。

Playground 验证通过后，说明"模型后端 → LiteLLM"这条链路已打通，下一步就是把它开放给客户端应用。

将 LiteLLM 与 Open WebUI 一起使用

本节以 Open WebUI 为例演示接入方式。相同的方法适用于任何支持 OpenAI 兼容 API 的客户端应用，例如 LobeHub、OpenCode 等。

生成虚拟密钥

客户端不能直接使用 LiteLLM 的管理员凭据，而应使用按模型授权范围签发的虚拟密钥，实现最小权限访问：

1. 在 LiteLLM 中，从左侧边栏选择虚拟密钥（Virtual Keys），然后点击创建新密钥（Create New Key）。
2. 在密钥所有权窗口中，配置以下设置：
   • 密钥名称（Key Name）：输入一个描述性名称以便识别，例如open-webui。
   • 模型（Models）：选择此密钥允许访问的模型。建议只勾选需要开放的模型，限制密钥的调用范围。
   • 保持所有其他选项为默认值。
3. 点击创建密钥（Create Key）。
4. 在Save your Key窗口中，复制虚拟密钥并妥善保存，供后续在 Open WebUI 中使用。关闭窗口后密钥将不再完整展示。

获取 LiteLLM API Endpoint

当客户端连接 Olares 上的另一个应用时，使用的是该应用的**端点（Endpoint）**作为网络地址；如果应用暴露多个端点，应选择与客户端所需功能或协议匹配的那一个。

对于 LiteLLM：

1. 前往 OlaresSettings>Applications>LiteLLM>Entrances。
2. 选择LiteLLM API，然后复制EndpointURL。

这个 Endpoint 就是 Open WebUI 所需的API Base URL。

将 Open WebUI 连接到 LiteLLM

1. 启动 Open WebUI，点击左下角的用户头像，然后选择管理面板（Admin Panel）。
2. 点击设置（Settings）标签页，然后点击连接（Connections）。
3. 在OpenAI API下，点击添加按钮新增一条连接。
4. 在添加连接窗口中，配置以下设置：
   • 连接类型（Connection Type）：点击外部（External）将其切换为本地（Local）。本地连接表明请求来自 Olares 内部网络，无需外部鉴权流程。
   • API 基础地址（API Base URL）：输入之前记下的 LiteLLM API Endpoint URL。
   • API 密钥（API Key）：输入之前复制的虚拟密钥。
5. 点击刷新/验证按钮验证连接。
6. 当看到 "Server connection verified" 消息时，点击保存。
7. 在连接（Connections）下，选择模型（Models）确认 LiteLLM 中配置的模型现在可用，并显示你之前设置的公共模型名称（本示例为qwen3.6-27b）。

聊天并监控使用情况

1. 在 Open WebUI 中开始新聊天，选择你的 LiteLLM 管理模型，验证它在对话中正确响应。此时链路为：Open WebUI → LiteLLM 网关 → Qwen3.6-27B 本地引擎。
2. 返回 LiteLLM 监控你的使用数据：
   • 要查看图形化使用统计，从左侧边栏选择使用（Usage）。这里按时间维度展示请求量、token 消耗等统计，便于观察模型负载与配额。
   • 要查看详细的 API 请求记录，从左侧边栏选择日志（Logs）。每条请求的模型、耗时、状态码与 token 明细都可以在此追溯，用于排查连接问题与性能瓶颈。

理解虚拟密钥与平台访问控制

细心的读者会发现整套链路中有两套凭据，它们职责不同：

• 管理员凭据（UI_USERNAME / UI_PASSWORD）：用于登录 LiteLLM 管理界面，负责模型配置、密钥签发与用量查看，只在安装时设置一次。
• 虚拟密钥（Virtual Key）：签发给客户端应用，用于调用 LiteLLM 暴露的 API。密钥可以按模型范围授权，最小化每个客户端的访问面。

在 Olares 平台上，这套身份体系还有更底层的支撑：来自 Olares 内应用的请求会由平台网络层管理。源码测试中可以看到，LiteLLM 应用（AppID6aead52a）在开启共享调用者决策（settingSharedCallerDecide: "true"）时，平台会为其创建应用级 JWT 密钥用于内部调用鉴权（见 issuer_test.go）；同时网关通过共享主机与 TLS 入口管理来维护应用间网络的加密通道（相关实现见 mesh_in_shared_hosts_test.go 与 entrance_tls_test.go）。这正是文档中本地模型 API Key 可以填写local占位值、Olares 内应用间调用无需外部 API 密钥的原因——平台身份层已经完成了调用方的识别与鉴权，LiteLLM 的虚拟密钥则进一步为跨应用调用提供模型级授权。

了解更多

• 使用引擎基座应用托管本地大语言模型：了解 Ollama、vLLM、llama.cpp、SGLang 四种引擎基座，自行部署模型实例。
• 使用 Open WebUI 与本地 LLM 聊天：从零开始安装并配置 Open WebUI。
• 使用 Olares Router 作为你的 AI 网关：了解 Olares 1.12.7+ 内置的 Router 统一网关与模型命名规范。
• 如何将 AI 应用连接到 Olares 模型：理解客户端应用、Router 与模型服务三者之间的关系及连接参数含义。

• 云原生
• 后端
• 运维