K-Sort Arena

K-Sort Arena 是一个面向视觉生成模型的偏好评测与排行榜系统。项目提供基于 Gradio 的交互式 Arena 页面，支持图像生成与视频生成模型的匿名多模型比较、人工偏好投票、贡献者统计、日志保存与排行榜展示。

本项目实现思想主要参考以下两篇工作：

[1] Zhikai Li, Xuewen Liu, Dongrong Fu, Jianquan Li, Qingyi Gu, Kurt Keutzer, and Zhen Dong. K-Sort Arena: Efficient and reliable benchmarking for generative models via k-wise human preferences. IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR), 2025.
[2] Zhikai Li, Jiatong Li, Xuewen Liu, Wangbo Zhao, Pan Du, Kaicheng Zhou, Qingyi Gu, Yang You, Zhen Dong, Kurt Keutzer. K-Sort Eval: Efficient preference evaluation for visual generation via corrected VLM-as-a-judge. International Conference on Learning Representations (ICLR), 2026.

项目功能

1. K-wise 人类偏好评测

传统 Arena 通常采用两两比较。K-Sort Arena 面向视觉生成任务提供 K-wise 比较流程，即一次向用户展示多个模型输出，让用户在同一提示词下比较多个候选结果。

当前界面主要支持四模型匿名比较：

给定同一个文本提示词。
同时展示多个模型的生成结果。
用户可以通过排序、选择更优结果、平局或全部较差等方式提交偏好。
系统记录每次投票的模型、提示词、输出文件、用户信息和时间等日志。

这种方式能够在接近 pairwise 比较交互成本的情况下收集更丰富的偏好信息，对应论文 [1] 中 K-wise human preferences 的核心思想。

2. 图像生成 Arena

项目提供文本到图像生成模型的评测页面，入口位于主界面的 Image Generation 标签。

支持的能力包括：

图像生成排行榜展示。
匿名模型对战页面。
四个模型在同一 prompt 下并行生成图像。
基于缓存样例的快速评测流程。
支持用户填写姓名和机构，用于贡献者排行榜统计。
支持将投票结果、生成图像和相关元信息写入日志。

核心相关文件：

app.py：Gradio 主入口。
serve/gradio_web.py：图像生成 Arena 页面构建。
serve/vote_utils.py：投票、日志、状态管理与结果保存。
model/model_manager.py：模型加载、并行调用和缓存样例读取。
model/matchmaker.py：图像模型匹配逻辑。

3. 视频生成 Arena

项目同样支持文本到视频生成模型的评测页面，入口位于主界面的 Video Generation 标签。

支持的能力包括：

视频生成排行榜展示。
匿名视频模型对战。
从远程或本地缓存中加载多个模型的视频输出。
保存用户投票结果和视频文件路径。
针对不同模型来源选择不同的视频缓存目录。

核心相关文件：

serve/gradio_web_video.py：视频生成 Arena 页面构建。
model/matchmaker_video.py：视频模型匹配逻辑。
model/model_manager.py：视频缓存样例读取和模型选择。
serve/vote_utils.py：视频投票和日志保存。

4. 模型匹配与样本选择

项目内置 matchmaker 机制，用于自动选择参与同一轮比较的模型。用户不手动指定模型时，系统会根据匹配策略从候选模型池中选择模型，减少随机配对带来的低效比较。

5. 排行榜展示

系统提供图像、视频和贡献者三个排行榜页面：

图像生成排行榜：展示图像模型的评测排名。
视频生成排行榜：展示视频模型的评测排名。
贡献者排行榜：统计用户提交贡献。

6. 日志与结果保存

项目支持将用户投票和生成结果写入日志目录，也提供简单的日志服务接口。

主要保存内容包括：

用户投票类型。
匿名模型对应的真实模型名称。
prompt 文本。
图像或视频输出路径。
用户 IP。
用户姓名和机构信息。
对局 ID 和时间信息。

K-Sort Eval 相关说明

论文 [2] 提出 K-Sort Eval，通过 corrected VLM-as-a-judge 实现更高效的视觉生成偏好评估。与完全依赖人工投票的 Arena 不同，K-Sort Eval 关注使用经过修正的视觉语言模型作为裁判来进行偏好判断，从而降低大规模评测成本。

本仓库当前主要提供 K-Sort Arena 的人类偏好交互评测与排行榜系统。若需要扩展到 K-Sort Eval，可在现有结构上增加自动裁判模块：

将同一 prompt 下的多模型输出提交给 VLM judge。
收集 VLM 给出的排序或偏好判断。
对 VLM 判断进行校正。
将自动评测结果写入与人工投票兼容的排序或日志格式。
与排行榜模块对接，生成自动化偏好评测结果。

目录结构

