PaddlePaddle/PaddleOCR · error · InvalidRequestError

top_p must be greater than 0 and less than or equal to 1.

Error message

top_p must be greater than 0 and less than or equal to 1.

What it means

InvalidRequestError thrown by _validate_vl_options when PaddleOCRVLOptions.top_p is set outside the range (0, 1]. top_p is nucleus-sampling probability; zero or negative values, and values above 1, are meaningless and rejected client-side before the request is sent.

Source

Thrown at paddleocr/_api_client/models.py:186

DocParsingOptions = Union[PPStructureV3Options, PaddleOCRVLOptions]


def _build_payload(options) -> dict:
    payload = {}
    for field in fields(options):
        value = getattr(options, field.name)
        if value is None:
            continue
        if field.name == "extra_options":
            payload.update(value)
        else:
            payload[snake_to_camel(field.name)] = value
    return payload


def _validate_vl_options(options: PaddleOCRVLOptions) -> None:
    if options.top_p is not None and not (0 < options.top_p <= 1):
        raise InvalidRequestError(
            "top_p must be greater than 0 and less than or equal to 1."
        )
    if options.temperature is not None and options.temperature < 0:
        raise InvalidRequestError("temperature must be greater than or equal to 0.")
    if options.repetition_penalty is not None and options.repetition_penalty <= 0:
        raise InvalidRequestError("repetition_penalty must be greater than 0.")
    if options.min_pixels is not None and options.min_pixels <= 0:
        raise InvalidRequestError("min_pixels must be greater than 0.")
    if options.max_pixels is not None and options.max_pixels <= 0:
        raise InvalidRequestError("max_pixels must be greater than 0.")
    if (
        options.min_pixels is not None
        and options.max_pixels is not None
        and options.min_pixels > options.max_pixels
    ):
        raise InvalidRequestError("min_pixels cannot be greater than max_pixels.")

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Set top_p to a float in (0, 1], e.g. 0.9
2. Leave top_p=None to use the server default
3. If you meant a percentage, divide by 100 first

Example fix

# before
options = PaddleOCRVLOptions(top_p=90)
# after
options = PaddleOCRVLOptions(top_p=0.9)

def valid_top_p(v):
    return v is None or (isinstance(v, (int, float)) and 0 < v <= 1)

assert valid_top_p(options.top_p), f'bad top_p={options.top_p}'

from paddleocr._api_client.errors import InvalidRequestError

try:
    client.predict(..., vl_options=options)
except InvalidRequestError as e:
    if 'top_p' in str(e):
        options.top_p = min(max(options.top_p, 1e-6), 1.0)
    else:
        raise

When it happens

Trigger: Passing PaddleOCRVLOptions(top_p=0), top_p=1.2, or top_p=-0.1 to a VL (vision-language) API call; misreading top_p as a percentage (e.g. 50 for 50%).

Common situations: Porting hyperparameters from another SDK where top_p is a 0-100 percent; copy-pasting sampling configs tuned for temperature-style parameters.

Related errors

• temperature must be greater than or equal to 0.
• repetition_penalty must be greater than 0.
• Resource filename must not be empty.
• min_pixels must be greater than 0.
• max_pixels must be greater than 0.

AI-assisted analysis of PaddlePaddle/PaddleOCR@2661c7c0ef (2026-08-14). Data as JSON: /api/errors/d518494525ffc6db. Report an issue: GitHub.