FlagEmbedding/Tutorials/1_Embedding/1.1_Intro&Inference.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Intro to Embedding"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For text retrieval, pattern matching is the most intuitive way. People would use certain characters, words, phrases, or sentence patterns. However, not only for human, it is also extremely inefficient for computer to do pattern matching between a query and a collection of text files to find the possible results. \n",
    "\n",
    "For images and acoustic waves, there are rgb pixels and digital signals. Similarly, in order to accomplish more sophisticated tasks of natural language such as retrieval, classification, clustering, or semantic search, we need a way to represent text data. That's how text embedding comes in front of the stage."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Background"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Traditional text embedding methods like one-hot encoding and bag-of-words (BoW) represent words and sentences as sparse vectors based on their statistical features, such as word appearance and frequency within a document. More advanced methods like TF-IDF and BM25 improve on these by considering a word's importance across an entire corpus, while n-gram techniques capture word order in small groups. However, these approaches suffer from the \"curse of dimensionality\" and fail to capture semantic similarity like \"cat\" and \"kitty\", difference like \"play the watch\" and \"watch the play\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# example of bag-of-words\n",
    "sentence1 = \"I love basketball\"\n",
    "sentence2 = \"I have a basketball match\"\n",
    "\n",
    "words = ['I', 'love', 'basketball', 'have', 'a', 'match']\n",
    "sen1_vec = [1, 1, 1, 0, 0, 0]\n",
    "sen2_vec = [1, 0, 1, 1, 1, 1]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To overcome these limitations, dense word embeddings were developed, mapping words to vectors in a low-dimensional space that captures semantic and relational information. Early models like Word2Vec demonstrated the power of dense embeddings using neural networks. Subsequent advancements with neural network architectures like RNNs, LSTMs, and Transformers have enabled more sophisticated models such as BERT, RoBERTa, and GPT to excel in capturing complex word relationships and contexts. **BAAI General Embedding (BGE)** provide a series of open-source models that could satisfy all kinds of demands."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get Embedding"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The first step of modern text retrieval is embedding the text. So let's take a look at how to use the embedding models."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Install the packages:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%capture\n",
    "%pip install -U FlagEmbedding sentence_transformers openai cohere"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os \n",
    "os.environ['TRANSFORMERS_NO_ADVISORY_WARNINGS'] = 'true'\n",
    "# single GPU is better for small tasks\n",
    "os.environ['CUDA_VISIBLE_DEVICES'] = '0'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We'll use the following three sentences as the inputs:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "sentences = [\n",
    "    \"That is a happy dog\",\n",
    "    \"That is a very happy person\",\n",
    "    \"Today is a sunny day\",\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Open-source Models"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A huge portion of embedding models are in the open source community. The advantages of open-source models include:\n",
    "- Free, no extra cost. But make sure to check the License and your use case before using.\n",
    "- No frequency limit, can accelerate a lot if you have enough GPUs to parallelize.\n",
    "- Transparent and might be reproducible.\n",
    "\n",
    "Let's take a look at two representatives:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### BGE"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "BGE is a series of embedding models and rerankers published by BAAI. Several of them reached SOTA at the time they released."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "initial target device: 100%|██████████| 8/8 [00:31<00:00,  3.89s/it]\n",
      "Chunks: 100%|██████████| 3/3 [00:04<00:00,  1.61s/it]\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Embeddings:\n",
      "(3, 768)\n",
      "Similarity scores:\n",
      "[[1.     0.79   0.575 ]\n",
      " [0.79   0.9995 0.592 ]\n",
      " [0.575  0.592  0.999 ]]\n"
     ]
    }
   ],
   "source": [
    "from FlagEmbedding import FlagModel\n",
    "\n",
    "# Load BGE model\n",
    "model = FlagModel('BAAI/bge-base-en-v1.5')\n",
    "\n",
    "# encode the queries and corpus\n",
    "embeddings = model.encode(sentences)\n",
    "print(f\"Embeddings:\\n{embeddings.shape}\")\n",
    "\n",
    "scores = embeddings @ embeddings.T\n",
    "print(f\"Similarity scores:\\n{scores}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Sentence Transformers"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Sentence Transformers is a library for sentence embeddings with a huge amount of embedding models and datasets for related tasks."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Embeddings:\n",
      "(3, 384)\n",
      "Similarity scores:\n",
      "[[0.99999976 0.6210502  0.24906276]\n",
      " [0.6210502  0.9999997  0.21061528]\n",
      " [0.24906276 0.21061528 0.9999999 ]]\n"
     ]
    }
   ],
   "source": [
    "from sentence_transformers import SentenceTransformer\n",
    "\n",
    "model = SentenceTransformer(\"all-MiniLM-L6-v2\")\n",
    "\n",
    "embeddings = model.encode(sentences, normalize_embeddings=True)\n",
    "print(f\"Embeddings:\\n{embeddings.shape}\")\n",
    "\n",
    "scores = embeddings @ embeddings.T\n",
    "print(f\"Similarity scores:\\n{scores}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Commercial Models"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are also plenty choices of commercial models. They have the advantages of:\n",
    "- Efficient memory usage, fast inference with no need of GPUs.\n",
    "- Systematic support, commercial models have closer connections with their other products.\n",
    "- Better training data, commercial models might be trained on larger, higher-quality datasets than some open-source models."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### OpenAI"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Along with GPT series, OpenAI has their own embedding models. Make sure to fill in your own API key in the field `\"YOUR_API_KEY\"`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import numpy as np\n",
    "\n",
    "os.environ[\"OPENAI_API_KEY\"] = \"YOUR_API_KEY\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then run the following cells to get the embeddings. Check their official [documentation](https://platform.openai.com/docs/guides/embeddings) for more details."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "from openai import OpenAI\n",
    "\n",
    "client = OpenAI()\n",
    "\n",
    "response = client.embeddings.create(input = sentences, model=\"text-embedding-3-small\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Embeddings:\n",
      "(3, 1536)\n",
      "Similarity scores:\n",
      "[[1.00000004 0.697673   0.34739798]\n",
      " [0.697673   1.00000005 0.31969923]\n",
      " [0.34739798 0.31969923 0.99999998]]\n"
     ]
    }
   ],
   "source": [
    "embeddings = np.asarray([response.data[i].embedding for i in range(len(sentences))])\n",
    "print(f\"Embeddings:\\n{embeddings.shape}\")\n",
    "\n",
    "scores = embeddings @ embeddings.T\n",
    "print(f\"Similarity scores:\\n{scores}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Voyage AI"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Voyage AI provides embedding models and rerankers for different purpus and in various fields. Their API keys can be freely used in low frequency and token length."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [],
   "source": [
    "os.environ[\"VOYAGE_API_KEY\"] = \"YOUR_API_KEY\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Check their official [documentation](https://docs.voyageai.com/docs/api-key-and-installation) for more details."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [],
   "source": [
    "import voyageai\n",
    "\n",
    "vo = voyageai.Client()\n",
    "\n",
    "result = vo.embed(sentences, model=\"voyage-large-2-instruct\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Embeddings:\n",
      "(3, 1024)\n",
      "Similarity scores:\n",
      "[[0.99999997 0.87282517 0.63276503]\n",
      " [0.87282517 0.99999998 0.64720015]\n",
      " [0.63276503 0.64720015 0.99999999]]\n"
     ]
    }
   ],
   "source": [
    "embeddings = np.asarray(result.embeddings)\n",
    "print(f\"Embeddings:\\n{embeddings.shape}\")\n",
    "\n",
    "scores = embeddings @ embeddings.T\n",
    "print(f\"Similarity scores:\\n{scores}\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "dev",
   "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.12.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}