Text Embeddings

Weaviate's integration with the Hugging Face Transformers library allows you to access their models' capabilities directly from Weaviate.

Configure a Weaviate vector index to use the Transformers integration, and configure the Weaviate instance with a model image, and Weaviate will generate embeddings for various operations using the specified model in the Transformers inference container. This feature is called the vectorizer.

At import time, Weaviate generates text object embeddings and saves them into the index. For vector and hybrid search operations, Weaviate converts text queries into embeddings.

Your Weaviate instance must be configured with the Hugging Face Transformers vectorizer integration (text2vec-transformers) module.

• Check the cluster metadata to verify if the module is enabled.
• Follow the how-to configure modules guide to enable the module in Weaviate.

To use this integration, configure the container image of the Hugging Face Transformers model and the inference endpoint of the containerized model.

The following example shows how to configure the Hugging Face Transformers integration in Weaviate:

services:
  weaviate:
    # Other Weaviate configuration
    environment:
      ENABLE_MODULES: text2vec-transformers # Enable this module
      TRANSFORMERS_INFERENCE_API: http://text2vec-transformers:8080  # Set the inference API endpoint
  text2vec-transformers:  # Set the name of the inference container
    image: cr.weaviate.io/semitechnologies/transformers-inference:sentence-transformers-multi-qa-MiniLM-L6-cos-v1
    environment:
      ENABLE_CUDA: 0  # Set to 1 to enable

modules:

  text2vec-transformers:

    enabled: true
    tag: sentence-transformers-paraphrase-multilingual-MiniLM-L12-v2
    repo: semitechnologies/transformers-inference
    registry: cr.weaviate.io
    envconfig:
      enable_cuda: true

As this integration runs a local container with the Transformers model, no additional credentials (e.g. API key) are required. Connect to Weaviate as usual, such as in the examples below.

Configure a Weaviate index as follows to use the Transformer inference container:

