Azure OpenAI Swagger Validation Failure with APIM

题意：Azure OpenAI Swagger 验证失败与 APIM

问题背景：

I'm converting the Swagger for Azure OpenAI API Version 2023-07-01-preview from json to yaml

我正在将 Azure OpenAI API 版本 2023-07-01-preview 的 Swagger 从 JSON 转换为 YAML。

My Swagger looks like this        我的 Swagger 看起来是这样的

openapi: 3.0.1
info:title: OpenAI Models APIdescription: ''version: '123'
servers:- url: https://def.com/openai
paths:/gpt-35-turbo/chat/completions:post:tags:- openaisummary: Creates a completion for the chat messagedescription: gpt-35-turbo-chat-completionoperationId: GPT_35_Turbo_ChatCompletions_CreaterequestBody:required: truecontent:application/json:schema:$ref: '#/components/schemas/createChatCompletionRequest'responses:'200':description: OKcontent:application/json:schema:$ref: '#/components/schemas/createChatCompletionResponse'headers:apim-request-id:description: Request ID for troubleshooting purposesschema:type: stringdefault:description: Service unavailablecontent:application/json:schema:$ref: '#/components/schemas/errorResponse'headers:apim-request-id:description: Request ID for troubleshooting purposesschema:type: string
components:schemas:errorResponse:type: objectproperties:error:$ref: '#/components/schemas/error'errorBase:type: objectproperties:code:type: stringmessage:type: stringerror:type: objectallOf:- $ref: '#/components/schemas/errorBase'properties:code:type: stringmessage:type: stringparam:type: stringtype:type: stringinner_error:$ref: '#/components/schemas/innerError'innerError:description: Inner error with additional details.type: objectproperties:code:$ref: '#/components/schemas/innerErrorCode'content_filter_results:$ref: '#/components/schemas/contentFilterResults'innerErrorCode:description: Error codes for the inner error object.enum:- ResponsibleAIPolicyViolationtype: stringx-ms-enum:name: InnerErrorCodemodelAsString: truevalues:- value: ResponsibleAIPolicyViolationdescription: The prompt violated one of more content filter rules.  contentFilterResult:type: objectproperties:severity:type: stringenum:- safe- low- medium- highx-ms-enum:name: ContentFilterSeveritymodelAsString: truevalues:- value: safedescription: >-General content or related content in generic or non-harmfulcontexts.- value: lowdescription: Harmful content at a low intensity and risk level.- value: mediumdescription: Harmful content at a medium intensity and risk level.- value: highdescription: Harmful content at a high intensity and risk level.filtered:type: booleanrequired:- severity- filteredcontentFilterResults:type: objectdescription: >-Information about the content filtering category (hate, sexual,violence, self_harm), if it has been detected, as well as the severitylevel (very_low, low, medium, high-scale that determines the intensityand risk level of harmful content) and if it has been filtered or not.properties:sexual:$ref: '#/components/schemas/contentFilterResult'violence:$ref: '#/components/schemas/contentFilterResult'hate:$ref: '#/components/schemas/contentFilterResult'self_harm:$ref: '#/components/schemas/contentFilterResult'error:$ref: '#/components/schemas/errorBase'promptFilterResult:type: objectdescription: Content filtering results for a single prompt in the request.properties:prompt_index:type: integercontent_filter_results:$ref: '#/components/schemas/contentFilterResults'promptFilterResults:type: arraydescription: >-Content filtering results for zero or more prompts in the request. In astreaming request, results for different prompts may arrive at differenttimes or in different orders.items:$ref: '#/components/schemas/promptFilterResult'  createChatCompletionRequest:type: objectallOf:- $ref: '#/components/schemas/chatCompletionsRequestCommon'- properties:messages:description: >-A list of messages comprising the conversation so far. [ExamplePythoncode](https://github.com/openai/openai-cookbook/blob/main/examples/How_to_format_inputs_to_ChatGPT_models.ipynb).type: arrayminItems: 1items:$ref: '#/components/schemas/chatCompletionRequestMessage'functions:description: A list of functions the model may generate JSON inputs for.type: arrayminItems: 1items:$ref: '#/components/schemas/chatCompletionFunctions'function_call:description: >-Controls how the model responds to function calls. "none" meansthe model does not call a function, and responds to theend-user. "auto" means the model can pick between an end-user orcalling a function.  Specifying a particular function via`{"name":\ "my_function"}` forces the model to call thatfunction. "none" is the default when no functions are present."auto" is the default if functions are present.oneOf:- type: stringenum:- none- auto- type: objectproperties:name:type: stringdescription: The name of the function to call.required:- name'n':type: integerminimum: 1maximum: 128default: 1example: 1nullable: truedescription: >-How many chat completion choices to generate for each inputmessage.required:- messages    chatCompletionsRequestCommon:type: objectproperties:temperature:description: >-What sampling temperature to use, between 0 and 2. Higher valueslike 0.8 will make the output more random, while lower values like0.2 will make it more focused and deterministic.We generally recommend altering this or `top_p` but not both.type: numberminimum: 0maximum: 2default: 1example: 1nullable: truetop_p:description: >-An alternative to sampling with temperature, called nucleussampling, where the model considers the results of the tokens withtop_p probability mass. So 0.1 means only the tokens comprising thetop 10% probability mass are considered.We generally recommend altering this or `temperature` but not both.type: numberminimum: 0maximum: 1default: 1example: 1nullable: truestop:description: Up to 4 sequences where the API will stop generating further tokens.oneOf:- type: stringnullable: true- type: arrayitems:type: stringnullable: falseminItems: 1maxItems: 4description: Array minimum size of 1 and maximum of 4default: nullmax_tokens:description: >-The maximum number of tokens allowed for the generated answer. Bydefault, the number of tokens the model can return will be (4096 -prompt tokens).type: integerdefault: 4096presence_penalty:description: >-Number between -2.0 and 2.0. Positive values penalize new tokensbased on whether they appear in the text so far, increasing themodel's likelihood to talk about new topics.type: numberdefault: 0minimum: -2maximum: 2frequency_penalty:description: >-Number between -2.0 and 2.0. Positive values penalize new tokensbased on their existing frequency in the text so far, decreasing themodel's likelihood to repeat the same line verbatim.type: numberdefault: 0minimum: -2maximum: 2logit_bias:description: >-Modify the likelihood of specified tokens appearing in thecompletion. Accepts a json object that maps tokens (specified bytheir token ID in the tokenizer) to an associated bias value from-100 to 100. Mathematically, the bias is added to the logitsgenerated by the model prior to sampling. The exact effect will varyper model, but values between -1 and 1 should decrease or increaselikelihood of selection; values like -100 or 100 should result in aban or exclusive selection of the relevant token.type: objectnullable: trueuser:description: >-A unique identifier representing your end-user, which can help AzureOpenAI to monitor and detect abuse.type: stringexample: user-1234nullable: falsechatCompletionRequestMessage:type: objectproperties:role:type: stringenum:- system- user- assistant- functiondescription: >-The role of the messages author. One of `system`, `user`,`assistant`, or `function`.content:type: stringdescription: >-The contents of the message. `content` is required for all messagesexcept assistant messages with function calls.name:type: stringdescription: >-The name of the author of this message. `name` is required if roleis `function`, and it should be the name of the function whoseresponse is in the `content`. May contain a-z, A-Z, 0-9, andunderscores, with a maximum length of 64 characters.function_call:type: objectdescription: >-The name and arguments of a function that should be called, asgenerated by the model.properties:name:type: stringdescription: The name of the function to call.arguments:type: stringdescription: >-The arguments to call the function with, as generated by themodel in JSON format. Note that the model does not alwaysgenerate valid JSON, and may hallucinate parameters not definedby your function schema. Validate the arguments in your codebefore calling your function.required:- rolecreateChatCompletionResponse:type: objectallOf:- $ref: '#/components/schemas/chatCompletionsResponseCommon'- properties:prompt_filter_results:$ref: '#/components/schemas/promptFilterResults'choices:type: arrayitems:type: objectallOf:- $ref: '#/components/schemas/chatCompletionChoiceCommon'- properties:message:$ref: '#/components/schemas/chatCompletionResponseMessage'content_filter_results:$ref: '#/components/schemas/contentFilterResults'required:- id- object- created- model- choices                chatCompletionFunctions:type: objectproperties:name:type: stringdescription: >-The name of the function to be called. Must be a-z, A-Z, 0-9, orcontain underscores and dashes, with a maximum length of 64.description:type: stringdescription: The description of what the function does.parameters:$ref: '#/components/schemas/chatCompletionFunctionParameters'required:- namechatCompletionFunctionParameters:type: objectdescription: >-The parameters the functions accepts, described as a JSON Schema object.See the [guide](/docs/guides/gpt/function-calling) for examples, and the[JSON Schemareference](https://json-schema.org/understanding-json-schema/) fordocumentation about the format.additionalProperties: truechatCompletionsResponseCommon:type: objectproperties:id:type: stringobject:type: stringcreated:type: integerformat: unixtimemodel:type: stringusage:type: objectproperties:prompt_tokens:type: integercompletion_tokens:type: integertotal_tokens:type: integerrequired:- prompt_tokens- completion_tokens- total_tokensrequired:- id- object- created- modelchatCompletionChoiceCommon:type: objectproperties:index:type: integerfinish_reason:type: stringchatCompletionResponseMessage:type: objectproperties:role:type: stringenum:- system- user- assistant- functiondescription: The role of the author of this message.content:type: stringdescription: The contents of the message.function_call:type: objectdescription: >-The name and arguments of a function that should be called, asgenerated by the model.properties:name:type: stringdescription: The name of the function to call.arguments:type: stringdescription: >-The arguments to call the function with, as generated by themodel in JSON format. Note that the model does not alwaysgenerate valid JSON, and may hallucinate parameters not definedby your function schema. Validate the arguments in your codebefore calling your function.required:- role          securitySchemes:apiKeyHeader:type: apiKeyname: Ocp-Apim-Subscription-Keyin: headerapiKeyQuery:type: apiKeyname: subscription-keyin: query
security:- apiKeyHeader: [ ]- apiKeyQuery: [ ]

I used this in azure apim and validating the content like this

我在 Azure APIM 中使用了这个，并像这样验证内容。

<validate-content unspecified-content-type-action="ignore" max-size="102400" size-exceeded-action="detect" errors-variable-name="requestBodyValidation"><content type="application/json" validate-as="json" action="prevent" allow-additional-properties="false" /></validate-content>

Now I tried to give the request like the actual property

现在我尝试像实际属性一样提供请求。

{"messages": [{"role": "user", "content": "Find beachfront hotels in San Diego for less than $300 a month with free breakfast."}],"temperature": 1,"top_p": 1,"stop": "","max_tokens": 2000,"presence_penalty": 0,"frequency_penalty": 0,"logit_bias": {},"user": "user-1234","n": 1,"function_call" : "auto","functions" : [{"name": "search_hotels","description": "Retrieves hotels from the search index based on the parameters provided","parameters": {"type": "object","properties": {"location": {"type": "string","description": "The location of the hotel (i.e. Seattle, WA)"},"max_price": {"type": "number","description": "The maximum price for the hotel"},"features": {"type": "string","description": "A comma separated list of features (i.e. beachfront, free wifi, etc.)"}},"required": ["location"]}}]
}

And the APIM is giving the error like

而 APIM 给出了如下错误：

{"statusCode": 400,"message": "Body of the request does not conform to the definition which is associated with the content type application/json. JSON does not match all schemas from 'allOf'. Invalid schema indexes: 0, 1. Line: 42, Position: 1"
}

But the same request is working when I directly hit the azure openai.

但当我直接请求 Azure OpenAI 时，同样的请求是有效的。

What could be the possible issue here ?

这里可能是什么问题？

问题解决：

I believe your problem is this line allow-additional-properties="false"

我认为你遇到的问题是这一行 allow-additional-properties="false"。

allow-additional-properties Boolean. For a JSON schema, specifies whether to implement a runtime override of the additionalProperties value configured in the schema:

• true: allow additional properties in the request or response body, even if the JSON schema's additionalProperties field is configured to not allow additional properties.

true：允许在请求或响应主体中添加额外的属性，即使 JSON 模式的 additionalProperties 字段配置为不允许额外属性。

• false: do not allow additional properties in the request or response body, even if the JSON schema's additionalProperties field is configured to allow additional properties

false：不允许在请求或响应主体中添加额外的属性，即使 JSON 模式的 additionalProperties 字段配置为允许额外属性。

If the attribute isn't specified, the policy validates additional properties according to configuration of the additionalProperties field in the schema.

如果未指定该属性，则策略将根据模式中 additionalProperties 字段的配置来验证额外属性。

source:    来源        https://learn.microsoft.com/en-us/azure/api-management/validate-content-policy#content-attributes

This property overrides your JSON Schema. Even though your allOf definition does not use additionalProperties: false, apim will inject this constraint to the root schema, which translates to

此属性会覆盖你的 JSON Schema。即使你的 allOf 定义没有使用 additionalProperties: false，APIM 仍会将此约束注入到根模式中，这会转化为

{"type": "object","additionalProperties": false,"allOf": [{...}, {...}]
}

This schema doesn't allow any properties to be validated because no properties are defined at the root.

该模式不允许验证任何属性，因为根本没有定义属性。

The only valid schemas in this situation would be

在这种情况下，唯一有效的模式是

{}ORtrue

There are a few ways to tackle this but IMHO, the best option is to use the schema definition, rather than the apim attribute because you're introducing constraints on the schema where they are not defined. If someone else were to review the schema, they would run into the same issue you are having.

解决这个问题有几种方法，但依我看来，最好的选择是使用模式定义，而不是使用 APIM 属性，因为你在模式中引入了未定义的约束。如果其他人来审查这个模式，他们也会遇到你现在面临的相同问题。

This is where it may get tricky for you depending on which version of JSON Schema is supported in APIM and which version you are using.

这可能会变得棘手，具体取决于 APIM 支持的 JSON Schema 版本以及你正在使用的版本。

Draft-04 - 07 requires some massaging to the schema, in most circumstances, to achieve the desired behavior of using allOf with additionalProperties": false

在大多数情况下，Draft-04 到 Draft-07 需要对模式进行一些调整，以实现使用 allOf 与 additionalProperties: false 的预期行为。

• turn off the content attribute in your apim validation

在你的 APIM 验证中关闭 content 属性。

• add all properties of the first depth of subschemas to the root with an empty schema. This will allow the validator to recognize those properties at the root level to satisfy additionalProperties

将所有子模式第一层的属性添加到根模式中，并使用一个空模式。这将允许验证器在根级别识别这些属性，以满足 additionalProperties 的要求。

{"$schema": "http://json-schema.org/draft-07/schema#","type": "object","additionalProperties": false,"properties": {"messages": {},"temperature": {},"top_p": {},"stop": {},"max_tokens": {},"presence_penalty": {},"frequency_penalty": {},"logit_bias": {},"user": { },"n": { },"function_call": { },"functions": { }},"allOf": [{"type": "object","properties": {"temperature": {},"top_p": {},"stop": {},"max_tokens": {},"presence_penalty": {},"frequency_penalty": {},"logit_bias": {},"user": {}}},{"type": "object","properties": {"messages": {},"n": {},"function_call": {},"functions": {}}}]
}

If you're using JSON Schema draft 2019-09 or later, you can use the newer keyword unevaluatedProperties which performs the behavior described above, automatically.

如果你使用的是 JSON Schema draft 2019-09 或更高版本，你可以使用较新的关键字 unevaluatedProperties，它会自动执行上述描述的行为。

{"$schema": "https://json-schema.org/draft/2019-09/schema","type": "object","unevaluatedProperties": false,"allOf": [{"type": "object","properties": {"temperature": {},"top_p": {},"stop": {},"max_tokens": {},"presence_penalty": {},"frequency_penalty": {},"logit_bias": {},"user": {}}},{"type": "object","properties": {"messages": {},"n": {},"function_call": {},"functions": {}}}]
}

This example fails:        这个示例失败了

{"messages": [{"role": "user", "content": "Find beachfront hotels in San Diego for less than $300 a month with free breakfast."}],"stackOverflow": -1
}

Invalid# fails schema constraint https://json-schema.hyperjump.io/schema#/unevaluatedProperties#/stackOverflow fails schema constraint https://json-schema.hyperjump.io/schema#/unevaluatedProperties