structured

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 24, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

概述

包 structured 提供结构化输出的 Schema 建模、生成、解析与校验能力。

该包用于约束 LLM 输出格式，降低自由文本导致的解析失败风险。 当 Provider 支持原生结构化输出时自动启用，否则回退到 Prompt Engineering。

核心接口

  • StructuredOutputProvider — 扩展 llm.Provider，声明是否支持原生结构化输出
  • SchemaValidator — 对 JSON 数据按 JSONSchema 进行字段级校验

主要类型

  • JSONSchema — 完整的 JSON Schema 定义，支持 object/array/enum/组合关键词
  • StructuredOutput[T] — 泛型结构化输出处理器，自动生成 Schema 并驱动 LLM 生成
  • SchemaGenerator — 通过反射从 Go 类型生成 JSONSchema，支持 jsonschema 标签
  • DefaultValidator — 内置格式校验（email/uri/uuid/datetime/ipv4 等）
  • ParseResult[T] / ParseError / ValidationErrors — 解析与校验结果

典型用法 

so, _ := structured.NewStructuredOutput[MyStruct](provider)
result, _ := so.Generate(ctx, "提取用户信息")

// 或使用自定义 Schema
so2, _ := structured.NewStructuredOutputWithSchema[MyStruct](provider, schema)
pr, _ := so2.GenerateWithParse(ctx, prompt)
if !pr.IsValid() { // 处理校验错误 }

主要能力

  • Schema 建模：定义对象、数组、枚举及约束规则
  • 结构化生成：引导模型按指定结构输出，支持原生模式与 Prompt 回退
  • 结果校验：对输出进行字段级校验与错误报告
  • 反射生成：从 Go struct 标签自动推导 JSONSchema

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AdditionalProperties 

type AdditionalProperties struct {
	Allowed bool
	Schema  *JSONSchema
}

附加Properties 代表额外的Properties字段,可以是 或布林克或计划。

func (*AdditionalProperties) MarshalJSON 

func (ap *AdditionalProperties) MarshalJSON() ([]byte, error)

JSON警长执行JSON。 增产元帅.

func (*AdditionalProperties) UnmarshalJSON 

func (ap *AdditionalProperties) UnmarshalJSON(data []byte) error

UnmarshalJSON 执行json。 (原始内容存档于2018-10-21). Unmarshaler for Purposities.

type DefaultValidator 

type DefaultValidator struct {
	// contains filtered or unexported fields
}

默认变量是 SchemaValidator 的默认执行.

func NewValidator 

func NewValidator() *DefaultValidator

NewValidator 创建了带有内置格式验证符的新默认变量.

func (*DefaultValidator) RegisterFormat 

func (v *DefaultValidator) RegisterFormat(format StringFormat, validator func(string) bool)

RegisterFormat 注册自定义格式验证符 。

func (*DefaultValidator) Validate 

func (v *DefaultValidator) Validate(data []byte, schema *JSONSchema) error

校验组对照一个计划验证JSON数据.

type JSONSchema 

type JSONSchema struct {
	// 核心元数据
	Schema      string `json:"$schema,omitempty"`
	ID          string `json:"$id,omitempty"`
	Ref         string `json:"$ref,omitempty"`
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`

	// 类型定义
	Type SchemaType `json:"type,omitempty"`

	// 对象属性
	Properties           map[string]*JSONSchema `json:"properties,omitempty"`
	Required             []string               `json:"required,omitempty"`
	AdditionalProperties *AdditionalProperties  `json:"additionalProperties,omitempty"`
	MinProperties        *int                   `json:"minProperties,omitempty"`
	MaxProperties        *int                   `json:"maxProperties,omitempty"`
	PatternProperties    map[string]*JSONSchema `json:"patternProperties,omitempty"`
	PropertyNames        *JSONSchema            `json:"propertyNames,omitempty"`

	// 矩阵项目
	Items       *JSONSchema   `json:"items,omitempty"`
	PrefixItems []*JSONSchema `json:"prefixItems,omitempty"`
	Contains    *JSONSchema   `json:"contains,omitempty"`
	MinItems    *int          `json:"minItems,omitempty"`
	MaxItems    *int          `json:"maxItems,omitempty"`
	UniqueItems *bool         `json:"uniqueItems,omitempty"`
	MinContains *int          `json:"minContains,omitempty"`
	MaxContains *int          `json:"maxContains,omitempty"`

	// 凸起和凸起
	Enum  []any `json:"enum,omitempty"`
	Const any   `json:"const,omitempty"`

	// 字符串制约
	MinLength *int         `json:"minLength,omitempty"`
	MaxLength *int         `json:"maxLength,omitempty"`
	Pattern   string       `json:"pattern,omitempty"`
	Format    StringFormat `json:"format,omitempty"`

	// 数字限制
	Minimum          *float64 `json:"minimum,omitempty"`
	Maximum          *float64 `json:"maximum,omitempty"`
	ExclusiveMinimum *float64 `json:"exclusiveMinimum,omitempty"`
	ExclusiveMaximum *float64 `json:"exclusiveMaximum,omitempty"`
	MultipleOf       *float64 `json:"multipleOf,omitempty"`

	// 默认值
	Default any `json:"default,omitempty"`

	// 实例
	Examples []any `json:"examples,omitempty"`

	// 组成关键词
	AllOf []*JSONSchema `json:"allOf,omitempty"`
	AnyOf []*JSONSchema `json:"anyOf,omitempty"`
	OneOf []*JSONSchema `json:"oneOf,omitempty"`
	Not   *JSONSchema   `json:"not,omitempty"`

	// 有条件的关键词
	If   *JSONSchema `json:"if,omitempty"`
	Then *JSONSchema `json:"then,omitempty"`
	Else *JSONSchema `json:"else,omitempty"`

	// 重复使用的定义
	Defs map[string]*JSONSchema `json:"$defs,omitempty"`
}

JSONSchema代表了JSON Schema的定义. 它支持嵌入对象,阵列,enum以及各种验证约束.

func FromJSON 

func FromJSON(data []byte) (*JSONSchema, error)

从JSON 解析出一个计划 从JSON。

func NewArraySchema 

func NewArraySchema(items *JSONSchema) *JSONSchema

NewArraySchema 创建一个带有指定项目 schema 的新阵列计划.

func NewBooleanSchema 

func NewBooleanSchema() *JSONSchema

NewBooleanSchema 创建了一个新的布尔计划.

func NewEnumSchema 

func NewEnumSchema(values ...any) *JSONSchema

NewEnumSchema 创建一个带有指定值的新的enumschema.

func NewIntegerSchema 

func NewIntegerSchema() *JSONSchema

NewIntegerSchema创建了新的整数计划.

func NewNumberSchema 

func NewNumberSchema() *JSONSchema

NumberSchema创建了新的编号Schema.

func NewObjectSchema 

func NewObjectSchema() *JSONSchema

新对象计划创建了新对象计划.

func NewSchema 

func NewSchema(t SchemaType) *JSONSchema

NewSchema创建了具有指定类型的新的JSONSchema.

func NewStringSchema 

func NewStringSchema() *JSONSchema

NewStringSchema创建了一个新的字符串Schema.

func (*JSONSchema) AddProperty 

func (s *JSONSchema) AddProperty(name string, prop *JSONSchema) *JSONSchema

添加 Property 为对象计划添加属性。

func (*JSONSchema) AddRequired 

func (s *JSONSchema) AddRequired(names ...string) *JSONSchema

添加所需的字段名称到对象计划 。

func (*JSONSchema) Clone 

func (s *JSONSchema) Clone() *JSONSchema

克隆人创造出一个深层的复制图案.

func (*JSONSchema) GetProperty 

func (s *JSONSchema) GetProperty(name string) *JSONSchema

GetProperty 以名称返回财产计划 。

func (*JSONSchema) HasProperty 

func (s *JSONSchema) HasProperty(name string) bool

是否有财产 。

func (*JSONSchema) IsRequired 

func (s *JSONSchema) IsRequired(name string) bool

如果需要财产,则需要进行检查。

func (*JSONSchema) ToJSON 

func (s *JSONSchema) ToJSON() ([]byte, error)

JSON将计划序列化为JSON.

func (*JSONSchema) ToJSONIndent 

func (s *JSONSchema) ToJSONIndent() ([]byte, error)

给JSON缩进序列化计划为JSON缩入.

func (*JSONSchema) WithAdditionalProperties 

func (s *JSONSchema) WithAdditionalProperties(allowed bool) *JSONSchema

附加物业设置附加物业约束.

func (*JSONSchema) WithAdditionalPropertiesSchema 

func (s *JSONSchema) WithAdditionalPropertiesSchema(schema *JSONSchema) *JSONSchema

附加的PropertiesSchema将附加的Properties设定为一个 schema.

func (*JSONSchema) WithConst 

func (s *JSONSchema) WithConst(value any) *JSONSchema

用 Const 设置 Const 值 。

func (*JSONSchema) WithDefault 

func (s *JSONSchema) WithDefault(def any) *JSONSchema

With Default 设置了默认值并返回用于链路的图案.

func (*JSONSchema) WithDescription 

func (s *JSONSchema) WithDescription(desc string) *JSONSchema

使用Description 设置描述并返回链路的策略 。

func (*JSONSchema) WithEnum 

func (s *JSONSchema) WithEnum(values ...any) *JSONSchema

用 Enum 设置 enum 值 。

func (*JSONSchema) WithExamples 

func (s *JSONSchema) WithExamples(examples ...any) *JSONSchema

以实例设置示例并返回链条的图案。

func (*JSONSchema) WithExclusiveMaximum 

func (s *JSONSchema) WithExclusiveMaximum(max float64) *JSONSchema

With Exclusive Maximum 为数值计设置了独有的最大值.

func (*JSONSchema) WithExclusiveMinimum 

func (s *JSONSchema) WithExclusiveMinimum(min float64) *JSONSchema

以排除最小值设置数值计的专属最小值。

func (*JSONSchema) WithFormat 

func (s *JSONSchema) WithFormat(format StringFormat) *JSONSchema

用Format设置字符串计划的格式。

func (*JSONSchema) WithMaxItems 

func (s *JSONSchema) WithMaxItems(max int) *JSONSchema

With Max Projects为阵列计划设定了最大项目.

func (*JSONSchema) WithMaxLength 

func (s *JSONSchema) WithMaxLength(max int) *JSONSchema

通过MaxLength设定了字符串计划的最大长度.

func (*JSONSchema) WithMaxProperties 

func (s *JSONSchema) WithMaxProperties(max int) *JSONSchema

与MaxProperties设定对象计划的最大属性.

func (*JSONSchema) WithMaximum 

func (s *JSONSchema) WithMaximum(max float64) *JSONSchema

使用 Maximum 设置了数值计数的最大值 。

func (*JSONSchema) WithMinItems 

func (s *JSONSchema) WithMinItems(min int) *JSONSchema

With Min Projects 为阵列计划设定最小项目 。

func (*JSONSchema) WithMinLength 

func (s *JSONSchema) WithMinLength(min int) *JSONSchema

通过MinLength设定了字符串计划的最低长度.

func (*JSONSchema) WithMinProperties 

func (s *JSONSchema) WithMinProperties(min int) *JSONSchema

与 MinProperties 设定对象方案的最低属性 。

func (*JSONSchema) WithMinimum 

func (s *JSONSchema) WithMinimum(min float64) *JSONSchema

以最小值设定数值方案的最低值。

func (*JSONSchema) WithMultipleOf 

func (s *JSONSchema) WithMultipleOf(val float64) *JSONSchema

MultipleOf 设置了数值图的多 Of 约束。

func (*JSONSchema) WithPattern 

func (s *JSONSchema) WithPattern(pattern string) *JSONSchema

WithPattern设定了字符串计划的模式.

func (*JSONSchema) WithTitle 

func (s *JSONSchema) WithTitle(title string) *JSONSchema

使用 Title 设置标题并返回用于连锁的图案 。

func (*JSONSchema) WithUniqueItems 

func (s *JSONSchema) WithUniqueItems(unique bool) *JSONSchema

独有的项目设置了数组计划唯一的项目限制 。

type ParseError 

type ParseError struct {
	Path    string `json:"path"`
	Message string `json:"message"`
}

ParseError 代表着与字段路径的校验错误 。

func (*ParseError) Error 

func (e *ParseError) Error() string

执行错误接口出错 。

type ParseResult 

type ParseResult[T any] struct {
	Value  *T           `json:"value,omitempty"`
	Raw    string       `json:"raw"`
	Errors []ParseError `json:"errors,omitempty"`
}

ParseResult代表了解析结构化输出的结果.

func (*ParseResult[T]) IsValid 

func (r *ParseResult[T]) IsValid() bool

IsValid 如果解析成功且没有出错, 则返回为真 。

type SchemaGenerator 

type SchemaGenerator struct {
	// contains filtered or unexported fields
}

SchemaGenerator利用反射从Go类型生成了JSON Schema.

func NewSchemaGenerator 

func NewSchemaGenerator() *SchemaGenerator

NewSchemaGenerator创建了一个新的SchemaGenerator实例.

func (*SchemaGenerator) GenerateSchema 

func (g *SchemaGenerator) GenerateSchema(t reflect.Type) (*JSONSchema, error)

生成Schema从Go类型生成一个JSON Schema. 它支持结构、切片、地图、指针和基本类型。 Struct字段可以使用"json"标记来表示字段名称和"jsonschema"标记来表示验证限制.

支持的 jsonschema 标签选项 :

  • 所需:按需要标出字段
  • enum=a,b,c: enum值
  • 最小=0:数字的最低值
  • 最大值=100:数字的最大值
  • minLength=1:最小字符串长度
  • 最大Length=100:最大字符串长度 -图案QQ[a-z]+美元:字符串的正则图案 -格式=电子邮件:字符串格式(电子邮件、uri、uuid、日期-时间等)
  • 分钟项目=1:最小数组项目
  • 最大项目=10:最大数组项目
  • 说明=: 实地说明
  • 默认=.: 默认值

func (*SchemaGenerator) GenerateSchemaFromValue 

func (g *SchemaGenerator) GenerateSchemaFromValue(v any) (*JSONSchema, error)

生成SchemaFromValue 从一个值的类型生成一个JSON Schema. 这是一个从一个值中提取类型的便利函数.

type SchemaType 

type SchemaType string

SchemaType代表JSON Schema类型. 

const (
	TypeString  SchemaType = "string"
	TypeNumber  SchemaType = "number"
	TypeInteger SchemaType = "integer"
	TypeBoolean SchemaType = "boolean"
	TypeNull    SchemaType = "null"
	TypeObject  SchemaType = "object"
	TypeArray   SchemaType = "array"
)

type SchemaValidator 

type SchemaValidator interface {
	Validate(data []byte, schema *JSONSchema) error
}

SchemaValidator对照一个JSONSchema验证了JSON数据.

type StringFormat 

type StringFormat string

StringFormat 代表常见的字符串格式限制. 

const (
	FormatDateTime StringFormat = "date-time"
	FormatDate     StringFormat = "date"
	FormatTime     StringFormat = "time"
	FormatEmail    StringFormat = "email"
	FormatURI      StringFormat = "uri"
	FormatUUID     StringFormat = "uuid"
	FormatHostname StringFormat = "hostname"
	FormatIPv4     StringFormat = "ipv4"
	FormatIPv6     StringFormat = "ipv6"
)

type StructuredOutput 

type StructuredOutput[T any] struct {
	// contains filtered or unexported fields
}

结构化输出是一个通用结构化输出处理器,生成 LLM 提供者的类型安全输出。

func NewStructuredOutput 

func NewStructuredOutput[T any](provider llm.Provider) (*StructuredOutput[T], error)

NewStructuredOutput为T型创建了新的结构化输出处理器. 它从类型参数中自动生成了JSON Schema.

func NewStructuredOutputWithSchema 

func NewStructuredOutputWithSchema[T any](provider llm.Provider, schema *JSONSchema) (*StructuredOutput[T], error)

NewStructured Output With Schema 创建了自定义的自定义计划的新结构化输出处理器.

func (*StructuredOutput[T]) Generate 

func (s *StructuredOutput[T]) Generate(ctx context.Context, prompt string) (*T, error)

生成从快取字符串生成结构化输出 。 它使用本地结构输出 如果提供者支持它, 否则会回到即时工程

func (*StructuredOutput[T]) GenerateWithMessages 

func (s *StructuredOutput[T]) GenerateWithMessages(ctx context.Context, messages []llm.Message) (*T, error)

生成 Messages 从信件列表中生成结构化输出 。 它使用本地结构输出 如果提供者支持它, 否则会回到即时工程

func (*StructuredOutput[T]) GenerateWithMessagesAndParse 

func (s *StructuredOutput[T]) GenerateWithMessagesAndParse(ctx context.Context, messages []llm.Message) (*ParseResult[T], error)

生成与Messages AndParse 从消息中生成结构化输出并返回详细解析结果.

func (*StructuredOutput[T]) GenerateWithParse 

func (s *StructuredOutput[T]) GenerateWithParse(ctx context.Context, prompt string) (*ParseResult[T], error)

生成 WithParse 生成结构化输出并返回详细解析结果 。

func (*StructuredOutput[T]) Parse 

func (s *StructuredOutput[T]) Parse(jsonStr string) (*T, error)

解析将 JSON 字符串解析为目标类型,并进行验证。

func (*StructuredOutput[T]) ParseWithResult 

func (s *StructuredOutput[T]) ParseWithResult(jsonStr string) *ParseResult[T]

ParseWithResult 解析出 JSON 字符串并返回详细结果 。

func (*StructuredOutput[T]) Schema 

func (s *StructuredOutput[T]) Schema() *JSONSchema

Schema返回用于验证的JSON Schema.

func (*StructuredOutput[T]) ValidateValue 

func (s *StructuredOutput[T]) ValidateValue(value *T) error

校验Value 对照 schema 验证一个值 。

type StructuredOutputProvider 

type StructuredOutputProvider interface {
	llm.Provider
	// 如果提供者支持本地结构输出, 则支持StructuredOutput 返回 true 。
	SupportsStructuredOutput() bool
}

结构输出输出输出扩展为 llm. 提供商具有结构化输出能力检测. 支持本土结构输出(如OpenAI的JSON模式)的提供商应当执行.

type ValidationErrors 

type ValidationErrors struct {
	Errors []ParseError `json:"errors"`
}

校验错误( Errors) 代表多个校验错误.

func (*ValidationErrors) Error 

func (e *ValidationErrors) Error() string

执行错误接口出错 。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.