Documentation
¶
Overview ¶
Package embedding defines provider-independent embedding generation contracts, vectors, request options, and results.
Implement Generator to integrate an embedding service. Use Generate for a single input, GenerateVector for its vector, or GenerateAndZip to pair a batch of inputs with their embeddings. Generators and their wrappers must support concurrent calls; inputs and options must be treated as read-only. Bind adapts a typed generator to BoundGenerator for heterogeneous callers while preserving its declared input and output types.
An Embedding contains metadata and a statically typed Vector. Numeric vectors use VectorOf, and bit vectors use Binary. Their slices are borrowed, not copied. Of and GeneratedOf are shorthands for numeric embeddings and their batches. Embedding[Vector] holds vectors polymorphically. Embeddings support encoding/json directly in fields, slices, and Generated results.
Index ¶
- func Generate[TInput, TEmbedding any](ctx context.Context, generator Generator[TInput, TEmbedding], value TInput, ...) (TEmbedding, error)
- func GenerateVector[TElement, TInput any](ctx context.Context, generator Generator[TInput, *Of[TElement]], value TInput, ...) ([]TElement, error)
- type Binary
- type BoundGenerator
- type Embedding
- type Generated
- type GeneratedOf
- type Generator
- type Of
- type Options
- type Pair
- type Vector
- type VectorOf
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Generate ¶
func Generate[TInput, TEmbedding any](ctx context.Context, generator Generator[TInput, TEmbedding], value TInput, options *Options) (TEmbedding, error)
Generate generates exactly one embedding. A nil generator or input is invalid. It returns an error if the generator returns a nil result, the wrong number of embeddings, or a nil embedding. Interface nil checks do not reject typed nil values.
func GenerateVector ¶
func GenerateVector[TElement, TInput any](ctx context.Context, generator Generator[TInput, *Of[TElement]], value TInput, options *Options) ([]TElement, error)
GenerateVector generates a single embedding and returns its vector without copying it. The generator's output determines the vector element type.
Types ¶
type Binary ¶
type Binary []bool
Binary is a bit vector with one bool per dimension. The slice is borrowed, not copied. Its zero value is empty. JSON encodes it as a string of '0' and '1' characters.
func (Binary) Dimensions ¶
Dimensions returns the number of bits in the vector.
func (Binary) MarshalJSON ¶
MarshalJSON encodes the bits as a binary string.
func (*Binary) UnmarshalJSON ¶
UnmarshalJSON decodes a binary string. Invalid bits or non-string values return an error without changing the receiver.
type BoundGenerator ¶
type BoundGenerator struct {
// contains filtered or unexported fields
}
BoundGenerator adapts a typed Generator to Generator[any, any] while retaining its declared input and output types. Create it with Bind; its zero value is invalid for generation. A binding is immutable and can be shared across callers. It borrows the generator and does not close it or expose its optional interfaces.
func Bind ¶
func Bind[I, E any](generator Generator[I, E]) *BoundGenerator
Bind binds generator's input and output types without changing the generator. It panics if generator is nil. Interface nil checks do not reject typed nil values. The generator must support concurrent calls.
Example ¶
generator := &testGenerator[string, *embedding.Of[float32]]{
generate: func(_ context.Context, values []string, _ *embedding.Options) (*embedding.GeneratedOf[float32], error) {
return &embedding.GeneratedOf[float32]{
Embeddings: []*embedding.Of[float32]{{Vector: embedding.VectorOf[float32]{float32(len(values[0]))}}},
}, nil
},
}
binding := embedding.Bind(generator)
result, err := binding.Generate(context.Background(), []any{"hello"}, nil)
if err != nil {
panic(err)
}
fmt.Println(binding.InputType())
fmt.Println(result.Embeddings[0].(*embedding.Of[float32]).Vector)
Output: string [5]
func (*BoundGenerator) EmbeddingType ¶
func (g *BoundGenerator) EmbeddingType() reflect.Type
EmbeddingType returns the generator's declared embedding output type, or nil for an uninitialized binding.
func (*BoundGenerator) Generate ¶
func (g *BoundGenerator) Generate(ctx context.Context, values []any, options *Options) (*Generated[any], error)
Generate checks all inputs before making one call to the typed generator. Each input must satisfy InputType without conversion; an untyped nil is invalid. Typed nils are forwarded normally. Nil and empty slices remain distinct, and empty batches are forwarded to the generator rather than short-circuited.
Context and options are forwarded unchanged. The input and output slices are shallow copies; records, embeddings, usage, and additional properties are not cloned. Provider results and errors, including partial results, are preserved. A pre-canceled context, nil binding, or zero-value binding returns an error without invoking the generator.
func (*BoundGenerator) InputType ¶
func (g *BoundGenerator) InputType() reflect.Type
InputType returns the generator's declared input type, or nil for an uninitialized binding.
type Embedding ¶
type Embedding[TVector Vector] struct { CreatedAt time.Time `json:",omitzero"` ModelID string `json:",omitzero"` AdditionalProperties map[string]any `json:",omitzero"` Vector TVector }
Embedding contains a vector and metadata about its generation. TVector specifies the vector representation, such as VectorOf[float32] or Binary. Use Vector for a polymorphic vector. Its zero value uses TVector's zero value.
Example ¶
package main
import (
"encoding/json"
"fmt"
"github.com/microsoft/agent-framework-go/embedding"
)
func main() {
e := embedding.Of[float32]{
ModelID: "text-embedding-3-small",
Vector: embedding.VectorOf[float32]{0.1, 0.2, 0.3},
}
data, err := json.Marshal(e)
if err != nil {
panic(err)
}
var result embedding.Of[float32]
if err := json.Unmarshal(data, &result); err != nil {
panic(err)
}
fmt.Println(result.Dimensions())
}
Output: 3
func (*Embedding[TVector]) Dimensions ¶
Dimensions returns the vector's dimensions, or zero if Vector is nil.
func (Embedding[TVector]) MarshalJSON ¶
MarshalJSON encodes the embedding with a Type discriminator for VectorOf[uint8], VectorOf[int8], VectorOf[float32], VectorOf[float64], or Binary. Other vector types return an error. A nil Vector is encoded as null without a discriminator.
func (*Embedding[TVector]) UnmarshalJSON ¶
UnmarshalJSON decodes an embedding using its Type discriminator. Unknown types, vectors incompatible with TVector, and invalid vectors return an error without changing the receiver. An absent type is valid only for an absent or null vector. Numeric vectors may be null, but individual coordinates must not be null. JSON null leaves the receiver unchanged; other valid payloads replace it.
type Generated ¶
type Generated[TEmbedding any] struct { Embeddings []TEmbedding Usage *message.UsageDetails `json:",omitzero"` AdditionalProperties map[string]any `json:",omitzero"` }
Generated contains an ordered batch of embeddings and generation metadata. Use ordinary slice operations to inspect and modify Embeddings. The zero value represents an empty result. Usage is nil when no usage was reported.
type GeneratedOf ¶
GeneratedOf is an alias for Generated[*Of[T]], a batch of pointers to numeric embeddings with vector elements of type T.
type Generator ¶
type Generator[TInput, TEmbedding any] interface { Generate(ctx context.Context, values []TInput, options *Options) (*Generated[TEmbedding], error) }
Generator generates one embedding for each input, preserving input order. Implementations must support concurrent requests, honor context cancellation, validate provider-specific constraints, and treat input slices, input values, and options as read-only. Nil and empty input slices both represent an empty batch.
TEmbedding specifies the output representation. Use *Of[T] for a statically typed numeric vector, *Embedding[Vector] for a polymorphic vector, or a custom output type.
type Of ¶
Of is an alias for Embedding[VectorOf[T]], an embedding with a numeric vector of T elements.
type Options ¶
type Options struct {
// Dimensions requests a vector size. Nil uses the provider default.
// Explicit zero is preserved. Supported values are provider-specific.
Dimensions *int `json:",omitzero"`
// ModelID overrides the generator's default model. Nil leaves it unchanged.
ModelID *string `json:",omitzero"`
AdditionalProperties map[string]any `json:",omitzero"`
// RawRepresentationFactory creates provider-specific request options for
// the supplied generator.
// Providers may modify the returned value, so return a fresh instance on
// each call. Providers apply the other Options fields to that instance.
RawRepresentationFactory func(any) any `json:"-"`
}
Options configures an embedding generation request. Nil options use provider defaults. Generators must not mutate the options; use Options.Clone when changes are needed.
type Pair ¶
type Pair[TInput, TEmbedding any] struct { Value TInput Embedding TEmbedding }
Pair associates an input value with its generated embedding.
func GenerateAndZip ¶
func GenerateAndZip[TInput, TEmbedding any](ctx context.Context, generator Generator[TInput, TEmbedding], values []TInput, options *Options) ([]Pair[TInput, TEmbedding], error)
GenerateAndZip generates embeddings and pairs them with inputs in order. An empty input returns an empty, non-nil slice without invoking the generator. A result count different from the input count returns an error.
type Vector ¶
type Vector interface {
Dimensions() int
}
Vector represents the data in an embedding.
type VectorOf ¶
type VectorOf[T any] []T
VectorOf is a numeric vector with one T per dimension. The slice is borrowed, not copied; modifying its elements modifies any embedding that uses it. Its zero value is empty. Embedding JSON supports uint8, int8, float32, and float64 elements. Other element types can be used in memory.
func (VectorOf[T]) Dimensions ¶
Dimensions returns the number of elements in the vector.
Source Files