InstructorEmbeddings

1.0.1 · active · verified Wed Apr 15

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.

Warnings

gotcha The `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.
gotcha By 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')`.
gotcha Models 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.
gotcha The '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.

Install

pip install InstructorEmbedding Install via pip

Imports

INSTRUCTOR

from InstructorEmbedding import INSTRUCTOR

Quickstart

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]}")

view raw JSON →