What causes "LLM_TEMPERATURE 必须位于 0 到 2 之间" in datawhalechina/hello-agents?

Set LLM_TEMPERATURE to a value between 0 and 2 inclusive (e.g. 0.2).

datawhalechina/hello-agents · error · ConfigurationError

LLM_TEMPERATURE 必须位于 0 到 2 之间

Error message

LLM_TEMPERATURE 必须位于 0 到 2 之间

What it means

Raised by LLMSettings validation when LLM_TEMPERATURE (or the temperature field) is outside [0, 2]. The bounds match the OpenAI-style temperature range; values like -0.1 or 2.5 are rejected before the LLM client is created, avoiding a provider-side 400 later.

Source

Thrown at Co-creation-projects/zenith191-RequirementClarifierAgent/src/config.py:78

        missing = [
            name
            for name, value in (
                ("LLM_MODEL_ID", self.model),
                ("LLM_API_KEY", self.api_key),
                ("LLM_BASE_URL", self.base_url),
            )
            if not value
        ]
        if missing:
            raise ConfigurationError(
                "缺少 LLM 配置：" + ", ".join(missing) + "。请先复制并填写 .env。"
            )

        lowered_key = self.api_key.casefold()
        if lowered_key.startswith("your_") or lowered_key in {"changeme", "replace_me"}:
            raise ConfigurationError("LLM_API_KEY 仍是占位符，请在 .env 中填写真实密钥")
        if not 0 <= self.temperature <= 2:
            raise ConfigurationError("LLM_TEMPERATURE 必须位于 0 到 2 之间")
        if self.timeout <= 0:
            raise ConfigurationError("LLM_TIMEOUT 必须大于 0")

View on GitHub (pinned to 606a07d341)

Solutions

Set LLM_TEMPERATURE to a value between 0 and 2 inclusive (e.g. 0.2).
Unset the variable to fall back to the default of 0.2 if you don't need to tune it.
If you truly need provider-specific ranges, clamp in your own wrapper before building settings.

Example fix

# .env before
LLM_TEMPERATURE=2.5

# .env after
LLM_TEMPERATURE=1.5

Defensive patterns

Strategy: validation

Validate before calling

import os

raw = os.getenv("LLM_TEMPERATURE", "0.2")
temp = float(raw)
assert 0 <= temp <= 2, f"LLM_TEMPERATURE={temp} outside [0, 2]"

Try / catch

try:
    settings = LLMSettings.from_env()
except ConfigurationError as e:
    if "TEMPERATURE" in str(e):
        os.environ["LLM_TEMPERATURE"] = "0.2"  # reset to default and retry
        settings = LLMSettings.from_env()
    else:
        raise

Prevention

Document valid ranges inline in .env.example comments.
Clamp user-provided sampling params at the API boundary before they reach config.
Prefer unset-and-default over hand-typed values until tuning is deliberate.

When it happens

Trigger: Setting LLM_TEMPERATURE=-1 for 'more deterministic' output, or 3.0 expecting 'more creative', or a typo like 22 instead of 2.2. Also a non-default temperature passed programmatically to LLMSettings(...).

Common situations: Migrating configs between providers whose temperature ranges differ (some allow 0–1 only, others 0–2); hand-editing .env and dropping the decimal point; experimenting with sampling values from another model's docs.

Related errors

AI-assisted analysis of datawhalechina/hello-agents@606a07d341 (2026-08-14). Data as JSON: /api/errors/03624e20f653c147. Report an issue: GitHub.