[Cognitive Services - AzureOpenAI] API Review

[azure-sdk]

New API Review meeting has been requested.

Service Name: Cognitive Services - AzureOpenAI Review Created By: Ralf Beckers Review Date: 11/22/2022 1:00 PM PT PR: https://github.com/Azure/azure-rest-api-specs/pull/21312 Hero Scenarios Link: Not Provided Core Concepts Doc Link: Not Provided

Description: GA version of OpenAI fine tuning API (2022-12-01)

Previous Reviews: 6273 6301

Detailed meeting information and documents provided can be accessed here

[mikekistler]

• Should entityError just use the Error schema? You can still define the error code enum but just leave it stand alone.

  • We should review the language in the guidelines to make sure it's clear that the error code enum can have new values to describe new error conditions

• Some information on the maximum values for numeric values would be helpful, even if it is just to say that it varies by model.

• Should OpenAI use the Azure deprecating header when models are deprecated?

• Should use x-ms-client-default rather than default for the api-version parameter.

• Use "format: unixtime" on the integer timestamps.

• Please add descriptions to the properties in inference.json.

Ted left some questions/comments in the APIView

Mike left some questions/comments in the PR

Meeting recording

[markweitzel]

Follow up from the review meeting yesterday:

There were concerns, that without doc generation, the inference part will be basically an undocumented API. @Chris Hoder pointed out that we have hand written docs for using Azure OpenAI which includes the inference part too. One can find it here: https://learn.microsoft.com/en-us/azure/cognitive-services/openai/reference Can we close this question now that we have public doc about the inference part? We have the OpenApi v3 doc available for all details.

All Cognitive services swagger files have the error type (re)defined in their swagger files. I’ve updated my PR to use the single error schema with the merged error codes. Is it OK to leave the single error schema in to have a self contained document? If not, which type from common types should I reference? I could not find a matching one.

[bexxx]

Feedback and open issues have been addressed in the PR.

• replaced entityerror with the common error type
• maximum and minimum values are going to addressed in hand written docs because they are model specific
• We will not use deprecation headers right now, there is some discussion and update to the azure rest spec documentation needed before this can be done (possible SDK generation work too). However this can be added in a non breaking way in a future version.
• switched to using x-ms-client-default as suggested
• switch to format: unixtime" for time stamps
• added descriptions to inference.json where available on OpenAI API spec
• addressed Ted's comments on APIView (resolved them there)
• addressed Mike's comments in PR
• commented on current tooling failures in PR