TypeSpec for Azure AI Inference

[dargilco]

Data Plane API - Pull Request

Azure AI Studio now hosts a catalog of Large Language Models (LLM) for chat completion, embeddings and image generation, as two offerings called Model-as-a-Service (MaaS, aka "Pay as you go") and Model-as-a-Platform (MaaP, aka "Real-time endpoint"). This TypeSpec defines the common REST API for endpoints hosting these models. It is checked in here to facilitate auto-geration of the client libraries (Python, JS and C# at the moment). Other programing languages will follow. The service team uses Python code which at run-time auto-generates a Swagger file for the service. They do not use the TypeSpec files in this PR. But I am verifying that their Swagger and the one created by this TypeSpec are equivalent, and the emitted client libraries work properly when connecting to this service.

For more information on the catalog see Explore the model catalog in Azure AI Studio.

This TypeSpec is a subset of the Azure OpenAI Inference TypeSpec and additional changes. We use the same model and property names for now, but that may be subject to change. It implements four routes /chat/completions, /embeddings, /image-generation/ and /info.

Is this review for (select one):

• [x] a private preview
• [ ] a public preview
• [ ] GA release

[openapi-pipeline-app[bot]]

Next Steps to Merge

Next steps that must be taken to merge this PR:

• ❌ This PR targets either the main branch of the public specs repo or the RPSaaSMaster branch of the private specs repo. These branches are not intended for iterative development. Therefore, you must acknowledge you understand that after this PR is merged, the APIs are considered shipped to Azure customers. Any further attempts at in-place modifications to the APIs will be subject to Azure's versioning and breaking change policies. Additionally, for control plane APIs, you must acknowledge that you are following all the best practices documented by ARM at aka.ms/armapibestpractices. If you do intend to release the APIs to your customers by merging this PR, add the PublishToCustomers label to your PR in acknowledgement of the above. 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.
• ❌ The required check named TypeSpec Validation 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]]

Swagger Validation Report

️️✔️BreakingChange succeeded [Detail] [Expand]

There are no breaking changes.

️️✔️Breaking Change(Cross-Version) succeeded [Detail] [Expand]

There are no breaking changes.

️️✔️CredScan succeeded [Detail] [Expand]

There is no credential detected.

️⚠️LintDiff: 12 Warnings warning [Detail]

Compared specs (v2.2.2)	new version	base version
package-2024-05-01-preview	package-2024-05-01-preview(dda6da8)	default(main)

[must fix]The following errors/warnings are introduced by current PR:

Rule	Message	Related RPC [For API reviewers]
:warning: SecurityDefinitionDescription	Security definition should have a description. Location: ModelClient/preview/2024-05-01-preview/openapi.json#L29
:warning: OperationId	OperationId should be of the form 'Noun_Verb' Location: ModelClient/preview/2024-05-01-preview/openapi.json#L42
:warning: ParameterDescription	Parameter should have a description. Location: ModelClient/preview/2024-05-01-preview/openapi.json#L82
:warning: EnumInsteadOfBoolean	Booleans properties are not descriptive in all cases and can make them to use, evaluate whether is makes sense to keep the property as boolean or turn it into an enum. Location: ModelClient/preview/2024-05-01-preview/openapi.json#L106
:warning: PropertyType	Property should have a defined type. Location: ModelClient/preview/2024-05-01-preview/openapi.json#L161
:warning: OperationId	OperationId should be of the form 'Noun_Verb' Location: ModelClient/preview/2024-05-01-preview/openapi.json#L213
:warning: ParameterDescription	Parameter should have a description. Location: ModelClient/preview/2024-05-01-preview/openapi.json#L253
:warning: OperationId	OperationId should be of the form 'Noun_Verb' Location: ModelClient/preview/2024-05-01-preview/openapi.json#L319
:warning: ParameterDescription	Parameter should have a description. Location: ModelClient/preview/2024-05-01-preview/openapi.json#L359
:warning: OperationId	OperationId should be of the form 'Noun_Verb' Location: ModelClient/preview/2024-05-01-preview/openapi.json#L426
:warning: PropertyType	Property should have a defined type. Location: ModelClient/preview/2024-05-01-preview/openapi.json#L950
:warning: PropertyType	Property should have a defined type. Location: ModelClient/preview/2024-05-01-preview/openapi.json#L1289

