{"id":6678,"library":"instructorembedding","title":"InstructorEmbeddings","description":"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.","status":"active","version":"1.0.1","language":"en","source_language":"en","source_url":"https://github.com/HKUNLP/instructor-embedding","tags":["nlp","embeddings","sentence-transformers","deep-learning"],"install":[{"cmd":"pip install InstructorEmbedding","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"Core dependency for loading and encoding sentence models.","package":"sentence-transformers"},{"reason":"Underlying deep learning framework for model execution.","package":"torch"},{"reason":"Hugging Face library for model architecture and tokenizer loading.","package":"transformers"}],"imports":[{"symbol":"INSTRUCTOR","correct":"from InstructorEmbedding import INSTRUCTOR"}],"quickstart":{"code":"from InstructorEmbedding import INSTRUCTOR\n\n# Initialize the model (downloads 'hkunlp/instructor-xl' on first use)\nmodel = INSTRUCTOR('hkunlp/instructor-xl')\n\n# Define the instruction and the sentence to embed\ninstruction = \"Represent the document for retrieval:\"\nsentence = \"This is a document about machine learning.\"\n\n# Generate embedding (can also take a list of sentences)\n# For optimal performance, ensure a relevant instruction is provided.\nembeddings = model.encode([[instruction, sentence]])\n\nprint(f\"Embedding shape: {embeddings.shape}\")\nprint(f\"First 5 dimensions: {embeddings[0,:5]}\")","lang":"python","description":"Initialize an INSTRUCTOR model, provide a suitable instruction, and encode text to generate embeddings. The model will be downloaded on first use."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Initialize the model with `device='cuda'` if a GPU is available: `model = INSTRUCTOR('hkunlp/instructor-xl', device='cuda')`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}