diff --git a/specification/ai/ModelClient/client.tsp b/specification/ai/ModelClient/client.tsp index a79fe7c54788..010538e65580 100644 --- a/specification/ai/ModelClient/client.tsp +++ b/specification/ai/ModelClient/client.tsp @@ -16,17 +16,20 @@ namespace Customizations; // The actual name here doesn't matter and is here for @@usage(AI.Model.StreamingChatResponseMessageUpdate, Usage.output); @@usage(AI.Model.StreamingChatResponseToolCallUpdate, Usage.output); -// Since we made all operator methods internal, we need to expliclty -// say we still want the models they use to be public. +// The operators need to be hidden, since we hand-write the public versions of those +@@access(AI.Model.getChatCompletions, Access.internal); +@@access(AI.Model.getEmbeddings, Access.internal); +@@access(AI.Model.getImageEmbeddings, Access.internal); +@@access(AI.Model.getModelInfo, Access.internal, "python"); + +// Since we made all operator methods internal, we need to explicity +// say we still want the models they use to be public, since they will be used by hand-written operator methods. @@access(AI.Model.ChatChoice, Access.public); @@access(AI.Model.ChatCompletions, Access.public); @@access(AI.Model.ChatCompletionsToolCall, Access.public); @@access(AI.Model.ChatCompletionsToolDefinition, Access.public); @@access(AI.Model.ChatCompletionsNamedToolChoice, Access.public); @@access(AI.Model.ChatCompletionsNamedToolChoiceFunction, Access.public); -@@access(AI.Model.ChatCompletionsResponseFormat, Access.public); -@@access(AI.Model.ChatCompletionsResponseFormatJsonObject, Access.public); -@@access(AI.Model.ChatCompletionsResponseFormatText, Access.public); @@access(AI.Model.ChatCompletionsToolCall, Access.public); @@access(AI.Model.ChatCompletionsToolDefinition, Access.public); @@access(AI.Model.ChatCompletionsToolChoicePreset, Access.public); @@ -58,17 +61,14 @@ namespace Customizations; // The actual name here doesn't matter and is here for @@access(AI.Model.StreamingChatChoiceUpdate, Access.public, "python"); @@access(AI.Model.StreamingChatResponseMessageUpdate, Access.public, "python"); @@access(AI.Model.StreamingChatResponseToolCallUpdate, Access.public, "python"); +@@access(AI.Model.ChatCompletionsResponseFormatJsonSchemaDefinition, + Access.public, + "python" +); -// The operators need to be hidden, since we hand-write the public versions of those -@@access(AI.Model.getChatCompletions, Access.internal); -@@access(AI.Model.getEmbeddings, Access.internal); -@@access(AI.Model.getImageEmbeddings, Access.internal); -@@access(AI.Model.getModelInfo, Access.internal, "python"); - -// Hide the JSON schema class in favor of a factory method on the ChatCompletionsResponseFormat class -@@access(AI.Model.ChatCompletionsResponseFormatJsonSchema, - Access.internal, - "csharp" +@@clientName(AI.Model.ChatCompletionsResponseFormatJsonSchemaDefinition, + "JsonSchemaFormat", + "python" ); // We use shorter names in the Python client library diff --git a/specification/ai/ModelClient/models/chat_completions.tsp b/specification/ai/ModelClient/models/chat_completions.tsp index 0441d120cf25..d116015b550b 100644 --- a/specification/ai/ModelClient/models/chat_completions.tsp +++ b/specification/ai/ModelClient/models/chat_completions.tsp @@ -266,22 +266,32 @@ model ChatCompletionsResponseFormatJsonObject } @doc(""" - The definition of the required JSON schema in the response, and associated metadata. + Defines the response format for chat completions as JSON with a given schema. The AI model + will need to adhere to this schema when generating completions. """) model ChatCompletionsResponseFormatJsonSchemaDefinition { - /** The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. */ + @doc(""" + A name that labels this JSON schema. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + """) name: string; - /** The definition of the JSON schema */ + @doc(""" + The definition of the JSON schema. See https://json-schema.org/overview/what-is-jsonschema. + Note that AI models usually only support a subset of the keywords defined by JSON schema. Consult your AI model documentation + to determine what is supported. + """) schema: Record; - /** A description of the response format, used by the AI model to determine how to generate responses in this format. */ + @doc(""" + A description of the response format, used by the AI model to determine how to generate responses in this format. + """) description?: string; @doc(""" - Whether to enable strict schema adherence when generating the output. - If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of - JSON Schema is supported when `strict` is `true`. + If set to true, the service will error out if the provided JSON schema contains keywords + not supported by the AI model. An example of such keyword may be `maxLength` for JSON type `string`. + If false, and the provided JSON schema contains keywords not supported + by the AI model, the AI model will not error out. Instead it will ignore the unsupported keywords. """) strict?: boolean = false; } diff --git a/specification/ai/data-plane/AI.Model/preview/2024-05-01-preview/openapi.json b/specification/ai/data-plane/AI.Model/preview/2024-05-01-preview/openapi.json index d4496175fee6..7c947507a382 100644 --- a/specification/ai/data-plane/AI.Model/preview/2024-05-01-preview/openapi.json +++ b/specification/ai/data-plane/AI.Model/preview/2024-05-01-preview/openapi.json @@ -688,15 +688,15 @@ }, "ChatCompletionsResponseFormatJsonSchemaDefinition": { "type": "object", - "description": "The definition of the required JSON schema in the response, and associated metadata.", + "description": "Defines the response format for chat completions as JSON with a given schema. The AI model\nwill need to adhere to this schema when generating completions.", "properties": { "name": { "type": "string", - "description": "The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64." + "description": "A name that labels this JSON schema. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64." }, "schema": { "type": "object", - "description": "The definition of the JSON schema", + "description": "The definition of the JSON schema. See https://json-schema.org/overview/what-is-jsonschema.\nNote that AI models usually only support a subset of the keywords defined by JSON schema. Consult your AI model documentation\nto determine what is supported.", "additionalProperties": {} }, "description": { @@ -705,7 +705,7 @@ }, "strict": { "type": "boolean", - "description": "Whether to enable strict schema adherence when generating the output.\nIf set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of\nJSON Schema is supported when `strict` is `true`.", + "description": "If set to true, the service will error out if the provided JSON schema contains keywords\nnot supported by the AI model. An example of such keyword may be `maxLength` for JSON type `string`.\nIf false, and the provided JSON schema contains keywords not supported\nby the AI model, the AI model will not error out. Instead it will ignore the unsupported keywords.", "default": false } },