环境准备
打开模型前，先准备与 SDK、系统和模型匹配的运行环境。环境包由 darra-env-setup 环境部署工具按需拉取，Studio 启动时也会自动检测并强制补齐基础环境。Darra AI Studio 是独立 Windows 桌面端工业视觉建模工具，不是 PLC IDE 内置模块；现场推理走独立发布的 Darra AI SDK，协议只有一份 C ABI 加六语言薄绑定。
SDK 只查找、验证和加载本机已有的 Provider，不下载或安装，也不会替你创建环境目录。环境的下载与安装由 darra-env-setup 环境部署工具完成，Studio 内的环境服务是同一套核心。
Studio 与 SDK
| 产品 | 用途 |
|---|---|
| AI Studio | 数据集、标注、训练/导出、单向加密出包 |
| Darra AI SDK | 打开会话、推理、关闭会话 |
| Software PLC | 软 PLC / 视觉运行时消费 SDK |
SDK 的推理会话入口是 darra_session_open → infer → close。Software PLC 的站点是 plc.darra.xyz。
环境分级
| 分级 | 内容 | 什么时候装 |
|---|---|---|
| 强制基础环境 | 运行时内核 + onnx-cpu 推理后端 | 启动时自动补齐，不可跳过 |
| 可选进阶包 | GPU 推理后端（CUDA / TensorRT / DirectML / OpenVINO） | 需要 GPU 推理时 |
| 可选进阶包 | 训练 Python 环境（嵌入式 Python + PyTorch） | 要训练或评估时 |
| 可选进阶包 | 导出工具链（TensorRT engine / OpenVINO IR） | 要导出对应格式时 |
强制项缺一不可，由工具按清单缺什么下什么；可选进阶包按硬件与项目需要勾选。TensorRT 通过本机 trtexec 或已验证可加载的 TensorRT Python 模块导出 .engine，OpenVINO 在 Intel CPU 导出 xml+bin，两者都是导出不是推理。环境就绪后，具体模型和显卡的转换兼容性仍在导出时检查。
Python 与导出工具链由环境服务分别管理，独立于项目和模型库目录。
在 Studio 里准备环境
- 打开 Studio，主窗显示前先做环境检测。强制基础环境全部就绪就直接进主窗。
- 有缺件时弹出强制进度窗（无关闭按钮、不可跳过），显示与工具同款的下载、校验、安装进度，完成后才进主窗。
- 检测失败或网络失败时显示错误与「重试」按钮，不带病进主窗。
- 可选进阶包不阻塞启动，在右上角 下载中心 按硬件勾选并一键安装；可查看进度、取消、重试或看失败原因。强制项不在这个列表里重复出现。
- Ribbon 开始 → 环境管理 查看环境列表、名称和版本。
用 darra-env-setup 环境部署工具
Windows 交付 darra-env-setup.exe，Linux 交付 darra-env-setup 控制台版，都是单文件自发布。
| 用法 | 行为 |
|---|---|
| 无参数 | 静默确保强制基础环境（下载 + 校验 + 登记），已就绪秒退 0 |
| --silent --required | 与无参数等价的显式写法，给调用方用 |
| -i | 进交互 TUI，含可选进阶包菜单（上下键移动、空格勾选、Enter 开始、Esc 只装强制项） |
| --all | 交互模式默认勾选全部可选包 |
| --check | 只检测并打印结果，不下载不安装 |
Linux 控制台版同一套行为：TTY 下默认进交互 TUI，非 TTY 或带 --silent 走静默。
SDK 的 ensure 会探测并拉起这个工具，顺序是环境变量 DARRA_ENV_SETUP、程序同目录、PATH，找到就用 --silent --required 拉起并等退出码。找不到工具时返回「请先运行 darra-env-setup」，不会自己下载安装。
Windows 缺省 C:\DARRA\Runtime，Linux 缺省 $HOME/.local/share/darra/runtime，都可用 DARRA_ENV_ROOT 覆盖。已装环境登记在 darra-installed.json，不另造注册表。
Windows 默认位置：
C:\DARRA\Runtime\<provider>\<version> 已安装环境
C:\DARRA\Runtime\.cache\runtime-packages 下载缓存
例如 CPU 推理使用 onnx-cpu 对应版本。Provider 种类见 运行时 Provider。
手动或离线部署
按正式交付清单复制完整环境，保留版本目录、登记文件和依赖，并核对大小、SHA-256 及签名；客户程序不必安装 Studio。手动部署要保留正式交付物中的 darra-installed.json、Provider 模块和依赖；加密模型还需要 provider.json 与 provider.json.sig，不能自行填写登记文件代替校验。
断网现场两种做法：在联网机上先跑 darra-env-setup 装齐，再把整个运行根目录连同 darra-installed.json 一起拷到目标机；或按正式交付清单、离线整合包逐项部署。装完用 darra-env-setup --check 核对。
现场 CUDA EP 仍是 13.0 一份，必须配 cuda-libs 13.0.0 与 cuDNN 9.0.0。其他代际的 cuda-libs 是运行库存货，不能拿来喂这份 EP。驱动 CUDA 低于 13.2 的 NVIDIA 走 DirectML。手动拼包时尤其注意，工具按清单配依赖不会混代际。
环境不放进项目或模型库，下载缓存不能当已安装环境。使用自定义根时，让部署流程与客户进程的 DARRA_ENV_ROOT 指向同一目录。
打开模型前先检查
- 跑
darra-env-setup --check，看强制基础环境是否齐全、有没有校验问题。 - 核对 SDK 与 Provider 的平台、位数、版本和 ABI。
- 运行 SDK 本地诊断，确认找到预期 Provider 及安装位置。
- 打开模型，完成激活要求，再运行一张真实图片验证推理。
AiEnvironment.Check().Ready 只表示诊断发现了推荐 Provider 的安装登记，不证明哈希、签名、激活或实际推理已通过。
缺包或失败时
| 提示 | 下一步 |
|---|---|
| 找不到 darra-env-setup | 先装环境部署工具，见下载页；SDK 的 ensure 按环境变量、程序同目录、PATH 顺序找 |
| 缺少 Provider | 跑 darra-env-setup 补强制基础环境，或在 Studio 下载中心装可选进阶包，再重试打开模型 |
| 检测失败、网络失败 | 检查下载地址连通性后重试；断网走手动或离线部署 |
| 环境目录不可写 | 为工具或部署流程选择可写位置；SDK 不会提升权限或改写机器目录 |
| 包不完整、哈希或签名错误 | 删掉残包重新下载，或从原始介质重拷离线包；校验失败不会被跳过 |
| 平台、位数或 ABI 不匹配 | 使用同平台、同发布批次的 SDK 和 Provider |
| 系统驱动缺失或过旧 | 按诊断提示安装硬件厂商驱动；工具和 SDK 都不代装系统驱动 |
下载失败、取消或未完成安装不等于环境已就绪。已准备并验证的环境可离线使用；SDK 打开模型不会临时联网补包。
加密模型还需要与 Core 信任根匹配的正式签名 Provider。2026-09-22 对公开 CPU / DirectML 包的抽查未发现 provider.json / provider.json.sig；包能下载不能代表加密推理可交付。Linux 加密可信加载暂不支持，RK3588 仍需对应包与板端验证。