Open WebUI接入Ollama时模型列表不显示的排查:环境变量与API地址校验

文章导读
Open WebUI接入Ollama时模型列表不显示,最常见的原因是Open WebUI无法访问到Ollama的API地址,要么是环境变量没有传对,要么是API地址本身不通。下面的步骤按检查顺序排列,建议从前置条件开始逐项确认。
📋 目录
  1. 壹 前置条件:确认Ollama本身可用
  2. 贰 环境变量与API地址配置
  3. 叁 验证API地址是否可访问
  4. 肆 确认Open WebUI侧是否已加载配置
  5. 伍 失败时的回退步骤
A A

Open WebUI接入Ollama时模型列表不显示,最常见的原因是Open WebUI无法访问到Ollama的API地址,要么是环境变量没有传对,要么是API地址本身不通。下面的步骤按检查顺序排列,建议从前置条件开始逐项确认。

前置条件:确认Ollama本身可用

先排除Ollama侧的问题。Ollama默认监听127.0.0.1:11434,如果是在本机运行,先确认服务状态和模型列表。

ollama serve  # 若未运行则启动
ollama list    # 查看本地已安装模型

若ollama list有输出,说明Ollama本身正常。若没有输出或报错,先处理Ollama再继续。对于远程主机上的Ollama,需要确认宿主机的11434端口已监听,且未被防火墙拦截。

环境变量与API地址配置

Open WebUI通过环境变量OLLAMA_BASE_URL来定位Ollama服务。若使用Docker启动,常见配置如下:

docker run -d -p 3000:8080 \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -v open-webui:/app/backend/data \
  ghcr.io/open-webui/open-webui:main

在宿主机直接运行时,通常在启动脚本或.env文件中设置:

Open WebUI接入Ollama时模型列表不显示的排查:环境变量与API地址校验
OLLAMA_BASE_URL=http://localhost:11434

需要注意:Open WebUI容器内的localhost指向容器自身,不能访问宿主机的Ollama。所以容器部署时需要使用host.docker.internal,或在Linux下使用宿主机IP。如果是Docker Compose,可参考类似形式:

services:
  open-webui:
    environment:
      - OLLAMA_BASE_URL=http://host.docker.internal:11434

还要检查Open WebUI是否真的读取了这个变量。在启动时打印环境变量容易暴露敏感信息,可用进入容器验证:

docker exec -it <容器名> printenv OLLAMA_BASE_URL

验证API地址是否可访问

无论环境变量怎么设置,最终目标是让Open WebUI能访问到Ollama的API。先用curl从Open WebUI运行环境测试连通性。如果Open WebUI在容器中,则从容器内执行;否则从本机执行。以下是从容器内测试的示例:

docker exec -it <容器名> curl http://host.docker.internal:11434/api/tags

若返回类似{"models":[...]}的JSON,说明API可访问。若连接超时或拒绝,说明地址或监听范围有问题。Ollama若要接受来自其他机器的请求,需要设置OLLAMA_HOST环境变量为0.0.0.0或具体网卡地址,并重新启动。例如宿主机启动Ollama时:

OLLAMA_HOST=0.0.0.0:11434 ollama serve

修改后,再通过Open WebUI所在环境用宿主机IP测试。

Open WebUI接入Ollama时模型列表不显示的排查:环境变量与API地址校验

确认Open WebUI侧是否已加载配置

即使环境变量在启动时已传入,也可能未生效。Open WebUI有些版本会在前端缓存配置,或者需要等待一段时间。建议先强制刷新浏览器页面,或清掉浏览器缓存后重新登录。如果还不行,可以查看Open WebUI的运行日志,里面的连接错误会有明确线索。

docker logs <容器名> `--tail` 50

日志中通常会显示请求Ollama时的URL和HTTP状态码。如果状态码为404,可能是路径错误;为连接拒绝,则是网络不通。

失败时的回退步骤

若以上检查都无异常但列表仍不显示,可尝试以下回退:

  • 将OLLAMA_BASE_URL改为http://127.0.0.1:11434再试,排除主机名解析问题。
  • 重启Open WebUI容器,确保环境变量重新加载。
  • 确认Open WebUI与Ollama在同一网络命名空间时,直接使用宿主机IP。
  • 关闭宿主机防火墙或添加放行11434端口后重试。

如果这些操作仍未生效,需结合Open WebUI版本和部署环境,检查是否还有额外的代理重写或反向代理干扰。定位时尽量把范围缩小到“API地址是否可达”和“环境变量是否传入”两个点上,通常能较快找到原因。