Integrate Hugging Face Serverless as an embedding provider

Astra vectorize integrations can automatically generate embeddings for data in collections and tables in Serverless (vector) databases. For more information about how vectorize works, see Manage embedding provider integrations for vectorize.

This guide explains how to configure the Hugging Face Serverless integration, and then add it to a collection or table.

Prepare your Hugging Face Serverless account

To use the Hugging Face Serverless embedding provider integration, you need the following:

A paid Hugging Face Serverless account.

At least one Hugging Face Serverless user access token with unrestricted access to the API.

Don’t remove or restrict the user access token in your Hugging Face Serverless account after you add it to Astra. This can break the integration. For more information about managing, rotating, and removing credentials, see Manage embedding provider integrations for vectorize.

Enable the integration in your Astra organization

Before you can use the Hugging Face Serverless integration in a collection or table, you must enable the integration in your Astra organization and authorize a Serverless (vector) database to use it.

Recommended: Create a Serverless (vector) database if you don’t already have one.

You can enable the integration without any Serverless (vector) databases. However, you cannot add the integration to any collections or tables until you authorize a Serverless (vector) database to use the integration. This is handled through the integration’s settings, as described in the following steps. To fully enable and test a vectorize integration, you need at least one Serverless (vector) database.
In the Astra Portal header, click Settings.
In the Settings navigation menu, make sure the enterprise/organization filter is set to the organization that you want to manage.

If the organization belongs to an enterprise, you must filter on the enterprise, and then click the organization name in the Organizations list.
In the Settings navigation menu, click Integrations.
Click the Hugging Face Serverless Embedding provider tile.
Click Add integration.
For User access token name, enter a unique, meaningful label that provides a brief, clear description of the credential. For example, prod-support-chat-created-oct-2026 or webstore-test-jira-1234.

The name is immutable, and it is the unique identifier for the credential. You can add more credentials after you enable the integration.

User access token names must follow these rules:
- Must start and end with a letter or number
- Can contain letters, numbers underscores, and hyphens
- Must contain at least 2 characters, but no more than 50 characters
- Must be unique within the embedding provider integration’s settings.
Enter your Hugging Face Serverless user access token.
In the Add databases to scope section, select a Serverless (vector) database that is authorized to use the integration.

Specifically, this authorizes the database to use the Hugging Face Serverless user access token to call the embedding provider’s API. This is required to add this integration to a collection or table. If a database isn’t authorized to use any credentials, then the integration isn’t available to that database.

You can add multiple databases to each user access token, you can add multiple user access tokens, and you can add databases after you enable the integration. New databases aren’t added to credential scopes automatically; you must add them to a credential’s scope manually. For more information, see Manage embedding provider integrations for vectorize.
Click Add Integration to save the credential and activate the integration.

Add the integration to a collection

To use the Hugging Face Serverless integration to generate embeddings for data in a collection, you must select the integration when you create the collection.

You cannot add a vectorize integration to an existing collection.

You cannot change a collection’s embedding provider or embedding generation method after you create it. To use a different embedding provider, you must create a new collection with a different embedding provider integration.

If you get a Collection Limit Reached or TOO_MANY_INDEXES error, you must delete a collection before you can create a new one.

Serverless (vector) databases created after June 24, 2024 can have approximately 10 collections. Databases created before this date can have approximately 5 collections. The collection limit is based on the number of indexes.

You can create a collection in the Astra Portal or with the Data API.

Use the Astra Portal

In the Astra Portal, click the name of the Serverless (vector) database where you want to use the integration.
Click Data Explorer.
In the Keyspace field, select the keyspace where you want to create the collection.
Click Create Collection.
Enter a name for the collection.

For collection name rules and more information about creating collections, see Manage collections and tables.
Make sure Vector-enabled collection is enabled.
For Embedding generation method, select the Hugging Face Serverless embedding provider integration.

If the integration isn’t listed, see Manage scoped databases and Troubleshoot vectorize integrations.
Configure the integration settings for this collection. For information about each setting, see Hugging Face Serverless settings for collections and tables.
Click Create collection.

To learn how to generate embeddings and perform vector searches on your integrated collection, see Next steps.

Use the Data API

You can use the Data API to create a collection that uses the Hugging Face Serverless integration.

The following example uses curl. For Data API client examples and more information, see the Data API reference documentation: Create a collection

