提交

提交一张图，拿 ticket，再 wait / try_wait 取结果 JSON。图像会被拷走，调用方可立即释放入参。Submit / Wait 永不收密码。

队列满时的策略见 InferOverflow。码 19（DARRA_BUSY）见 错误处理。

功能概览

类别	属性	类型	访问	说明
提交 / 等待	submit	int	方法	提交一张图。返回 ticket。图像会被拷走
	wait	dict	方法	等待结果 JSON。被 DROP_OLDEST 挤掉的票抛码 19
	try_wait	dict	方法	非阻塞。还没好抛码 19
	submit_async	Future	方法	异步糖：submit + 在执行器里 wait。须在事件循环里调用
调度	set_gpu_slots	None	函数	设置某张卡同时 InferImage 上限。slots=0 不限制

图像格式常量与 infer_image 相同，见 类型 · 图像格式。

提交 / 等待

submit()

def submit(
    self,
    image_bytes: bytes | bytearray | memoryview,
    *,
    format: int = IMAGE_AUTO,
    width: int = 0,
    height: int = 0,
    stride: int = 0,
) -> int

提交一张图。返回 ticket。图像会被拷走，调用方可立即释放入参。

参数:

• image_bytes (bytes | bytearray | memoryview) — 图像字节
• format (int) — 图像格式，默认 IMAGE_AUTO
• width (int) — 裸缓冲必须 >0，默认 0
• height (int) — 裸缓冲必须 >0，默认 0
• stride (int) — 每行字节数。0 = 紧凑排列（width × 3），默认 0

返回值:

• int — ticket（uint64，大于 0）

备注

IMAGE_AUTO / IMAGE_ENCODED：编码字节流，忽略宽高。IMAGE_RGB888 / IMAGE_BGR888：裸像素，必须给 width/height。缺宽高、stride < 0、长度不足、未知 format、或 image_bytes 类型不对 → InternalError（码 18）。overflow 为 FAIL 且队列满 → 码 19。可多线程 submit。

示例:

from darra_ai import IMAGE_AUTO, InferPool

with InferPool.open("model.darmodel") as pool:
    ticket = pool.submit(jpg, format=IMAGE_AUTO)

wait()

def wait(self, ticket: int) -> dict

等待结果 JSON（envelope 见 类型 · 推理结果）。

参数:

• ticket (int) — submit 返回的票

返回值:

• dict — 结果 JSON 对象。永不包含模型明文、密钥等任何敏感字节

备注

被 DROP_OLDEST 挤掉的票抛码 19（DARRA_BUSY）。本绑定没有独立 BusyError 子类，兜底为 DarraError，code 为 19。

示例:

result = pool.wait(ticket)

try_wait()

def try_wait(self, ticket: int) -> dict

非阻塞。还没好则抛忙（码 19，message 说明仍在队列 / 推理）。

参数:

• ticket (int) — submit 返回的票

返回值:

• dict — 结果 JSON 对象

备注

还没好 / 被挤掉都是码 19。调用方按 ex.code == 19 分支。

示例:

from darra_ai import DarraError

try:
    result = pool.try_wait(ticket)
except DarraError as ex:
    if ex.code == 19:
        pass  # 仍在队列或推理
    else:
        raise

submit_async()

def submit_async(
    self,
    image_bytes: bytes | bytearray | memoryview,
    *,
    format: int = IMAGE_AUTO,
    width: int = 0,
    height: int = 0,
    stride: int = 0,
)

异步糖：submit + 在执行器里 wait。图像会被拷走。

参数:

• 同 submit

返回值:

• asyncio.Future — 结果与 wait 相同（dict）

备注

须在正在跑的事件循环里调用。返回 Future，不是 coroutine。

示例:

result = await pool.submit_async(jpg, format=IMAGE_AUTO)

GPU 槽

set_gpu_slots()

def set_gpu_slots(gpu_device: int, slots: int) -> None

设置某张卡同时推理上限。对齐 darra_sched_set_gpu_slots。

参数:

• gpu_device (int) — 对应 SessionOptions.gpu_device
• slots (int) — 同时 InferImage 上限。0（默认）不限制

备注

slots 是并发推理槽，不是 CUDA SM%。4 卡：对 device 0..3 分别设槽。会加载 native。

示例:

from darra_ai import set_gpu_slots

set_gpu_slots(0, 2)

完整示例

突发 100 张：队列 ≥ 100，或 overflow=BLOCK。max_workers 硬顶 8。

from darra_ai import IMAGE_AUTO, InferOverflow, InferPool, InferPoolOptions

opt = InferPoolOptions(
    max_workers=2,
    queue_capacity=100,
    overflow=InferOverflow.FAIL,
)
jpg = open("photo.jpg", "rb").read()
with InferPool.open("model.darmodel", options=opt) as pool:
    tickets = [pool.submit(jpg, format=IMAGE_AUTO) for _ in range(100)]
    for t in tickets:
        handle(pool.wait(t))

摄像头保最新帧：overflow=DROP_OLDEST。被挤掉的票 wait 抛码 19。