在本地大模型应用中，Ollama 解决了模型下载、运行与推理服务问题，但当业务需要同时使用不同模型、切换多台推理节点，甚至在本地模型不可用时自动转向备用服务，仅靠应用代码逐一适配会迅速变得复杂。LiteLLM 可以作为统一 API 网关，将 Ollama 及其他模型服务映射为一致的 OpenAI 风格接口，并在网关层集中处理路由、重试、超时和故障回退。🚀
一、为什么在 Ollama 前增加 LiteLLM
Ollama 本身已经提供部分 OpenAI API 兼容能力，例如通过 /v1/chat/completions 接收聊天请求，具体支持范围可查看 Ollama OpenAI 兼容文档。不过，直接连接单个 Ollama 实例时，调用方仍需要关心模型名称、服务地址和节点状态。
LiteLLM 位于应用与模型服务之间，对外暴露统一入口，对内维护模型别名与实际部署的对应关系。应用只调用“local-chat”之类的逻辑名称，网关再决定请求应该进入哪台 Ollama、哪个本地模型或备用模型。这样可以减少客户端配置分散、模型更换引发代码修改等问题。
- 统一协议：让支持 OpenAI SDK 的应用通过同一种请求格式访问模型。
- 模型解耦：业务使用稳定别名，不直接依赖具体 Ollama 模型标签。
- 集中治理：统一设置超时、重试、日志、鉴权和调用限制。
- 提升可用性：主模型失败后，自动尝试备用模型或备用节点。
二、准备 Ollama 推理服务
首先确保 Ollama 已启动，并提前拉取计划使用的主模型和备用模型。模型选择应结合机器内存、显存、上下文长度和实际任务测试结果，不宜仅凭参数规模判断。可以先访问 Ollama 的模型列表或聊天接口，排除模型未下载、内存不足以及端口不可达等基础问题。
ollama pull qwen3:8b
ollama pull qwen3:4b
curl 来源链接
默认情况下，Ollama 常监听本机的 11434 端口。如果 LiteLLM 与 Ollama 位于不同容器或不同主机，配置中的地址不能继续使用 127.0.0.1，而应改为容器服务名、宿主机地址或内网地址。同时建议通过防火墙或反向代理限制访问范围，不要把未鉴权的推理端口直接暴露到公网。🔐
三、配置 LiteLLM 统一模型入口
安装带代理能力的 LiteLLM 后，新建 config.yaml。LiteLLM 官方建议使用 ollama_chat/模型名 调用 Ollama 聊天模型，并通过 api_base 指定 Ollama 服务地址，相关参数可参考 LiteLLM Ollama 接入文档。
model_list:
- model_name: local-chat
litellm_params:
model: ollama_chat/qwen3:8b
api_base: 来源链接
- model_name: local-chat-backup
litellm_params:
model: ollama_chat/qwen3:4b
api_base: 来源链接
这里的 model_name 是客户端看到的逻辑名称，而 litellm_params 下的 model 才是实际调用目标。配置完成后，可以启动代理：
litellm --config config.yaml --port 4000
应用随后只需把 OpenAI SDK 的 base_url 改为 LiteLLM 网关地址，并使用 local-chat 作为模型名称。由此形成“应用—LiteLLM—Ollama”的调用链，后续替换底层模型时通常不需要修改业务逻辑。
四、设置自动故障回退
在 config.yaml 中增加 router_settings，并将主模型映射到备用模型组。LiteLLM Router 支持重试、冷却、超时与 fallback；当主模型在指定重试后仍然失败，才会进入备用模型，机制说明可参阅 路由与故障回退文档。
router_settings:
num_retries: 1
timeout: 60
cooldown_time: 30
fallbacks:
- local-chat:
- local-chat-backup
这段配置表达的策略是：local-chat 调用失败后先进行有限重试，如果仍无法完成，再转向 local-chat-backup。不要盲目增加重试次数，因为模型加载失败、节点离线或资源耗尽时，重复请求可能只会延长用户等待时间。对于交互式聊天，应设置明确的整体超时，并让上游应用对最终失败提供友好提示。
多节点负载均衡的配置思路
如果有两台运行相同模型的 Ollama 主机，可以为它们配置相同的 model_name，并分别填写 api_base。LiteLLM 会把它们视为同一逻辑模型下的多个 deployment，根据路由策略选择可用节点。备用模型则使用另一个 model_name，通过 fallbacks 建立模型组之间的降级关系。
需要注意，同名 deployment 切换通常用于节点级容错，而fallback 模型组用于模型级降级。两者结合后，可以先在同规格节点之间尝试，再降级到资源需求较低的模型，从而避免把所有异常都直接转移给能力差异较大的备用模型。
五、调用验证与故障演练
配置上线前，应先验证统一接口是否能够正常返回结果：
curl 来源链接 \
-H "Content-Type: application/json" \
-d '{"model":"local-chat","messages":[{"role":"user","content":"请用一句话介绍统一模型网关"}]}'
正常调用通过后，可以临时停止主 Ollama 节点，或把测试环境中的主节点地址改为不可达地址，再观察请求是否经过重试并落到备用模型。验证时应记录最终模型、响应耗时、错误类型和回退次数，避免出现“接口返回成功，但实际上始终在使用备用模型”的隐性故障。🧪
- 验证主模型正常时不会错误触发回退。
- 验证主节点停止后备用模型能够接管请求。
- 验证主节点恢复后能够重新参与服务。
- 测试流式输出、长上下文和并发请求是否符合预期。
- 检查客户端超时是否短于网关完整回退流程。
六、生产环境中的实用建议
网关应设置访问密钥，并把上游模型凭据放入环境变量或密钥管理系统，避免直接写入配置仓库。还应对 LiteLLM 与 Ollama 分别监控：前者关注请求量、失败率、回退比例和延迟，后者关注模型加载、内存或显存占用、生成速度与进程状态。
主备模型的接口兼容并不代表输出能力完全一致。如果业务使用工具调用、结构化 JSON、多模态输入或特殊参数，应分别验证每个候选模型。必要时可针对上下文超限和普通服务异常设置不同回退路径，避免长文本请求被错误降级到上下文窗口更小的模型。
总结
Ollama 与 LiteLLM 的组合，把本地推理能力与统一网关治理连接起来：Ollama 负责运行模型，LiteLLM 负责稳定接口、部署映射、路由重试和故障回退。实践中的关键不是简单“加一个代理”，而是清晰区分节点容错与模型降级，合理设置超时和重试，并通过主动故障演练确认回退链路真实有效。完成这些工作后，业务应用便能在不频繁修改调用代码的前提下，更灵活地使用本地多模型服务。✅