Create a collection, specifying the new collection’s name and the embedding provider integration settings:

curl -sS -L -X POST "$API_ENDPOINT/api/json/v1/default_keyspace" \
  --header "Token: $APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createCollection": {
    "name": "COLLECTION_NAME",
    "options": {
      "vector": {
        "dimension": MODEL_DIMENSIONS,
        "metric": "SIMILARITY_METRIC",
        "service": {
          "provider": "huggingface",
          "modelName": "MODEL_NAME",
          "authentication": {
            "providerKey": "API_KEY_NAME"
          }
        }
      }
    }
  }
}'

To learn how to generate embeddings and perform vector searches on your integrated collection, see Next steps.

Add the integration to a table

You can use the Data API to add the Hugging Face Serverless integration to a table in multiple ways:

Create a table that has a vector column with a vectorize integration.
Alter a table to add a vector column with a vectorize integration.
Alter a table to add or change a vectorize integration on an existing vector column.

The following example uses curl to create a table with a vector column that has a vectorize integration. For Data API client examples and more information, see the Data API reference documentation:

Create a table with a vector column, specifying the table name, schema, and the embedding provider integration settings:

curl -sS -L -X POST "$API_ENDPOINT/api/json/v1/default_keyspace" \
  --header "Token: $APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createTable": {
    "name": "TABLE_NAME",
    "definition": {
      "columns": {
        # This column will store vector embeddings.
        # The Hugging Face Serverless integration
        # will automatically generate vector embeddings
        # for any text inserted to this column.
        "VECTOR_COLUMN_NAME": {
          "type": "vector",
          "dimension": MODEL_DIMENSIONS,
          "service": {
            "provider": "huggingface",
            "modelName": "MODEL_NAME",
            "authentication": {
              "providerKey": "API_KEY_NAME"
            }
          }
        },
        # If you want to store the original text
        # in addition to the generated embeddings
        # you must create a separate column.
        "TEXT_COLUMN_NAME": "text"
      },
      # You should change the primary key definition to meet the needs of your data.
      "primaryKey": "TEXT_COLUMN_NAME"
    }
  }
}'

The same embedding provider integration settings are used to configure a vectorize integration when you create or alter a table.

Index the vector column so that you can perform a vector search on it:

curl -sS -L -X POST "$API_ENDPOINT/api/json/v1/default_keyspace" \
  --header "Token: $APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createVectorIndex": {
    "name": "INDEX_NAME",
    "definition": {
      "column": "VECTOR_COLUMN_NAME",
      "options": {
        "metric": "SIMILARITY_METRIC"
      }
    }
  }
}'

To learn how to generate embeddings and perform vector searches on your integrated vector column, see Next steps.

Hugging Face Serverless settings for collections and tables

When you add the Hugging Face Serverless integration to a collection or table, the following settings are available. These settings apply to the scope of one collection or one vector column on a table. Each collection and column can have different values for each setting if needed.

Embedding generation method (provider): The embedding provider integration to use to automatically generate embeddings.
User access token (providerKey): Select a user access token to use to call the embedding provider’s API when generating embeddings for this collection. If only one user access token is available, that user access token is selected by default and this field cannot be changed. If multiple user access tokens are available, select one user access token. For more information, see Manage scoped databases.
Embedding model (modelName): The model that you want to use to generate embeddings. The available models are: sentence-transformers/all-MiniLM-L6-v2, intfloat/multilingual-e5-large, intfloat/multilingual-e5-large-instruct, BAAI/bge-small-en-v1.5, BAAI/bge-base-en-v1.5, BAAI/bge-large-en-v1.5.
Dimensions (dimension): The dimensions of the generated vectors. This field can be set automatically based on the embedding model. You can edit this field if the model supports a range of dimensions or the integration uses an endpoint-defined model. For supported dimensions, see the documentation for your embedding model.
Similarity metric (metric): The method to use to calculate vector similarity scores: Cosine, Dot Product, or Euclidean.

Integrate Hugging Face Serverless as an embedding provider

Prepare your Hugging Face Serverless account

Enable the integration in your Astra organization

Add the integration to a collection

Use the Astra Portal

Use the Data API

Add the integration to a table

Hugging Face Serverless settings for collections and tables

Next steps

Was this helpful?

Give Feedback