K-Sort-Arena/
├── app.py                         # Gradio 主入口
├── requirements.txt               # Python 依赖
├── contributor.json               # 贡献者排行榜数据
├── sorted_score_list.json         # 图像生成排行榜数据
├── sorted_score_list_video.json   # 视频生成排行榜数据
├── coco_prompt.txt                # 图像生成 prompt 样本
├── examples/                      # 示例图片
├── model/
│   ├── model_manager.py           # 模型调用、并行生成、缓存读取
│   ├── model_registry.py          # 模型信息注册与描述
│   ├── matchmaker.py              # 图像模型匹配
│   ├── matchmaker_video.py        # 视频模型匹配
│   └── models/                    # 各类模型 API 与 pipeline 封装
└── serve/
    ├── gradio_web.py              # 图像 Arena 页面
    ├── gradio_web_video.py        # 视频 Arena 页面
    ├── leaderboard.py             # 排行榜页面
    ├── vote_utils.py              # 投票逻辑与结果保存
    ├── upload.py                  # SSH、缓存与文件上传
    ├── log_utils.py               # 日志工具
    ├── log_server.py              # 日志服务
    ├── constants.py               # 全局配置
    └── utils.py                   # 通用 UI 与辅助函数

安装依赖

建议使用独立的 Python 环境安装依赖：

pip install -r requirements.txt

依赖中包含部分 Git 仓库形式的包，例如 CLIP、latent-diffusion、ImagenHub 和 VideoGenHub。安装时需要能够访问对应仓库。

启动方式

在项目根目录运行：

python app.py

默认会启动 Gradio Web 服务。端口由 SERVER_PORT 控制，默认值为 7860。

启动后可在浏览器访问：

http://127.0.0.1:7860

常用环境变量

项目通过环境变量管理日志、服务端口、远程缓存和 SSH 信息。

变量名	默认值	说明
`SERVER_PORT`	`7860`	Gradio 服务端口
`ROOT_PATH`	`None`	部署在子路径时使用
`ELO_RESULTS_DIR`	`./arena_elo/results/latest`	外部 Elo 或排行榜结果目录
`LOGDIR`	`./ksort-logs/vote_log`	投票日志目录
`IMAGE_DIR`	`${LOGDIR}/images`	图像结果保存目录
`VIDEO_DIR`	`${LOGDIR}/videos`	视频结果保存目录
`LOG_SERVER`	`http://127.0.0.1:22005`	日志服务地址
`SSH_SERVER`	`default_value`	远程缓存服务器
`SSH_PORT`	`default_value`	SSH 端口
`SSH_USER`	`default_value`	SSH 用户
`SSH_PASSWORD`	`default_value`	SSH 密码
`SSH_CACHE_IMAGE`	`/home/zhendongucb/ksort/ksort_image_cache/`	图像缓存目录
`SSH_CACHE_OPENSOURCE`	`/home/zhendongucb/ksort/ksort_video_cache/Opensource/`	开源视频模型缓存目录
`SSH_CACHE_ADVANCE`	`/home/zhendongucb/ksort/ksort_video_cache/Advance/`	高级视频模型缓存目录
`SSH_CACHE_PIKA`	`/home/zhendongucb/ksort/ksort_video_cache/Pika-Beta/`	Pika 缓存目录
`SSH_CACHE_SORA`	`/home/zhendongucb/ksort/ksort_video_cache/Sora/`	Sora 缓存目录

基本使用流程

启动项目：

python app.py

进入图像或视频 Arena 页面。
输入 prompt，或使用缓存样例。
系统展示多个匿名模型输出。
用户根据质量进行排序或投票。
系统记录投票日志和生成结果。
根据日志或排序结果更新排行榜。

添加新模型

添加新模型通常需要完成以下步骤：

在 model/models/ 中实现模型加载或 API 调用封装。
在 model/models/__init__.py 中加入模型名称列表。
如需在页面展示模型描述，可在 model/model_registry.py 中注册模型信息。
如需参与自动匹配，确保模型出现在对应的图像或视频模型列表中。
如模型依赖远程缓存，需要在 serve/upload.py 和相关 SSH 配置中准备对应目录。

数据与缓存

项目支持两类生成方式：

在线生成：调用本地模型 pipeline 或外部 API 实时生成。
缓存评测：从远程或本地缓存中读取指定 prompt 下的模型输出。

缓存评测适合公开 Arena 或大规模人工投票场景，可以避免实时调用模型带来的高延迟、高成本和 API 并发限制。

引用

如果使用本项目或相关方法，请引用：

@inproceedings{li2025ksortarena,
  title={K-Sort Arena: Efficient and reliable benchmarking for generative models via k-wise human preferences},
  author={Li, Zhikai and Liu, Xuewen and Fu, Dongrong and Li, Jianquan and Gu, Qingyi and Keutzer, Kurt and Dong, Zhen},
  booktitle={IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR)},
  year={2025}
}

@inproceedings{li2026ksorteval,
  title={K-Sort Eval: Efficient preference evaluation for visual generation via corrected VLM-as-a-judge},
  author={Li, Zhikai and Li, Jiatong and Liu, Xuewen and Zhao, Wangbo and Du, Pan and Zhou, Kaicheng and Gu, Qingyi and You, Yang and Dong, Zhen and Keutzer, Kurt},
  booktitle={International Conference on Learning Representations (ICLR)},
  year={2026}
}

许可证与致谢

本项目代码和评测流程构建在多个开源视觉生成与 Web 服务组件之上，包括 Gradio、Diffusers、ImagenHub、VideoGenHub、CLIP 等。请在使用对应模型、数据和依赖时遵守其原始许可证和使用条款。