from weaviate.classes.config import Configureclient.collections.create(    "DemoCollection",    vector_config=[        Configure.Vectors.text2vec_transformers(            name="title_vector",            source_properties=["title"]        )    ],    # Additional parameters not shown)

await client.collections.create({  name: 'DemoCollection',  properties: [    {      name: 'title',      dataType: 'text' as const,    },  ],  vectorizers: [    weaviate.configure.vectors.text2VecTransformers({      name: 'title_vector',      sourceProperties: ['title'],    },    ),  ],  // Additional parameters not shown});

The following examples show how to configure Transformers-specific options.

Optionally, if your stack includes multiple inference containers, specify the inference container(s) to use with a collection.

If no parameters are specified, the default inference URL from the Weaviate configuration is used.

Specify inferenceUrl for a single inference container.

Specify passageInferenceUrl and queryInferenceUrl if using a DPR model.

• poolingStrategy: the pooling strategy to use when the input exceeds the model's context window.
  • Default: masked_mean. Allowed values: masked_mean or cls. (Read more on this topic.)

from weaviate.classes.config import Configureclient.collections.create(    "DemoCollection",    vector_config=[        Configure.Vectors.text2vec_transformers(            name="title_vector",            source_properties=["title"],            # Further options            pooling_strategy="masked_mean",            inference_url="<custom_transformers_url>",          # For when using multiple inference containers            # passage_inference_url="<custom_transformers_url>",  # For when using DPR models            # query_inference_url="<custom_transformers_url>",    # For when using DPR models        )    ],    # Additional parameters not shown)

await client.collections.create({
  name: 'DemoCollection',
  properties: [
    {
      name: 'title',
      dataType: 'text' as const,
    },
  ],
  vectorizers: [
    weaviate.configure.vectors.text2VecTransformers({
      name: 'title_vector',
      sourceProperties: ['title'],
      // Further options
      // poolingStrategy: 'masked_mean',
      // inferenceUrl: '<custom_transformers_url>',          // For when using multiple inference containers
      // passageInferenceUrl: `<custom_transformers_url>`,  // For when using DPR models
      // queryInferenceUrl: `<custom_transformers_url>`,    // For when using DPR models
    },
    ),
  ],
  // highlight-end
  // Additional parameters not shown
});

After configuring the vectorizer, import data into Weaviate. Weaviate generates embeddings for text objects using the specified model.

source_objects = [    {"title": "The Shawshank Redemption", "description": "A wrongfully imprisoned man forms an inspiring friendship while finding hope and redemption in the darkest of places."},    {"title": "The Godfather", "description": "A powerful mafia family struggles to balance loyalty, power, and betrayal in this iconic crime saga."},    {"title": "The Dark Knight", "description": "Batman faces his greatest challenge as he battles the chaos unleashed by the Joker in Gotham City."},    {"title": "Jingle All the Way", "description": "A desperate father goes to hilarious lengths to secure the season's hottest toy for his son on Christmas Eve."},    {"title": "A Christmas Carol", "description": "A miserly old man is transformed after being visited by three ghosts on Christmas Eve in this timeless tale of redemption."}]collection = client.collections.use("DemoCollection")with collection.batch.fixed_size(batch_size=200) as batch:    for src_obj in source_objects:        # The model provider integration will automatically vectorize the object        batch.add_object(            properties={                "title": src_obj["title"],                "description": src_obj["description"],            },            # vector=vector  # Optionally provide a pre-obtained vector        )        if batch.number_errors > 10:            print("Batch import stopped due to excessive errors.")            breakfailed_objects = collection.batch.failed_objectsif failed_objects:    print(f"Number of failed imports: {len(failed_objects)}")    print(f"First failed object: {failed_objects[0]}")

let srcObjects = [
  { title: "The Shawshank Redemption", description: "A wrongfully imprisoned man forms an inspiring friendship while finding hope and redemption in the darkest of places." },
  { title: "The Godfather", description: "A powerful mafia family struggles to balance loyalty, power, and betrayal in this iconic crime saga." },
  { title: "The Dark Knight", description: "Batman faces his greatest challenge as he battles the chaos unleashed by the Joker in Gotham City." },
  { title: "Jingle All the Way", description: "A desperate father goes to hilarious lengths to secure the season's hottest toy for his son on Christmas Eve." },
  { title: "A Christmas Carol", description: "A miserly old man is transformed after being visited by three ghosts on Christmas Eve in this timeless tale of redemption." }
];

Once the vectorizer is configured, Weaviate will perform vector and hybrid search operations using the Transformers inference container.

When you perform a vector search, Weaviate converts the text query into an embedding using the specified model and returns the most similar objects from the database.

The query below returns the n most similar objects from the database, set by limit.

collection = client.collections.use("DemoCollection")response = collection.query.near_text(    query="A holiday film",  # The model provider integration will automatically vectorize the query    limit=2)for obj in response.objects:    print(obj.properties["title"])

const collectionName = 'DemoCollection'
const myCollection = client.collections.use(collectionName)

When you perform a hybrid search, Weaviate converts the text query into an embedding using the specified model and returns the best scoring objects from the database.

The query below returns the n best scoring objects from the database, set by limit.

collection = client.collections.use("DemoCollection")response = collection.query.hybrid(    query="A holiday film",  # The model provider integration will automatically vectorize the query    limit=2)for obj in response.objects:    print(obj.properties["title"])

const collectionName = 'DemoCollection'
const myCollection = client.collections.use(collectionName)

Lists of pre-built Docker images for this integration are available in the tabs below. If you do not have a GPU available, we recommend using an ONNX-enabled image for CPU inference.

You can also build your own Docker image

We add new model support over time. For the latest list of available models, see the Docker Hub tags for the transformers-inference container.

As an alternative, you can run the inference container independently from Weaviate. To do so, follow these steps:

• Enable text2vec-transformers and omit text2vec-transformers container parameters in your Weaviate configuration
• Run the inference container separately, e.g. using Docker, and
• Use TRANSFORMERS_INFERENCE_API or inferenceUrl to set the URL of the inference container.

For example, run the container with Docker:

docker run -itp "8000:8080" semitechnologies/transformers-inference:sentence-transformers-multi-qa-MiniLM-L6-cos-v1

Then, set TRANSFORMERS_INFERENCE_API="http://localhost:8000". If Weaviate is part of the same Docker network, as a part of the same docker-compose.yml file, you can use the Docker networking/DNS, such as TRANSFORMERS_INFERENCE_API=http://text2vec-transformers:8080.

• Transformers multi-modal embedding models + Weaviate.
• Transformers reranker models + Weaviate.

This integration automatically chunks text if it exceeds the model's maximum token length before it is passed to the model. It will then return the pooled vectors.

See HuggingFaceVectorizer.vectorizer() for the exact implementation.

Once the integrations are configured at the collection, the data management and search operations in Weaviate work identically to any other collection. See the following model-agnostic examples:

• The How-to: Manage collections and How-to: Manage objects guides show how to perform data operations (i.e. create, read, update, delete collections and objects within them).
• The How-to: Query & Search guides show how to perform search operations (i.e. vector, keyword, hybrid) as well as retrieval augmented generation.

Each of the compatible models has its own license. For detailed information, review the license for the model you are using in the Hugging Face Model Hub.

It is your responsibility to evaluate whether the terms of its license(s), if any, are appropriate for your intended use.

To run the integration with a custom model, refer to the custom image guide.

• Hugging Face Model Hub

Have a question or feedback? Here's how to reach us.