[Azure OpenAI] Replace SearchKey and EmbeddingKey properties with SetSearchKey and SetEmbeddingKey methods

sdk/openai/Azure.AI.OpenAI/CHANGELOG.md

@@ -80,10 +80,18 @@ And *added* as replacements are:
 - `CompletionsOptions(string, IEnumerable<string>)`
 - `EmbeddingsOptions(string, IEnumerable<string>)`
 
-#### Embeddings
+#### Embeddings now represented as `ReadOnlyMemory<float>`
 
-To align representations of embeddings across Azure AI, the `Embeddings` type has been updated to use
-`ReadOnlyMemory<float>` instead of `IReadOnlyList<float>`.
+Changed the representation of embeddings (specifically, the type of the `Embedding` property of the `EmbeddingItem` class)
+from `IReadOnlyList<float>` to `ReadOnlyMemory<float>` as part of a broader effort to establish consistency across the
+.NET ecosystem.
+
+#### `SearchKey` and `EmbeddingKey` properties replaced by `SetSearchKey` and `SetEmbeddingKey` methods
+
+Replaced the `SearchKey` and `EmbeddingKey` properties of the `AzureCognitiveSearchChatExtensionConfiguration` class with
+new `SetSearchKey` and `SetEmbeddingKey` methods respectively. These methods simplify the configuration of the Azure Cognitive
+Search chat extension by receiving a plain string instead of an `AzureKeyCredential`, promote more sensible key and secret
+management, and align with the Azure SDK guidelines.
 
 ### Bugs Fixed
 

sdk/openai/Azure.AI.OpenAI/README.md

