{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Azure chat completion models with your own data (preview)\n", "\n", "> Note: There is a newer version of the openai library available. See https://github.com/openai/openai-python/discussions/742\n", "\n", "This example shows how to use Azure OpenAI service models with your own data. The feature is currently in preview. \n", "\n", "Azure OpenAI on your data enables you to run supported chat models such as GPT-3.5-Turbo and GPT-4 on your data without needing to train or fine-tune models. Running models on your data enables you to chat on top of, and analyze your data with greater accuracy and speed. One of the key benefits of Azure OpenAI on your data is its ability to tailor the content of conversational AI. Because the model has access to, and can reference specific sources to support its responses, answers are not only based on its pretrained knowledge but also on the latest information available in the designated data source. This grounding data also helps the model avoid generating responses based on outdated or incorrect information.\n", "\n", "Azure OpenAI on your own data with Azure Cognitive Search provides a customizable, pre-built solution for knowledge retrieval, from which a conversational AI application can be built. To see alternative methods for knowledge retrieval and semantic search, check out the cookbook examples for [vector databases](https://github.com/openai/openai-cookbook/tree/main/examples/vector_databases)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## How it works\n", "\n", "[Azure OpenAI on your own data](https://learn.microsoft.com/azure/ai-services/openai/concepts/use-your-data) connects the model with your data, giving it the ability to retrieve and utilize data in a way that enhances the model's output. Together with Azure Cognitive Search, data is retrieved from designated data sources based on the user input and provided conversation history. The data is then augmented and resubmitted as a prompt to the model, giving the model contextual information it can use to generate a response.\n", "\n", "See the [Data, privacy, and security for Azure OpenAI Service](https://learn.microsoft.com/legal/cognitive-services/openai/data-privacy?context=%2Fazure%2Fai-services%2Fopenai%2Fcontext%2Fcontext) for more information." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Prerequisites\n", "To get started, we'll cover a few prequisites. \n", "\n", "To properly access the Azure OpenAI Service, we need to create the proper resources at the [Azure Portal](https://portal.azure.com) (you can check a detailed guide on how to do this in the [Microsoft Docs](https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource?pivots=web-portal))\n", "\n", "To use your own data with Azure OpenAI models, you will need:\n", "\n", "1. Azure OpenAI access and a resource with a chat model deployed (for example, GPT-3 or GPT-4)\n", "2. Azure Cognitive Search resource\n", "3. Azure Blob Storage resource\n", "4. Your documents to be used as data (See [data source options](https://learn.microsoft.com/azure/ai-services/openai/concepts/use-your-data#data-source-options))\n", "\n", "\n", "For a full walk-through on how to upload your documents to blob storage and create an index using the Azure AI Studio, see this [Quickstart](https://learn.microsoft.com/azure/ai-services/openai/use-your-data-quickstart?pivots=programming-language-studio&tabs=command-line)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Setup\n", "\n", "First, we install the necessary dependencies." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "! pip install \"openai>=0.28.1,<1.0.0\"\n", "! pip install python-dotenv" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In this example, we'll use `dotenv` to load our environment variables. To connect with Azure OpenAI and the Search index, the following variables should be added to a `.env` file in `KEY=VALUE` format:\n", "\n", "* `OPENAI_API_BASE` - the Azure OpenAI endpoint. This can be found under \"Keys and Endpoints\" for your Azure OpenAI resource in the Azure Portal.\n", "* `OPENAI_API_KEY` - the Azure OpenAI API key. This can be found under \"Keys and Endpoints\" for your Azure OpenAI resource in the Azure Portal. Omit if using Azure Active Directory authentication (see below `Authentication using Microsoft Active Directory`)\n", "* `SEARCH_ENDPOINT` - the Cognitive Search endpoint. This URL be found on the \"Overview\" of your Search resource on the Azure Portal.\n", "* `SEARCH_KEY` - the Cognitive Search API key. Found under \"Keys\" for your Search resource in the Azure Portal.\n", "* `SEARCH_INDEX_NAME` - the name of the index you created with your own data." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import os\n", "import openai\n", "import dotenv\n", "\n", "dotenv.load_dotenv()" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [], "source": [ "openai.api_base = os.environ[\"OPENAI_API_BASE\"]\n", "\n", "# Azure OpenAI on your own data is only supported by the 2023-08-01-preview API version\n", "openai.api_version = \"2023-08-01-preview\"" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Authentication\n", "\n", "The Azure OpenAI service supports multiple authentication mechanisms that include API keys and Azure credentials." ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [], "source": [ "use_azure_active_directory = False # Set this flag to True if you are using Azure Active Directory" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "#### Authentication using API key\n", "\n", "To set up the OpenAI SDK to use an *Azure API Key*, we need to set up the `api_type` to `azure` and set `api_key` to a key associated with your endpoint (you can find this key in *\"Keys and Endpoints\"* under *\"Resource Management\"* in the [Azure Portal](https://portal.azure.com))" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [], "source": [ "if not use_azure_active_directory:\n", " openai.api_type = 'azure'\n", " openai.api_key = os.environ[\"OPENAI_API_KEY\"]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Authentication using Microsoft Active Directory\n", "Let's now see how we can get a key via Microsoft Active Directory Authentication. See the [documentation](https://learn.microsoft.com/azure/ai-services/openai/how-to/managed-identity) for more information on how to set this up." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "! pip install azure-identity" ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [], "source": [ "from azure.identity import DefaultAzureCredential\n", "\n", "if use_azure_active_directory:\n", " default_credential = DefaultAzureCredential()\n", " token = default_credential.get_token(\"https://cognitiveservices.azure.com/.default\")\n", "\n", " openai.api_type = \"azure_ad\"\n", " openai.api_key = token.token" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "A token is valid for a period of time, after which it will expire. To ensure a valid token is sent with every request, you can refresh an expiring token by hooking into requests.auth:" ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [], "source": [ "import typing\n", "import time\n", "import requests\n", "\n", "if typing.TYPE_CHECKING:\n", " from azure.core.credentials import TokenCredential\n", "\n", "class TokenRefresh(requests.auth.AuthBase):\n", "\n", " def __init__(self, credential: \"TokenCredential\", scopes: typing.List[str]) -> None:\n", " self.credential = credential\n", " self.scopes = scopes\n", " self.cached_token: typing.Optional[str] = None\n", "\n", " def __call__(self, req):\n", " if not self.cached_token or self.cached_token.expires_on - time.time() < 300:\n", " self.cached_token = self.credential.get_token(*self.scopes)\n", " req.headers[\"Authorization\"] = f\"Bearer {self.cached_token.token}\"\n", " return req\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Chat completion model with your own data" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Setting the context" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In this example, we want our model to base its responses on Azure AI services documentation data. Following the [Quickstart](https://learn.microsoft.com/azure/ai-services/openai/use-your-data-quickstart?tabs=command-line&pivots=programming-language-studio) shared previously, we have added the [markdown](https://github.com/MicrosoftDocs/azure-docs/blob/main/articles/ai-services/cognitive-services-and-machine-learning.md) file for the [Azure AI services and machine learning](https://learn.microsoft.com/azure/ai-services/cognitive-services-and-machine-learning) documentation page to our search index. The model is now ready to answer questions about Azure AI services and machine learning." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Code" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "To chat with Azure OpenAI models using your own data with the Python SDK, we must first set up the code to target the chat completions extensions endpoint which is designed to work with your own data. To do this, we've created a convenience function that can be called to set a custom adapter for the library which will target the extensions endpoint for a given deployment ID." ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [], "source": [ "import requests\n", "\n", "def setup_byod(deployment_id: str) -> None:\n", " \"\"\"Sets up the OpenAI Python SDK to use your own data for the chat endpoint.\n", " \n", " :param deployment_id: The deployment ID for the model to use with your own data.\n", "\n", " To remove this configuration, simply set openai.requestssession to None.\n", " \"\"\"\n", "\n", " class BringYourOwnDataAdapter(requests.adapters.HTTPAdapter):\n", "\n", " def send(self, request, **kwargs):\n", " request.url = f\"{openai.api_base}/openai/deployments/{deployment_id}/extensions/chat/completions?api-version={openai.api_version}\"\n", " return super().send(request, **kwargs)\n", "\n", " session = requests.Session()\n", "\n", " # Mount a custom adapter which will use the extensions endpoint for any call using the given `deployment_id`\n", " session.mount(\n", " prefix=f\"{openai.api_base}/openai/deployments/{deployment_id}\",\n", " adapter=BringYourOwnDataAdapter()\n", " )\n", "\n", " if use_azure_active_directory:\n", " session.auth = TokenRefresh(default_credential, [\"https://cognitiveservices.azure.com/.default\"])\n", "\n", " openai.requestssession = session\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now we can call the convenience function to configure the SDK with the model we plan to use for our own data." ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [], "source": [ "setup_byod(\"gpt-4\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Providing our search endpoint, key, and index name for the `dataSources` keyword argument, any questions posed to the model will now be grounded in our own data. An additional property, `context`, will be provided to show the data the model referenced to answer the question." ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "{\n", " \"id\": \"65b485bb-b3c9-48da-8b6f-7d3a219f0b40\",\n", " \"model\": \"gpt-4\",\n", " \"created\": 1693338769,\n", " \"object\": \"extensions.chat.completion\",\n", " \"choices\": [\n", " {\n", " \"index\": 0,\n", " \"finish_reason\": \"stop\",\n", " \"message\": {\n", " \"role\": \"assistant\",\n", " \"content\": \"Azure AI services and Azure Machine Learning (AML) both aim to apply artificial intelligence (AI) to enhance business operations, but they target different audiences and offer different capabilities [doc1]. \\n\\nAzure AI services are designed for developers without machine learning experience and provide pre-trained models to solve general problems such as text analysis, image recognition, and natural language processing [doc5]. These services require general knowledge about your data without needing experience with machine learning or data science and provide REST APIs and language-based SDKs [doc2].\\n\\nOn the other hand, Azure Machine Learning is tailored for data scientists and involves a longer process of data collection, cleaning, transformation, algorithm selection, model training, and deployment [doc5]. It allows users to create custom solutions for highly specialized and specific problems, requiring familiarity with the subject matter, data, and expertise in data science [doc5].\\n\\nIn summary, Azure AI services offer pre-trained models for developers without machine learning experience, while Azure Machine Learning is designed for data scientists to create custom solutions for specific problems.\",\n", " \"end_turn\": true,\n", " \"context\": {\n", " \"messages\": [\n", " {\n", " \"role\": \"tool\",\n", " \"content\": \"{\\\"citations\\\": [{\\\"content\\\": \\\"

How are Azure AI services and Azure Machine Learning (AML) similar?.

\\\\n

Both have the end-goal of applying artificial intelligence (AI) to enhance business operations, though how each provides this in the respective offerings is different..

\\\\n

Generally, the audiences are different:

\\\\n