insightface

README

go-insightface

go-insightface runs SCRFD face detection and ArcFace feature extraction from Go without CGO or OpenCV. It loads ONNX Runtime dynamically through onnxruntime-purego, keeps model weights outside the module, and includes an exact identity matcher for galleries of several thousand people.

Status

The initial backend targets Go 1.25+, ONNX Runtime 1.23.x (API 23), and CPU inference on Linux or macOS. The upstream runtime wrapper is pre-release, so it is pinned to a commit and isolated behind an internal adapter. Windows and GPU execution are not supported in the first release.

No model weights or biometric samples are included.

Install

go get github.com/lib-x/go-insightface

Assets can be supplied as ordinary files, downloaded during the calling application's build, or embedded by the calling application. This module does not contain or publish ONNX Runtime binaries or model weights. See asset provisioning and the model contract.

Asset provisioning

The existing file-path API remains the simplest option. To download verified assets during go generate, a Makefile, or a container build, create a manifest containing your licensed models:

{
  "detector": {
    "url": "https://models.example/detector.onnx",
    "sha256": "<64 lowercase hex characters>"
  },
  "recognizer": {
    "url": "https://models.example/recognizer.onnx",
    "sha256": "<64 lowercase hex characters>"
  }
}

Then run:

go run github.com/lib-x/go-insightface/cmd/insightface-assets@v0.2.0 \
  -manifest insightface-assets.json \
  -output ./faceassets/files

When runtime is omitted, the command selects the pinned official ONNX Runtime 1.23.2 archive for the target OS and architecture. Model URLs and SHA-256 values are always supplied by the caller. A verified bundle replaces the output as one serialized publish operation; the directory must be dedicated to this tool.

Embedding is opt-in and happens only in the calling application:

import (
    "context"
    "embed"

    insightface "github.com/lib-x/go-insightface"
    "github.com/lib-x/go-insightface/runtimefs"
)

//go:embed files
var bundled embed.FS

func newEngine(ctx context.Context) (*insightface.Engine, error) {
    source, err := runtimefs.New(bundled, "")
    if err != nil {
        return nil, err
    }
    return insightface.NewFromFS(ctx, insightface.Config{
        RuntimeLibrary:  "files/runtime/libonnxruntime.so.1.23.2",
        DetectorModel:   "files/models/detector.onnx",
        RecognizerModel: "files/models/recognizer.onnx",
    }, source)
}

Models are loaded directly from the embedded filesystem. The dynamic runtime library must be materialized into a content-addressed user cache because the operating-system loader requires a path. runtimefs is optional; applications that use New do not need it.

Detect and embed

package main

import (
	"context"
	"image/jpeg"
	"os"

	insightface "github.com/lib-x/go-insightface"
)

func run() error {
	file, err := os.Open("face.jpg")
	if err != nil {
		return err
	}
	defer file.Close()

	img, err := jpeg.Decode(file)
	if err != nil {
		return err
	}

	engine, err := insightface.New(insightface.Config{
		RuntimeLibrary:  "/opt/onnxruntime/lib/libonnxruntime.so.1.23.2",
		DetectorModel:   "/opt/models/detector.onnx",
		RecognizerModel: "/opt/models/recognizer.onnx",
	})
	if err != nil {
		return err
	}
	defer engine.Close()

	faces, err := engine.Analyze(context.Background(), img)
	if err != nil {
		return err
	}
	for _, face := range faces {
		_ = face.Detection.Score
		_ = face.Embedding.Values() // copied, L2-normalized values
	}
	return nil
}

Engine.Detect, Engine.Embed, and Engine.Analyze are safe for concurrent use. Close waits for in-flight calls and is idempotent. Context cancellation is checked at Go boundaries; the pinned upstream wrapper cannot interrupt a native inference that has already started.

Identity matching

Keep multiple good enrollment images per identity. Matching selects the best sample for each identity, then applies both a cosine-similarity threshold and a Top-1/Top-2 different-identity margin:

matcher, err := insightface.NewMatcher(insightface.MatcherConfig{
	MinSimilarity: 0.55, // example only: calibrate on deployment data
	MinMargin:     0.05,
}, gallery)
if err != nil {
	return err
}

result, err := matcher.Match(query)
if err != nil {
	return err
}
if result.Accepted {
	_ = result.Best.Identity
}

Do not treat cosine similarity as confidence or probability. Thresholds above are illustrative; calibrate them with deployment-specific FPIR/FNIR tests. The included benchmark covers 3,000 identities × 3 samples × 512 dimensions.

