Box（框选题）

Box（框选题）是 System One 的一种题型，用于识别某物在图像中的位置。答案是包住目标的矩形的四条边，以图像宽高的比例表示。

非官方中文翻译 · 内容以英文原文 ↗ 为准 · 同步于 2026-10-15

当需要知道某物在图像中的位置时，就用 Box：台面上的马克杯、扫描表单上的签名、门口的人。答案是边界框，即包住目标的最小矩形，由四条边给出。Box 题型需要在请求中带一张图片；发送方式见 Images。Box 题型需要 Jev 1.14，请将 model 设为 jev-preview 或 jev-1.14.0。

每条边都是图像尺寸的比例，从左上角开始度量。left 与 right 是宽度的比例，top 与 bottom 是高度的比例，因此同一份答案在任何尺寸的图像下都适用。

请求结构

一道 Box 题型包含两个字段：

type：恒为 "box"。
instructions：要找什么，以及在哪张图里。它不一定要写成问句；「the coffee mug in photo」就够了。

Box 不使用 criteria。下面的请求在一张厨房照片中找一个马克杯，图片以文件部件（file part）形式发送，并带上图像请求头：

bash

curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "TypeSafe-Danger-Zone-Images: true" \
  -F 'request={
    "model": "jev-preview",
    "state": {"photo": "6e1d0b7c-kitchen"},
    "assets": {"6e1d0b7c-kitchen": {"type": "image", "part": "kitchen-photo"}},
    "questions": {
      "mug": {"type": "box", "instructions": "the coffee mug in `photo`"}
    }
  };type=application/json' \
  -F 'kitchen-photo=@kitchen.jpg;type=image/jpeg'

若要把图片以 base64 编码放进 JSON 请求体中，或使用 SDK 进行上传，请见 Uploading images。

同一个请求中，可以把 Box 题型与其他题型混合使用，所有题目都基于同一份 state（上下文状态）进行评判。

响应结构

json

{
  "model": "jev-1.14.0",
  "answers": {
    "mug": {
      "type": "box",
      "box": {
        "top": 0.25,
        "bottom": 0.82,
        "left": 0.44,
        "right": 0.84
      },
      "confidence": 0.92
    }
  },
  "usage": {"input_tokens": 290, "output_tokens": 21}
}

每个 Box 答案包含以下几个值：

type：该答案对应的 TypeSafe 题型。
box：四条边，分别为 top、bottom、left、right，每条取值为 0 到 1。left 小于 right，top 小于 bottom。
confidence：0 到 1 之间的数值，越大表示模型对答案越有把握。详见使用置信度。

读取 Box 答案

要把框画到图像上，或按框裁剪图像，只需把每条边乘以图像对应的宽或高（像素）：

python

from PIL import Image

image = Image.open("kitchen.jpg")
width, height = image.size
mug = response["answers"]["mug"]
edges = mug["box"]

box = (
    round(edges["left"] * width),
    round(edges["top"] * height),
    round(edges["right"] * width),
    round(edges["bottom"] * height),
)
image.crop(box).save("mug.jpg")

使用置信度

如何依据 Box 的 confidence（置信度）采取行动，由你的应用决定。一个常见的做法是设定一个阈值（threshold），对低于阈值的答案给予更多关注。目前还没有推荐阈值，请基于自己的图像自行调参。当 confidence 低于你的阈值时，可以：

用更好的图重问一次。 发送更大尺寸的图像，或将框周围区域裁剪出来，在更高分辨率下重问同一道 Box 题。在大图中找小目标的思路见编写 Box 题目。
裁剪前先扩展边界框。 当裁剪框绝不能切掉目标的任何一部分时，先把每条边向外推再裁剪。
用边缘问题复核边界框。 询问目标是否延伸到某条边之外，详见用边缘问题复核边界框。

下面这段代码会在 confidence 低于阈值时扩展边界框，并保证框始终留在图像内：

python

PAD = 0.05  # Fraction of the image to add on each side. Tune for your images.
MIN_CONFIDENCE = 0.6  # Example threshold. Tune it on your own images.

if mug["confidence"] < MIN_CONFIDENCE:
    edges = {
        "left": max(0.0, edges["left"] - PAD),
        "top": max(0.0, edges["top"] - PAD),
        "right": min(1.0, edges["right"] + PAD),
        "bottom": min(1.0, edges["bottom"] + PAD),
    }

然后用扩展后的 edges，按前面的代码裁剪即可。

编写 Box 题目

点明目标与所在图像。 「The coffee mug in photo」既指明要找什么，也指明在哪张图里找。当请求中有多张图像时，反引号里的路径用于指定搜索哪一张。

目标也可以是另一张图片。 直接把目标图的引用写在 instructions（指令）里即可：

json

"instructions": "the person in `photo` who matches this badge photo: 9a21c7d3-badge"

Box 答案永远是框。 没有「未找到」之类的回答，所以 Box 所问的目标即便不存在，也会返回一组四条边。在同一个请求里，再加一道 Noul，先判断目标在不在图中；当 Noul 答案偏低时，忽略对应的 Box 即可：

json

"questions": {
  "mug_visible": {"type": "noul", "instructions": "Is there a coffee mug in `photo`?"},
  "mug": {"type": "box", "instructions": "the coffee mug in `photo`"}
}

一道题只返回一个框。 Box 的设计目标就是定位单一目标，每个答案都是单独的框。要找多个不同目标时，请在同一个请求中为每个目标各起一道 Box 题。当图中可能有多个同类目标时，可以用语言限定到你想要的那一个，例如「the mug nearest the sink in photo」。当语言难以区分时，在 Box 旁再加一道 Choice（选择题），选项为 none、one、several。当答案为 several 时，将图像划分为多个区域，分别再问一次。

大图先裁再找小目标。 在非常大的图中，几十像素宽的小目标很容易漏检。可以先用一道 Choice 把图像分成若干图块作为选项，先把范围定位到某一块；然后在该图块上问 Box 题，再把它的四条边换算回整张图的比例。

用边缘问题复核边界框

要判断某个框是否切掉了目标的一部分，可以先裁到框的范围内，对每条边各发一道 Noul 提问，例如「Does the mug in crop continue past the left edge of the image?」。对 Noul 答案为「是」的边，向外推之后再问一次。

在 36 张裁掉已知目标的画作样本上测试，四道边缘问题能捕获其中 30 处裁切；单问一句「Is all of the mug inside crop?」能捕获 26 处；若把边界框作为轮廓画在整张图上再提问，则只能捕获 20 处。

本文档由 Mintlify 构建并托管——它是一个面向开发者的文档平台。