Python 用法
面向最终用户的 Python SDK 调用说明：装好依赖后打开模型、反复推理、关闭会话。
调用链
标准链路是「一次打开，反复推理，退出关闭」：
Session.open 或 open_plain 打开会话 → infer_image 或 infer_image_result 推理若干次 → close 关闭（with 退出自动调用）。
from darra_ai import Session
with Session.open("model.darmodel") as s:
for jpg in frames:
print(s.infer_image(jpg))
- Session.open 打开加密 .darmodel；Session.open_plain 打开明文 .onnx / .pdmodel，与 open 同一推理路径。
- infer_image 返回结果 dict；要字段级访问用 infer_image_result，同一份结果解成结构化对象，不二次推理。
- close 释放会话；写在 with 块里退出时自动 close。同一会话反复调 infer_image 即可，不必反复打开。
- 加密模型首次在本机打开走激活码分流：try_open 返回 (session, info)，info.needs_code 为真时收一次激活码再 try_activate。激活码只用于打开 / 激活，推理永不收码。
- 失败抛 darra_ai.errors.DarraError 子类，带 code / message / hint，hint 可原样展示给最终用户；找不到原生库抛 DarraLoadError。
- import darra_ai 只加载 Python 代码，不加载 native；第一次调会碰运行库的 API（open / infer_image / version）才加载 Core.dll。
前置依赖
| 项目 | 要求 |
|---|---|
| Python | 3.10–3.13 |
| cffi | 随 wheel 自带，不用另装 |
| 原生运行库 | wheel 自带 Core.dll（win_amd64）或 libCore.so，不用再拷 |
| VC++ 运行库 | Visual C++ 2015-2022 Redistributable（x64） |
| 推理 Provider | 环境管理器 / darra-env-setup 部署到 C:\DARRA\Runtime，SDK 不下载不安装 |
| 模型 | 加密 .darmodel 或明文 .onnx / .pdmodel |
| 操作系统 | Windows x64 / Linux x86_64 / Linux ARM64，macOS 不在 v1 |
找不到 Core.dll 或版本主次号对不上抛 DarraLoadError。可设环境变量 DARRA_AI_CORE_PATH 指向 Core.dll 文件或所在目录，覆盖默认查找。
安装
PyPI 分发名 darra-ai，代码内导入名 darra_ai，两者是独立概念，不要混用。
pip install darra-ai
开发树（源码树 Darra.AI.Studio.SDK/Python/）安装：
pip install -e .
离线安装，把文件名换成手上实际的 whl：
pip install darra_ai-1.0.0-py3-none-win_amd64.whl
快速开始
from darra_ai import Session
with Session.open("model.darmodel") as s:
jpg = open("photo.jpg", "rb").read()
print(s.infer_image(jpg))
- 明文模型一行：with Session.open_plain("model.onnx") as s:，与 open 同一推理路径，明文无需授权。
- 结构化结果一行：r = s.infer_image_result(jpg)，同一份结果解成对象，不二次推理。
- 运行时阈值一行：opt = SessionOptions(conf_threshold=0.25)，打开时 Session.open_ex("model.darmodel", options=opt)。0 或不给 = 不覆盖。
按场景索引
| 案例 | 一句话能力 |
|---|---|
| 推理入门 | 打开会话、推理一张图、关闭的最小调用链 |
| 视频连续推理 | 相机逐帧进图，满队列丢最旧帧保最新画面 |
| 图片队列 | 一次上百张进队列，容量与溢出策略由应用定 |
| 并行推理 | 同模型多路并发，推理线程数独立可配 |
| 多模型并行 | 多模型或多卡分槽，按 Weight 分并发槽份额 |
运行时与诊断见 Runtime，失败码与修复建议见 错误码。
设备池
多张卡按每卡权重分活，不是插队。和同一张卡上的推理池不是一回事。 打开没成功：路径空抛 InternalError；文件不在、未激活、缺 Provider 抛 DarraError 子类；找不到库或运行库缺符号抛 DarraLoadError。不是关了再开。
from darra_ai import DevicePool
pool = DevicePool.open_plain("model.onnx")
ticket = pool.submit(jpg, gpu_device=-1)
pool.wait(ticket)
pool.close()