exercises/05-store-embeddings-hana.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Store Embeddings for a Retrieval Augmented Generation (RAG) Use Case\n",
    "\n",
    "RAG is especially useful for question-answering use cases that involve large amounts of unstructured documents containing important information. \n",
    "\n",
    "Let’s implement a RAG use case so that the next time you ask about the [orchestration service](https://help.sap.com/doc/generative-ai-hub-sdk/CLOUD/en-US/_reference/orchestration-service.html), you get the correct response! To achieve this, you need to vectorize our context documents. You can find the documents to vectorize and store as embeddings in SAP HANA Cloud Vector Engine in the `documents` directory.\n",
    "\n",
    "## LangChain\n",
    "\n",
    "The Generative AI Hub Python SDK is compatible with the [LangChain](https://python.langchain.com/v0.1/docs/get_started/introduction) library. LangChain is a tool for building applications that utilize large language models, such as GPT models. It is valuable because it helps manage and connect different models, tools, and data, simplifying the process of creating complex AI workflows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import warnings\n",
    "warnings.filterwarnings(\"ignore\", message=\"As the c extension\") #Avoid a warning message for \"RuntimeWarning: As the c extension couldn't be imported, `google-crc32c` is using a pure python implementation that is significantly slower. If possible, please configure a c build environment and compile the extension. warnings.warn(_SLOW_CRC32C_WARNING, RuntimeWarning)\"\n",
    "\n",
    "# OpenAIEmbeddings to create text embeddings\n",
    "from gen_ai_hub.proxy.langchain.openai import OpenAIEmbeddings\n",
    "\n",
    "# TextLoader to load documents\n",
    "from langchain_community.document_loaders import PyPDFDirectoryLoader\n",
    "\n",
    "# different TextSplitters to chunk documents into smaller text chunks\n",
    "from langchain_text_splitters import RecursiveCharacterTextSplitter\n",
    "\n",
    "# LangChain & HANA Vector Engine\n",
    "from langchain_community.vectorstores.hanavector import HanaDB"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "👉 Change the `EMBEDDING_DEPLOYMENT_ID` in [variables.py](variables.py) to your deployment ID from exercise [01-explore-genai-hub](01-explore-genai-hub.md). For that go to **SAP AI Launchpad** application and navigate to **ML Operations** > **Deployments**.\n",
    "\n",
    "☝️ The `EMBEDDING_DEPLOYMENT_ID` is the embedding model that creates vector representations of your text e.g. **text-embedding-3-small**.\n",
    "\n",
    "👉 In [variables.py](variables.py) also set the `EMBEDDING_TABLE` to `\"EMBEDDINGS_CODEJAM_>add your name here<\"`, like `\"EMBEDDINGS_CODEJAM_NORA\"`.\n",
    "\n",
    "👉 In the root folder of the project create a [.user.ini](../.user.ini) file with the HANA login information provided by the instructor.\n",
    "```sh\n",
    "[hana]\n",
    "url=XXXXXX.hanacloud.ondemand.com\n",
    "user=XXXXXX\n",
    "passwd=XXXXXX\n",
    "port=443\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import init_env\n",
    "import variables\n",
    "\n",
    "init_env.set_environment_variables()\n",
    "\n",
    "# connect to HANA instance\n",
    "connection = init_env.connect_to_hana_db()\n",
    "print(f\"Successfuly connected to SAP HANA db instance: {connection.isconnected()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Chunking of the documents\n",
    "\n",
    "Before you can create embeddings for your documents, you need to break them down into smaller text pieces, called \"`chunks`\". You will use the simplest chunking technique, which involves splitting the text based on character length and the separator `\"\\n\\n\"`, using the [Character Text Splitter](https://python.langchain.com/v0.1/docs/modules/data_connection/document_transformers/character_text_splitter/) from LangChain.\n",
    "\n",
    "## Character Text Splitter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "\n",
    "# Load custom documents\n",
    "loader = PyPDFDirectoryLoader('documents/')\n",
    "documents = loader.load()\n",
    "text_splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)\n",
    "texts = text_splitter.split_documents(documents)\n",
    "print(f\"Number of document chunks: {len(texts)}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now you can connect to your SAP HANA Cloud Vector Engine and store the embeddings for your text chunks."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import importlib\n",
    "variables = importlib.reload(variables)\n",
    "\n",
    "# DO NOT CHANGE THIS LINE BELOW - It is only to check whether you changed the table name in variables.py\n",
    "assert variables.EMBEDDING_TABLE != 'EMBEDDINGS_CODEJAM_ADD_YOUR_NAME_HERE', 'EMBEDDING_TABLE name not changed in variables.py'\n",
    "\n",
    "# Create embeddings for custom documents\n",
    "embeddings = OpenAIEmbeddings(deployment_id=variables.EMBEDDING_DEPLOYMENT_ID)\n",
    "\n",
    "db = HanaDB(\n",
    "    embedding=embeddings, connection=connection, table_name=variables.EMBEDDING_TABLE\n",
    ")\n",
    "\n",
    "# Delete already existing documents from the table\n",
    "db.delete(filter={})\n",
    "\n",
    "# add the loaded document chunks\n",
    "db.add_documents(texts)\n",
    "print(f\"Table {db.table_name} created in the SAP HANA database.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Check the embeddings in SAP HANA Cloud Vector Engine\n",
    "\n",
    "👉 Print the rows from your embedding table and scroll to the right to see the embeddings."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import Markdown\n",
    "cursor = connection.cursor()\n",
    "\n",
    "# Use `db.table_name` instead of `variables.EMBEDDING_TABLE` because HANA driver sanitizes a table name by removing unaccepted characters\n",
    "is_ok = cursor.execute(f'''SELECT \"VEC_TEXT\", \"VEC_META\", TO_NVARCHAR(\"VEC_VECTOR\") FROM \"{db.table_name}\"''')\n",
    "record_columns=cursor.fetchone()\n",
    "if record_columns:\n",
    "    display({\"VEC_TEXT\" : record_columns[0], \"VEC_META\" : eval(record_columns[1]), \"VEC_VECTOR\" : record_columns[2]})\n",
    "cursor.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[Next exercise](06-RAG.ipynb)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "env",
   "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.13.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}