sagemaker

Documentation

Overview

Package sagemaker provides an Amazon SageMaker implementation of retrieval.RepresentationEncoder for endpoints running a handler that speaks agentic.representations.v1.

The runtime invocation is the same for a real-time endpoint and a serverless one: infrastructure mode is deployment configuration, not a different API. SigV4, credentials, regions, and role policy stay with the AWS SDK and the deployment.

Vector spaces

An opaque endpoint cannot prove its own weights revision, so a deployment whose output you intend to keep supplies the descriptor with WithVectorSpaces. A space the handler reports must match what is pinned; a kind it leaves undescribed is filled from the pin. Without either, the response has no usable space and is rejected rather than stored under an identity nobody can verify.

Index

• type Encoder
  • func MustNew(ctx context.Context, endpointName string, opts ...Option) *Encoder
  • func New(ctx context.Context, endpointName string, opts ...Option) (*Encoder, error)
  • func (e *Encoder) Capabilities() retrieval.RepresentationCapabilities
  • func (e *Encoder) Embed(ctx context.Context, req *retrieval.EmbeddingRequest) (*retrieval.EmbeddingResponse, error)
  • func (e *Encoder) Encode(ctx context.Context, req *retrieval.RepresentationRequest) (*retrieval.RepresentationResponse, error)
  • func (e *Encoder) ModelMetadata() core.ModelMetadata
  • func (e *Encoder) Name() string
• type InvocationError
  • func (e *InvocationError) Error() string
  • func (e *InvocationError) Unwrap() error
• type InvokeAPI
• type Option
  • func WithAWSConfig(cfg aws.Config) Option
  • func WithBatchSize(size int) Option
  • func WithClient(client InvokeAPI) Option
  • func WithCredentials(accessKeyID, secretAccessKey, sessionToken string) Option
  • func WithInferenceComponent(name string) Option
  • func WithLimits(limits retrieval.RepresentationLimits) Option
  • func WithMaxResponseBytes(limit int) Option
  • func WithModel(model string) Option
  • func WithOutputs(kinds ...retrieval.RepresentationKind) Option
  • func WithProfile(profile string) Option
  • func WithRegion(region string) Option
  • func WithTargetModel(name string) Option
  • func WithTargetVariant(name string) Option
  • func WithVectorSpaces(spaces map[retrieval.RepresentationKind]retrieval.VectorSpace) Option

Types

type Encoder

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

Encoder invokes a SageMaker endpoint that speaks agentic.representations.v1.

func MustNew

func MustNew(ctx context.Context, endpointName string, opts ...Option) *Encoder

MustNew is like New but panics on error.

func New

func New(ctx context.Context, endpointName string, opts ...Option) (*Encoder, error)

New creates an encoder for a SageMaker endpoint.

Example:

encoder, err := sagemaker.New(ctx, "bge-m3-endpoint",
    sagemaker.WithRegion("us-east-1"),
    sagemaker.WithModel("BAAI/bge-m3"),
    sagemaker.WithVectorSpaces(spaces),
)

func (*Encoder) Capabilities

func (e *Encoder) Capabilities() retrieval.RepresentationCapabilities

Capabilities implements retrieval.RepresentationEncoder.

func (*Encoder) Embed

func (e *Encoder) Embed(ctx context.Context, req *retrieval.EmbeddingRequest) (*retrieval.EmbeddingResponse, error)

Embed implements retrieval.Embedder by requesting dense output only.

func (*Encoder) Encode

func (e *Encoder) Encode(ctx context.Context, req *retrieval.RepresentationRequest) (*retrieval.RepresentationResponse, error)

Encode implements retrieval.RepresentationEncoder.

func (*Encoder) ModelMetadata

func (e *Encoder) ModelMetadata() core.ModelMetadata

ModelMetadata reports semantic provider identity. The AWS SDK owns runtime endpoint resolution, so server fields remain unknown.

func (*Encoder) Name

func (e *Encoder) Name() string

Name implements retrieval.RepresentationEncoder. It reports the configured model name, falling back to the endpoint name, because an endpoint is a deployment rather than a model and may not name one.

type InvocationError

type InvocationError struct {
	// Endpoint is the SageMaker endpoint name.
	Endpoint string

	// RequestID is the AWS request ID, when the SDK reported one.
	RequestID string

	// Err is the underlying SDK error.
	Err error
}

InvocationError reports a failed InvokeEndpoint call.

It carries the endpoint name and the AWS request ID so a failure can be correlated with CloudWatch, and nothing from the payload: an inference error message quotes the input that produced it.

func (*InvocationError) Error

func (e *InvocationError) Error() string

func (*InvocationError) Unwrap

func (e *InvocationError) Unwrap() error

type InvokeAPI

type InvokeAPI interface {
	InvokeEndpoint(
		ctx context.Context,
		params *sagemakerruntime.InvokeEndpointInput,
		optFns ...func(*sagemakerruntime.Options),
	) (*sagemakerruntime.InvokeEndpointOutput, error)
}

InvokeAPI is the slice of the SageMaker Runtime client this package uses.

It is an interface so that transport behavior can be driven deterministically in tests without an AWS account, a network, or a signed request.

type Option

type Option func(*config)

Option configures the Encoder.

func WithAWSConfig

func WithAWSConfig(cfg aws.Config) Option

WithAWSConfig uses an already-resolved AWS config, so an application that centralizes credential loading does not resolve it twice.

func WithBatchSize

func WithBatchSize(size int) Option

WithBatchSize splits requests larger than size into that many inputs per invocation. Zero, the default, sends the batch as one payload.

SageMaker caps an InvokeEndpoint payload at 6 MB for a real-time endpoint, so a large batch of long documents needs a batch size whether or not the model would have accepted it.

func WithClient

func WithClient(client InvokeAPI) Option

WithClient injects the SageMaker Runtime client, bypassing AWS config resolution. It is how transport tests run without credentials.

func WithCredentials

func WithCredentials(accessKeyID, secretAccessKey, sessionToken string) Option

WithCredentials sets static credentials. Prefer the default credential chain; this exists for callers who already hold short-lived credentials.

func WithInferenceComponent

func WithInferenceComponent(name string) Option

WithInferenceComponent targets a specific inference component on a multi-model endpoint.

func WithLimits

func WithLimits(limits retrieval.RepresentationLimits) Option

WithLimits overrides the request and response size ceilings.

func WithMaxResponseBytes

func WithMaxResponseBytes(limit int) Option

WithMaxResponseBytes caps the response payload this encoder will decode (default 64 MiB).

func WithModel

func WithModel(model string) Option

WithModel records the model name the endpoint serves, used when the handler reports none.

func WithOutputs

func WithOutputs(kinds ...retrieval.RepresentationKind) Option

WithOutputs declares which representation kinds this endpoint serves (default all three, matching the reference handler).

func WithProfile

func WithProfile(profile string) Option

WithProfile selects a shared-configuration profile.

func WithRegion

func WithRegion(region string) Option

WithRegion sets the AWS region. If not set, AWS_DEFAULT_REGION and then AWS_REGION are used.

func WithTargetModel

func WithTargetModel(name string) Option

WithTargetModel selects the model artifact on a multi-model endpoint.

func WithTargetVariant

func WithTargetVariant(name string) Option

WithTargetVariant pins the production variant to invoke, for a deliberate A/B comparison rather than the endpoint's own traffic split.

func WithVectorSpaces

func WithVectorSpaces(spaces map[retrieval.RepresentationKind]retrieval.VectorSpace) Option

WithVectorSpaces pins the vector spaces this endpoint encodes into. See the package documentation for why an opaque endpoint needs them.