ngnn-general-encoder-v1

NGNN general encoder v1

This repository distributes the fixed NGNN compressor used by steffen-negabo/ngnn-general-encoder-v1. The complete encoder calls the user's OpenAI text-embedding-3-large API, normalizes each 3072-dimensional base vector, and independently compresses it to 512 float32 values. It accepts previously unseen text and runs the compressor locally on CPU.

The compressor weights and inference library are MIT licensed. OpenAI's base weights are not distributed; API access and its terms remain the caller's responsibility. This is not a fully open-weight embedding model. The NGNN training algorithm, optimizer and training data are not part of this release.

Inference

Install the versioned ngnn-encoder library from PyPI:

python -m pip install ngnn-encoder==0.1.0

The public inference repository contains source, usage and release evidence. The library's NgnnGeneralEncoder.from_pretrained(repo_id, revision=commit_sha) method downloads config.json and model.npz at a full immutable Hub commit, checks the configuration and artifact SHA-256, then creates the provider. The library requires CPU inference with PyTorch 2.11.0 to preserve top-k tie behavior. Load the published immutable artifact commit:

from ngnn_encoder import NgnnGeneralEncoder

repo_id = "steffen-negabo/ngnn-general-encoder-v1"
hub_commit = "bab7d30011438e52f22be540067c73ca37f462eb"
model = NgnnGeneralEncoder.from_pretrained(repo_id, revision=hub_commit)
vectors = model.encode(["A previously unseen sentence.", "Another sentence."])
assert vectors.shape == (2, 512)

This Hub commit pins the distributed files. It is separate from the canonical MTEB revision below. Configuration and weight checks reject a different model.

Set OPENAI_API_KEY locally through the environment. Calls to encode make billable OpenAI embedding requests. Keep credentials out of model kwargs: MTEB serializes those kwargs into experiment metadata.

Empty or whitespace-only strings return local zero vectors. Nonempty inputs are limited to 8,191 cl100k_base tokens. The encoder enforces both request item and total token limits. No cached benchmark texts or vectors are needed for inference.

Artifact and model identity

The Hub commit is a distribution coordinate. It does not replace the canonical MTEB revision or change the evaluated model. The original public weights and weights in this repository have the same SHA-256. The revision mapping connects the evaluation label to the canonical submission revision.

Training provenance and limitations

The local compressor was fit on an archived FineWeb calibration split. Evaluation texts were used as exclusion inputs, not as compressor fitting data. The OpenAI base model's training data are unknown; no claim of an empty training dataset or known total parameter count is made.

The local weights and transform are fixed, but the externally managed OpenAI model alias is not an immutable provider snapshot. Future provider changes can affect embeddings. These results cover four English tasks; no global MTEB aggregate or general multilingual performance is claimed.

Evaluation

Evaluation used native MTEB 2.20.10 at upstream commit ed47a25455157433b458db2625e72960468597ab on September 6, 2026.

NGNN scores below both controls on all four tasks. Both 512D variants use 2,048 float32 bytes per vector, compared with 12,288 bytes for raw 3072D. These measurements do not show an advantage over the provider's native dimensionality reduction. Archived raw responses and fresh native512 responses were obtained at different times under the provider alias. Original STSBenchmark retains its evaluated identity despite its v2 successor.

The evaluation manifest and exact results record task, data, source and result hashes. The historical cache-only ngnn-sparse-v1-api study is a separate model; its scores do not describe this general encoder.

The model implementation PR and four-task results PR are submissions for review. Publishing this artifact does not establish official MTEB acceptance.