Home

TypeSafe AI Go SDK — Wiki

English Version | 简体中文

---

TypeSafe AI 官方 Go 语言客户端 SDK —— 用于对任意文本、结构化 JSON 数据或多模态图像进行确定性定性判断、分类评级与目标定位（System One 定性决策模型）。

单次调用即可并发评估数十个问题，直接获取校准概率、分类标签、分值以及边界框坐标，无需解析和清洗自由格式的大模型文本。

client, err := typesafe.NewClient(
    typesafe.WithImages(true), // 开启多模态与 Box 目标检测支持
)
if err != nil {
	log.Fatal(err)
}
defer client.Close()

// 发起 SystemOne 评估
response, err := client.SystemOne(ctx, state, typesafe.Questions{
	"billing": typesafe.NewNoul("该内容是否与账单或退款相关？"),
	"queue": typesafe.NewChoice(
		map[string]any{"billing": "财务或退款", "technical": "技术故障", "other": nil},
		typesafe.WithInstructions("该工单应指派到哪个队列？"),
	),
	"urgency": typesafe.NewScore(
		[]any{"日常处理", "48小时内处理", "紧急立即处理"},
		typesafe.WithInstructions("客户情绪和紧急程度如何？"),
	),
	"target": typesafe.NewBox("定位图片中的主要目标物体"),
}, typesafe.WithModel(typesafe.ModelJevPreview))

---

指南目录

页面	说明
使用场景 (Use Cases)	典型应用（工单分流、内容风控、Agent 守卫等）及完整端到端示例
核心问题原语 (Questions)	Noul（二元）、Choice（多分类）、Score（评级打分）、Box（目标检测）以及原始自定义问题
图像与多模态资产 (Images & Assets)	Image 构造、自动资产收集、Danger Zone 标头、多模态目标定位与限制规格
响应结果处理 (Responses)	响应结构体、分组访问器（Nouls()、Choices()、Scores()、Boxes()）、可空 Token 统计及严格解码规则
自定义响应模型 (Custom Response Models)	使用 SystemOneAs[T] 泛型直解自定义业务结构体
CLI 命令行工具 (CLI)	纯标准库打造的 typesafe 命令行：安装、常用参数、输出格式与退出码
配置选项 (Configuration)	客户端全局配置、环境变量、Gzip 自动压缩、Danger Zone 与每调用局部重载
重试策略 (Retry Policy)	智能指数退避、抖动算法、Retry-After 服务端提示遵守及重试预算
错误处理 (Errors)	强类型错误层次体系、HTTP 413/415/429/529 状态码映射与匹配助手
日志与脱敏 (Logging)	基于 log/slog 的结构化日志记录与敏感凭证自动脱敏机制
安全机制 (Security)	凭证脱敏、受保护请求头、URL 净化、禁止危险重定向、16 MB 响应上限与 TLS 配置
并发控制 (Concurrency)	客户端多 Goroutine 安全共享、有界并发信号量与上下文取消生命周期
示例程序 (Examples)	仓库内置的可运行代码示例导引

---

规格一览

属性	说明
Go 模块	github.com/guchengod/typesafe-sdk-go
最低版本要求	Go 1.26 或更高
外部依赖	零依赖（仅使用标准库 net/http、encoding/json、log/slog）
API 密钥	环境变量 TYPESAFE_API_KEY，或选项 typesafe.WithAPIKey
服务端点	POST /v1/systemone，GET /v1/models
数据压缩	请求体 $\ge 1\text{ KiB}$ 自动透明启用 Gzip 压缩（WithCompression(true)）
多模态规格	支持 PNG/JPEG，单张上限 16 MiB，整包请求上限 32 MiB
API 参考文档	pkg.go.dev
发布版本	Releases

---

一分钟理解核心概念

单次核心调用 SystemOne 围绕 State 评估一组 Questions：

• State（上下文内容）：问题所指向的判定对象。可以是任意能序列化为 JSON 的值：字符串、结构体、Map、切片或内嵌 *typesafe.Image 图像资产。例如一封客服邮件、一段用户输入、一个工单工件、数据库记录或产品截图。
• Assets（多模态资产）：可选的图片资产字典。当 State 中包含 *typesafe.Image 时，SDK 会通过 CollectAssets 自动扫描提取并在序列化时替换为引用。
• Questions（问题集合）：以问题名称（自定义字符串）为键的 Map。名称应以业务决策目的命名（如 "is_spam"、"queue"、"urgency"、"cup_box"）。
• Answers（判定结果）：包含对应名称答案的响应对象，答案的数据类型与问题的原语类型天然严格对应。同时返回实际应答的模型标识以及 Token 统计信息。