@@ -418,7 +418,15 @@ See [the Azure OpenAI using your own data quickstart](https://learn.microsoft.co
 **NOTE:** The concurrent use of [Chat Functions](#use-chat-functions) and Azure Chat Extensions on a single request is not yet supported. Supplying both will result in the Chat Functions information being ignored and the operation behaving as if only the Azure Chat Extensions were provided. To address this limitation, consider separating the evaluation of Chat Functions and Azure Chat Extensions across multiple requests in your solution design.
 
 ```C# Snippet:ChatUsingYourOwnData
-var chatCompletionsOptions = new ChatCompletionsOptions()
+AzureCognitiveSearchChatExtensionConfiguration contosoExtensionConfig = new()
+{
+    SearchEndpoint = new Uri("https://your-contoso-search-resource.search.windows.net"),
+    IndexName = "contoso-products-index",
+};
+
+contosoExtensionConfig.SetSearchKey("<your Cognitive Search resource API key>");
+
+ChatCompletionsOptions chatCompletionsOptions = new()
 {
     DeploymentName = "gpt-35-turbo-0613",
     Messages =
@@ -428,29 +436,26 @@ var chatCompletionsOptions = new ChatCompletionsOptions()
             "You are a helpful assistant that answers questions about the Contoso product database."),
         new ChatMessage(ChatRole.User, "What are the best-selling Contoso products this month?")
     },
+
     // The addition of AzureChatExtensionsOptions enables the use of Azure OpenAI capabilities that add to
     // the behavior of Chat Completions, here the "using your own data" feature to supplement the context
     // with information from an Azure Cognitive Search resource with documents that have been indexed.
     AzureExtensionsOptions = new AzureChatExtensionsOptions()
     {
-        Extensions =
-        {
-            new AzureCognitiveSearchChatExtensionConfiguration()
-            {
-                SearchEndpoint = new Uri("https://your-contoso-search-resource.search.windows.net"),
-                IndexName = "contoso-products-index",
-                SearchKey = new AzureKeyCredential("<your Cognitive Search resource API key>"),
-            }
-        }
+        Extensions = { contosoExtensionConfig }
     }
 };
+
 Response<ChatCompletions> response = await client.GetChatCompletionsAsync(chatCompletionsOptions);
 ChatMessage message = response.Value.Choices[0].Message;
+
 // The final, data-informed response still appears in the ChatMessages as usual
 Console.WriteLine($"{message.Role}: {message.Content}");
+
 // Responses that used extensions will also have Context information that includes special Tool messages
 // to explain extension activity and provide supplemental information like citations.
 Console.WriteLine($"Citations and other information:");
+
 foreach (ChatMessage contextMessage in message.AzureExtensionsContext.Messages)
 {
     // Note: citations and other extension payloads from the "tool" role are often encoded JSON documents

sdk/openai/Azure.AI.OpenAI/api/Azure.AI.OpenAI.netstandard2.0.cs

@@ -144,18 +144,18 @@ public AzureChatExtensionsOptions() { }
     public partial class AzureCognitiveSearchChatExtensionConfiguration : Azure.AI.OpenAI.AzureChatExtensionConfiguration
     {
         public AzureCognitiveSearchChatExtensionConfiguration() { }
-        public AzureCognitiveSearchChatExtensionConfiguration(Azure.AI.OpenAI.AzureChatExtensionType type, System.Uri searchEndpoint, Azure.AzureKeyCredential searchKey, string indexName) { }
+        public AzureCognitiveSearchChatExtensionConfiguration(Azure.AI.OpenAI.AzureChatExtensionType type, System.Uri searchEndpoint, string indexName) { }
         public int? DocumentCount { get { throw null; } set { } }
         public System.Uri EmbeddingEndpoint { get { throw null; } set { } }
-        public Azure.AzureKeyCredential EmbeddingKey { get { throw null; } set { } }
         public Azure.AI.OpenAI.AzureCognitiveSearchIndexFieldMappingOptions FieldMappingOptions { get { throw null; } set { } }
         public string IndexName { get { throw null; } set { } }
         public Azure.AI.OpenAI.AzureCognitiveSearchQueryType? QueryType { get { throw null; } set { } }
         public System.Uri SearchEndpoint { get { throw null; } set { } }
-        public Azure.AzureKeyCredential SearchKey { get { throw null; } set { } }
         public string SemanticConfiguration { get { throw null; } set { } }
         public bool? ShouldRestrictResultScope { get { throw null; } set { } }
         public override Azure.AI.OpenAI.AzureChatExtensionType Type { get { throw null; } set { } }
+        public void SetEmbeddingKey(string embeddingKey) { }
+        public void SetSearchKey(string searchKey) { }
     }
     public partial class AzureCognitiveSearchIndexFieldMappingOptions
     {

sdk/openai/Azure.AI.OpenAI/src/Custom/AzureCognitiveSearchChatExtensionConfiguration.Serialization.cs

@@ -22,7 +22,7 @@ void IUtf8JsonSerializable.Write(Utf8JsonWriter writer)
 
             writer.WritePropertyName("endpoint"u8);
             writer.WriteStringValue(SearchEndpoint.AbsoluteUri);
-            writer.WriteString("key"u8, SearchKey.Key);
+            writer.WriteString("key"u8, SearchKey);
             writer.WritePropertyName("indexName"u8);
             writer.WriteStringValue(IndexName);
             if (Optional.IsDefined(FieldMappingOptions))
@@ -57,7 +57,7 @@ void IUtf8JsonSerializable.Write(Utf8JsonWriter writer)
             }
             if (Optional.IsDefined(EmbeddingKey))
             {
-                writer.WriteString("embeddingKey"u8, EmbeddingKey.Key);
+                writer.WriteString("embeddingKey"u8, EmbeddingKey);
             }
             // CUSTOM CODE NOTE: end of induced 'parameters' first, then the parent object
             writer.WriteEndObject();

sdk/openai/Azure.AI.OpenAI/src/Custom/AzureCognitiveSearchChatExtensionConfiguration.cs

@@ -26,12 +26,25 @@ public override AzureChatExtensionType Type
 
         /// <summary> The absolute endpoint path for the Azure Cognitive Search resource to use. </summary>
         public Uri SearchEndpoint { get; set; }
-        /// <summary> The API key to use with the specified Azure Cognitive Search endpoint. </summary>
-        public AzureKeyCredential SearchKey { get; set; }
         /// <summary> The name of the index to use as available in the referenced Azure Cognitive Search resource. </summary>
         public string IndexName { get; set; }
+        /// <summary> Customized field mapping behavior to use when interacting with the search index. </summary>
+        public AzureCognitiveSearchIndexFieldMappingOptions FieldMappingOptions { get; set; }
+        /// <summary> The configured top number of documents to feature for the configured query. </summary>
+        public int? DocumentCount { get; set; }
+        /// <summary> The query type to use with Azure Cognitive Search. </summary>
+        public AzureCognitiveSearchQueryType? QueryType { get; set; }
+        /// <summary> Whether queries should be restricted to use of indexed data. </summary>
+        public bool? ShouldRestrictResultScope { get; set; }
+        /// <summary> The additional semantic configuration for the query. </summary>
+        public string SemanticConfiguration { get; set; }
+        /// <summary> When using embeddings for search, specifies the resource URL from which embeddings should be retrieved. </summary>
+        public Uri EmbeddingEndpoint { get; set; }
+
+        /// <summary> The API key to use with the specified Azure Cognitive Search endpoint. </summary>
+        private string SearchKey { get; set; }
         /// <summary> When using embeddings, specifies the API key to use with the provided embeddings endpoint. </summary>
-        public AzureKeyCredential EmbeddingKey { get; set; }
+        private string EmbeddingKey { get; set; }
 
         /// <summary>
         /// Initializes a new instance of AzureCognitiveSearchChatExtensionConfiguration.
@@ -46,61 +59,34 @@ public AzureCognitiveSearchChatExtensionConfiguration()
         /// default value for Azure Cognitive Search.
         /// </param>
         /// <param name="searchEndpoint"> The absolute endpoint path for the Azure Cognitive Search resource to use. </param>
-        /// <param name="searchKey"> The API key to use with the specified Azure Cognitive Search endpoint. </param>
         /// <param name="indexName"> The name of the index to use as available in the referenced Azure Cognitive Search resource. </param>
-        /// <exception cref="ArgumentNullException"> <paramref name="searchEndpoint"/>, <paramref name="searchKey"/> or <paramref name="indexName"/> is null. </exception>
-        public AzureCognitiveSearchChatExtensionConfiguration(AzureChatExtensionType type, Uri searchEndpoint, AzureKeyCredential searchKey, string indexName)
+        /// <exception cref="ArgumentNullException"> <paramref name="searchEndpoint"/>, or <paramref name="indexName"/> is null. </exception>
+        public AzureCognitiveSearchChatExtensionConfiguration(AzureChatExtensionType type, Uri searchEndpoint, string indexName)
         {
             Argument.AssertNotNull(searchEndpoint, nameof(searchEndpoint));
-            Argument.AssertNotNull(searchKey, nameof(searchKey));
             Argument.AssertNotNull(indexName, nameof(indexName));
 
             Type = type;
             SearchEndpoint = searchEndpoint;
-            SearchKey = searchKey;
             IndexName = indexName;
         }
 
-        /// <summary> Initializes a new instance of AzureCognitiveSearchChatExtensionConfiguration. </summary>
-        /// <param name="type">
-        /// The type label to use when configuring Azure OpenAI chat extensions. This should typically not be changed from its
-        /// default value for Azure Cognitive Search.
-        /// </param>
-        /// <param name="searchEndpoint"> The absolute endpoint path for the Azure Cognitive Search resource to use. </param>
-        /// <param name="searchKey"> The API key to use with the specified Azure Cognitive Search endpoint. </param>
-        /// <param name="indexName"> The name of the index to use as available in the referenced Azure Cognitive Search resource. </param>
-        /// <param name="fieldMappingOptions"> Customized field mapping behavior to use when interacting with the search index. </param>
-        /// <param name="documentCount"> The configured top number of documents to feature for the configured query. </param>
-        /// <param name="queryType"> The query type to use with Azure Cognitive Search. </param>
-        /// <param name="shouldRestrictResultScope"> Whether queries should be restricted to use of indexed data. </param>
-        /// <param name="semanticConfiguration"> The additional semantic configuration for the query. </param>
-        /// <param name="embeddingEndpoint"> When using embeddings for search, specifies the resource URL from which embeddings should be retrieved. </param>
-        /// <param name="embeddingKey"> When using embeddings, specifies the API key to use with the provided embeddings endpoint. </param>
-        internal AzureCognitiveSearchChatExtensionConfiguration(AzureChatExtensionType type, Uri searchEndpoint, AzureKeyCredential searchKey, string indexName, AzureCognitiveSearchIndexFieldMappingOptions fieldMappingOptions, int? documentCount, AzureCognitiveSearchQueryType? queryType, bool? shouldRestrictResultScope, string semanticConfiguration, Uri embeddingEndpoint, AzureKeyCredential embeddingKey)
+        /// <summary>
+        /// Sets the API key to use with the specified Azure Cognitive Search endpoint.
+        /// </summary>
+        /// <param name="searchKey"> The API key. </param>
+        public void SetSearchKey(string searchKey)
         {
-            Type = type;
-            SearchEndpoint = searchEndpoint;
             SearchKey = searchKey;
-            IndexName = indexName;
-            FieldMappingOptions = fieldMappingOptions;
-            DocumentCount = documentCount;
-            QueryType = queryType;
-            ShouldRestrictResultScope = shouldRestrictResultScope;
-            SemanticConfiguration = semanticConfiguration;
-            EmbeddingEndpoint = embeddingEndpoint;
+        }
+
+        /// <summary>
+        /// Sets the API key to use with the provided embeddings endpoint when using embeddings.
+        /// </summary>
+        /// <param name="embeddingKey"> The API key. </param>
+        public void SetEmbeddingKey(string embeddingKey)
+        {
             EmbeddingKey = embeddingKey;
         }
-        /// <summary> Customized field mapping behavior to use when interacting with the search index. </summary>
-        public AzureCognitiveSearchIndexFieldMappingOptions FieldMappingOptions { get; set; }
-        /// <summary> The configured top number of documents to feature for the configured query. </summary>
-        public int? DocumentCount { get; set; }
-        /// <summary> The query type to use with Azure Cognitive Search. </summary>
-        public AzureCognitiveSearchQueryType? QueryType { get; set; }
-        /// <summary> Whether queries should be restricted to use of indexed data. </summary>
-        public bool? ShouldRestrictResultScope { get; set; }
-        /// <summary> The additional semantic configuration for the query. </summary>
-        public string SemanticConfiguration { get; set; }
-        /// <summary> When using embeddings for search, specifies the resource URL from which embeddings should be retrieved. </summary>
-        public Uri EmbeddingEndpoint { get; set; }
     }
 }