Model changes and historical data

An embedding is valid only in the model space that produced it. Store the model fingerprint/version next to every embedding. After changing the recognizer, regenerate historical embeddings from retained source images via an idempotent enrollment API, keep old/new galleries separate, and switch only after the new gallery is complete. Existing vectors cannot be mathematically converted to a different ArcFace model space.

Licensing and sensitive deployments

The library code is MIT licensed. Model weights have independent terms. InsightFace's officially distributed pretrained models are described as non-commercial research models; do not use those weights in military, government, commercial, or production environments without explicit licensing for the intended use. Use appropriately licensed or internally trained weights.

Face images and embeddings are biometric data. Review deployment and operational guidance before integration.

Verification

go test ./...
go test -race ./...
go vet ./...
go test -run '^$' -bench . -benchmem ./...

An end-to-end test accepts external models and a local face image:

ORT_LIBRARY=/path/libonnxruntime.so.1.23.2 \
DETECTOR_MODEL=/path/detector.onnx \
RECOGNIZER_MODEL=/path/recognizer.onnx \
FACE_IMAGE=/path/face.jpg \
go test -tags=integration -run TestEngineRunsLicensedExternalModels .

Set REFERENCE_RESULT=/path/reference.json to additionally compare the first detection and embedding with an independent implementation. The JSON object contains box ([left,top,right,bottom]), landmarks ([5][2]), and the raw or normalized embedding. Bounding boxes and landmarks use a one-pixel tolerance; embedding cosine must be at least 0.999. These external files are never committed by the project.

Documentation

Overview

Package insightface provides pure-Go image processing and dynamic ONNX Runtime loading for SCRFD face detection and ArcFace embeddings.

Model weights and the ONNX Runtime shared library are supplied by the application. Similarity scores returned by this package are cosine similarities, not probabilities.

Index

• Variables
• type Box
• type Config
• type Detection
• type Embedding
  • func NewEmbedding(raw []float32) (Embedding, error)
  • func (e Embedding) CosineSimilarity(other Embedding) (float32, error)
  • func (e Embedding) Dimension() int
  • func (e Embedding) Values() []float32
• type Engine
  • func New(config Config) (*Engine, error)
  • func NewFromFS(ctx context.Context, config Config, source runtimefs.FS) (*Engine, error)
  • func (e *Engine) Analyze(ctx context.Context, src image.Image) ([]Face, error)
  • func (e *Engine) Close() error
  • func (e *Engine) Detect(ctx context.Context, src image.Image) ([]Detection, error)
  • func (e *Engine) Embed(ctx context.Context, src image.Image, landmarks Landmarks) (Embedding, error)
• type Face
• type GalleryIdentity
• type Landmarks
• type MatchCandidate
• type MatchResult
• type Matcher
  • func NewMatcher(config MatcherConfig, gallery []GalleryIdentity) (*Matcher, error)
  • func (m *Matcher) Match(query Embedding) (MatchResult, error)
  • func (m *Matcher) MatchVector(raw []float32) (MatchResult, error)
  • func (m *Matcher) ReplaceGallery(gallery []GalleryIdentity) error
• type MatcherConfig
• type Point

Variables

var (
	ErrEmptyEmbedding             = errors.New("insightface: embedding is empty")
	ErrZeroNormEmbedding          = errors.New("insightface: embedding has zero L2 norm")
	ErrInvalidEmbeddingValue      = errors.New("insightface: embedding contains non-finite value")
	ErrEmbeddingDimensionMismatch = errors.New("insightface: embedding dimension mismatch")
)

var (
	ErrInvalidConfig    = errors.New("insightface: invalid engine config")
	ErrInvalidContext   = errors.New("insightface: context is nil")
	ErrInvalidImage     = errors.New("insightface: invalid image")
	ErrInvalidLandmarks = errors.New("insightface: invalid landmarks")
	ErrEngineClosed     = errors.New("insightface: engine is closed")
	ErrInitialization   = errors.New("insightface: engine initialization failed")
	ErrInference        = errors.New("insightface: model inference failed")
	ErrInvalidRuntimeFS = errors.New("insightface: runtime fs is nil")
)

