拿到桌面视觉项目后，我更倾向于先确认解释器、依赖和工作目录，再打开图形界面。否则，看起来是按钮失效的问题，实际可能是终端与应用用了不同的 Python，或者程序没有找到数据目录。这篇以配套工作台的入口和配置代码为线索，梳理第一次启动时最值得确认的几件事。
1. 先认清运行方式：它是一套本地桌面应用
主入口 main.py 创建 PySide6 的 QApplication，加载配置、登录窗口和现代化主窗口。程序需要桌面会话，不能直接当作 PHP 网站放进服务器目录运行。安装验证优先使用 Windows 与 Python 3.10 的独立环境；本次界面检查使用的也是 Python 3.10 环境。
GPU 是训练加速选项。第一次启动可以先检查 CPU 路径和界面，等数据与模型能够正确加载后，再核对驱动和 PyTorch 的 GPU 构建，减少同时排查多个变量的成本。
2. 让安装和运行始终使用同一个解释器
在源码根目录执行下面的 Windows 命令。这里显式使用虚拟环境里的 python.exe，可以避免 pip 把包装进其他环境。PyTorch 的 CPU/GPU 版本需结合实际机器选择；原依赖清单是版本范围，安装完成后应保存自己的已验证环境记录。
py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements-minimal.txt
.\.venv\Scripts\python.exe -m pip check
.\.venv\Scripts\python.exe main.py3. 把依赖检查拆成可定位的几步
先确认 PySide6、OpenCV、PyTorch 和 Ultralytics 可以导入，再检查 torch.cuda.is_available()。返回 False 只表示当前环境没有可用的 CUDA 计算设备，不能据此断言整个程序不可用。
若错误发生在 Matplotlib 的 Qt 后端，先检查当前解释器中的 Qt 绑定与 Matplotlib 版本，保留第一条异常信息。不要通过在不同终端重复安装一整套依赖来碰运气。
import sys
import PySide6
import cv2
import torch
from ultralytics import YOLO
print('Python:', sys.executable)
print('PySide6:', PySide6.__version__)
print('OpenCV:', cv2.__version__)
print('PyTorch:', torch.__version__)
print('CUDA available:', torch.cuda.is_available())4. 首次登录与工作目录分别检查
认证模块 AuthManager 在没有用户文件时会初始化本地演示管理员，源码中的初始账号为 admin、密码为 admin123。它属于桌面应用，和网站后台账号没有关系。首次进入后应更换密码；整理副本没有携带原使用者的用户、会话和登录日志。
DatasetManager 默认使用相对目录 workspace/datasets，因此应从源码根目录启动。全局配置由 core/config.py 管理，并支持显式指定配置路径。若换一个启动目录就看不到数据，先核对实际工作目录和配置，不要急着删除数据集或重新标注。
5. 可选功能按目标补齐依赖
本地 API 服务依赖 FastAPI、Uvicorn 和文件上传组件；不同模型导出格式还依赖相应运行时。建议按实际需求逐项安装和验证，避免一次加入所有可选工具后增加版本冲突。
当前源码的 launcher.py 引用了未随目录提供的依赖安装器文件。依赖准备完成后，可以按上述方式直接运行 main.py。完成界面启动、登录、导航和小样本数据导入后，再进入训练或推理验证。本文的操作步骤不代表已经在所有系统和 GPU 上完成测试。
对应源码模块与配套项目
本文结合本次整理源码编写，主要对应：main.py、launcher.py、core/config.py、auth/manager.py、data/dataset_manager.py。
项目介绍、界面截图与资料清单：桌面视觉模型训练与推理一体化工作台。
