Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update ServerlessEndpoints design #25593

Merged
merged 20 commits into from
Sep 22, 2023
Merged

Update ServerlessEndpoints design #25593

Changes from 1 commit
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
666e7aa
first draft redesign of ServerlessEndpoints
forteddyt Aug 30, 2023
d07667d
add getStatus.json
forteddyt Aug 30, 2023
d908cda
update examples
forteddyt Aug 30, 2023
79103cc
add LRO location header to example
forteddyt Aug 30, 2023
7899fe1
add CapacityReservationGroups API
forteddyt Sep 1, 2023
be6f5d3
spellcheck fix
forteddyt Sep 1, 2023
15e9f19
example fix
forteddyt Sep 1, 2023
29752b6
capacity reservation groups should be under resource groups
forteddyt Sep 7, 2023
8109593
fix examples
forteddyt Sep 7, 2023
5addebf
inferenceUri -> uri
forteddyt Sep 7, 2023
62a75a6
CapacityReservation -> ServerlessEndpointCapacityReservation
forteddyt Sep 7, 2023
9f18b19
update description
forteddyt Sep 15, 2023
9e7d67c
remove ExcessCapacityReservation concept
forteddyt Sep 21, 2023
7a1bfeb
remove parentGroupId concept
forteddyt Sep 21, 2023
767baac
rename /status api to /getStatus
forteddyt Sep 21, 2023
d447cb8
label metrics as readOnly
forteddyt Sep 22, 2023
1754025
lintdiff GET fix
forteddyt Sep 22, 2023
bb6c086
more fixes
forteddyt Sep 22, 2023
93462c1
add listBySubscription
forteddyt Sep 22, 2023
88ab27c
add/fix examples
forteddyt Sep 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
197 changes: 175 additions & 22 deletions ...es/resource-manager/Microsoft.MachineLearningServices/preview/2023-08-01-preview/mfe.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11866,6 +11866,59 @@
"final-state-via": "location"
}
}
},
"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.MachineLearningServices/workspaces/{workspaceName}/serverlessEndpoints/{name}/status": {
"post": {
"tags": [
"ServerlessEndpoint"
],
"summary": "Temporary status API until integration completes.",
"operationId": "ServerlessEndpoints_GetStatus",
"produces": [
"application/json"
],
"parameters": [
{
"$ref": "../../../../../common-types/resource-management/v3/types.json#/parameters/SubscriptionIdParameter"
},
{
"$ref": "../../../../../common-types/resource-management/v3/types.json#/parameters/ResourceGroupNameParameter"
},
{
"$ref": "machineLearningServices.json#/parameters/WorkspaceNameParameter"
},
{
"in": "path",
"name": "name",
"description": "Serverless Endpoint name.",
"required": true,
"type": "string",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9\\-_]{0,254}$"
},
{
"$ref": "../../../../../common-types/resource-management/v3/types.json#/parameters/ApiVersionParameter"
}
],
"responses": {
"200": {
"description": "Success",
"schema": {
"$ref": "#/definitions/ServerlessEndpointStatus"
}
},
"default": {
"description": "Error",
"schema": {
"$ref": "../../../../../common-types/resource-management/v3/types.json#/definitions/ErrorResponse"
}
}
},
"x-ms-examples": {
"GetStatus Workspace Serverless Endpoint.": {
"$ref": "./examples/Workspace/ServerlessEndpoint/getStatus.json"
}
}
}
}
},
"definitions": {
Expand Down Expand Up @@ -13277,6 +13330,27 @@
},
"additionalProperties": false
},
"CapacityReservation": {
"required": [
"capacityReservationGroupId"
],
"type": "object",
"properties": {
"capacityReservationGroupId": {
"description": "[Required] Specifies a capacity reservation group ID to allocate capacity from.",
"minLength": 1,
"pattern": "[a-zA-Z0-9_]",
"type": "string"
},
"endpointReservedCapacity": {
"format": "int32",
"description": "Specifies a capacity amount to reserve for this endpoint within the parent capacity reservation group.",
"type": "integer",
"x-nullable": true
}
},
"additionalProperties": false
},
"CategoricalDataDriftMetric": {
"enum": [
"JensenShannonDistance",
Expand Down Expand Up @@ -20615,21 +20689,6 @@
"x-ms-discriminator-value": "ModelPerformance",
"additionalProperties": false
},
"ModelProfile": {
"required": [
"modelUri"
],
"type": "object",
"properties": {
"modelUri": {
"description": "[Required] The model to create a serverless endpoint of",
"minLength": 1,
"pattern": "[a-zA-Z0-9_]",
"type": "string"
}
},
"additionalProperties": false
},
"ModelSize": {
"description": "Image model size.",
"enum": [
Expand Down Expand Up @@ -24544,23 +24603,31 @@
},
"ServerlessEndpoint": {
"required": [
"modelProfile"
"offer"
],
"type": "object",
"properties": {
"inferenceUri": {
"format": "uri",
"authMode": {
"description": "Specifies the authentication mode for the Serverless endpoint.",
"$ref": "#/definitions/ServerlessInferenceEndpointAuthMode"
},
"capacityReservation": {
"description": "Optional capacity reservation information for the endpoint. When specified, the Serverless Endpoint\r\nwill be allocated capacity from the specified capacity reservation group.",
"$ref": "#/definitions/CapacityReservation",
"x-nullable": true
},
"inferenceEndpoint": {
"description": "The inference uri to target when making requests against the serverless endpoint",
"type": "string",
"$ref": "#/definitions/ServerlessInferenceEndpoint",
"readOnly": true,
"x-ms-mutability": [
"read"
],
"x-nullable": true
},
"modelProfile": {
"description": "[Required] The model profile to configure the serverless endpoint with",
"$ref": "#/definitions/ModelProfile"
"offer": {
"description": "[Required] The publisher-defined Serverless Offer to provision the endpoint with.",
"$ref": "#/definitions/ServerlessOffer"
},
"provisioningState": {
"description": "Provisioning state for the endpoint.",
Expand All @@ -24574,6 +24641,20 @@
"x-ms-client-name": "ServerlessEndpointProperties",
"additionalProperties": false
},
"ServerlessEndpointStatus": {
"type": "object",
"properties": {
"metrics": {
"type": "object",
"additionalProperties": {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

additionalProperties

Additional properties pattern is an ARM anti-pattern.
Generally, this pattern should only be used when needed and the object properties are dynamic, unknown, or user defined. Ref: https://armwiki.azurewebsites.net/api_contracts/guidelines/openapi.html#oapi032-only-use-additionalproperties-when-the-object-properties-are-dynamic-unknown-or-user-defined.

Can you schematize this?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case, the information dynamic. The list of metrics will be model dependent, some of which may come from 3P ISVs etc. Hence it is modeled as a generic string dictionary.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please book an ARM modeling office hours slot and go over the design with the ARM API reviewer to assess if this pattern can be approved.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We have booked an office hour, however we are concerned about the time delay so wondering if we can close on this faster over IM or a team call.

The key thing here is that our service is not in control of all possible keys in this dictionary, because this data comes from customers (specifically, model providers). We are hoping this is a valid use case of additional properties

Copy link
Contributor

@visingla-ms visingla-ms Sep 22, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please make this read only as was discussed in office hours. #Resolved

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added readonly

"type": "string",
"x-nullable": true
},
"x-nullable": true
}
},
"additionalProperties": false
},
"ServerlessEndpointTrackedResource": {
"required": [
"location",
Expand Down Expand Up @@ -24624,6 +24705,78 @@
},
"additionalProperties": false
},
"ServerlessInferenceEndpoint": {
"required": [
"inferenceUri"
],
"type": "object",
"properties": {
"headers": {
"description": "Specifies any required headers to target this serverless endpoint.",
"type": "object",
Copy link
Contributor

@visingla-ms visingla-ms Sep 22, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please make this read only property here as discussed earlier. #Resolved

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

readonly is already there, it looks like

"additionalProperties": {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

additionalProperties

Same feedback here. Can this be schematized? Otherwise it's difficult and risky for clients to consume.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same situation here applies. The content here is model dependent. It is intended as a generic contract to the client to populate these required headers when sending inferencing requests.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To elaborate, the possible "headers" is unbounded based on customer (specifically, the model provider), so there is no way for us to specify all possible values in the schema upfront. I hope this is a valid use case of additional properties.

"type": "string",
"x-nullable": true
},
"readOnly": true,
"x-ms-mutability": [
"read"
],
"x-nullable": true
},
"inferenceUri": {
"format": "uri",
"description": "[Required] The inference uri to target when making requests against the Serverless Endpoint.",
"type": "string",
"x-ms-mutability": [
"read"
]
}
},
"additionalProperties": false
},
"ServerlessInferenceEndpointAuthMode": {
"enum": [
"Key",
"AAD"
],
"type": "string",
"x-ms-enum": {
"name": "ServerlessInferenceEndpointAuthMode",
"modelAsString": true,
"values": [
{
"value": "Key"
},
{
"value": "AAD"
}
]
},
"additionalProperties": false
},
"ServerlessOffer": {
"required": [
"offerName",
"publisher"
],
"type": "object",
"properties": {
"offerName": {
"description": "[Required] The name of the Serverless Offer",
"minLength": 1,
"pattern": "[a-zA-Z0-9_]",
"type": "string"
},
"publisher": {
"description": "[Required] Publisher name of the Serverless Offer",
"minLength": 1,
"pattern": "[a-zA-Z0-9_]",
"type": "string"
}
},
"additionalProperties": false
},
"ServiceDataAccessAuthIdentity": {
"enum": [
"None",
Expand Down