Images and Assets

图像与多模态资产 (Images & Assets)

English Version | 简体中文

---

TypeSafe AI Go SDK 全面支持多模态评估。您可以在 state、问题指令或判定准则中直接包含图像，结合 Noul、Choice、Score 进行视觉属性判断，或者通过 Box 原语在图像中进行精准的目标物体边界框检测。

---

快速上手示例

package main

import (
	"context"
	"fmt"
	"log"

	typesafe "github.com/guchengod/typesafe-sdk-go"
)

func main() {
	// 1. 初始化客户端并开启图像危险区标头
	client, err := typesafe.NewClient(typesafe.WithImages(true))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	// 2. 从本地文件加载图片
	photo, err := typesafe.NewImageFromFile("kitchen.jpg")
	if err != nil {
		log.Fatal(err)
	}

	// 3. 将图片直接置于 state 中发起多模态评估
	resp, err := client.SystemOne(
		context.Background(),
		map[string]any{
			"room":  "kitchen",
			"photo": photo, // SDK 会自动收集并序列化为引用 ID
		},
		typesafe.Questions{
			"has_cup": typesafe.NewNoul("`photo` 中是否有咖啡杯？"),
			"cup_box": typesafe.NewBox("`photo` 中的咖啡杯"),
		},
		typesafe.WithModel(typesafe.ModelJevPreview), // 多模态与 Box 推荐使用 jev-preview
	)
	if err != nil {
		log.Fatal(err)
	}

	// 4. 解析结果
	if resp.Nouls()["has_cup"].Noul > 0.8 {
		box := resp.Boxes()["cup_box"].Box
		fmt.Printf("检测到咖啡杯！边界框: Top=%.2f, Bottom=%.2f, Left=%.2f, Right=%.2f\n",
			box.Top, box.Bottom, box.Left, box.Right)
	}
}

---

图像结构与构造器

SDK 提供了 typesafe.Image 结构体，用于安全地封装图片二进制内容与格式规范：

type Image struct {
	Ref    string // 唯一引用标识符（如 "img-7f8e..."）
	Format string // 规范化格式 ("png" 或 "jpg")
	Data   []byte // 原始二进制字节
	Base64 string // 标准 Base64 编码字符串
}

1. 从文件加载 (NewImageFromFile)

自动读取文件内容，根据后缀名推断格式，并校验文件大小：

img, err := typesafe.NewImageFromFile("document.png")

2. 从字节切片创建 (NewImage)

自动生成全局唯一的 Ref 标识符：

img, err := typesafe.NewImage(rawBytes, "jpeg")

3. 自定义引用标识符 (NewImageWithRef)

指定业务相关的固定引用名称（如 "front_cover"、"id_card"）：

img, err := typesafe.NewImageWithRef("id_card", rawBytes, "png")

4. 从 Base64 字符串创建 (NewImageFromBase64)

img, err := typesafe.NewImageFromBase64("avatar", b64String, "png")

---

自动资产收集与引用机制

在底层 API 交互中，图片内容存放在请求体根目录的 assets 字典中，而在 state 内部则使用引用字符串（如 "img-01a2..."）进行指代。

Go SDK 将这一过程完全自动化：

1. 直接嵌入：您可以将 *typesafe.Image 直接作为字段放入结构体、Map、切片或多层嵌套对象中。
2. 透明序列化：Image 实现了 json.Marshaler，在 JSON 编码时自动输出为其对应的引用字符串 Ref。
3. 自动扫描提取：在调用 client.SystemOne 时，SDK 会自动深度递归扫描 state，将发现的所有 *Image 提取并挂载到请求体的 assets 字段中。

手动传递 Assets (WithAssets)

如果您的图片资产未直接存放在 state 中，亦可通过调用选项手动注入：

assets := typesafe.CollectAssets(img1, img2)

resp, err := client.SystemOne(ctx, state, questions,
	typesafe.WithAssets(assets),
)

WithAssets 支持传入 typesafe.Assets、map[string]typesafe.Asset 或 map[string]any。

---

危险区标头 (Danger Zone Header)

由于多模态处理涉及更密集的算力与更严格的风控规范，TypeSafe API 要求调用方显式确认开启图片特性：

• 客户端全局开启：

  client, err := typesafe.NewClient(typesafe.WithImages(true))

• 单次调用按需开启：

  resp, err := client.SystemOne(ctx, state, questions,
      typesafe.WithCallImages(true),
  )

该选项会在 HTTP 请求标头中注入 x-typesafe-images: true（服务端兼容 TypeSafe-Danger-Zone-Images: true）。若发送包含图片资产或 Box 问题的请求却未携带此标头，服务端将返回权限或参数校验错误。

---

规格与限制说明

限制项	限制值	触发时的行为
支持的图像格式	png、jpeg / jpg	传入 gif、webp 等其他格式会在客户端立即返回 *SDKError
单张图像大小上限	16 MiB (MaxImageSizeLimit)	超过 16 MiB 会在客户端构造 NewImage 时拦截，或由服务端返回 HTTP 413
完整请求体大小上限	32 MiB (MaxRequestBodyLimit)	超过 32 MiB 时，服务端返回 HTTP 413 *PayloadTooLargeError
推荐模型	jev-preview (ModelJevPreview)	具备最新的多模态图文对齐与目标定位支持