var (
	ErrEmptyGallery         = errors.New("insightface: gallery is empty")
	ErrEmptyIdentity        = errors.New("insightface: identity is empty")
	ErrIdentityHasNoSample  = errors.New("insightface: identity has no samples")
	ErrDuplicateIdentity    = errors.New("insightface: duplicate identity")
	ErrInvalidMatcherConfig = errors.New("insightface: invalid matcher config")
	ErrNilMatcher           = errors.New("insightface: matcher is nil")
)

Types

type Box

type Box struct {
	Left   float32
	Top    float32
	Right  float32
	Bottom float32
}

type Config

type Config struct {
	RuntimeLibrary      string
	DetectorModel       string
	RecognizerModel     string
	DetectorInputWidth  int
	DetectorInputHeight int
	DetectionThreshold  float32
	NMSThreshold        float32
	IntraOpThreads      int
}

Config identifies the ONNX Runtime library and the two model files. DetectionThreshold and NMSThreshold default to 0.5 and 0.4 when zero. DetectorInputWidth and DetectorInputHeight default to 640 when zero.

type Detection

type Detection struct {
	Score     float32
	Box       Box
	Landmarks Landmarks
}

type Embedding

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

Embedding is an immutable, L2-normalized face embedding.

func NewEmbedding

func NewEmbedding(raw []float32) (Embedding, error)

NewEmbedding validates, copies, and L2-normalizes a raw embedding vector.

func (Embedding) CosineSimilarity

func (e Embedding) CosineSimilarity(other Embedding) (float32, error)

CosineSimilarity returns the cosine similarity between two normalized embeddings.

func (Embedding) Dimension

func (e Embedding) Dimension() int

Dimension returns the embedding dimensionality.

func (Embedding) Values

func (e Embedding) Values() []float32

Values returns a copy of the normalized embedding values.

type Engine

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

Engine owns the ONNX Runtime environment and detector/recognizer sessions. Its inference methods are safe for concurrent use.

func New

func New(config Config) (*Engine, error)

func NewFromFS

func NewFromFS(ctx context.Context, config Config, source runtimefs.FS) (*Engine, error)

NewFromFS creates an Engine whose model files and runtime library are read from source. Models are loaded directly from source; the runtime library is materialized because operating-system dynamic loaders require a file path. Config path fields are interpreted as fs.ValidPath names in source.

func (*Engine) Analyze

func (e *Engine) Analyze(ctx context.Context, src image.Image) ([]Face, error)

func (*Engine) Close

func (e *Engine) Close() error

Close waits for in-flight inference, then releases both sessions and the ONNX Runtime environment. Repeated calls return the first close result.

func (*Engine) Detect

func (e *Engine) Detect(ctx context.Context, src image.Image) ([]Detection, error)

func (*Engine) Embed

func (e *Engine) Embed(ctx context.Context, src image.Image, landmarks Landmarks) (Embedding, error)

type Face

type Face struct {
	Detection Detection
	Embedding Embedding
}

type GalleryIdentity

type GalleryIdentity struct {
	ID      string
	Samples []Embedding
}

GalleryIdentity stores all enrolled samples for one identity.

type Landmarks

type Landmarks [5]Point

type MatchCandidate

type MatchCandidate struct {
	Identity    string
	Similarity  float32
	SampleIndex int
	Found       bool
}

MatchCandidate is an identity-level search candidate.

type MatchResult

type MatchResult struct {
	Best                MatchCandidate
	SecondBestDifferent MatchCandidate
	Margin              float32
	Accepted            bool
}

MatchResult contains the best identity, second-best different identity, and acceptance decision.

type Matcher

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

Matcher performs exact identity-level search over an immutable gallery snapshot.

func NewMatcher

func NewMatcher(config MatcherConfig, gallery []GalleryIdentity) (*Matcher, error)

NewMatcher validates the configuration and installs a copied gallery snapshot.

func (*Matcher) Match

func (m *Matcher) Match(query Embedding) (MatchResult, error)

Match searches the gallery using a normalized query embedding.

func (*Matcher) MatchVector

func (m *Matcher) MatchVector(raw []float32) (MatchResult, error)

MatchVector validates and normalizes a raw query vector before matching.

func (*Matcher) ReplaceGallery

func (m *Matcher) ReplaceGallery(gallery []GalleryIdentity) error

ReplaceGallery swaps the matcher gallery with a copied immutable snapshot.

type MatcherConfig

type MatcherConfig struct {
	MinSimilarity float32
	MinMargin     float32
}

MatcherConfig controls similarity and margin acceptance for identity matching.

type Point

type Point struct {
	X float32
	Y float32
}