azureChat should get endpoint and deployment from env

ccreutzi · ccreutzi · commit 348fb672d79c · 2024-06-20T15:26:31.000+01:00
Removed the positional arguments from `azureChat` constructor, and replaced with NVPs that default to reading from the environment instead.

Updated instructions to include those environment variables in `.env`.
diff --git a/+llms/+utils/errorMessageCatalog.m b/+llms/+utils/errorMessageCatalog.m
@@ -43,6 +43,8 @@
 catalog("llms:assistantMustHaveTextNameAndArguments") = "Fields 'name' and 'arguments' must be text with one or more characters.";
 catalog("llms:mustBeValidIndex") = "Value is larger than the number of elements in Messages ({1}).";
 catalog("llms:stopSequencesMustHaveMax4Elements") = "Number of elements must not be larger than 4.";
+catalog("llms:endpointMustBeSpecified") = "Unable to find endpoint. Either set environment variable AZURE_OPENAI_ENDPOINT or specify name-value argument ""Endpoint"".";
+catalog("llms:deploymentMustBeSpecified") = "Unable to find deployment name. Either set environment variable AZURE_OPENAI_DEPLOYMENT or specify name-value argument ""Deployment"".";
 catalog("llms:keyMustBeSpecified") = "Unable to find API key. Either set environment variable {1} or specify name-value argument ""APIKey"".";
 catalog("llms:mustHaveMessages") = "Value must contain at least one message in Messages.";
 catalog("llms:mustSetFunctionsForCall") = "When no functions are defined, ToolChoice must not be specified.";
diff --git a/azureChat.m b/azureChat.m
@@ -2,16 +2,27 @@
     llms.internal.gptPenalties & llms.internal.hasTools & llms.internal.needsAPIKey
 %azureChat Chat completion API from Azure.
 %
-%   CHAT = azureChat(endpoint, deploymentID) creates an azureChat object with
-%   the endpoint and deployment ID path parameters required by Azure to
-%   establish the connection.
+%   CHAT = azureChat creates an azureChat object, with the parameters needed
+%   to connect to Azure taken from the environment.
 %
-%   CHAT = azureChat(__,systemPrompt) creates an azureChat object with the
+%   CHAT = azureChat(systemPrompt) creates an azureChat object with the
 %   specified system prompt.
 %
 %   CHAT = azureChat(__,Name=Value) specifies additional options
 %   using one or more name-value arguments:
 %
