More comments, explanations and updates to RAG tutorial

Author: HeidiSteen

Tutorial-RAG/Tutorial-rag.ipynb

@@ -187,7 +187,7 @@
     "\n",
     "Provide the endpoints you collected in a previous step. You can leave the API keys empty if you enabled role-based authentication. Otherwise, if you can't use roles, provide API keys for each resource.\n",
     "\n",
-    "The Azure AI multiservce key must be provided even if you're using roles. The key isn't used on the connection, but it's currently used for billing purposes."
+    "The Azure AI multiservice account is used for skills processing. The multiservice account key must be provided, even if you're using role-based access control. The key isn't used on the connection, but it's currently used for billing purposes."
    ]
   },
   {
@@ -314,7 +314,7 @@
     "\n",
     "# Create a data source \n",
     "indexer_client = SearchIndexerClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential)\n",
-    "container = SearchIndexerDataContainer(name=\"nasatext\")\n",
+    "container = SearchIndexerDataContainer(name=\"nasa-ebooks-pdfs-all\")\n",
     "data_source_connection = SearchIndexerDataSourceConnection(\n",
     "    name=\"py-rag-tutorial-ds\",\n",
     "    type=\"azureblob\",\n",
@@ -557,7 +557,7 @@
     "\n",
     "This script sends a query, the query response, and a prompt to an LLM for chat completion. This time, the response is created using generative AI.\n",
     "\n",
-    "For more information about this step, its behaviors, and changing the settings, revisit [Search and generate answers](https://learn.microsoft.com/azure/search/tutorial-rag-build-solution-query) in the tutorial."
+    "We broke this task out into three separate tasks: set up the clients, set up the search query, call the LLM and get the response. For more information about this step, its behaviors, and changing the settings, revisit [Search and generate answers](https://learn.microsoft.com/azure/search/tutorial-rag-build-solution-query) in the tutorial."
    ]
   },
   {
@@ -570,6 +570,7 @@
     "from azure.search.documents import SearchClient\n",
     "from openai import AzureOpenAI\n",
     "\n",
+    "# Set up the Azure OpenAI client\n",
     "token_provider = get_bearer_token_provider(credential, \"https://cognitiveservices.azure.com/.default\")\n",
     "openai_client = AzureOpenAI(\n",
     "     api_version=\"2024-06-01\",\n",
@@ -579,6 +580,7 @@
     "\n",
     "deployment_name = \"gpt-4o\"\n",
     "\n",
+    "# Set up the Azure Azure AI Search client\n",
     "search_client = SearchClient(\n",
     "     endpoint=AZURE_SEARCH_SERVICE,\n",
     "     index_name=index_name,\n",
@@ -605,21 +607,25 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Provide the query. Notice it's sent to both the search engine and the LLM.\n",
-    "# The query sent to the search engine is hybrid. Keyword search on \"query\". Text-to-vector conversion for vector search.\n",
+    "# Provide the search query. \n",
+    "# It's hybrid: a keyword search on \"query\", with text-to-vector conversion for \"vector_query\".\n",
+    "# The vector query finds 50 nearest neighbor matches in the search index\n",
     "query=\"What's the NASA earth book about?\"\n",
     "vector_query = VectorizableTextQuery(text=query, k_nearest_neighbors=50, fields=\"text_vector\")\n",
     "\n",
     "# Set up the search results and the chat thread.\n",
     "# Retrieve the selected fields from the search index related to the question.\n",
+    "# Search results are limited to the top 5 matches. Limiting top can help you stay under LLM quotas.\n",
     "search_results = search_client.search(\n",
     "    search_text=query,\n",
     "    vector_queries= [vector_query],\n",
     "    select=[\"title\", \"chunk\", \"locations\"],\n",
     "    top=5,\n",
     ")\n",
     "\n",
-    "# Newlines could be in the OCR'd content. Use a unique separator to make the sources distinct\n",
+    "# Newlines could be in the OCR'd content or in PDFs, as is the case for the sample PDFs used for this tutorial.\n",
+    "# Use a unique separator to make the sources distinct. \n",
+    "# We chose repeated equal signs (=) followed by a newline because it's unlikely the source documents contain this sequence.\n",
     "sources_formatted = \"=================\\n\".join([f'TITLE: {document[\"title\"]}, CONTENT: {document[\"chunk\"]}, LOCATIONS: {document[\"locations\"]}' for document in search_results])\n"
    ]
   },
@@ -709,7 +715,7 @@
     "    SearchField(name=\"locations\", type=SearchFieldDataType.Collection(SearchFieldDataType.String), filterable=True),\n",
     "    SearchField(name=\"chunk_id\", type=SearchFieldDataType.String, key=True, sortable=True, filterable=True, facetable=True, analyzer_name=\"keyword\"),  \n",
     "    SearchField(name=\"chunk\", type=SearchFieldDataType.String, sortable=False, filterable=False, facetable=False),  \n",
-    "    SearchField(name=\"text_vector\", type=SearchFieldDataType.Collection(SearchFieldDataType.Single), vector_search_dimensions=1536, vector_search_profile_name=\"myHnswProfile\")\n",
+    "    SearchField(name=\"text_vector\", type=SearchFieldDataType.Collection(SearchFieldDataType.Single), vector_search_dimensions=1024, vector_search_profile_name=\"myHnswProfile\")\n",
     "    ]  \n",
     "  \n",
     "# Existing vector search configuration  \n",
@@ -730,8 +736,8 @@
     "            kind=\"azureOpenAI\",  \n",
     "            parameters=AzureOpenAIVectorizerParameters(  \n",
     "                resource_url=AZURE_OPENAI_ACCOUNT,  \n",
-    "                deployment_name=\"text-embedding-ada-002\",\n",
-    "                model_name=\"text-embedding-ada-002\"\n",
+    "                deployment_name=\"text-embedding-3-large\",\n",
+    "                model_name=\"text-embedding-3-large\"\n",
     "            ),\n",
     "        ),  \n",
     "    ], \n",
@@ -799,7 +805,7 @@
     "     azure_ad_token_provider=token_provider\n",
     " )\n",
     "\n",
-    "deployment_name = \"gpt-35-turbo\"\n",
+    "deployment_name = \"gpt-4o\"\n",
     "\n",
     "search_client = SearchClient(\n",
     "     endpoint=AZURE_SEARCH_SERVICE,\n",
@@ -821,8 +827,8 @@
     "\"\"\"\n",
     "\n",
     "# Queries are unchanged in this update\n",
-    "query=\"how much of earth is covered by water\"\n",
-    "vector_query = VectorizableTextQuery(text=query, k_nearest_neighbors=1, fields=\"text_vector\", exhaustive=True)\n",
+    "query=\"What's the NASA earth book about?\"\n",
+    "vector_query = VectorizableTextQuery(text=query, k_nearest_neighbors=1, fields=\"text_vector\")\n",
     "\n",
     "# Add query_type semantic and semantic_configuration_name\n",
     "# Add scoring_profile and scoring_parameters\n",