OpenUI：用自然语言描述就能生成可预览 UI 的开源 v0 平替｜部署与使用全指南

适用读者：想自己跑一个"说一句话就出界面"工具的前端/全栈开发者、想在公司内网用开源版 v0 原型工具的团队、希望同时接 OpenAI/Claude/Gemini/Groq/本地 Ollama 的玩家。本文所有命令、端口、环境变量均来自官方 README，可直接照做；版本类信息以官方仓库最新说明为准。

一、项目简介

OpenUI 是 Weights & Biases（W&B）开源的一个本地 Web 应用：你用自然语言描述想要的界面，它实时渲染出 HTML；可以继续用自然语言让它改样式、改布局，也可以一键把 HTML 转成 React、Svelte、Web Components 等框架代码。官方 README 自己的定位是："像 v0.dev，但开源，且没那么精致"——意思是能力方向对标 v0，但作为开源项目，打磨程度和云服务还有差距。

它的后端是 Python（FastAPI 风格的 python -m openui），前端是一个独立的 Web 工程，模型层走 LiteLLM，所以接哪家大模型都只是配环境变量的事。W&B 自己也在拿它做下一代 LLM 应用工具的内部原型，所以仓库里除了用户用的 Web 界面，还带了 dev container、Codespace、Gitpod 三套开箱配置，方便你直接把开发环境拉到云上。

核心信息一览表

适用场景

• 产品/前端快速做一个可点的原型，边说边调，省去手写 HTML 的时间；
• 把一段现成 HTML 转成 React / Svelte / Web Components，方便搬进已有工程；
• 公司内网部署，Key 不出门，不把需求草图传到第三方 SaaS；
• 配合本地 Ollama（如 Llava）跑离线/低成本方案；
• 想研究"LLM 怎么把自然语言直接编译成可渲染界面"这条链路，源码里后端是 Python、前端独立，适合当阅读材料。

能力边界

• 它生成的是单个 UI 组件/页面，不是完整全栈应用，不写后端逻辑与数据库；
• 官方 README 明确说开源版"没 v0 精致"，复杂动效与像素级还原仍需手改；
• 多模态图片输入依赖具体模型（Ollama 侧官方点名 Llava 是少数支持图片的模型之一）；
• Docker Compose 自带 Ollama 的方案官方备注"很可能很慢"，Mac 建议原生跑 Ollama 利用 M1/M2 加速；
• 选模型时如果只配了一家 Key，模型选择器里就只看得到那一家；想横向比模型效果就把多家 Key 一起配上。

二、功能特性

• 自然语言出 UI：描述想要什么，实时渲染 HTML 预览；官方 README 的原话是"用你的想象力描述 UI，然后看着它被实时渲染出来"；
• 多轮迭代：继续用自然语言提修改意见，例如"把按钮换成圆角""加个暗色模式开关"，模型在原页面上增量改，不是每次重画；
• 框架互转：把已经成型的 HTML 一键转成 React、Svelte、Web Components 等，方便直接搬进前端工程；
• 多模型统一接入：基于 LiteLLM，OpenAI / Groq / Gemini / Anthropic / Cohere / Mistral 全部通过环境变量切换，不用为每家模型改代码；
• OpenAI 兼容端点：通过 OPENAI_COMPATIBLE_ENDPOINT + OPENAI_COMPATIBLE_API_KEY 接 localai、vLLM、各种 OpenAI 兼容中转，在 UI 的模型选择器里会归到 LiteLLM 分组下；
• Ollama 本地模型：默认连 http://127.0.0.1:11434，可改 OLLAMA_HOST；Docker 里用 http://host.docker.internal:11434 指向宿主机；官方 README 特别提示，Ollama 侧目前支持图片输入的模型不多，Llava 是其中之一；
• 自定义 LiteLLM 配置：默认根据环境变量自动生成 LiteLLM 配置；想完全接管，就放一个自己的 litellm-config.yaml 覆盖；
• Dev Container / Codespace / Gitpod 三开箱：仓库自带 .devcontainer/devcontainer.json，GitHub Codespace 选 New with options、配好 OPENAI_API_KEY secret（或填 xxx 走 Ollama，至少要 16GB 内存）就能跑；Gitpod 也有一键按钮；
• 在线 Demo：官方挂了一个 https://openui.fly.dev 可以零部署先玩，再决定要不要自托管。

三、官方界面预览

下面这张图来自官方 README，展示在 OpenUI 设置齿轮里选择 Ollama 模型的界面。

四、官方链接汇总

五、前置要求

六、安装部署

方式 A：Docker 单容器（官方推荐）

官方 README 原文照抄：

export ANTHROPIC_API_KEY=xxx
export OPENAI_API_KEY=xxx
docker run --rm --name openui -p 7878:7878 \
  -e OPENAI_API_KEY -e ANTHROPIC_KEY \
  -e OLLAMA_HOST=http://host.docker.internal:11434 \
  ghcr.io/wandb/openui

注意：上面 -e 后面的变量名必须与你 export 的一致；本文按 README 原样写 OPENAI_API_KEY、ANTHROPIC_API_KEY，仅在示例里省写。启动后访问 http://localhost:7878 。

自定义 LiteLLM 配置的 Docker 写法：

