wandb/openui · 上手攻略

• 仓库：wandb/openui
• 链接：https://github.com/wandb/openui
• 分类：ai（LLM 驱动的 UI 生成/原型工具）
• 作者：spark
• 更新：2026-07-14

是什么

OpenUI 是 Weights & Biases（W&B）开源的一款"用自然语言描述 UI，立刻看到渲染结果"的工具。你可以输入"一个带搜索框的暗色 dashboard，顶部有用户头像"，它会输出实时预览的 HTML/Svelte/React/Web Components；你可以继续用对话让它改样式、加组件、把生成的代码一键转成 React 等多端实现。官方自述是「像 v0，但开源、不那么精致」。

它本质是一个 Web 应用（FastAPI 后端 + 前端），后端通过 LiteLLM 统一对接 OpenAI / Anthropic / Groq / Gemini / Mistral / Cohere / Ollama 等多种模型，前端用对话 + 实时预览的形式把 LLM 的输出渲染出来。除了 UI 生成，它也能用作 W&B 自家下一代 LLM 应用工具链的试验场。

解决什么问题

• 设计稿到代码太慢：产品/前端在写第一版页面时大量时间花在排版、调样式，OpenUI 让你先描述意图、看到效果，再决定要不要真写。
• 跨框架迁移 HTML 资产：存量 HTML 页面可以用对话让它转成 React / Svelte / Web Components，避免重写。
• 多模型 A/B 同一段 prompt：因为 LiteLLM 在底层，前端里点几下就能在 GPT-4o、Claude、Gemini、Llava 之间切换，直观看哪个模型更擅长生成 UI。
• 本地/隐私场景跑视觉模型：通过 Ollama 后端跑本地 Llava 等视觉模型，能离线完成"截图→描述→HTML"这种往返。

快速安装

方式一：Docker 一行跑（最省事）

# 任选一种 API key，导出到 shell
export OPENAI_API_KEY=sk-xxx      # 或 ANTHROPIC_API_KEY / GROQ_API_KEY 等
docker run --rm --name openui -p 7878:7878 \
  -e OPENAI_API_KEY \
  ghcr.io/wandb/openui
# 浏览器打开 http://localhost:7878

要接本地 Ollama 时，把宿主机的 11434 端口转发进去：

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

方式二：从源码运行（推荐改前端/后端时用）

需要 git 和 uv：

git clone https://github.com/wandb/openui
cd openui/backend
uv sync --frozen --extra litellm
source .venv/bin/activate

export OPENAI_API_KEY=sk-xxx
python -m openui

源码跑同时开前后端开发模式：

# 终端 1
cd openui/backend && source .venv/bin/activate
python -m openui --dev

# 终端 2
cd openui/frontend
npm run dev          # 5173 端口

访问 http://localhost:5173 即可，改前端/后端代码会自动热重载。

方式三：GitHub Codespaces

仓库自带 .devcontainer，在 GitHub 上点 Code → Codespaces → "New with options"，选 US West 启动最快。把 OPENAI_API_KEY 配成 Codespace secret 即可，Codespace 启动时还会自动装 Ollama 并拉取 llava 视觉模型，可以纯本地玩。

方式四：Gitpod

直接点 https://gitpod.io/#https://github.com/wandb/openui 会自动部署。需要在 Gitpod 用户变量里把 OPENAI_API_KEY 配到 wandb/openui 仓库作用域。

核心用法

1. 描述 → 实时预览

打开首页，输入框里直接写：

"一个 Notion 风格的文章详情页：左侧 240px 侧边栏，右侧主区域宽度 720px，标题用 32px 半粗，正文最大宽度 64ch，行高 1.7。"

OpenUI 会立刻渲染一版 HTML。点导航栏的 ⚙️ 可以切换模型（GPT-4o / Claude / Gemini / Llava 等），点导出按钮可以下载 HTML 或转成 React/Svelte/Web Components。

2. 上传截图反推

上传一张截图，让它"复刻这个页面"或者"按这个风格再生成一个 hero section"。要本地跑视觉模型，先装 Ollama：

# 宿主机
ollama pull llava        # llava 是少数支持图像输入的 Ollama 模型之一

