ghcr.io/kserve/models-web-app:1.0.5

KSERVE UI

该 Web 应用用于让用户在 Kubeflow 集群中管理 KServe 推理资源，它提供了友好的交互方式来处理 InferenceService 和 InferenceGraph 自定义资源的完整生命周期。

支持的资源

• 属于 serving.kserve.io/v1beta1 版本的 InferenceService 资源
• 属于 serving.kserve.io/v1alpha1 版本的 InferenceGraph 资源

创建表单还支持多文档 YAML，可按指定顺序创建受支持的 KServe 资源。目前多文档创建功能接受 InferenceService、InferenceGraph 和 TrainedModel 三类资源。资源会按照文档定义的顺序依次创建；如果某一步创建失败，应用会返回失败的文档以及所有已成功创建的资源信息，但不会对此前已创建成功的资源执行回滚操作。

当前功能范围

InferenceService 和 InferenceGraph 都是该应用的一级资源，但二者目前的 UI 覆盖范围并不完全一致：

• InferenceService 仍是核心模型服务管理流程，包含完整的列表/详情体验，以及服务专属的运维视图
• InferenceGraph 提供独立的列表、创建、编辑和详情页面路由
• InferenceGraph 详情页面目前仅包含图概览、事件和 YAML 视图，暂不支持 InferenceService 的全部运维视图

文档

• 测试指南：基于 Jest 和 Cypress 完成单元测试与 E2E 测试的完整说明文档

连接到应用

该 Web 应用会与其他 KServe 组件一同安装，部署命名空间可以是 kserve 或者 kubeflow。系统会创建一个 VirtualService，通过 Istio Ingress Gateway 对外暴露应用。不同的安装模式会使用对应的 Ingress Gateway，对应关系如下：

你可以在浏览器中访问以下地址进入应用：

${INGRESS_IP}/models/

你也可以通过 kubectl port-forward 访问应用，这种场景下需要将应用配置为满足以下条件：

• 不执行任何授权检查，因为没有登录用户
• 服务运行在 / 路径前缀下
• 禁用安全 Cookie，因为应用会通过纯 HTTP 协议暴露

你可以执行以下命令完成上述配置：

# 编辑配置文件
# 若为 Kubeflow 部署，请使用 CONFIG=manifests/kustomize/overlays/kubeflow/kustomization.yaml
CONFIG=manifests/kustomize/base/kustomization.yaml
vim ${CONFIG}

# 在 kserve-models-web-app-config 的 configMapGenerator 配置项的 literals 字段中添加以下环境变量
- APP_PREFIX=/
- APP_DISABLE_AUTH="True"
- APP_SECURE_COOKIES="False"

# 重新应用 Kustomize 配置
# 若为 Kubeflow 部署，请使用 kustomize build manifests/kustomize/overlays/kubeflow | kubectl apply -f -
kustomize build manifests/kustomize/base | kubectl apply -f -

配置

以下是所有可用于该基础 Web 应用的环境变量说明：

命名空间过滤配置

对于独立部署场景，你可以通过 ALLOWED_NAMESPACES 配置用户可访问的命名空间：

• 留空/未设置（默认值）：允许访问集群所有命名空间
• 单个命名空间：ALLOWED_NAMESPACES="kubeflow-user"，系统会自动选中该命名空间并隐藏下拉选择器
• 多个命名空间：ALLOWED_NAMESPACES="ns1,ns2,ns3"，下拉选择器仅展示配置的命名空间

所有无效的命名空间配置会被忽略；如果配置的命名空间全部无效，系统将回退到允许访问所有命名空间的行为。

配置示例

# 仅允许访问单个命名空间（自动选中，隐藏下拉选择器）
export ALLOWED_NAMESPACES="kubeflow-user"

# 允许访问多个指定命名空间
export ALLOWED_NAMESPACES="kubeflow-user,kubeflow-admin,ml-team"

