Timeout, verbotene Parameter und Konfiguration

Aktualisiert am 3. November 2026. Basierend auf den xAI-Best Practices und dem Reasoning-Guide: Die empfohlene Wartezeit beträgt mindestens 900 Sekunden (in den Beispielen des Reasoning-Guides 3.600 Sekunden), nicht „mindestens 3.600 Sekunden”; die Liste der Reasoning-Modelle umfasst grok-4.6 und grok-4.7; grok-4.7 streamt eine Zusammenfassung seiner Reasoning-Prozesse; Begründungen für verbotene Parameter, die in der Dokumentation fehlen, wurden entfernt. Quellen: Best Practices · Reasoning.

Ihre Reasoning-Anfragen korrekt konfigurieren

Reasoning-Modelle unterliegen spezifischen Einschränkungen, die bei klassischen Modellen nicht gelten. Das Ignorieren dieser Einschränkungen kann zu stillen Fehlern, unerwarteten Timeouts oder abgeschnittenen Antworten führen. In dieser Lektion werden die wesentlichen Konfigurationsparameter behandelt.

Timeout: Mindestens 900 Sekunden

Die xAI-Best Practices verlangen mindestens 900 Sekunden pro Anfrage und 1.800 Sekunden oder mehr für langwierige Evaluierungen; die Beispiele im Reasoning-Guide setzen die Verzögerung sogar auf 3.600 Sekunden (1 Stunde). Diese Werte mögen zunächst hoch erscheinen, spiegeln aber die Realität wider: tiefes Reasoning zu einem komplexen Problem kann mehrere Minuten in Anspruch nehmen. xAI empfiehlt zudem den Vorzug von Streaming, wodurch die Verbindung während langer Generationsprozesse aktiv bleibt.

Warum ein so langer Timeout?

Wenn ein Reasoning-Modell ein schwieriges Problem bearbeitet (mathematischer Beweis, komplexe Code-Analyse, mehrstufiges Reasoning), generiert es potenziell Tausende interner Reasoning-Tokens, bevor es seine Antwort formuliert. Dieser Prozess ist linear und kann nicht parallelisiert werden.

Timeout-Konfiguration

import httpx
from openai import OpenAI

# Konfiguration mit hohem Timeout
client = OpenAI(
    api_key="your-api-key",
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(3600.0, connect=10.0)
)

In JavaScript mit dem OpenAI SDK:

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'your-api-key',
  baseURL: 'https://api.x.ai/v1',
  timeout: 3600 * 1000  // 3600 Sekunden in Millisekunden
});

Webserver-Timeout

Wenn sich Ihre Anwendung hinter einem Reverse-Proxy (nginx, Apache) befindet, konfigurieren Sie auch den serverseitigen Timeout:

# nginx
location /api/ {
    proxy_read_timeout 3600s;
    proxy_connect_timeout 10s;
    proxy_send_timeout 3600s;
}

Verbotene Parameter bei Reasoning-Modellen

Drei Parameter, die bei klassischen Modellen üblich sind, dürfen nicht an xAI Reasoning-Modelle gesendet werden: Laut dem Reasoning-Guide führt eine Anfrage, die diese enthält, zu einem Fehler. Die Dokumentation gibt keine Begründung für diese Verbote an; merken Sie sich die Regel.

presencePenalty

// FALSCHE ANFRAGE bei Reasoning-Modellen
{
  "model": "grok-4.20-0309-reasoning",
  "presence_penalty": 0.5,  // Verboten!
  "messages": [...]
}

presencePenalty bestraft Tokens, die bereits in der Antwort erschienen sind, um Vielfalt zu fördern.

frequencyPenalty

// FALSCHE ANFRAGE bei Reasoning-Modellen
{
  "model": "grok-4.20-0309-reasoning",
  "frequency_penalty": 0.3,  // Verboten!
  "messages": [...]
}

frequencyPenalty bestraft Tokens proportional zu ihrer Häufigkeit des Auftretens.

stop

// FALSCHE ANFRAGE bei Reasoning-Modellen
{
  "model": "grok-4.20-0309-reasoning",
  "stop": ["\n\n"],  // Verboten!
  "messages": [...]
}

Der Parameter stop beendet die Generierung, sobald eine bestimmte Sequenz erscheint. Um die Länge der Antwort zu begrenzen, verwenden Sie stattdessen max_completion_tokens, das nur die sichtbare Antwort begrenzt, sowie eine Formatierungsanweisung im Prompt.

Behandlung von Parametern-bezogenen Fehlern

Beim Umzug von bestehendem Code zu einem Reasoning-Modell sollten Sie nicht unterstützte Parameter bereinigen:

def prepare_params(model, base_params):
    """Bereinigt Parameter für Reasoning-Modelle."""
    reasoning_models = [
        # aktueller Bereich
        "grok-4.7", "grok-4.6", "grok-4.5", "grok-4.20-0309-reasoning",
        # historische Identifikatoren, die noch in bestehendem Code vorhanden sind
        "grok-3-mini", "grok-4-fast-reasoning",
    ]

    params = {**base_params, "model": model}

    if model in reasoning_models:
        # Entfernt verbotene Parameter
        for forbidden in ["presence_penalty", "frequency_penalty", "stop"]:
            params.pop(forbidden, None)

        # Ersetzt max_tokens durch max_completion_tokens
        if "max_tokens" in params:
            params["max_completion_tokens"] = params.pop("max_tokens")

    return params

Streaming mit Reasoning-Modellen

Streaming funktioniert mit Reasoning-Modellen, aber das Verhalten hängt von der Generierung ab: Bei grok-3-mini (vorherige Generation) erschien reasoning_content im Stream klar vor den Antwort-Tokens. Bei grok-4.20-0309-reasoning bleibt Reasoning intern und wird nicht gestreamt: Nur die finale Antwort kommt im Stream an. Bemerkenswerte Ausnahme: Bei der Responses API streamt grok-4.7 eine Zusammenfassung seines Reasoning-Prozesses in response.reasoning_summary_text.delta-Ereignissen, die Sie vor der Antwort anzeigen können.

Historisches Beispiel mit grok-3-mini:

stream = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[{"role": "user", "content": "Warum ist der Himmel blau?"}],
    reasoning_effort="high",
    stream=True
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if hasattr(delta, 'reasoning_content') and delta.reasoning_content:
        print(f"[Reasoning] {delta.reasoning_content}", end="")
    elif delta.content:
        print(f"[Response] {delta.content}", end="")

Wichtige Erkenntnisse

• Erlauben Sie mindestens 900 Sekunden pro Anfrage (3.600 in den Beispielen des Reasoning-Guides) und bevorzugen Sie Streaming.
• Drei Parameter sind verboten: presencePenalty, frequencyPenalty und stop.
• Bereinigen Sie Parameter beim Umzug von klassischen Modellen.
• Verwenden Sie max_completion_tokens statt max_tokens.
• Streaming funktioniert, aber das Verhalten unterscheidet sich je nach Modell.