{"record":{"id":"c84b8a9cc658a121","repo":"microsoft/semantic-kernel","slug":"when-used-with-number-of-responses-best-of-contro","errorCode":null,"errorMessage":"When used with number_of_responses, best_of controls the number of candidate completions and n specifies how many to return, therefore best_of must be greater than number_of_responses.","messagePattern":"When used with number_of_responses, best_of controls the number of candidate completions and n specifies how many to return, therefore best_of must be greater than number_of_responses\\.","errorType":"exception","errorClass":"ServiceInvalidExecutionSettingsError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/ai/open_ai/prompt_execution_settings/open_ai_prompt_execution_settings.py","lineNumber":51,"sourceCode":"class OpenAITextPromptExecutionSettings(OpenAIPromptExecutionSettings):\n    \"\"\"Specific settings for the completions endpoint.\"\"\"\n\n    prompt: Annotated[\n        str | None, Field(description=\"Do not set this manually. It is set by the service based on the text content.\")\n    ] = None\n    best_of: Annotated[int | None, Field(ge=1)] = None\n    echo: bool = False\n    logprobs: Annotated[int | None, Field(ge=0, le=5)] = None\n    suffix: str | None = None\n\n    @model_validator(mode=\"after\")\n    def check_best_of_and_n(self) -> \"OpenAITextPromptExecutionSettings\":\n        \"\"\"Check that the best_of parameter is not greater than the number_of_responses parameter.\"\"\"\n        best_of = self.best_of or self.extension_data.get(\"best_of\")\n        number_of_responses = self.number_of_responses or self.extension_data.get(\"number_of_responses\")\n\n        if best_of is not None and number_of_responses is not None and best_of < number_of_responses:\n            raise ServiceInvalidExecutionSettingsError(\n                \"When used with number_of_responses, best_of controls the number of candidate completions and n specifies how many to return, therefore best_of must be greater than number_of_responses.\"  # noqa: E501\n            )\n\n        return self\n\n\nclass OpenAIChatPromptExecutionSettings(OpenAIPromptExecutionSettings):\n    \"\"\"Specific settings for the Chat Completion endpoint.\"\"\"\n\n    response_format: (\n        dict[Literal[\"type\"], Literal[\"text\", \"json_object\"]] | dict[str, Any] | type[BaseModel] | type | None\n    ) = None\n    function_call: str | None = None\n    functions: list[dict[str, Any]] | None = None\n    messages: Annotated[\n        list[dict[str, Any]] | None, Field(description=\"Do not set this manually. It is set by the service.\")\n    ] = None\n    parallel_tool_calls: bool | None = None","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/ai/open_ai/prompt_execution_settings/open_ai_prompt_execution_settings.py#L33-L69","documentation":"OpenAI's text completion API requires that the best_of parameter (number of candidate completions generated server-side) be >= n / number_of_responses (how many are returned). The pydantic model_validator in OpenAITextPromptExecutionSettings checks this after instantiation and raises ServiceInvalidExecutionSettingsError if best_of < number_of_responses. Both fields can come from the model attributes or from extension_data.","triggerScenarios":"Setting OpenAITextPromptExecutionSettings(best_of=2, number_of_responses=5) — or passing them via extension_data with best_of < number_of_responses. The validator runs on any pydantic model validation (instantiation, copy, re-validation).","commonSituations":"Copy-pasting settings from a chat completion config (where n/best_of semantics differ); setting number_of_responses high for variety but forgetting to raise best_of proportionally; reading values from a config file where best_of and n are independently set.","solutions":["Set best_of >= number_of_responses (e.g. best_of=5, number_of_responses=3).","Remove best_of entirely if you don't need server-side candidate filtering — OpenAI defaults best_of to n.","Audit your settings dict before instantiation to ensure the constraint holds."],"exampleFix":"// before\nsettings = OpenAITextPromptExecutionSettings(best_of=2, number_of_responses=5)\n// after\nsettings = OpenAITextPromptExecutionSettings(best_of=5, number_of_responses=5)","handlingStrategy":"validation","validationCode":"def validate_best_of_and_n(best_of: int | None, number_of_responses: int | None) -> None:\n    if best_of is not None and number_of_responses is not None:\n        if best_of < number_of_responses:\n            raise ValueError(\n                f'best_of ({best_of}) must be >= number_of_responses ({number_of_responses})'\n            )","typeGuard":"def are_text_completion_settings_valid(best_of, number_of_responses) -> bool:\n    if best_of is None or number_of_responses is None:\n        return True\n    return best_of >= number_of_responses","tryCatchPattern":"from semantic_kernel.exceptions import ServiceInvalidExecutionSettingsError\n\ntry:\n    settings = OpenAITextPromptExecutionSettings(best_of=b, number_of_responses=n)\nexcept ServiceInvalidExecutionSettingsError as e:\n    b = max(b, n)  # fix by raising best_of\n    settings = OpenAITextPromptExecutionSettings(best_of=b, number_of_responses=n)","preventionTips":["Always set best_of >= number_of_responses — or omit best_of to let it default to n.","Centralize completion settings in a config builder that enforces the constraint.","Add a unit test that verifies the constraint for all your config presets."],"tags":["openai","execution-settings","best-of","pydantic","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}