91 lines
4.2 KiB
Markdown
91 lines
4.2 KiB
Markdown
# 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)。
|