在 OpenUI 设置里把模型切到 Ollama 下的 llava 即可。⚠️ 官方提示：纯本地模型在没有 GPU 的机器上会很慢；Mac 用户直接原生跑 Ollama 能用上 M1/M2。

3. 对话式迭代

预览出来后不要重新写描述，直接对话：

"把主色改成 #2563eb，圆角统一 12px，按钮用大写英文。"

多次迭代会保持上下文，不会"忘了"之前的布局。

4. 转成目标框架

点导出按钮选 React/Svelte/Web Components，会拿到对应框架的代码片段，可以直接粘进项目。注意：导出的是单文件版本，不是完整工程；接入真实项目时还要自己处理依赖、路由、构建配置。

5. 自定义 LiteLLM 后端

要接一个自定义 OpenAI 兼容服务（比如 localai、自部署 vLLM）：

export OPENAI_COMPATIBLE_ENDPOINT=http://localhost:8080/v1
export OPENAI_COMPATIBLE_API_KEY=sk-local
python -m openui --litellm

或在 docker 模式挂载配置：

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

LiteLLM 配置路径优先级：当前目录 litellm-config.yaml → 容器内 /app/litellm-config.yaml → 环境变量 OPENUI_LITELLM_CONFIG。

6. compose 一键起 OpenUI + Ollama

仓库根目录有 docker-compose.yml，包含 openui 容器和 ollama 容器：

docker-compose up -d
docker exec -it openui-ollama-1 ollama pull llava
# 浏览器访问 http://localhost:7878

修改了前端或后端代码后必须 docker-compose build 才能生效。

典型适用场景

• 产品 / 前端：把"先描述 → 看一版"作为设计评审前的快速 mock 工具，10 分钟就能出 5 个不同方向。
• 跨栈迁移团队：把老 HTML 资产批量喂进去，让它转成 React/Svelte，节约重写时间。
• 模型对比：同一段 UI prompt，分别用 GPT-4o / Claude / Gemini 生成，肉眼对比哪个模型对设计指令理解更准。
• 离线/隐私场景：把 OpenUI + Ollama 跑在内网或本地机器上，UI 描述完全不出网。
• 内部工具脚手架：admin 后台、dashboard、内部 wiki 用 OpenUI 出一版再人工调整，比从空白仓库写快。

坑与注意

• 不是生产级代码生成器：v0 的"工程化"（路由、状态、SSR、构建集成）这里都没有，输出默认是单文件 HTML / 片段；粘到真实项目里大概率还要手工改依赖和结构。
• 本地 Ollama 视觉模型支持有限：目前 Ollama 里真正能处理图像输入的就 llava 一个，文字转 UI 用 llama 系列效果一般；想要好的视觉模型还是走 OpenAI/Gemini。
• Mac 之外本地很慢：没有 GPU 的 x86 机器上跑 llava 几乎是煎熬，官方明确说"this is likely going to be very slow"。
• 没有版本控制：迭代只在一个 session 上下文里，关掉页面就丢了；如果产出要复用，先用导出按钮存成文件。
• 多容器改动要 build：docker run 模式下改了代码不会自动重载，必须停掉、build 再 run；想热重载还是走源码 python -m openui --dev + npm run dev。
• API key 通过 -e 透传：docker run -e OPENAI_API_KEY（注意没有 =xxx）才能透传当前 shell 的同名环境变量；写 =xxx 就是把字面字符串当 key 了。
• Codespace 最低 16GB RAM：纯本地玩 Llava 需要这个内存量；小机器会 OOM。

与同类对比

定位差异：v0/Bolt 走的是"产出可直接跑的工程"路线；OpenUI 走的是"开源 + 多模型 + 跨框架原型"路线，工程师上手成本最低，定制空间最大，但要把产物落地到生产还得自己接。

一句话推荐结论

如果你的团队已经在用 v0，但想要一个能换模型、能本地跑、能转 React/Svelte 的开源备胎，OpenUI 是当下最合适的；否则就把"描述→预览→迭代"当成一个 10 分钟出 mock 的辅助工具，单独依赖它出生产代码还不现实。