# 恢复默认行为，允许访问所有命名空间
unset ALLOWED_NAMESPACES

Kubernetes 部署配置

将环境变量添加到你的部署配置中即可生效：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: kserve-models-web-application
spec:
  template:
    spec:
      containers:
      - name: kserve-models-web-application
        env:
        - name: ALLOWED_NAMESPACES
          value: "kubeflow-user,kubeflow-admin"

Grafana 配置

该应用支持运行时配置 Grafana 端点和仪表盘名称，你无需重新构建应用，即可对接自定义的 Grafana 实例与仪表盘配置。

如果你使用 Kustomize 在 Kubernetes 上部署，可以编辑 manifests/kustomize/base/kustomization.yaml（或你自定义的 overlay 文件）中 kserve-models-web-app-config 对应的 configMapGenerator 配置项，按需更新以下参数即可：

• GRAFANA_PREFIX（例如 /grafana 或 /custom-grafana）
• GRAFANA_CPU_MEMORY_DB（例如 db/custom-cpu-memory-dashboard）
• GRAFANA_HTTP_REQUESTS_DB（例如 db/custom-http-requests-dashboard）

编辑完成后重新应用资源清单即可，示例命令如下：

kustomize build manifests/kustomize/base | kubectl apply -f -

配置 API

你可以通过访问 /api/config 接口校验 Grafana 配置是否生效：

curl http://your-app-url/api/config

接口预期返回内容：

{
"grafanaPrefix": "/custom-grafana",
"grafanaCpuMemoryDb": "db/custom-cpu-memory-dashboard",
"grafanaHttpRequestsDb": "db/custom-http-requests-dashboard"
}

开发说明

本 Web 应用的前端基于 Angular 构建，后端采用 Python Flask 框架编写。

本应用所需的通用 Angular 和 Python 库均维护在当前仓库的 common 目录下，因此本地开发和 OCI 镜像构建仅需使用本仓库即可完成。

若要在本地运行该应用，你需要完成以下操作：

• 以监听模式构建前端
• 启动后端 执行 npm run build:watch 命令会将前端构建产物输出到后端的 static 目录中供后端直接提供服务。因此你只需启动后端，访问 localhost:5000 即可查看应用。

环境要求

• node 22.0.0
• python 3.12

前端

方案 1：使用 Makefile（推荐）

cd $KSERVE_MODELS_WEB_APPLICATION_REPOSITORY/frontend

# 安装依赖并构建通用库
make setup

# 清理命令：提供 make clean 目标用于删除 node_modules
# make clean

# 构建并监听文件变更
npm run build:watch

方案 2：手动配置

# 构建本仓库中包含的通用库
cd $KSERVE_MODELS_WEB_APPLICATION_REPOSITORY/common/frontend/kubeflow-common-lib
npm i
npm run build
cd dist/kubeflow
npm link

# 运行应用前端
cd $KSERVE_MODELS_WEB_APPLICATION_REPOSITORY/frontend
npm i
npm link kubeflow
npm run build:watch

后端

在本地运行

# 创建虚拟环境并安装依赖
# 参考官方指南：https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/
cd $KSERVE_MODELS_WEB_APPLICATION_REPOSITORY
python3.12 -m pip install --user virtualenv
python3.12 -m venv backend/web-application-development
source backend/web-application-development/bin/activate

# 在已激活的虚拟环境中安装依赖
make -C backend install-deps

# 运行后端
make -C backend run-dev

已知问题

oauth2-proxy 场景下的大体积 JWT Token 问题

持有大体积 JWT Token 的用户（在 Azure AD 环境中且所属用户组数量较多时很常见）可能会遇到请求失败的问题。本部署内置了 Gunicorn 配置 GUNICORN_CMD_ARGS=--limit-request-field_size 32000，用于处理更大的请求头。

更多细节请参考 oauth2-proxy 已知问题文档。

---

KSERVE UI

