Getting Started With Embeddings – Hugging Face tutorial

TL;DR

Hugging Face released a practical tutorial that shows how to generate text embeddings with the sentence-transformers/all-MiniLM-L6-v2 model via the Inference API, host the resulting vectors for free on the Hub, and perform semantic search to retrieve the most relevant FAQ entries.

Understanding embeddings

An embedding is a dense numerical vector that captures the semantic meaning of data such as text, images, or audio. For example, the sentence "What is the main benefit of voting?" can be represented as a 384‑dimensional vector like [0.84, 0.42, …, 0.02]. Because the vector encodes meaning, distances between vectors (e.g., cosine similarity) reveal how closely two pieces of information match.

Embeddings are not limited to text; image embeddings can be compared with text embeddings to enable cross‑modal search and classification. The open‑source Sentence Transformers library provides state‑of‑the‑art models for generating such embeddings for free.

What embeddings enable

"once you understand this ML multitool (embedding), you'll be able to build everything from search engines to recommendation systems to chatbots and a whole lot more. You don't have to be a data scientist with ML expertise to use them, nor do you need a huge labeled dataset." – Dale Markowitz, Google Cloud

Major products rely on embeddings: Google Search matches text‑to‑text and text‑to‑image, Snapchat uses them for ad ranking, and Meta employs them for social search. Embedding a dataset turns raw content into a searchable vector space, but doing so can be technically demanding and costly. This tutorial demonstrates a lightweight, open‑source workflow that avoids those hurdles.

End‑to‑end FAQ engine example

The guide builds a simple FAQ retrieval system using the U.S. Social Security Medicare FAQ dataset. The workflow consists of three steps:

  1. Embed the FAQ questions with the Hugging Face Inference API.
  2. Upload the embedding matrix to the Hugging Face Hub for free hosting.
  3. Query the embeddings to find the most semantically similar FAQ for a user’s question.

Each step is described in detail below.

1. Embedding a dataset

Model selection

The tutorial selects sentence-transformers/all-MiniLM-L6-v2, a compact yet powerful model from the Sentence Transformers library.

model_id = "sentence-transformers/all-MiniLM-L6-v2"

Authentication

Create a write token in your Hugging Face account settings and store it in hf_token.

hf_token = "<your token>"

API call

Use the feature‑extraction endpoint to obtain embeddings. The first request may take ~20 seconds because the model is downloaded on the server; subsequent calls are fast.

import requests
api_url = f"https://api-inference.huggingface.co/pipeline/feature-extraction/{model_id}"
headers = {"Authorization": f"Bearer {hf_token}"}

def query(texts):
    response = requests.post(
        api_url,
        headers=headers,
        json={"inputs": texts, "options": {"wait_for_model": True}}
    )
    return response.json()

Example input

texts = [
    "How do I get a replacement Medicare card?",
    "What is the monthly premium for Medicare Part B?",
    # … (additional 11 questions) …
]
output = query(texts)

The API returns a list of 384‑dimensional vectors, one per question. Converting to a Pandas DataFrame yields a matrix of shape (13, 384).

import pandas as pd
embeddings = pd.DataFrame(output)

2. Host embeddings for free on the Hugging Face Hub

The datasets library lets you share the CSV file containing the embeddings. After exporting:

embeddings.to_csv("embeddings.csv", index=False)

Upload embeddings.csv via the Hub UI (New dataset → upload file) or the CLI. The resulting repository, e.g., datasets/ITESM/embedded_faqs_medicare, can be loaded with a single command:

from datasets import load_dataset
faqs = load_dataset("ITESM/embedded_faqs_medicare")

3. Retrieve the most similar FAQ for a query

Load embeddings as tensors

import torch
faqs_embeddings = load_dataset('ITESM/embedded_faqs_medicare')
corpus = torch.from_numpy(
    faqs_embeddings["train"].to_pandas().to_numpy()
).float()

Embed the user query

question = ["How can Medicare help me?"]
query_vec = torch.FloatTensor(query(question))

Semantic search

The semantic_search utility from Sentence Transformers computes cosine similarity and returns the top‑k closest vectors.

from sentence_transformers.util import semantic_search
hits = semantic_search(query_vec, corpus, top_k=5)

Sample output:

[{'corpus_id': 8, 'score': 0.7565},
 {'corpus_id': 7, 'score': 0.7419},
 {'corpus_id': 3, 'score': 0.7253},
 {'corpus_id': 9, 'score': 0.6736},
 {'corpus_id': 10, 'score': 0.6505}]

Mapping corpus_id back to the original texts list yields the five most relevant FAQs:

print([texts[h['corpus_id']] for h in hits[0]])

Result:

  • How can I get help with my Medicare Part A and Part B premiums?
  • What is Medicare and who can get it?
  • How do I sign up for Medicare?
  • What are the different parts of Medicare?
  • Will my Medicare premiums be higher because of my higher income?

The same workflow can be adapted to other domains, larger corpora, or multimodal data.

Additional learning resources

  • Sentence Transformers Hub – collection of models and usage instructions.
  • Comparative tweet by Nils Reimers highlighting Sentence Transformers vs. GPT‑3 embeddings.
  • Official documentation at sbert.net.
  • Research threads on recent embedding advances (e.g., Nima Boscarino’s Twitter thread).

Training and advanced techniques

When you are comfortable with inference, explore:

  • Fine‑tuning embedding models (train-sentence-transformers).
  • Reranker (cross‑encoder) training (train-reranker).
  • Sparse embedding models like SPLADE (train-sparse-encoder).
  • Multimodal embeddings for text, image, audio, and video (multimodal-sentence-transformers).
  • Matryoshka embeddings that allow dimensionality reduction with minimal loss.
  • Static embeddings optimized for CPU (static-embeddings).
  • Quantization methods to shrink storage and accelerate retrieval.

These extensions enable higher accuracy, lower latency, and cost‑effective deployment for production‑grade semantic search systems.

The tutorial is accompanied by a Colab notebook that reproduces every step.

Sources