Azure OpenAI Typespec definition for v2024-09-01-preview and v2024-10-01-preview service releases

[jpalvarezl]

[!IMPORTANT] This PR is introducing changes for both v2024-09-01-preview and v2024-10-01-preview

v2024-09-01-preview changes

OpenAI.Inference

• stream_options was re-added for Completions and ChatCompletions
• new field max_completion_tokens for ChatCompletions. Existing nax_tokens is deprecated.
• new field completion_tokens_details in CompletionUsage (tokens used for OAI reasoning purposes it seems)
• parallel_tool_calls for CreateChatCompletionRequest was re-added as well (seems to be a change only for Assistants)

OpenAI.Assistants

• parallel_tool_calls for RunObject, CreateRunRequest and CreateRunAndThreadRequest was re-added as well (seems to be a change only for Assistants)

v2024-10-01-preview changes

OpenAI.Inference

• Updating documentation for embeddings POST endpoint
• Adding model contentFilterCompletionTextSpan and contentFilterDetectedWithCompletionTextSpansResult
• Adding optional property ungrounded_material of the type mentioned above to contentFilterChoiceResults model
• details property in contentFilterChoiceResults is mandatory from now on
• Updating documentation for chatCompletionsRequest members: max_tokens and max_completion_tokens
• Adding prompt_token_details property to completionDetails model

[openapi-pipeline-app[bot]]

Next Steps to Merge

Next steps that must be taken to merge this PR:

• ❌ This is the public specs repo main branch which is not intended for iterative development.
  You must acknowledge that you understand that after this PR is merged, you won't be able to stop your changes from being published to Azure customers.
  If this is what you intend, add PublishToCustomers label to your PR.
  Otherwise, retarget this PR onto a feature branch, i.e. with prefix release- (see aka.ms/azsdk/api-versions#release--branches).
• ❌ Your PR requires an API stewardship board review as it introduces a new API version (label: new-api-version). Schedule the review by following aka.ms/azsdk/onboarding/restapischedule.
• ❌ This PR has at least one change violating Azure versioning policy (label: VersioningReviewRequired).
  To unblock this PR, either a) introduce a new API version with these changes instead of modifying an existing API version, or b) follow the process at aka.ms/brch.
• ❌ The required check named Swagger LintDiff has failed. Refer to the check in the PR's 'Checks' tab for details on how to fix it and consult the aka.ms/ci-fix guide

[openapi-pipeline-app[bot]]

Generated ApiView

Language	Package Name	ApiView Link
Java	azure-ai-openai	https://apiview.dev/Assemblies/Review/0b875c11102a447c8807ad710b3d4e7c?revisionId=7bb1b3b3e7ed45478cc777ab762b576c
Java	azure-ai-openai-assistants	https://apiview.dev/Assemblies/Review/0de2531533684902a49ba4716e45072d?revisionId=f581fe9f89fb4086a00afb826758c42a
TypeSpec	OpenAI.Assistants	https://apiview.dev/Assemblies/Review/4b4fdc5389144eb0b1bc12f2d179963a?revisionId=5261f06274f146bbabaea4786ea98a6d
TypeSpec	OpenAI.Inference	https://apiview.dev/Assemblies/Review/b8c186a18c34460e831aaed4436c9b43?revisionId=a427c9c2b3bb4cd084d5e0f4c54b1ee8
Swagger	AzureOpenAI	https://apiview.dev/Assemblies/Review/6693675ace534d4aa3159f202a195962?revisionId=7ef0bfbc1d1d4b00a8e45e3a219e45a4
Swagger	OpenAI.Assistants	https://apiview.dev/Assemblies/Review/837caf5c571a45d590bc4a2da0d1a103?revisionId=a2b75b7431284ea5a61602805a43f0ab

[brandom-msft]

Why does parallel_tool_calls show as required here? https://github.com/Azure/azure-rest-api-specs/blob/4d8ea51f1b2400a8c5840a13eec1dd8c16f6c564/specification/ai/data-plane/OpenAI.Assistants/OpenApiV3/2024-09-01-preview/assistants_generated.yaml#L3633

For that to be the case, there needs to be an associated entry in inference.yaml, right? (I don't see it there, so it makes me think I'm missing a step)

[trrwilson]

Why does parallel_tool_calls show as required here?

https://github.com/Azure/azure-rest-api-specs/blob/4d8ea51f1b2400a8c5840a13eec1dd8c16f6c564/specification/ai/data-plane/OpenAI.Assistants/OpenApiV3/2024-09-01-preview/assistants_generated.yaml#L3633

For that to be the case, there needs to be an associated entry in inference.yaml, right? (I don't see it there, so it makes me think I'm missing a step)

It's defined in the TypeSpec as required (hence why it reflects that way here):

  @added(ServiceApiVersions.v2024_09_01_preview)
  @encodedName("application/json", "parallel_tool_calls")
  parallelToolCalls: boolean = true;

Interestingly, the published inference.* files in the data-plane folder (the hand-maintained ones from the service team) do not include parallel_tool_calls in the required properties of runObject (line 5619 in the 2024-09-01-preview .yaml) -- but I'm almost certain that it actually is required. It is in OpenAI's spec, too.

[openapi-pipeline-app[bot]]

PR validation pipeline can not start as the pull request is not merged or mergeable - most likely it has merge conflicts.

[jpalvarezl]

@trrwilson , I will resolve this comment: https://github.com/Azure/azure-rest-api-specs/pull/30909#discussion_r1797414167

But this remains an issues that I understand will be addressed as code customization at the client library level. Let's re-open this discussion if we see that there is something smart that can be done in the spec side of things.

[jpalvarezl]

Added changes for v2024_10_01_preview in 65f854e

[lmazuel]

Discussed offline that CI breakage can't be fixed