# TUI 指南 (/zh/docs/guides/tui)



终端界面 (TUI) 在你的终端中提供了一个基于文本的交互式面板。这是浏览模型和基准目录、检查就绪状态、生成 CLI 命令的最简单方式，无需死记硬背各种参数。

## 启动 TUI [#启动-tui]

在使用之前，请确保已安装 WorldFoundry 包。推荐使用统一环境脚本：

```bash
bash scripts/setup/unified_install.sh
source tmp/worldfoundry_unified_env.sh
conda activate "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}"
```

如果是手动管理的 conda 环境，请在代码库根目录安装包含 `[tui]` 依赖组的包：

```bash
pip install -e ".[tui]"
```

环境激活后，启动 TUI：

```bash
worldfoundry-eval tui
```

TUI 读取与 CLI 发现命令相同的 model-zoo 和 benchmark-zoo 清单。它不会绕过清单就绪检查、运行时 profile 或运行器验证。

### 启动选项 [#启动选项]

| 标志                      | 作用                                    |
| ----------------------- | ------------------------------------- |
| `--catalog-json`        | 打印 TUI 使用的 catalog payload 后退出。       |
| `--model-id openvla`    | 预选一个模型，跳过模型选择器。                       |
| `--benchmark-id libero` | 预选一个基准，跳过基准选择器。                       |
| `--print-command`       | 将生成的 `run` 命令打印到 stdout 并退出，不进入交互式会话。 |

示例——为特定模型 × 基准组合生成命令后退出：

```bash
worldfoundry-eval tui --model-id openvla --benchmark-id libero --print-command
```

这在脚本或 CI 管道中非常有用——你需要标准命令但不需要手动交互。

## 浏览与操作 [#浏览与操作]

TUI 展示三个主要面板：

1. **模型目录** — 列出所有 model-zoo 条目，包含 ID、别名、成熟度等级和运行时状态。使用方向键浏览；按 Enter 选择模型。

2. **基准目录** — 列出所有 benchmark-zoo 条目，包含 ID、任务范围、成熟度等级和数据集就绪状态。使用方向键浏览；按 Enter 选择基准。

3. **命令输出** — 底部面板根据你的选择动态生成对应的 `worldfoundry-eval run` 命令。你可以复制此命令，稍后在 GPU 节点上执行。

### 参数配置 [#参数配置]

选择模型和基准后，TUI 展示可调整的推理参数：

* **步数 / 迭代次数** — 去噪或采样步数。
* **引导系数 / cfg** — 无分类器引导 (classifier-free guidance) 强度。
* **序列长度** — 最大 token 或帧数。
* **种子** — 确定性生成种子（可选）。

这些字段映射到 `worldfoundry-eval run` 接受的相同标志。在 TUI 中更改参数会实时更新生成的命令。

### 就绪指示器 [#就绪指示器]

TUI 在目录条目旁显示就绪警告：

* **缺失 checkpoint** — 模型要求一个在声明路径中未找到的 checkpoint。
* **缺失数据集** — 基准要求一个本地未暂存的数据集。
* **缺失环境** — 运行时 profile 声明的 conda 包或 CUDA 版本未被满足。
* **License 限制** — 模型或数据集有 gated 或非商业 license，需要手动审查。

当就绪阻碍项存在时，生成的命令默认包含 `--mode official-validation`。这确保你可以验证连接（wiring），而不需要为被阻断的运行消耗 GPU 资源。

## 回退模式 [#回退模式]

如果未安装 Textual 依赖，TUI 会打印一个静态回退摘要代替交互式面板。回退摘要列出模型 ID、基准 ID 和简短的就绪说明。

要恢复完整的交互式 TUI，安装 `[tui]` 依赖组：

```bash
pip install -e ".[tui]"
```

## TUI 与 CLI 发现 [#tui-与-cli-发现]

TUI 和 CLI 发现命令读取相同的目录清单。根据你的工作流选择：

| 需求                        | 使用                                                                                                                                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 可视化浏览目录，交互式调整参数           | TUI (`worldfoundry-eval tui`)                                                                                                                                                                                 |
| 为脚本或 CI 生成单个命令            | TUI 配合 `--print-command`                                                                                                                                                                                      |
| 以 JSON 列出所有模型或基准 ID       | `worldfoundry-eval zoo models --json` 或 `zoo benchmarks --json`                                                                                                                                               |
| 检查特定模型就绪状态                | `worldfoundry-eval zoo model-download --check-local --model-id <id> --json`                                                                                                                                   |
| 检查 benchmark/runtime 就绪状态 | `worldfoundry-eval preflight runtime --profile <benchmark-id> --manifest worldfoundry/data/benchmarks/runtime_profiles/official/<benchmark-id>.yaml --output-dir tmp/preflight/runtime/<benchmark-id> --json` |
| 完整环境预检                    | 对需要验证的每个 benchmark profile 分别运行上一行的单 profile 命令。                                                                                                                                                              |

## 下一步 [#下一步]

<Cards>
  <Card title="Studio" description="检查富媒体产物、可视化为模型发送 Prompt、查看评测历史。" href="/zh/docs/guides/studio" />

  <Card title="CLI" description="发现、评测、套件和门槛的完整命令图。" href="/zh/docs/reference/cli" />

  <Card title="评测" description="用基准运行器和记分卡评分生成产物。" href="/zh/docs/evaluation" />
</Cards>