fastembed/docs/Getting Started.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "3f159fb4",
   "metadata": {},
   "source": [
    "# Getting Started\n",
    "\n",
    "Here you will learn how to use the fastembed package to embed your data into a vector space. The package is designed to be easy to use and fast. It is built on top of the [ONNX](https://onnx.ai/) standard, which allows for fast inference on a variety of hardware (called Runtimes in ONNX). \n",
    "\n",
    "## Installation\n",
    "\n",
    "To get started, install the fastembed package with pip."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a3b5612a",
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install fastembed"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6b5b503b",
   "metadata": {},
   "source": [
    "# Quick Start\n",
    "\n",
    "The fastembed package is designed to be easy to use. The main class is the `Embedding` class. It takes a list of strings as input and returns a list of vectors as output. The `Embedding` class is initialized with a model file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8349e72d",
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import List\n",
    "import numpy as np\n",
    "from fastembed.embedding import FlagEmbedding as Embedding\n",
    "\n",
    "# Example list of documents to encode\n",
    "documents: List[str] = [\n",
    "    \"Hello, World!\",\n",
    "    \"This is an example document.\",\n",
    "    \"fastembed is supported by and maintained by Qdrant.\",\n",
    "]\n",
    "# Initialize the DefaultEmbedding class with the desired parameters\n",
    "embedding_model = Embedding(model_name=\"BAAI/bge-small-en\", max_length=512)\n",
    "embeddings: List[np.ndarray] = list(embedding_model.encode(documents)) # notice that we are casting the generator to a list\n",
    "\n",
    "print(embeddings[0].shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c49ae50",
   "metadata": {},
   "source": [
    "## Explanation of what is happening"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "92cf4b76",
   "metadata": {},
   "source": [
    "Importing the required classes and modules:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c0a6f634",
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import List\n",
    "import numpy as np\n",
    "from fastembed.embedding import FlagEmbedding as Embedding"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3fd03a71",
   "metadata": {},
   "source": [
    "Notice that we are using the FlagEmbedding -- which is state of the Art and beats OpenAI's Embedding by a large margin. \n",
    "\n",
    "## Prepare your Documents\n",
    "You can define a list of documents that you'd like to encode. These can be sentences, paragraphs, or even entire documents. \n",
    "\n",
    "### Format of the List:\n",
    "1. List of Strings: Your documents must be in a list, and each document must be a string.\n",
    "2. For Retrieval Tasks: If you're working with queries and passages, you can add special labels to them:\n",
    "- **Queries**: Add \"query:\" at the beginning of each query string.\n",
    "- **Passages**: Add \"passage:\" at the beginning of each passage string."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "145a56ce",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Example list of documents to encode\n",
    "documents: List[str] = [\n",
    "    \"query: Hello, World!\",\n",
    "    \"query: This is an example document.\",\n",
    "    \"passage: fastembed is supported by and maintained by Qdrant.\",\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1cb3cc87",
   "metadata": {},
   "source": [
    "## Load the Embedding Model Weights\n",
    "Next, initialize the Embedding class with the desired parameters. Here, \"BAAI/bge-small-en\" is the pre-trained model name, and max_length=512 is the maximum token length for each document."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "272c8915",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Initialize the DefaultEmbedding class with the desired parameters\n",
    "embedding_model = Embedding(model_name=\"BAAI/bge-small-en\", max_length=512)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5549d501",
   "metadata": {},
   "source": [
    "## Embed your Documents\n",
    "\n",
    "Use the encode method of the embedding model to transform the documents into a List of np.array. The method returns a generator, so we cast it to a list to get the embeddings."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8013eee9",
   "metadata": {},
   "outputs": [],
   "source": [
    "embeddings: List[np.ndarray] = list(embedding_model.encode(documents)) # notice that we are casting the generator to a list"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e5b5a6ad",
   "metadata": {},
   "source": [
    "You can print the shape of the embeddings to understand their dimensions. Typically, the shape will indicate the number of dimensions in the encoded vector."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0d8c8e08",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(embeddings[0].shape) # (768,) or similar output"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.17"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}