# 最小真实推理运行说明

## 1. 独立 CUDA 环境
本次实测：Windows 11、Python 3.12.4、RTX 4060 Laptop 8GB、约 32GB 内存。请预留约 20GB 空间用于环境和权重。以下命令在解压后的项目根目录执行：
```powershell
python -m venv .venv
.venv/Scripts/python -m pip install torch==2.5.1+cu124 torchvision==0.20.1+cu124 --index-url https://download.pytorch.org/whl/cu124
.venv/Scripts/python -m pip install -r requirements-inference.txt huggingface-hub==0.29.3 requests
.venv/Scripts/python -c "import torch; print(torch.__version__,torch.cuda.is_available())"
```
应显示 CUDA 可用。Linux 解释器改为 .venv/bin/python。量化模型不要整体执行 .half().cuda()，脚本负责各模块的加载和释放。

## 2. 下载固定版本权重
```powershell
.venv/Scripts/python scripts/download_minimal_weights.py --weights ../.nextgpt_weights
```
权重总计约 9.5GB（十进制）：ImageBind 4.80GB、Vicuna v0 GPTQ 3.89GB、官方 delta 0.79GB。支持分块续传，并核验两个 Hub 大权重 SHA256。
```text
../.nextgpt_weights/
  imagebind_huge.pth
  vicuna-v0-gptq/model.safetensors
  vicuna-v0-gptq/{config.json,tokenizer.model,tokenizer_config.json,...}
  nextgpt_7b_tiva_v0/pytorch_model.pt
  nextgpt_7b_tiva_v0/config.json
```

## 3. 执行真实图片问答
```powershell
.venv/Scripts/python scripts/verify_quant_linear.py
.venv/Scripts/python -u scripts/minimal_inference.py --weights ../.nextgpt_weights --image evidence/real-inference/input.jpg --prompt "What animal is shown in this picture? Answer in one short sentence." --max-new-tokens 24
.venv/Scripts/python scripts/check_environment.py --weights ../.nextgpt_weights
```
实测原始回答：A dog is shown in this picture.

输出到 evidence/real-inference/result.json、output.txt、image_embedding.pt；重新运行会覆盖这些结果，请先备份需要保留的文件。控制台可重定向到新日志。

## 4. 展示页面
本地 Gradio：在单独展示环境执行 pip install -r requirements.txt，然后 python app.py，访问 http://localhost:7860 。在线使用免费 Static Space，入口为 index.html。

这两个页面展示保存的实际结果，不执行实时推理。上传区只检查输入类型。更新 Space 时上传源码、assets、evidence，勿上传大权重、环境或凭据。

## 5. 全量官方实现参考
upstream/ 保留课程对应官方原始模型、inference.py、demo_app.py 和训练配置。全量实现需另建旧版 Linux CUDA 环境、FP16 Vicuna v0、ImageBind 与三个生成器。该全量环境未验证；本项目实测的是 scripts/minimal_inference.py 图片问答子集。

量化与兼容实现可能改变输出。早期长描述测试存在幻觉，记录保留。未完成四模态生成与训练。

## 在线推理入口

- [作业 Space 与在线交互](https://jp2023213625-nlp-chapter6-nextgpt.static.hf.space/#live)
- [公开推理后端及其源码](https://huggingface.co/spaces/nemoyu/nlp-chapter6-nextgpt)
- [线上验证脚本](scripts/verify_public_demo.py)与[验证记录](evidence/public-demo/)

作业 Space 使用 Hugging Face Static SDK。实时推理由 nemoyu 的公开 ZeroGPU Space 执行，上传的输入由该服务接收，使用时可能排队或触发额度限制。当前账号创建自有 ZeroGPU Space 时，平台返回 HTTP 402，提示账号年龄未达到免费托管门槛。本机 RTX 4060 的量化图片问答仍可按本项目运行说明复现。线上验证使用预训练推理，未重新训练。

复测在线四组组合时使用 Python 3.10+：

```sh
python -m pip install gradio_client==1.8.0
python scripts/verify_public_demo.py --output-dir online-rerun
```
