added troubleshooting steps

Author: HeidiSteen

Quickstart-RAG/Quickstart-rag.ipynb

@@ -10,10 +10,12 @@
     "\n",
     "We took a few shortcuts to keep the exercise basic and focused on query definitions:\n",
     "\n",
-    "- We use the hotels-sample-index, which can be created in minutes and runs on any search service tier. This index is created by a wizard using built-in sample data.\n",
+    "- We use the **hotels-sample-index**, which can be created in minutes and runs on any search service tier. This index is created by a wizard using built-in sample data.\n",
     "\n",
     "- We omit vectors so that we can skip chunking and embedding. The index contains plain text.\n",
     "\n",
+    "A non-vector index isn't ideal for RAG patterns, but it makes for a simpler example.\n",
+    "\n",
     "Once you understand the fundamentals of integrating queries from Azure AI Search to an LLM, you can build on that experience by adding vector fields and vector and hybrid queries. We recommend the [phi-chat Python code example](https://github.com/Azure/azure-search-vector-samples/blob/main/demo-python/code/phi-chat/phi-chat.ipynb) for that step.\n",
     "\n",
     "This example is fully documented in [Quickstart: Generative search (RAG) with grounding data from Azure AI Search](https://learn.microsoft.com/azure/search/search-get-started-rag). If you need more guidance than the readme provides, please refer to the article.\n"
@@ -54,9 +56,17 @@
     "\n",
     "This quickstart assumes the hotels-sample-index, which you can create in minutes using [this quickstart](https://learn.microsoft.com/azure/search/search-get-started-portal).\n",
     "\n",
-    "Once the index exists, modify it in the Azure portal to use this semantic configuration:\n",
-    "  \n",
-    "    ```json\n",
+    "Once the index exists, modify it in the Azure portal to use this semantic configuration:"
+   ]
+  },
+  {
+   "cell_type": "raw",
+   "metadata": {
+    "vscode": {
+     "languageId": "raw"
+    }
+   },
+   "source": [
     "    \"semantic\": {\n",
     "    \"defaultConfiguration\": \"semantic-config\",\n",
     "    \"configurations\": [\n",
@@ -69,9 +79,13 @@
     "            { \"fieldName\": \"Category\" },\n",
     "            { \"fieldName\": \"Tags\" }\n",
     "          ]}\n",
-    "       }]},\n",
-    "    ```\n",
-    "\n",
+    "       }]},"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
     "Now that you have your Azure resources, an index, and model in place, you can run the script to chat with the index."
    ]
   },
@@ -83,7 +97,7 @@
     "\n",
     "Create a virtual environment so that you can install the dependencies in isolation.\n",
     "\n",
-    "1. In Visual Studio Code, open the folder containing quickstart-rag.ipynb.\n",
+    "1. In Visual Studio Code, open the folder containing Quickstart-RAG.ipynb.\n",
     "\n",
     "1. Press Ctrl-shift-P to open the command palette, search for \"Python: Create Environment\", and then select `Venv` to create a virtual environment in the current workspace.\n",
     "\n",
@@ -130,23 +144,9 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": null,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Sure, here are a few hotels that match your criteria: \n",
-      "\n",
-      "- Ocean Air Motel, which is an oceanfront hotel with beach access, private balconies, indoor and outdoor pools, shops, and art entertainment nearby.\n",
-      "- Marquis Plaza & Suites, which offers ocean views, free Wi-Fi, a full kitchen, and free breakfast buffet, along with beach access and a pool.\n",
-      "- Oceanside Resort is a new luxury hotel with bay views from every room, a rooftop pool, waterfront dining, and laundry service. \n",
-      "\n",
-      "Unfortunately, the Double Sanctuary Resort and Triple Landscape Hotel don't have beach access or mention views.\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "# Set up the query for generating responses\n",
     "from azure.identity import DefaultAzureCredential\n",
@@ -208,7 +208,15 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If you get an authorization error instead of results, wait a few minutes and try again. It can take several minutes for role assignments to become operational."
+    "If you get an authorization error instead of results:\n",
+    "\n",
+    "+ If you just enabled role assignments, wait a few minutes and try again. It can take several minutes for role assignments to become operational.\n",
+    "\n",
+    "+ Make sure you [enabled RBAC](https://learn.microsoft.com/azure/search/search-security-enable-roles?tabs=config-svc-portal%2Cdisable-keys-portal) on Azure AI Search. An HttpStatusMessage of **Forbidden** is an indicator that RBAC isn't enabled.\n",
+    "\n",
+    "+ Recheck role assignments for yourself and for the search service system identity.\n",
+    "\n",
+    "+ Check firewall settings. This quickstart assumes public network access. If you have a firewall, you need to add rules to allow inbound requests from your device and for service-to-service connections."
    ]
   }
  ],