本 Web 应用用于让用户在 Kubeflow 集群中管理 KServe 推理资源，它提供了友好的交互界面，用于完整管理 InferenceService 和 InferenceGraph 自定义资源的生命周期。

支持的资源

• serving.kserve.io/v1beta1 版本的 InferenceService 资源
• serving.kserve.io/v1alpha1 版本的 InferenceGraph 资源

创建表单还支持多文档 YAML 格式，可按指定顺序创建受支持的 KServe 资源。当前多文档创建功能支持 InferenceService、InferenceGraph 和 TrainedModel 三类资源。资源将严格按照文档中的顺序创建；如果某一步创建失败，应用会上报失败的文档以及所有已成功创建的资源，但不会回滚之前已经创建成功的资源。

当前功能范围

InferenceService 和 InferenceGraph 均是本应用的一级资源，但二者当前的 UI 覆盖范围并不完全一致：

• InferenceService 是核心的模型服务管理流程，包含完整的列表/详情展示体验，以及服务专属的运维视图。
• InferenceGraph 可通过独立的列表、创建、编辑和详情路由访问。
• InferenceGraph 的详情页当前仅聚焦于图概览、事件和 YAML 视图，暂不提供 InferenceService 具备的全套运维视图。

文档

• 测试指南 - 关于使用 Jest 和 Cypress 完成单元测试与 E2E 测试的完整指南

访问应用

本 Web 应用会与其他 KServe 组件一同部署，部署位置可以是 kserve 命名空间或 kubeflow 命名空间。部署中包含一条 VirtualService 资源，通过 Istio Ingress Gateway 向外暴露应用。不同的安装环境会使用对应的 Ingress Gateway，对应关系如下：

你可以在浏览器中访问以下地址进入应用：

${INGRESS_IP}/models/

你也可以通过 kubectl port-forward 方式访问应用，这种场景下需要对应用做如下配置：

1. 关闭所有授权校验，因为此时没有已登录用户
2. 将应用的服务路径前缀设置为 /
3. 禁用安全 Cookie，因为应用会通过纯 HTTP 协议暴露

你可以执行以下命令完成上述配置：

# 编辑配置文件
# CONFIG=manifests/kustomize/overlays/kubeflow/kustomization.yaml
CONFIG=manifests/kustomize/base/kustomization.yaml
vim ${CONFIG}

# 请为 kserve-models-web-app-config 对应的 configMapGenerator 添加以下字面量配置项
- APP_PREFIX=/
- APP_DISABLE_AUTH="True"
- APP_SECURE_COOKIES="False"

# 重新应用 Kustomize 配置
# kustomize build manifests/kustomize/overlays/kubeflow | kubectl apply -f -
kustomize build manifests/kustomize/base | kubectl apply -f -

配置

以下是可用于任意基于该基础应用构建的 Web 应用的环境变量完整配置清单：

命名空间过滤配置

对于独立部署场景，可通过 ALLOWED_NAMESPACES 配置用户可访问的命名空间范围：

• 留空/未设置（默认值）：集群内所有命名空间均可访问
• 单个命名空间：ALLOWED_NAMESPACES="kubeflow-user" - 自动选中该命名空间，下拉选择框将隐藏
• 多个命名空间：ALLOWED_NAMESPACES="ns1,ns2,ns3" - 命名空间下拉选择框将仅展示过滤后的命名空间列表

配置中的无效命名空间将被直接忽略；若所有指定的命名空间均无效，配置将自动回退为允许访问全部命名空间。

配置示例

# 仅允许访问单个命名空间（自动选中，下拉选择框隐藏）
export ALLOWED_NAMESPACES="kubeflow-user"

# 允许访问多个指定命名空间
export ALLOWED_NAMESPACES="kubeflow-user,kubeflow-admin,ml-team"

# 恢复默认行为 - 允许访问所有命名空间
unset ALLOWED_NAMESPACES

Kubernetes 部署配置

