# YoVision Brain

Brain 是无界面的独立推理交付单元。本骨架只提供可安装 Python 包、命令入口和运行时探测；尚不包含视频、模型、规则、事件或部署能力，也不依赖 Sense、Bell 在线。

## 冻结基线

| 项目 | 版本 / 选择 |
|---|---|
| Python | CPython `3.11.15`（`.python-version`；本机由 uv 隔离管理） |
| 环境与包管理 | Python `venv` + pip `26.2.1`；可用 uv `0.11.6` 取得固定 Python |
| 构建后端 | setuptools `80.9.0` |
| 测试 | pytest `8.4.2` |
| 数组运行时 | NumPy `2.3.3` |
| 推理运行时 | PyTorch `2.12.1` |
| CPU wheel | PyTorch 官方 `https://download.pytorch.org/whl/cpu` |
| NVIDIA wheel | PyTorch 官方 CUDA 12.6 `https://download.pytorch.org/whl/cu126` |

选择 Python 3.11 是因为 PyTorch 的 Windows 支持范围包含 Python 3.9–3.12，并且本机已有隔离的 CPython 3.11.15。选择 `torch 2.12.1 + cu126` 是因为 PyTorch 官方为 Linux/Windows 同时发布该固定组合；NVIDIA 的 CUDA 12.x 兼容表要求 Windows 驱动至少为 528.33，本机驱动 566.24 满足运行 CUDA 12.6 wheel 的驱动前提。

本机安装的 CUDA Toolkit 11.2 不参与 PyTorch wheel 构建，也不因本项目而修改。驱动满足最低版本只是兼容前提，不等于 GPU 已验证；必须以 `--smoke cuda` 的真实结果为准。

官方依据：

- [PyTorch - Start Locally](https://docs.pytorch.org/get-started/locally/)
- [PyTorch - Previous Versions](https://pytorch.org/get-started/previous-versions/)
- [NVIDIA CUDA 12.6 Release Notes](https://docs.nvidia.com/cuda/archive/12.6.0/cuda-toolkit-release-notes/index.html)
- [Python 3.11.15](https://www.python.org/downloads/release/python-31115/)

## 创建隔离环境

从仓库根目录执行。无需激活虚拟环境，也不需要更改 PowerShell 执行策略：

```powershell
uv python install 3.11.15
uv venv --python 3.11.15 Brain/.venv
Brain\.venv\Scripts\python.exe -m pip install pip==26.2.1 --index-url https://pypi.org/simple
Brain\.venv\Scripts\python.exe -m pip install -e "Brain[dev]" --index-url https://pypi.org/simple
```

若不使用 uv，也可以让已安装的 Python 3.11.15 创建环境：

```powershell
py -V:3.11 -m venv Brain/.venv
Brain\.venv\Scripts\python.exe -m pip install pip==26.2.1 --index-url https://pypi.org/simple
Brain\.venv\Scripts\python.exe -m pip install -e "Brain[dev]" --index-url https://pypi.org/simple
```

## 安装运行时

CPU 环境使用 PyTorch 官方 CPU 索引：

```powershell
Brain\.venv\Scripts\python.exe -m pip install numpy==2.3.3 --index-url https://pypi.org/simple
Brain\.venv\Scripts\python.exe -m pip install torch==2.12.1 --index-url https://download.pytorch.org/whl/cpu
```

目标 NVIDIA 环境使用官方 CUDA 12.6 wheel。该 wheel 自带所需 CUDA 用户态运行库，不要求把系统 Toolkit 改成 12.6：

```powershell
Brain\.venv\Scripts\python.exe -m pip install numpy==2.3.3 --index-url https://pypi.org/simple
Brain\.venv\Scripts\python.exe -m pip install torch==2.12.1 --index-url https://download.pytorch.org/whl/cu126
```

不要在同一环境混装 CPU 与 CUDA wheel；切换后端时重建 `.venv`。

## 运行和验证

入口的帮助与版本查询不导入 PyTorch，因此未安装运行时时也可用：

```powershell
Brain\.venv\Scripts\python.exe -m yovision_brain --help
Brain\.venv\Scripts\python.exe -m yovision_brain --version
```

安装相应运行时后执行：

```powershell
Brain\.venv\Scripts\python.exe -m pytest Brain/tests/test_package.py -q
Brain\.venv\Scripts\python.exe -m yovision_brain --runtime-info
Brain\.venv\Scripts\python.exe -m yovision_brain --smoke cpu
Brain\.venv\Scripts\python.exe -m yovision_brain --smoke cuda
```

`--runtime-info` 只输出 Python、PyTorch 和设备能力，不读取或显示环境变量值。`--smoke cuda` 在 CUDA wheel、驱动或设备不可用时以非零状态退出，不会回退 CPU 后伪称成功。

## 配置与安全边界

`.env.example` 只有无秘密默认值。Brain 不接收用户会话，不持有账户、RBAC、Alert 或通知状态。不得把 token、摄像头凭据、客户数据、内部文件路径或未经授权的人脸信息写入配置、日志或事件。

第三方许可证与来源见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。