diff --git a/specification/cognitiveservices/ContentSafety/models.tsp b/specification/cognitiveservices/ContentSafety/models.tsp index 3efd85052b07..2679c8fe1785 100644 --- a/specification/cognitiveservices/ContentSafety/models.tsp +++ b/specification/cognitiveservices/ContentSafety/models.tsp @@ -523,76 +523,97 @@ model AnalyzeImageWithTextResult { categoriesAnalysis: ImageWithTextCategoriesAnalysis[]; } -@added(Versions.v2023_11_30_Preview) -@doc("Connection information for GPT resource.") -model GptResource { - @doc("Endpoint of Azure OpenAI resource.") - azureOpenAIEndpoint: string; - - @doc("Deployment name of GPT model.") - deploymentName: string; -} - #suppress "@azure-tools/typespec-azure-core/documentation-required" "MUST fix in next update" -@added(ContentSafety.Versions.v2023_11_30_Preview) -@doc("domain category.") +@added(ContentSafety.Versions.v2023_10_30_Preview) +@doc("Domain.") enum Domain { Generic, Medical, } #suppress "@azure-tools/typespec-azure-core/documentation-required" "MUST fix in next update" -@added(ContentSafety.Versions.v2023_11_30_Preview) -@doc("task type.") +@added(ContentSafety.Versions.v2023_10_30_Preview) +@doc("Task type.") enum Task { Summarization, QnA, } -@added(Versions.v2023_11_30_Preview) +@added(Versions.v2023_10_30_Preview) +@doc("Connection details for the GPT resource.") +model GptResource { + @doc("Endpoint of Azure OpenAI resource.") + azureOpenAIEndpoint: string; + + @doc("Deployment model name.") + deploymentName: string; +} + +@added(Versions.v2023_10_30_Preview) @doc("The request of ungroudedness detection.") model DetectUngroundednessOptions { - @doc("Domain of the text to be analyzed.") + @doc(""" + The domain of the text for analysis. + This field is optional, with a default value of Generic. + """) domain?: Domain; - @doc("Task type of the text to be analyzed.") + @doc(""" + The task type for the text analysis. + This field is optional, with a default value of Summarization. + """) task?: Task; - @doc("This is optional and only required for QnA task.") + @doc(""" + The user's question input in a QnA scenario. + This field is optional, but if the Task type is set to QnA, it becomes required. + """) query?: string; - @doc("The text needs to be analyzed.") + @doc("The text requiring analysis.") text: string; - @doc("Source information that serves as grounding source.") + @doc("The source information used as a grounding reference.") groundingSources: string[]; - @doc("GPT resource connection information.") + @doc(""" + A value indicating if the output includes an explanation for the identified ungroundedness. + This field is optional, with a default value of false. + """) + reasoning?: boolean; + + @doc(""" + Connection details for the GPT resource. + This field will be used only when the 'reasoning' field is set to true; otherwise, it will be ignored. + """) gptResource?: GptResource; } -@added(Versions.v2023_11_30_Preview) -@doc("The detailed information about a text identified as ungroundness.") +@added(Versions.v2023_10_30_Preview) +@doc("The detailed information about a text identified as ungrounded.") model UngroundedDetails { @doc("The ungrounded text.") text: string; - @doc("The reason or explanation for identifying the text as ungrounded.") - reason: string; + @doc(""" + The explanation for identifying the text as ungrounded. + Only when the 'reasoning' field in the input is set to true will the API return this 'reason' field. + """) + reason?: string; } -@added(Versions.v2023_11_30_Preview) +@added(Versions.v2023_10_30_Preview) @doc("The response of ungroudedness detection.") model DetectUngroundednessResult { @doc("Detection result for ungrouded text.") ungrounded: boolean; - @doc("Model confidence store in the analysis results.") + @doc("Confidence score of the model in the analysis results.") confidenceScore: float32; - @doc("Percentage of Ungrounded Text.") + @doc("Percentage of ungrounded Text.") ungroundedPercentage: float32; - @doc("The detailed information about a text identified as ungroundness.") + @doc("The detailed information about a text identified as ungrounded.") ungroundedDetails: UngroundedDetails[]; } diff --git a/specification/cognitiveservices/ContentSafety/routes.tsp b/specification/cognitiveservices/ContentSafety/routes.tsp index 7db454d8a81b..b39a7c74bf07 100644 --- a/specification/cognitiveservices/ContentSafety/routes.tsp +++ b/specification/cognitiveservices/ContentSafety/routes.tsp @@ -302,10 +302,10 @@ interface ImageWithTextOperations { >; } -@added(Versions.v2023_11_30_Preview) +@added(Versions.v2023_10_30_Preview) interface TextUngroundednessDetectionOperations{ @summary("Detect Ungrounded Information") - @doc("A synchronous API for the analysis of language model outputs to determine if they align with the information provided by the user or contain fictional content.") + @doc("A synchronous API for the analysis of language model outputs to determine alignment with user-provided information or identify fictional content.") @route("/text:detectUngroundedness") @post detectUngroundedness is Azure.Core.RpcOperation< diff --git a/specification/cognitiveservices/data-plane/ContentSafety/preview/2023-10-30-preview/contentsafety.json b/specification/cognitiveservices/data-plane/ContentSafety/preview/2023-10-30-preview/contentsafety.json index e8d4361d08e6..9f4ae8425aca 100644 --- a/specification/cognitiveservices/data-plane/ContentSafety/preview/2023-10-30-preview/contentsafety.json +++ b/specification/cognitiveservices/data-plane/ContentSafety/preview/2023-10-30-preview/contentsafety.json @@ -1593,6 +1593,47 @@ } } } + }, + "/text:detectUngroundedness": { + "post": { + "operationId": "TextUngroundednessDetectionOperations_DetectUngroundedness", + "summary": "Detect Ungrounded Information", + "description": "A synchronous API for the analysis of language model outputs to determine alignment with user-provided information or identify fictional content.", + "parameters": [ + { + "$ref": "#/parameters/Azure.Core.Foundations.ApiVersionParameter" + }, + { + "name": "body", + "in": "body", + "description": "The ungroundedness detection request.", + "required": true, + "schema": { + "$ref": "#/definitions/DetectUngroundednessOptions" + } + } + ], + "responses": { + "200": { + "description": "The request has succeeded.", + "schema": { + "$ref": "#/definitions/DetectUngroundednessResult" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/Azure.Core.Foundations.ErrorResponse" + }, + "headers": { + "x-ms-error-code": { + "type": "string", + "description": "String error code indicating what went wrong." + } + } + } + } + } } }, "definitions": { @@ -2072,6 +2113,111 @@ } } }, + "DetectUngroundednessOptions": { + "type": "object", + "description": "The request of ungroudedness detection.", + "properties": { + "domain": { + "$ref": "#/definitions/Domain", + "description": "The domain of the text for analysis.\nThis field is optional, with a default value of Generic." + }, + "task": { + "$ref": "#/definitions/Task", + "description": "The task type for the text analysis.\nThis field is optional, with a default value of Summarization." + }, + "query": { + "type": "string", + "description": "The user's question input in a QnA scenario.\nThis field is optional, but if the Task type is set to QnA, it becomes required." + }, + "text": { + "type": "string", + "description": "The text requiring analysis." + }, + "groundingSources": { + "type": "array", + "description": "The source information used as a grounding reference.", + "items": { + "type": "string" + } + }, + "reasoning": { + "type": "boolean", + "description": "A value indicating if the output includes an explanation for the identified ungroundedness.\nThis field is optional, with a default value of false." + }, + "gptResource": { + "$ref": "#/definitions/GptResource", + "description": "Connection details for the GPT resource. \nThis field will be used only when the 'reasoning' field is set to true; otherwise, it will be ignored." + } + }, + "required": [ + "text", + "groundingSources" + ] + }, + "DetectUngroundednessResult": { + "type": "object", + "description": "The response of ungroudedness detection.", + "properties": { + "ungrounded": { + "type": "boolean", + "description": "Detection result for ungrouded text." + }, + "confidenceScore": { + "type": "number", + "format": "float", + "description": "Confidence score of the model in the analysis results." + }, + "ungroundedPercentage": { + "type": "number", + "format": "float", + "description": "Percentage of ungrounded Text." + }, + "ungroundedDetails": { + "type": "array", + "description": "The detailed information about a text identified as ungrounded.", + "items": { + "$ref": "#/definitions/UngroundedDetails" + }, + "x-ms-identifiers": [] + } + }, + "required": [ + "ungrounded", + "confidenceScore", + "ungroundedPercentage", + "ungroundedDetails" + ] + }, + "Domain": { + "type": "string", + "description": "Domain.", + "enum": [ + "Generic", + "Medical" + ], + "x-ms-enum": { + "name": "Domain", + "modelAsString": true + } + }, + "GptResource": { + "type": "object", + "description": "Connection details for the GPT resource.", + "properties": { + "azureOpenAIEndpoint": { + "type": "string", + "description": "Endpoint of Azure OpenAI resource." + }, + "deploymentName": { + "type": "string", + "description": "Deployment model name." + } + }, + "required": [ + "azureOpenAIEndpoint", + "deploymentName" + ] + }, "ImageCategoriesAnalysis": { "type": "object", "description": "Image analysis result.", @@ -2578,6 +2724,18 @@ "statements" ] }, + "Task": { + "type": "string", + "description": "Task type.", + "enum": [ + "Summarization", + "QnA" + ], + "x-ms-enum": { + "name": "Task", + "modelAsString": true + } + }, "TextBlocklist": { "type": "object", "description": "Text Blocklist.", @@ -2832,6 +2990,23 @@ "required": [ "incidentSampleId" ] + }, + "UngroundedDetails": { + "type": "object", + "description": "The detailed information about a text identified as ungrounded.", + "properties": { + "text": { + "type": "string", + "description": "The ungrounded text." + }, + "reason": { + "type": "string", + "description": "The explanation for identifying the text as ungrounded. \nOnly when the 'reasoning' field in the input is set to true will the API return this 'reason' field." + } + }, + "required": [ + "text" + ] } }, "parameters": { diff --git a/specification/cognitiveservices/data-plane/ContentSafety/preview/2023-11-30-preview/contentsafety.json b/specification/cognitiveservices/data-plane/ContentSafety/preview/2023-11-30-preview/contentsafety.json index 0bf718fe848e..c7620c93f53e 100644 --- a/specification/cognitiveservices/data-plane/ContentSafety/preview/2023-11-30-preview/contentsafety.json +++ b/specification/cognitiveservices/data-plane/ContentSafety/preview/2023-11-30-preview/contentsafety.json @@ -1648,7 +1648,7 @@ "post": { "operationId": "TextUngroundednessDetectionOperations_DetectUngroundedness", "summary": "Detect Ungrounded Information", - "description": "A synchronous API for the analysis of language model outputs to determine if they align with the information provided by the user or contain fictional content.", + "description": "A synchronous API for the analysis of language model outputs to determine alignment with user-provided information or identify fictional content.", "parameters": [ { "$ref": "#/parameters/Azure.Core.Foundations.ApiVersionParameter" @@ -2169,30 +2169,34 @@ "properties": { "domain": { "$ref": "#/definitions/Domain", - "description": "Domain of the text to be analyzed." + "description": "The domain of the text for analysis.\nThis field is optional, with a default value of Generic." }, "task": { "$ref": "#/definitions/Task", - "description": "Task type of the text to be analyzed." + "description": "The task type for the text analysis.\nThis field is optional, with a default value of Summarization." }, "query": { "type": "string", - "description": "This is optional and only required for QnA task." + "description": "The user's question input in a QnA scenario.\nThis field is optional, but if the Task type is set to QnA, it becomes required." }, "text": { "type": "string", - "description": "The text needs to be analyzed." + "description": "The text requiring analysis." }, "groundingSources": { "type": "array", - "description": "Source information that serves as grounding source.", + "description": "The source information used as a grounding reference.", "items": { "type": "string" } }, + "reasoning": { + "type": "boolean", + "description": "A value indicating if the output includes an explanation for the identified ungroundedness.\nThis field is optional, with a default value of false." + }, "gptResource": { "$ref": "#/definitions/GptResource", - "description": "GPT resource connection information." + "description": "Connection details for the GPT resource. \nThis field will be used only when the 'reasoning' field is set to true; otherwise, it will be ignored." } }, "required": [ @@ -2211,16 +2215,16 @@ "confidenceScore": { "type": "number", "format": "float", - "description": "Model confidence store in the analysis results." + "description": "Confidence score of the model in the analysis results." }, "ungroundedPercentage": { "type": "number", "format": "float", - "description": "Percentage of Ungrounded Text." + "description": "Percentage of ungrounded Text." }, "ungroundedDetails": { "type": "array", - "description": "The detailed information about a text identified as ungroundness.", + "description": "The detailed information about a text identified as ungrounded.", "items": { "$ref": "#/definitions/UngroundedDetails" }, @@ -2236,7 +2240,7 @@ }, "Domain": { "type": "string", - "description": "domain category.", + "description": "Domain.", "enum": [ "Generic", "Medical" @@ -2248,7 +2252,7 @@ }, "GptResource": { "type": "object", - "description": "Connection information for GPT resource.", + "description": "Connection details for the GPT resource.", "properties": { "azureOpenAIEndpoint": { "type": "string", @@ -2256,7 +2260,7 @@ }, "deploymentName": { "type": "string", - "description": "Deployment name of GPT model." + "description": "Deployment model name." } }, "required": [ @@ -2772,7 +2776,7 @@ }, "Task": { "type": "string", - "description": "task type.", + "description": "Task type.", "enum": [ "Summarization", "QnA" @@ -3039,7 +3043,7 @@ }, "UngroundedDetails": { "type": "object", - "description": "The detailed information about a text identified as ungroundness.", + "description": "The detailed information about a text identified as ungrounded.", "properties": { "text": { "type": "string", @@ -3047,12 +3051,11 @@ }, "reason": { "type": "string", - "description": "The reason or explanation for identifying the text as ungrounded." + "description": "The explanation for identifying the text as ungrounded. \nOnly when the 'reasoning' field in the input is set to true will the API return this 'reason' field." } }, "required": [ - "text", - "reason" + "text" ] } }, diff --git a/specification/cognitiveservices/data-plane/ContentSafety/preview/2023-12-30-preview/contentsafety.json b/specification/cognitiveservices/data-plane/ContentSafety/preview/2023-12-30-preview/contentsafety.json index 270636cf5fb4..9c4aad4a0c54 100644 --- a/specification/cognitiveservices/data-plane/ContentSafety/preview/2023-12-30-preview/contentsafety.json +++ b/specification/cognitiveservices/data-plane/ContentSafety/preview/2023-12-30-preview/contentsafety.json @@ -1648,7 +1648,7 @@ "post": { "operationId": "TextUngroundednessDetectionOperations_DetectUngroundedness", "summary": "Detect Ungrounded Information", - "description": "A synchronous API for the analysis of language model outputs to determine if they align with the information provided by the user or contain fictional content.", + "description": "A synchronous API for the analysis of language model outputs to determine alignment with user-provided information or identify fictional content.", "parameters": [ { "$ref": "#/parameters/Azure.Core.Foundations.ApiVersionParameter" @@ -2176,30 +2176,34 @@ "properties": { "domain": { "$ref": "#/definitions/Domain", - "description": "Domain of the text to be analyzed." + "description": "The domain of the text for analysis.\nThis field is optional, with a default value of Generic." }, "task": { "$ref": "#/definitions/Task", - "description": "Task type of the text to be analyzed." + "description": "The task type for the text analysis.\nThis field is optional, with a default value of Summarization." }, "query": { "type": "string", - "description": "This is optional and only required for QnA task." + "description": "The user's question input in a QnA scenario.\nThis field is optional, but if the Task type is set to QnA, it becomes required." }, "text": { "type": "string", - "description": "The text needs to be analyzed." + "description": "The text requiring analysis." }, "groundingSources": { "type": "array", - "description": "Source information that serves as grounding source.", + "description": "The source information used as a grounding reference.", "items": { "type": "string" } }, + "reasoning": { + "type": "boolean", + "description": "A value indicating if the output includes an explanation for the identified ungroundedness.\nThis field is optional, with a default value of false." + }, "gptResource": { "$ref": "#/definitions/GptResource", - "description": "GPT resource connection information." + "description": "Connection details for the GPT resource. \nThis field will be used only when the 'reasoning' field is set to true; otherwise, it will be ignored." } }, "required": [ @@ -2218,16 +2222,16 @@ "confidenceScore": { "type": "number", "format": "float", - "description": "Model confidence store in the analysis results." + "description": "Confidence score of the model in the analysis results." }, "ungroundedPercentage": { "type": "number", "format": "float", - "description": "Percentage of Ungrounded Text." + "description": "Percentage of ungrounded Text." }, "ungroundedDetails": { "type": "array", - "description": "The detailed information about a text identified as ungroundness.", + "description": "The detailed information about a text identified as ungrounded.", "items": { "$ref": "#/definitions/UngroundedDetails" }, @@ -2243,7 +2247,7 @@ }, "Domain": { "type": "string", - "description": "domain category.", + "description": "Domain.", "enum": [ "Generic", "Medical" @@ -2255,7 +2259,7 @@ }, "GptResource": { "type": "object", - "description": "Connection information for GPT resource.", + "description": "Connection details for the GPT resource.", "properties": { "azureOpenAIEndpoint": { "type": "string", @@ -2263,7 +2267,7 @@ }, "deploymentName": { "type": "string", - "description": "Deployment name of GPT model." + "description": "Deployment model name." } }, "required": [ @@ -2779,7 +2783,7 @@ }, "Task": { "type": "string", - "description": "task type.", + "description": "Task type.", "enum": [ "Summarization", "QnA" @@ -3046,7 +3050,7 @@ }, "UngroundedDetails": { "type": "object", - "description": "The detailed information about a text identified as ungroundness.", + "description": "The detailed information about a text identified as ungrounded.", "properties": { "text": { "type": "string", @@ -3054,12 +3058,11 @@ }, "reason": { "type": "string", - "description": "The reason or explanation for identifying the text as ungrounded." + "description": "The explanation for identifying the text as ungrounded. \nOnly when the 'reasoning' field in the input is set to true will the API return this 'reason' field." } }, "required": [ - "text", - "reason" + "text" ] } },