Registry / ai-ml / instructorembedding

instructorembedding

library1.0.1pypypiunverified

InstructorEmbeddings is a Python library that simplifies the generation of high-quality text embeddings using the INSTRUCTOR family of models. It's built upon `sentence-transformers` and Hugging Face `transformers`, providing an easy-to-use interface to leverage instruction-tuned embeddings. Currently at version 1.0.1, it has an active development status with releases as new models or features are integrated.

ai-ml llm-agents

pip install InstructorEmbedding

github ↗package ↗

INSTALL

IMPORT

SIG · INSTRUCTOREMBEDDIN

instructorembedding

ai-mlpythonv1.0.1

Install

1.5s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.5s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

INSTRUCTOR

✓ from InstructorEmbedding import INSTRUCTOR

✗ from InstructorEmbedding import INSTRUCTOR

Initialize an INSTRUCTOR model, provide a suitable instruction, and encode text to generate embeddings. The model will be downloaded on first use.

from InstructorEmbedding import INSTRUCTOR # Initialize the model (downloads 'hkunlp/instructor-xl' on first use) model = INSTRUCTOR('hkunlp/instructor-xl') # Define the instruction and the sentence to embed instruction = "Represent the document for retrieval:" sentence = "This is a document about machine learning." # Generate embedding (can also take a list of sentences) # For optimal performance, ensure a relevant instruction is provided. embeddings = model.encode([[instruction, sentence]]) print(f"Embedding shape: {embeddings.shape}") print(f"First 5 dimensions: {embeddings[0,:5]}")

Debug

Known issues

gotchaThe `INSTRUCTOR` model initializes by downloading potentially large model files (several GBs for `instructor-xl`) from Hugging Face on its first use. This can be slow and requires an active internet connection.

fix

Be prepared for an initial download time. For offline use, pre-download models or manage the cache directory with `HUGGINGFACE_HUB_CACHE` environment variable.

affects: All versions

gotchaBy default, the model may run on CPU if a GPU is not detected or explicitly specified. For large models like `instructor-xl`, CPU inference can be extremely slow. Explicitly set the device for better performance.

fix

Initialize the model with `device='cuda'` if a GPU is available: `model = INSTRUCTOR('hkunlp/instructor-xl', device='cuda')`.

affects: All versions

gotchaModels like `instructor-xl` are very large (5 billion parameters) and require significant VRAM (e.g., 24GB+). Users with less powerful GPUs may encounter Out-of-Memory (OOM) errors.

fix

Consider using smaller models from the INSTRUCTOR family (e.g., `hkunlp/instructor-large`, `hkunlp/instructor-base`) or implement batching/quantization if supported, or ensure sufficient GPU memory is available.

affects: All versions

gotchaThe 'Instructor' models are designed to be instruction-tuned. Providing a clear and relevant `instruction` during the `encode` call is crucial for achieving optimal embedding quality and performance for your specific task. Omitting or using a generic instruction might lead to suboptimal results.

fix

Always provide a task-specific instruction as the first element in the input list (e.g., `model.encode([['instruction', 'sentence']])`). Refer to the official documentation for instruction examples for various tasks.

affects: All versions

Upgrade

Version history

1.0.1latest on PyPI · released May 26, 2023

Audit

Dependencies

sentence-transformersrequiredCore dependency for loading and encoding sentence models.

torchrequiredUnderlying deep learning framework for model execution.

transformersrequiredHugging Face library for model architecture and tokenizer loading.

Agent activity

31 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/HKUNLP/instructor-embedding ↗

packagehttps://pypi.org/project/instructorembedding/ ↗