Skip to content

embedding.md

Latest commit

 

History

History
251 lines (169 loc) · 6.56 KB

embedding.md

File metadata and controls

251 lines (169 loc) · 6.56 KB

embedding

import "github.com/Aleph-Alpha/std/v1/embedding"

Package embedding provides a unified, high-level API for computing text embeddings through the Aleph Alpha inference service.

Overview

The package exposes a single public entrypoint, Client, which hides all low-level HTTP details, endpoint paths, authentication, and model-specific behavior.

A client is constructed using:

client, err := embedding.NewClient(cfg)

Once created, the client can generate embeddings via:

client.Create(ctx, "model-name", "hello")

or batch embeddings via:

client.Create(ctx, "model-name", "a", "b", "c")

This package exclusively supports OpenAI-compatible embeddings via the /v1/embeddings endpoint.

Configuration

Configuration is sourced from environment variables and constructed by:

cfg := embedding.NewConfig()

Required variables:

  • EMBEDDING_ENDPOINT Base URL of the inference service (no trailing path or slash).

  • EMBEDDING_SERVICE_TOKEN Internal PHARIA service token for authentication.

Optional variables:

  • EMBEDDING_HTTP_TIMEOUT_SECONDS Request timeout (default: 30 seconds).

Configuration correctness can be verified via:

if err := cfg.Validate(); err != nil { ... }

Dependency Injection \(Fx\)

A ready-to-use Fx module is provided:

embedding.FXModule

which supplies:

  • *embedding.Config
  • *embedding.Client

and registers a lifecycle hook to clean up HTTP resources on shutdown.

Example:

app := fx.New(
    embedding.FXModule,
    fx.Invoke(func(c *embedding.Client) {
        // Use embeddings
    }),
)

Summary

The embedding package provides:

  • A clean, stable API for OpenAI-compatible embeddings.
  • A no-leak abstraction over the Aleph Alpha inference service.

Usage:

client := embedding.NewClient(cfg)
client.Create(ctx, "model-name", texts...)

Index

Variables

FXModule wires the embedding system into Fx.

It provides:

  • Config (NewConfig)
  • Provider (via provider factory)
  • *Client (NewClient)
  • Lifecycle hook (RegisterEmbeddingLifecycle)
var FXModule = fx.Module(
    "embedding",

    fx.Provide(
        NewConfig,
        NewClient,
    ),

    fx.Invoke(RegisterEmbeddingLifecycle),
)

func RegisterEmbeddingLifecycle

func RegisterEmbeddingLifecycle(lc fx.Lifecycle, client *Client)

RegisterEmbeddingLifecycle ensures that the Client (and its provider) are properly cleaned up on application shutdown.

type Client

Client is the public entrypoint for computing embeddings.

It hides all provider details (inference endpoints, HTTP, etc.) from the application layer.

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

func NewClient

func NewClient(cfg *Config) (*Client, error)

NewClient constructs a Client from Config. It validates the config and internally constructs the inference provider. Application code should depend on *Client, not on Provider or inferenceProvider.

func (*Client) Close

func (c *Client) Close() error

Close allows the client to release any internal resources used by the provider. Currently this is a no-op unless the provider implements Close().

func (*Client) Create

func (c *Client) Create(ctx context.Context, token, model string, texts ...string) ([][]float64, error)

Create executes an embedding request for one or more texts.

type Config

type Config struct {
    // Inference endpoint and auth
    Endpoint     string // Base URL of the Aleph Alpha inference API
    HTTPTimeoutS int    // HTTP timeout seconds (default 30)
}

func NewConfig

func NewConfig() *Config

NewConfig reads from environment variables.

func (*Config) Validate

func (c *Config) Validate() error

Validate ensures required fields are present.

type InferenceProvider

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

func (*InferenceProvider) Create

func (p *InferenceProvider) Create(ctx context.Context, token, model string, texts ...string) ([][]float64, error)

Create generates embeddings for the given texts using the specified model. It uses the OpenAI-compatible /v1/embeddings endpoint.

type Provider

Provider contract

type Provider interface {
    // Create generates embeddings for the given texts using the specified model.
    Create(ctx context.Context, token, model string, texts ...string) ([][]float64, error)
}

Generated by gomarkdoc