️️✔️Avocado succeeded [Detail] [Expand]

Validation passes for Avocado.

️️✔️SwaggerAPIView succeeded [Detail] [Expand]

️️✔️TypeSpecAPIView succeeded [Detail] [Expand]

️️✔️ModelValidation succeeded [Detail] [Expand]

Validation passes for ModelValidation.

️️✔️SemanticValidation succeeded [Detail] [Expand]

Validation passes for SemanticValidation.

️️✔️PoliCheck succeeded [Detail] [Expand]

Validation passed for PoliCheck.

️️✔️SpellCheck succeeded [Detail] [Expand]

Validation passes for SpellCheck.

️️✔️Lint(RPaaS) succeeded [Detail] [Expand]

Validation passes for Lint(RPaaS).

️️✔️PR Summary succeeded [Detail] [Expand]

Validation passes for Summary.

️️✔️Automated merging requirements met succeeded [Detail] [Expand]

_{Posted by Swagger Pipeline | How to fix these errors?}

[openapi-pipeline-app[bot]]

Swagger Generation Artifacts

️️✔️ApiDocPreview succeeded [Detail] [Expand]

 Please click here to preview with your @microsoft account. 

️⚠️ azure-sdk-for-python warning [Detail]

For more instructions, please refer to the FAQ .
• ⚠️Warning in generating from 821752a02b00a60a2fb347197c1b9a8cb6c4b8e2. SDK Automation 14.0.0

  command	sh scripts/automation_init.sh ../azure-sdk-for-python_tmp/initInput.json ../azure-sdk-for-python_tmp/initOutput.json
  cmderr	[automation_init.sh] W: Target Packages (main/binary-amd64/Packages) is configured multiple times in /etc/apt/sources.list.d/azure-cli.list:1 and /etc/apt/sources.list.d/azure-cli.sources:1
  cmderr	[automation_init.sh] W: Target Packages (main/binary-all/Packages) is configured multiple times in /etc/apt/sources.list.d/azure-cli.list:1 and /etc/apt/sources.list.d/azure-cli.sources:1
  cmderr	[automation_init.sh] W: Target Translations (main/i18n/Translation-en) is configured multiple times in /etc/apt/sources.list.d/azure-cli.list:1 and /etc/apt/sources.list.d/azure-cli.sources:1
  cmderr	[automation_init.sh] W: Target CNF (main/cnf/Commands-amd64) is configured multiple times in /etc/apt/sources.list.d/azure-cli.list:1 and /etc/apt/sources.list.d/azure-cli.sources:1
  cmderr	[automation_init.sh] W: Target CNF (main/cnf/Commands-all) is configured multiple times in /etc/apt/sources.list.d/azure-cli.list:1 and /etc/apt/sources.list.d/azure-cli.sources:1
  cmderr	[automation_init.sh] W: Target Packages (main/binary-amd64/Packages) is configured multiple times in /etc/apt/sources.list.d/azure-cli.list:1 and /etc/apt/sources.list.d/azure-cli.sources:1
  cmderr	[automation_init.sh] W: Target Packages (main/binary-all/Packages) is configured multiple times in /etc/apt/sources.list.d/azure-cli.list:1 and /etc/apt/sources.list.d/azure-cli.sources:1
  cmderr	[automation_init.sh] W: Target Translations (main/i18n/Translation-en) is configured multiple times in /etc/apt/sources.list.d/azure-cli.list:1 and /etc/apt/sources.list.d/azure-cli.sources:1
  cmderr	[automation_init.sh] W: Target CNF (main/cnf/Commands-amd64) is configured multiple times in /etc/apt/sources.list.d/azure-cli.list:1 and /etc/apt/sources.list.d/azure-cli.sources:1
  cmderr	[automation_init.sh] W: Target CNF (main/cnf/Commands-all) is configured multiple times in /etc/apt/sources.list.d/azure-cli.list:1 and /etc/apt/sources.list.d/azure-cli.sources:1
  cmderr	[automation_init.sh] WARNING: Skipping azure-nspkg as it is not installed.
  cmderr	[automation_init.sh] npm notice
  cmderr	[automation_init.sh] npm notice New minor version of npm available! 10.7.0 -> 10.8.2
  cmderr	[automation_init.sh] npm notice Changelog: https://github.com/npm/cli/releases/tag/v10.8.2
  cmderr	[automation_init.sh] npm notice To update run: npm install -g [email protected]
  cmderr	[automation_init.sh] npm notice
  warn		Warning: azure-sdk-for-python cannot be found in specification/ai/data-plane/AI.Model/readme.md. This SDK will be skipped from SDK generation. Please add the right config to the readme file according to this guidance https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/code-gen/configure-go-sdk.md#swagger-to-sdk.
  command	sh scripts/automation_generate.sh ../azure-sdk-for-python_tmp/generateInput.json ../azure-sdk-for-python_tmp/generateOutput.json