+%   Endpoint                - The endpoint as defined in the Azure OpenAI Services
+%                             interface. Needs to be specified or stored in the
+%                             environment variable AZURE_OPENAI_ENDPOINT.
+%
+%   Deployment              - The deployment as defined in the Azure OpenAI Services
+%                             interface. Needs to be specified or stored in the
+%                             environment variable AZURE_OPENAI_DEPLOYMENT.
+%
+%   APIKey                  - The API key for accessing the Azure OpenAI Chat API.
+%                             Needs to be specified or stored in the
+%                             environment variable AZURE_OPENAI_API_KEY.
+%
 %   Temperature             - Temperature value for controlling the randomness
 %                             of the output. Default value is 1; higher values
 %                             increase the randomness (in some sense,
@@ -33,8 +44,6 @@
 %   ResponseFormat          - The format of response the model returns.
 %                             "text" (default) | "json"
 %
-%   APIKey                  - The API key for accessing the OpenAI Chat API.
-%
 %   PresencePenalty         - Penalty value for using a token in the response
 %                             that has already been used. Default value is 0.
 %                             Higher values reduce repetition of words in the output.
@@ -91,18 +100,18 @@
     end
 
     methods
-        function this = azureChat(endpoint, deploymentID, systemPrompt, nvp)
+        function this = azureChat(systemPrompt, nvp)
             arguments
-                endpoint                           {mustBeTextScalar}
-                deploymentID                       {mustBeTextScalar}
                 systemPrompt                       {llms.utils.mustBeTextOrEmpty} = []
+                nvp.Endpoint                       {mustBeNonzeroLengthTextScalar}
+                nvp.Deployment                     {mustBeNonzeroLengthTextScalar}
+                nvp.APIKey                         {mustBeNonzeroLengthTextScalar}
                 nvp.Tools                    (1,:) {mustBeA(nvp.Tools, "openAIFunction")} = openAIFunction.empty
                 nvp.APIVersion               (1,1) {mustBeAPIVersion} = "2024-02-01"
                 nvp.Temperature                    {llms.utils.mustBeValidTemperature} = 1
                 nvp.TopP                           {llms.utils.mustBeValidTopP} = 1
                 nvp.StopSequences                  {llms.utils.mustBeValidStop} = {}
                 nvp.ResponseFormat           (1,1) string {mustBeMember(nvp.ResponseFormat,["text","json"])} = "text"
-                nvp.APIKey                         {mustBeNonzeroLengthTextScalar}
                 nvp.PresencePenalty                {llms.utils.mustBeValidPenalty} = 0
                 nvp.FrequencyPenalty               {llms.utils.mustBeValidPenalty} = 0
                 nvp.TimeOut                  (1,1) {mustBeReal,mustBePositive} = 10
@@ -131,16 +140,16 @@
                 end
             end
 
-            this.Endpoint = endpoint;
-            this.DeploymentID = deploymentID;
+            this.Endpoint = getEndpoint(nvp);
+            this.DeploymentID = getDeployment(nvp);
+            this.APIKey = llms.internal.getApiKeyFromNvpOrEnv(nvp,"AZURE_OPENAI_API_KEY");
             this.APIVersion = nvp.APIVersion;
             this.ResponseFormat = nvp.ResponseFormat;
             this.Temperature = nvp.Temperature;
             this.TopP = nvp.TopP;
             this.StopSequences = nvp.StopSequences;
             this.PresencePenalty = nvp.PresencePenalty;
             this.FrequencyPenalty = nvp.FrequencyPenalty;
-            this.APIKey = llms.internal.getApiKeyFromNvpOrEnv(nvp,"AZURE_OPENAI_API_KEY");
             this.TimeOut = nvp.TimeOut;
         end
 
@@ -285,3 +294,27 @@ function mustBeIntegerOrEmpty(value)
 function mustBeAPIVersion(model)
     mustBeMember(model,llms.azure.apiVersions);
 end
+
+function endpoint = getEndpoint(nvp)
+    if isfield(nvp, "Endpoint")
+        endpoint = nvp.Endpoint;
+    else
+        if isenv("AZURE_OPENAI_ENDPOINT")
+            endpoint = getenv("AZURE_OPENAI_ENDPOINT");
+        else
+            error("llms:endpointMustBeSpecified", llms.utils.errorMessageCatalog.getMessage("llms:endpointMustBeSpecified"));
+        end
+    end
+end
+
+function deployment = getDeployment(nvp)
+    if isfield(nvp, "Deployment")
+        deployment = nvp.Deployment;
+    else
+        if isenv("AZURE_OPENAI_DEPLOYMENT")
+            deployment = getenv("AZURE_OPENAI_DEPLOYMENT");
+        else
+            error("llms:deploymentMustBeSpecified", llms.utils.errorMessageCatalog.getMessage("llms:deploymentMustBeSpecified"));
+        end
+    end
+end
diff --git a/doc/Azure.md b/doc/Azure.md
@@ -16,6 +16,8 @@ Some of the [current LLMs supported on Azure](https://learn.microsoft.com/en-us/
 Set up your [endpoint and deployment and retrieve one of the API keys](https://learn.microsoft.com/en-us/azure/ai-services/openai/chatgpt-quickstart?tabs=command-line%2Cpython-new&pivots=rest-api#retrieve-key-and-endpoint). Create a `.env` file in the project root directory with the following content.
 
 ```
+AZURE_OPENAI_ENDPOINT=<your endpoint>
+AZURE_OPENAI_DEPLOYMENT=<your deployment>
 AZURE_OPENAI_API_KEY=<your key>
 ```
 
@@ -29,11 +31,11 @@ loadenv(".env")
 
 ## Establishing a connection to Chat Completions API using Azure
 
-To connect MATLAB to Chat Completions API via Azure, you will have to create an `azureChat` object. See [the Azure documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/chatgpt-quickstart) for details on the setup required and where to find your key, endpoint, and deployment name. As explained above, the key should be in the environment variable `AZURE_OPENAI_API_KEY`, or provided as `APIKey=…` in the `azureChat` call below.
+To connect MATLAB to Chat Completions API via Azure, you will have to create an `azureChat` object. See [the Azure documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/chatgpt-quickstart) for details on the setup required and where to find your key, endpoint, and deployment name. As explained above, the endpoint, deployment, and key should be in the environment variables `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_DEPLOYMENYT`, and `AZURE_OPENAI_API_KEY`, or provided as `Endpoint=…`, `Deployment=…`, and `APIKey=…` in the `azureChat` call below.
 
-In order to create the chat assistant, specify your Azure OpenAI Resource and the LLM you want to use:
+In order to create the chat assistant, use the `azureChat` function, optionally providing a system prompt:
 ```matlab
-chat = azureChat(YOUR_ENDPOINT_NAME, YOUR_DEPLOYMENT_NAME, "You are a helpful AI assistant");
+chat = azureChat("You are a helpful AI assistant");
 ```
 
 The `azureChat` object also allows to specify additional options. Call `help azureChat` for more information.
@@ -60,7 +62,7 @@ systemPrompt = "You are a sentiment analyser. You will look at a sentence and ou
     "His attitude was terribly discouraging to the team." + newline +...
     "negative" + newline + newline;
 
-chat = azureChat(YOUR_ENDPOINT_NAME, YOUR_DEPLOYMENT_NAME, systemPrompt);
+chat = azureChat(systemPrompt);
 
 % Generate a response, passing a new sentence for classification
 txt = generate(chat,"The team is feeling very motivated")
@@ -80,7 +82,7 @@ history = messageHistory;
 Then create the chat assistant:
 
 ```matlab
-chat = azureChat(YOUR_ENDPOINT_NAME, YOUR_DEPLOYMENT_NAME, "You are a helpful AI assistant.");
+chat = azureChat;
 ```
 
 Add a user message to the history and pass it to `generate`:
@@ -108,7 +110,7 @@ Streaming allows you to start receiving the output from the API as it is generat
 ```matlab
 % streaming function
 sf = @(x) fprintf("%s",x);
-chat = azureChat(YOUR_ENDPOINT_NAME, YOUR_DEPLOYMENT_NAME, StreamFun=sf);
+chat = azureChat(StreamFun=sf);
 txt = generate(chat,"What is Model-Based Design and how is it related to Digital Twin?")
 % Should stream the response token by token
 ```
@@ -123,7 +125,7 @@ For example, if you want to use the API for mathematical operations such as `sin
 ```matlab
 f = openAIFunction("sind","Sine of argument in degrees");
 f = addParameter(f,"x",type="number",description="Angle in degrees.");
-chat = azureChat(YOUR_ENDPOINT_NAME,YOUR_DEPLOYMENT_NAME,"You are a helpful assistant.",Tools=f);
+chat = azureChat("You are a helpful assistant.",Tools=f);
 ```
 
 When the model identifies that it could use the defined functions to answer a query, it will return a `tool_calls` request, instead of directly generating the response:
@@ -217,8 +219,7 @@ f = addParameter(f,"patientSymptoms",type="string",description="Symptoms that th
 Note that this function does not need to exist, since it will only be used to extract the Name, Age and Symptoms of the patient and it does not need to be called:
 
 ```matlab
-chat = azureChat(YOUR_ENDPOINT_NAME, YOUR_DEPLOYMENT_NAME, ...
-    "You are helpful assistant that reads patient records and extracts information", ...
+chat = azureChat("You are helpful assistant that reads patient records and extracts information", ...
     Tools=f);
 messages = messageHistory;
 messages = addUserMessage(messages,"Extract the information from the report:" + newline + patientReport);
@@ -258,4 +259,3 @@ ans =
 ```
 
 You can extract the arguments and write the data to a table, for example.
-
diff --git a/functionSignatures.json b/functionSignatures.json
@@ -44,16 +44,16 @@
     {
         "inputs":
         [
-            {"name":"endpoint","kind":"positional","type":["string","scalar"]},
-            {"name":"deploymentID","kind":"positional","type":["string","scalar"]},
             {"name":"systemPrompt","kind":"ordered","type":["string","scalar"]},
+            {"name":"Endpoint","kind":"namevalue","type":["string","scalar"]},
+            {"name":"Deployment","kind":"namevalue","type":["string","scalar"]},
+            {"name":"APIKey","kind":"namevalue","type":["string","scalar"]},
             {"name":"Tools","kind":"namevalue","type":"openAIFunction"},
             {"name":"APIVersion","kind":"namevalue","type":"choices=llms.azure.apiVersions"},
             {"name":"Temperature","kind":"namevalue","type":["numeric","scalar",">=0","<=2"]},
             {"name":"TopP","kind":"namevalue","type":["numeric","scalar",">=0","<=1"]},
             {"name":"StopSequences","kind":"namevalue","type":["string","vector"]},
             {"name":"ResponseFormat","kind":"namevalue","type":"choices={'text','json'}"},
-            {"name":"APIKey","kind":"namevalue","type":["string","scalar"]},
             {"name":"PresencePenalty","kind":"namevalue","type":["numeric","scalar","<=2",">=-2"]},
             {"name":"FrequencyPenalty","kind":"namevalue","type":["numeric","scalar","<=2",">=-2"]},
             {"name":"TimeOut","kind":"namevalue","type":["numeric","scalar","real","positive"]},
@@ -108,7 +108,6 @@
         [
             {"name":"this","kind":"required","type":["ollamaChat","scalar"]},
             {"name":"messages","kind":"required","type":[["messageHistory","row"],["string","scalar"]]},
-            {"name":"NumCompletions","kind":"namevalue","type":["numeric","scalar","integer","positive"]},
             {"name":"MaxNumTokens","kind":"namevalue","type":["numeric","scalar","positive"]},
             {"name":"Seed","kind":"namevalue","type":["numeric","integer","scalar"]}
         ],
diff --git a/tests/tazureChat.m b/tests/tazureChat.m
@@ -12,7 +12,6 @@
 
     methods(Test)
         function constructChatWithAllNVP(testCase)
-            endpoint = getenv("AZURE_OPENAI_ENDPOINT");
             deploymentID = "hello";
             functions = openAIFunction("funName");
             temperature = 0;
@@ -23,7 +22,7 @@ function constructChatWithAllNVP(testCase)
             frequenceP = 2;
             systemPrompt = "This is a system prompt";
             timeout = 3;
-            chat = azureChat(endpoint, deploymentID, systemPrompt, Tools=functions, ...
+            chat = azureChat(systemPrompt, Deployment=deploymentID, Tools=functions, ...
                 Temperature=temperature, TopP=topP, StopSequences=stop, APIKey=apiKey,...
                 FrequencyPenalty=frequenceP, PresencePenalty=presenceP, TimeOut=timeout);
             testCase.verifyEqual(chat.Temperature, temperature);
@@ -35,22 +34,22 @@ function constructChatWithAllNVP(testCase)
 
         function doGenerate(testCase,StringInputs)
             testCase.assumeTrue(isenv("AZURE_OPENAI_API_KEY"),"end-to-end test requires environment variables AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, and AZURE_OPENAI_DEPLOYMENT.");
-            chat = azureChat(getenv("AZURE_OPENAI_ENDPOINT"), getenv("AZURE_OPENAI_DEPLOYMENT"));
+            chat = azureChat;
             response = testCase.verifyWarningFree(@() generate(chat,StringInputs));
             testCase.verifyClass(response,'string');
             testCase.verifyGreaterThan(strlength(response),0);
         end
 
         function generateMultipleResponses(testCase)
-            chat = azureChat(getenv("AZURE_OPENAI_ENDPOINT"), getenv("AZURE_OPENAI_DEPLOYMENT"));
+            chat = azureChat;
             [~,~,response] = generate(chat,"What is a cat?",NumCompletions=3);
             testCase.verifySize(response.Body.Data.choices,[3,1]);
         end
 
 
         function doReturnErrors(testCase)
             testCase.assumeTrue(isenv("AZURE_OPENAI_API_KEY"),"end-to-end test requires environment variables AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, and AZURE_OPENAI_DEPLOYMENT.");
-            chat = azureChat(getenv("AZURE_OPENAI_ENDPOINT"), getenv("AZURE_OPENAI_DEPLOYMENT"));
+            chat = azureChat;
             % This input is considerably longer than accepted as input for
             % GPT-3.5 (16385 tokens)
             wayTooLong = string(repmat('a ',1,20000));
@@ -59,7 +58,7 @@ function doReturnErrors(testCase)
 
         function seedFixesResult(testCase)
             testCase.assumeTrue(isenv("AZURE_OPENAI_API_KEY"),"end-to-end test requires environment variables AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, and AZURE_OPENAI_DEPLOYMENT.");
-            chat = azureChat(getenv("AZURE_OPENAI_ENDPOINT"), getenv("AZURE_OPENAI_DEPLOYMENT"));
+            chat = azureChat;
             response1 = generate(chat,"hi",Seed=1234);
             response2 = generate(chat,"hi",Seed=1234);
             testCase.verifyEqual(response1,response2);
@@ -76,8 +75,7 @@ function createAzureChatWithStreamFunc(testCase)
                 data = [data, str];
                 seen = data;
             end
-            chat = azureChat(getenv("AZURE_OPENAI_ENDPOINT"), getenv("AZURE_OPENAI_DEPLOYMENT"), ...
-                StreamFun=@sf);
+            chat = azureChat(StreamFun=@sf);
 
             testCase.verifyWarningFree(@()generate(chat, "Hello world."));
             % Checking that persistent data, which is still stored in
@@ -93,8 +91,7 @@ function generateWithTools(testCase)
             f = addParameter(f, "location", type="string", description="The city and country, optionally state. E.g., San Francisco, CA, USA");
             f = addParameter(f, "unit", type="string", enum=["Kelvin","Celsius"], RequiredParameter=false);
 
-            chat = azureChat(getenv("AZURE_OPENAI_ENDPOINT"), getenv("AZURE_OPENAI_DEPLOYMENT"), ...
-                Tools=f);
+            chat = azureChat(Tools=f);
 
             prompt =  "What's the weather like in San Francisco, Tokyo, and Paris?";
             [~, response] = generate(chat, prompt, ToolChoice="getCurrentWeather");
@@ -108,12 +105,12 @@ function generateWithTools(testCase)
         end
 
         function errorsWhenPassingToolChoiceWithEmptyTools(testCase)
-            chat = azureChat(getenv("AZURE_OPENAI_ENDPOINT"), getenv("AZURE_OPENAI_DEPLOYMENT"), APIKey="this-is-not-a-real-key");
+            chat = azureChat(APIKey="this-is-not-a-real-key");
             testCase.verifyError(@()generate(chat,"input", ToolChoice="bla"), "llms:mustSetFunctionsForCall");
         end
 
         function shortErrorForBadEndpoint(testCase)
-            chat = azureChat("https://nobodyhere.whatever/","deployment");
+            chat = azureChat(Endpoint="https://nobodyhere.whatever/");
             caught = false;
             try
                 generate(chat,"input");
@@ -126,17 +123,17 @@ function shortErrorForBadEndpoint(testCase)
         end
 
         function invalidInputsConstructor(testCase, InvalidConstructorInput)
-            testCase.verifyError(@()azureChat(getenv("AZURE_OPENAI_ENDPOINT"), getenv("AZURE_OPENAI_DEPLOYMENT"), InvalidConstructorInput.Input{:}), InvalidConstructorInput.Error);
+            testCase.verifyError(@()azureChat(InvalidConstructorInput.Input{:}), InvalidConstructorInput.Error);
         end
 
         function invalidInputsGenerate(testCase, InvalidGenerateInput)
             f = openAIFunction("validfunction");
-            chat = azureChat(getenv("AZURE_OPENAI_ENDPOINT"), getenv("AZURE_OPENAI_DEPLOYMENT"), Tools=f, APIKey="this-is-not-a-real-key");
+            chat = azureChat(Tools=f, APIKey="this-is-not-a-real-key");
             testCase.verifyError(@()generate(chat,InvalidGenerateInput.Input{:}), InvalidGenerateInput.Error);
         end
 
         function invalidSetters(testCase, InvalidValuesSetters)
-            chat = azureChat(getenv("AZURE_OPENAI_ENDPOINT"), getenv("AZURE_OPENAI_DEPLOYMENT"), APIKey="this-is-not-a-real-key");
+            chat = azureChat(APIKey="this-is-not-a-real-key");
             function assignValueToProperty(property, value)
                 chat.(property) = value;
             end
@@ -151,7 +148,7 @@ function keyNotFound(testCase)
             import matlab.unittest.fixtures.EnvironmentVariableFixture
             testCase.applyFixture(EnvironmentVariableFixture("AZURE_OPENAI_API_KEY","dummy"));
             unsetenv("AZURE_OPENAI_API_KEY");
-            testCase.verifyError(@()azureChat(getenv("AZURE_OPENAI_ENDPOINT"), getenv("AZURE_OPENAI_DEPLOYMENT")), "llms:keyMustBeSpecified");
+            testCase.verifyError(@()azureChat, "llms:keyMustBeSpecified");
         end
     end
 end
