---
title: CrossGaze
emoji: 👀
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
short_description: CrossGaze / PaGE FastAPI gaze target estimation demo.
pinned: false
---
# Gazelle+ Standalone Demo

一个自包含的视线估计(gaze target estimation)前后端 demo。所有运行所需的代码与配置都在本目录下,**不依赖父目录的 gazelle 仓库**。

## 目录结构

```
webapp_standalone/
├── app.py                  # FastAPI 后端
├── requirements.txt
├── static/                 # 前端 (index.html / app.js / style.css)
├── gazelle/                # 模型代码(从父仓库复制,本地自洽)
├── backbones/              # DINOv3 架构配置(仅 config.json + preprocessor_config.json,无 safetensors)
│   ├── dinov3_vith16plus/
│   └── dinov3_vitb16/
└── checkpoints/            # 你需要自己把 .pt 权重放进来
```

## 权重说明(重要)

后端的 backbone 架构由 `backbones/*/config.json` 构造,**不读取** DINOv3 的 `model.safetensors`;backbone 权重全部从 gazelle 的 `.pt` checkpoint 灌入(`include_backbone=True`)。

因此你只需把 checkpoint 文件放进 `checkpoints/`,**按以下文件名命名**:

| 文件名 | 模型 | 是否必需 |
|---|---|---|
| `vitb_distill_screen.pt` | CrossGaze ViT-B Distill Screen(默认预加载) | 必需 |
| `vith.pt` | CrossGaze ViT-H | 可选 |

也可以用环境变量指定任意路径:

```bash
export GAZELLE_VITH_CHECKPOINT=/path/to/vith.pt
export GAZELLE_VITB_CHECKPOINT=/path/to/vitb_distill_screen.pt
```

> 注:`vitb_distill_screen.pt` 若文件头是空填充(`\x00`),当前会被判为损坏而拒绝加载——这是 checkpoint 文件本身的问题,与 backbone 无关。

## 运行

```bash
cd webapp_standalone
pip install -r requirements.txt
# 把 vitb_distill_screen.pt 放进 checkpoints/
python app.py
```

浏览器打开 `http://localhost:8001`。摄像头仅限 `localhost` 或 HTTPS 页面;局域网 IP 访问请用"上传图片"。

## 使用 Hugging Face PaGE 模型

当前后端还支持以下 private Hugging Face 模型,运行前需要提供 token:

```bash
export HUGGING_FACE_HUB_TOKEN=hf_xxx
python app.py
```

可选模型名:

| 后端模型名 | Hugging Face repo | 前端显示名 |
|---|---|---|
| `page_vitb` | `Octopus1/page-vitb` | PaGE ViT-B |
| `page_vitb_screen` | `Octopus1/page-vitb-screen` | PaGE ViT-B Screen |
| `page_vitsplus` | `Octopus1/page-vitsplus` | PaGE ViT-S+ |
| `page_vits` | `Octopus1/page-vits` | PaGE ViT-S |
| `page_vithplus` | `Octopus1/page-vithplus` | PaGE ViT-H+ |

这些模型会通过 `AutoModel.from_pretrained(..., trust_remote_code=True)` 加载,不需要本地 `checkpoints/*.pt`。

## Hugging Face Space 部署

本 Space 当前使用 Docker SDK 运行原 FastAPI + 静态网页版本：

```yaml
sdk: docker
app_port: 7860
```

Space 环境默认设置：

- `SPACE_DEFAULT_HF_ONLY=1`：只暴露 Hugging Face 模型，避免依赖本地 checkpoint。
- `DEFAULT_MODEL_NAME=page_vithplus`：默认模型为 `Octopus1/page-vithplus`。
- `PRELOAD_DEFAULT_MODEL=0`：不在启动时预加载模型，避免阻塞 Space 启动。
- `HF_TOKEN`：用于读取 private PaGE 模型。

注意：FastAPI/Docker 不能使用 ZeroGPU。若要 GPU 推理，需要在 Space hardware 中选择普通付费 GPU，例如 `a10g-small`。