将环境变量添加到你的部署配置中：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: kserve-models-web-application
spec:
  template:
    spec:
      containers:
      - name: kserve-models-web-application
        env:
        - name: ALLOWED_NAMESPACES
          value: "kubeflow-user,kubeflow-admin"

Grafana 配置

该应用支持在运行时配置 Grafana 端点和仪表盘名称，无需重新构建应用即可对接自定义 Grafana 实例和自定义仪表盘配置。

如果你正在使用 Kustomize 部署到 Kubernetes 集群，可编辑 manifests/kustomize/base/kustomization.yaml（或你自定义的 overlay 层）中 kserve-models-web-app-config 的 configMapGenerator 段，按需更新以下配置项即可将配置写入应用的 ConfigMap：

• GRAFANA_PREFIX（例如：/grafana 或 /custom-grafana）
• GRAFANA_CPU_MEMORY_DB（例如：db/custom-cpu-memory-dashboard）
• GRAFANA_HTTP_REQUESTS_DB（例如：db/custom-http-requests-dashboard）

编辑完成后重新应用清单即可，示例命令如下：

kustomize build manifests/kustomize/base | kubectl apply -f -

配置校验 API

你可以通过访问 /api/config 接口校验 Grafana 配置是否生效：

curl http://your-app-url/api/config

预期返回结果：

{
  "grafanaPrefix": "/custom-grafana",
  "grafanaCpuMemoryDb": "db/custom-cpu-memory-dashboard",
  "grafanaHttpRequestsDb": "db/custom-http-requests-dashboard"
}

开发指南

该应用的前端使用 https://angular.io/ 构建，后端使用 Python https://flask.palletsprojects.com/en/1.1.x/ 框架开发。

本 Web 应用所需的通用 Angular 库和 Python 库均维护在当前仓库的 common 目录下。因此本地开发和 OCI 镜像构建仅依赖当前仓库即可完成。

本地运行该应用需要完成以下两个步骤：

1. 以监听模式构建前端项目
2. 启动后端服务

npm run build:watch 命令会将前端构建产物输出到后端的 static 目录下用于提供服务。因此你需要启动后端服务后，访问 localhost:5000 即可查看应用页面。

环境依赖要求：

• node 22.0.0
• python 3.12

前端开发

方案 1：使用 Makefile（推荐）

cd $KSERVE_MODELS_WEB_APPLICATION_REPOSITORY/frontend

# 安装依赖并构建通用库
make setup

# 清理命令：提供 make clean 目标用于移除 node_modules
# make clean

# 构建并监听文件变更自动重新构建
npm run build:watch

方案 2：手动配置环境

# 构建当前仓库中内置的通用库
cd $KSERVE_MODELS_WEB_APPLICATION_REPOSITORY/common/frontend/kubeflow-common-lib
npm i
npm run build
cd dist/kubeflow
npm link

# 运行应用前端
cd $KSERVE_MODELS_WEB_APPLICATION_REPOSITORY/frontend
npm i
npm link kubeflow
npm run build:watch

后端开发

本地运行后端服务

# 创建虚拟环境并安装依赖
# 参考文档：https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/
cd $KSERVE_MODELS_WEB_APPLICATION_REPOSITORY
python3.12 -m pip install --user virtualenv
python3.12 -m venv backend/web-application-development
source backend/web-application-development/bin/activate

# 在已激活的虚拟环境中安装所有依赖
make -C backend install-deps

# 启动开发模式后端服务
make -C backend run-dev

已知问题

oauth2-proxy 场景下的大体积 JWT Token 问题

携带大体积 JWT Token 的用户（这类场景在 Azure AD 环境中用户从属大量用户组时十分常见）可能会遇到请求失败问题。当前部署配置中已内置 Gunicorn 参数 GUNICORN_CMD_ARGS=--limit-request-field_size 32000 用于支持更大体积的请求头。

更多详情可参考 https://github.com/kubeflow/manifests/tree/master/common/oauth2-proxy#known-issues 文档。