• ️✔️azure-ai-inference [Preview SDK Changes]

  info	[Changelog] data-plan skip changelog generation temporarily

_{Posted by Swagger Pipeline | How to fix these errors?}

[openapi-pipeline-app[bot]]

PR validation pipeline restarted successfully. If there is ApiView generated, it will be updated in this comment.

[openapi-pipeline-app[bot]]

Swagger Generation Artifacts

️🔄ApiDocPreview inProgress [Detail]

_{Posted by Swagger Pipeline | How to fix these errors?}

[openapi-pipeline-app[bot]]

Swagger Validation Report

️️✔️BreakingChange succeeded [Detail] [Expand]

There are no breaking changes.

️️✔️Breaking Change(Cross-Version) succeeded [Detail] [Expand]

There are no breaking changes.

️⌛CredScan pending [Detail]

️🔄LintDiff inProgress [Detail]

️️✔️Avocado succeeded [Detail] [Expand]

Validation passes for Avocado.

️🔄SwaggerAPIView inProgress [Detail]

️️✔️TypeSpecAPIView succeeded [Detail] [Expand]

️️✔️ModelValidation succeeded [Detail] [Expand]

Validation passes for ModelValidation.

️️✔️SemanticValidation succeeded [Detail] [Expand]

Validation passes for SemanticValidation.

️⌛PoliCheck pending [Detail]

️️✔️SpellCheck succeeded [Detail] [Expand]

Validation passes for SpellCheck.

️🔄Lint(RPaaS) inProgress [Detail]

️⌛PR Summary pending [Detail]

️⌛Automated merging requirements met pending [Detail]

_{Posted by Swagger Pipeline | How to fix these errors?}

[dargilco]

Assigned to @dargilco

[dargilco]

Thank you for your comment @weidongxu-microsoft , I will look into this when I get back to working on this SDK, as part of releasing another beta version.

[azure-sdk]

API Change Check

APIView identified API level changes in this PR and created the following API reviews

Language	API Review for Package
TypeSpec	AI.Model
Swagger	AI.Model-AI.Model

[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.

[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.

[microsoft-github-policy-service[bot]]

Hi, @@dargilco. Your PR has no update for 14 days and it is marked as stale PR. If no further update for over 14 days, the bot will close the PR. If you want to refresh the PR, please remove no-recent-activity label.

[microsoft-github-policy-service[bot]]

Hi, @@dargilco. The PR will be closed since the PR has no update for 28 days. If you still need the PR review to proceed, please reopen it and @ mention PR assignee.