docker run -n openui -p 7878:7878 \
  -v $(pwd)/litellm-config.yaml:/app/litellm-config.yaml \
  ghcr.io/wandb/openui

方式 B：源码直跑（Python + uv）

git clone https://github.com/wandb/openui
cd openui/backend
uv sync --frozen --extra litellm
source .venv/bin/activate
# 配任意你想用的模型 Key
export OPENAI_API_KEY=xxx
python -m openui

从源码启用 LiteLLM 模式：

pip install .[litellm]
export ANTHROPIC_API_KEY=xxx
export OPENAI_COMPATIBLE_ENDPOINT=http://localhost:8080/v1
python -m openui --litellm

方式 C：Docker Compose（自带 Ollama）

仓库根目录执行：

docker-compose up -d
docker exec -it openui-ollama-1 ollama pull llava

访问 http://localhost:7878 。官方 README 提示：如果你已经在 shell 里导出了 OPENAI_API_KEY，把 compose 文件里那行 OPENAI_API_KEY=xxx 的 =xxx 去掉即可；改了前后端代码要重新 docker-compose build。

方式 D：GitHub Codespace / Gitpod（零本机环境）

仓库自带 .devcontainer/devcontainer.json。在 GitHub 上选 Code → Codespaces → New with options，区域选 US West 启动更快；把 OPENAI_API_KEY 配成 secret（想用 Ollama 就填 xxx，内存至少 16GB）。进去后一个终端跑 python -m openui --dev，另开终端 cd /workspaces/openui/frontend && npm run dev，访问 5173 端口那个服务。Gitpod 用户也有一键按钮，但要先在 Gitpod 用户变量里把 OPENAI_API_KEY 配好、scope 设到 wandb/openui。

七、配置项说明

LiteLLM 配置文件查找顺序（官方 README）：

1. 当前目录下的 litellm-config.yaml；
2. Docker 容器内的 /app/litellm-config.yaml；
3. 环境变量 OPENUI_LITELLM_CONFIG 指向的任意路径。

源码模式下启用 LiteLLM：

pip install .[litellm]
export ANTHROPIC_API_KEY=xxx
export OPENAI_COMPATIBLE_ENDPOINT=http://localhost:8080/v1
python -m openui --litellm

Groq 是官方 README 单独点名的"超快速"通道：把 GROQ_API_KEY 配好后，在导航栏齿轮里选 Groq 模型即可，不用改代码。

八、使用流程

1. 按上面任一方式启动，确认监听 7878；
2. 浏览器打开 http://localhost:7878 ；
3. 点导航栏齿轮图标，在设置里选模型（Groq、Ollama 等都在这里选；选 Groq 前要先把 GROQ_API_KEY 传进进程）；
4. 在输入框用自然语言描述你要的界面，例如"做一个深色主题的登录卡片，带邮箱、密码和登录按钮"；
5. 右侧实时看到渲染出来的 HTML；
6. 继续用自然语言让它改："把按钮改成圆角、加个忘记密码链接""把整张卡片居中，宽度限到 400px"；
7. 满意后选择转成 React / Svelte / Web Components，把代码拷进自己的前端工程；
8. 如果是在做二次开发，走 dev 模式：后端 python -m openui --dev，另开一个终端 cd frontend && npm run dev，前端会起在 5173 端口，前后端都热更新，改完直接在浏览器里看效果。

九、常用运维 / 更新命令

# Docker 路线拉新镜像
docker pull ghcr.io/wandb/openui
# 再按上面 docker run 命令重启容器

# 源码路线更新
git pull
cd backend
uv sync --frozen --extra litellm

# Docker Compose 路线
docker-compose pull
docker-compose up -d

# 本地 Ollama 拉新模型
ollama pull <model-name>
# 拉完后在 OpenUI 设置齿轮里就能看到

小提示：OpenUI 启动后默认只监听容器内的 7878；Docker 路线一定要把 -p 7878:7878 写对，否则宿主机浏览器打不开。源码直跑 python -m openui 也是监听 7878，直接访问 http://localhost:7878 即可。改了任何环境变量都要重启进程才生效。

十、常见故障排查

十一、风险与责任使用声明

1. 本文所有命令、端口（7878 / 5173 / 11434）、环境变量名均来自官方 README，不构成第三方担保；镜像 tag、依赖版本以 ghcr.io/wandb/openui 与仓库最新说明为准；
2. 调用 OpenAI / Anthropic / Gemini / Groq / Cohere / Mistral 都会产生真实 API 账单，请在各平台控制台设置额度；Key 通过 -e 或 export 传入，不要写进镜像或公开仓库；
3. 生成的 UI 代码可能引用外网 CDN、含未转义内容或不安全的事件绑定，上线前必须自行审计；
4. 本工具用于生成你自己的产品界面；不要用它复刻受版权保护的商业产品 UI、品牌组件或未经授权的设计稿；
5. 开源版按其仓库许可证发布，与官方在线 Demo https://openui.fly.dev 是同一代码的不同部署形态；
6. 用 Ollama 跑本地模型时，记得 ollama pull 下来的模型会占磁盘空间；官方 README 点名 llava 是少数支持图片输入的 Ollama 模型，纯文本模型只能做纯文本到 UI 的生成。