Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Schrittweise Migration zur Responses API

Lektion 12 von 12 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Warum und wann zu migrieren
  2. Schritt 1: Erfassen der genutzten Funktionen
  3. Schritt 2: Migrieren von Basisaufrufen
  4. Schritt 3: Migrieren von mehrstufigen Gesprächen
  5. Schritt 4: Neue Funktionen nutzen
  6. Empfohlene Migrationsstrategie
  7. Wichtige Erkenntnisse
  8. Testen Sie Ihr Wissen

Aktualisiert am 3. November 2026: Die vorherige Zuordnung der Parameter deutete an, dass max_tokens seinen Namen in der Responses API behält; die Tabelle von xAI ändert dies jedoch zu max_output_tokens, und auch die Zähler für die Nutzung ändern ihre Bezeichnungen. Quelle: Vergleich mit Chat Completions.

Warum und wann zu migrieren

Der Endpunkt für Chat Completions ist als veraltet (legacy) gekennzeichnet. Er wird weiterhin funktionieren, aber es werden keine neuen Funktionen mehr hinzugefügt. Wenn Ihre Anwendung serverseitige Tools (Web-Suche, Code-Ausführung), die Speicherung von Gesprächen oder verschlüsseltes Reasoning benötigt, wird eine Migration zur Responses API notwendig.

Die gute Nachricht: Diese Migration kann schrittweise erfolgen. Sie müssen nicht alles auf einmal umschreiben.

Schritt 1: Erfassen der genutzten Funktionen

Bevor Sie migrieren, sollten Sie feststellen, welche Funktionen Ihre Anwendung mit Chat Completions nutzt:

# Audit Ihres bestehenden Codes
# Suchen Sie nach diesen Mustern:

# 1. Basisaufrufe (einfacher Text)
client.chat.completions.create(model=..., messages=...)

# 2. Streaming
client.chat.completions.create(..., stream=True)

# 3. Funktionsaufrufe
client.chat.completions.create(..., tools=[...])

# 4. Vision (Bilder)
# Nachrichten mit Inhalt als Array [text, image_url]

# 5. Generierungsparameter
# temperature, max_tokens, top_p, stop, seed

Basisaufrufe und Streaming sind am einfachsten zu migrieren. Funktionsaufrufe erfordern eine Anpassung des Formats. Vision funktioniert ähnlich.

Schritt 2: Migrieren von Basisaufrufen

Das Migrieren eines einfachen Aufrufs folgt diesem Muster:

# VORHER — Chat Completions
response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[
        {"role": "system", "content": "Sie sind ein hilfreicher Assistent."},
        {"role": "user", "content": "Hallo!"}
    ]
)
texte = response.choices[0].message.content

# NACHHER — Responses API
response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    instructions="Sie sind ein hilfreicher Assistent.",
    input="Hallo!"
)
texte = response.output_text

Feldzuordnung

Die wichtigsten Änderungen sind:

  • messages mit der Rolle system → instructions (eigener Parameter)
  • messages mit der Rolle user → input (einfacher String)
  • response.choices[0].message.content → response.output_text
  • max_tokens → max_output_tokens, gemäß der Zuordnungstabelle von xAI; temperature behält seinen Namen
  • response.usage.prompt_tokens und completion_tokens → input_tokens und output_tokens (Details: input_tokens_details.cached_tokens, output_tokens_details.reasoning_tokens)

Schritt 3: Migrieren von mehrstufigen Gesprächen

Hier vereinfacht die Responses API die Dinge. Anstatt die Historie bei jedem Aufruf neu zu rekonstruieren, verknüpfen Sie diese über die ID:

# VORHER — Chat Completions (Historie selbst verwalten)
historique = [
    {"role": "system", "content": "Sie sind ein hilfreicher Assistent."}
]

def envoyer_message(texte: str) -> str:
    historique.append({"role": "user", "content": texte})
    response = client.chat.completions.create(
        model="grok-4.20-0309-reasoning",
        messages=historique
    )
    reponse = response.choices[0].message.content
    historique.append({"role": "assistant", "content": reponse})
    return reponse

# NACHHER — Responses API (Server verwaltet die Historie)
dernier_id = None

def envoyer_message(texte: str) -> str:
    response = client.responses.create(
        model="grok-4.20-0309-reasoning",
        instructions="Sie sind ein hilfreicher Assistent.",
        input=texte,
        previous_response_id=dernier_id
    )
    dernier_id = response.id
    return response.output_text

Der Code ist einfacher, und Sie müssen das Nachrichten-Array nicht mehr manuell verwalten.

Schritt 4: Neue Funktionen nutzen

Sobald migriert, können Sie Funktionen nutzen, die exklusiv für die Responses API verfügbar sind:

Eingebaute Web-Suche

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Was sind die neuesten Entwicklungen im Bereich generative KI?",
    tools=[{"type": "web_search"}]
)
# Die Antwort enthält Zitate mit Quell-URLs

Antwort-Speicherung

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Analysieren Sie dieses Dokument...",
    store=True  # Speichert für 30 Tage
)

# Später abrufen
stored = client.responses.retrieve(response.id)

Verschlüsseltes Reasoning

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Lösen Sie dieses komplexe Problem...",
    include=["reasoning.encrypted_content"]
)
# Das verschlüsselte Reasoning kann in nachfolgenden Anfragen wiederverwendet werden

Empfohlene Migrationsstrategie

Statt alles auf einmal zu migrieren, gehen Sie schrittweise vor:

  1. Erfassen Sie Chat Completions-Aufrufe in Ihrem Code
  2. Klassifizieren Sie sie nach Komplexität (Basis → Streaming → Funktionsaufrufe)
  3. Migrieren Sie zuerst neue Endpunkte oder Funktionen (Greenfield)
  4. Dann migrieren Sie die einfachsten bestehenden Aufrufe
  5. Behalten Sie Chat Completions für Drittanbieter-Integrationen, die diese benötigen (z. B. LangChain)

Temporäre Koexistenz

Es ist völlig in Ordnung, beide Endpunkte während des Übergangs parallel zu betreiben:

# Wrapper, der den genutzten Endpunkt abstrahiert
class GrokClient:
    def __init__(self, use_responses: bool = False):
        self.use_responses = use_responses
        self.client = OpenAI(
            api_key=os.getenv("XAI_API_KEY"),
            base_url="https://api.x.ai/v1"
        )

    def generate(self, system: str, user_message: str) -> str:
        if self.use_responses:
            response = self.client.responses.create(
                model="grok-4.20-0309-reasoning",
                instructions=system,
                input=user_message
            )
            return response.output_text
        else:
            response = self.client.chat.completions.create(
                model="grok-4.20-0309-reasoning",
                messages=[
                    {"role": "system", "content": system},
                    {"role": "user", "content": user_message}
                ]
            )
            return response.choices[0].message.content

Dieser Ansatz ermöglicht es Ihnen, schrittweise umzustellen, indem Sie jede Migration einzeln testen.

Wichtige Erkenntnisse

  • Die Migration kann schrittweise erfolgen: Es ist nicht nötig, alles auf einmal umzuschreiben.
  • Hauptänderungen: messages → input/instructions, choices[0].message.content → output_text.
  • Mehrstufige Gespräche wechseln von einem Nachrichten-Array zu einer einfachen previous_response_id.
  • Die Responses API bietet Zugang zu exklusiven Funktionen (Web-Suche, Speicherung, verschlüsseltes Reasoning).
  • Betreiben Sie beide Endpunkte während des Übergangs parallel und migrieren Sie nach Komplexitätsstufen.

Testen Sie Ihr Wissen

Die veraltete API verstanden und die Migration vorbereitet.

1. Was bedeutet der veraltete und zustandslose Status von Chat Completions?

Antwort: Der Endpunkt bleibt unterstützt, entwickelt sich aber nicht weiter: Zustandslos erfordert er das erneute Senden der gesamten Historie bei jedem Aufruf – die Responses API ist der moderne Weg.

2. Welche Rollen strukturieren die Nachrichten?

Antwort: system (und developer), user, assistant – das Gerüst, die Anfragen, die Antworten: Die vollständige Historie startet bei jedem neuen Aufruf neu.

3. Wie nutzen Sie bestehenden OpenAI-Code mit Grok?

Antwort: Indem Sie die base_url auf https://api.x.ai/v1 und den API-Schlüssel ändern – die Formatkompatibilität übernimmt den Rest, einschließlich OpenAI SDK und Vercel AI SDK.

4. Was lesen Sie in der Antwort und im Nutzungszähler?

Antwort: choices enthält Antworten mit finish_reason; usage liefert Details zu Tokens, einschließlich reasoning_tokens für Reasoning-Modelle – die Grundlage für die Kostenverfolgung.

5. Wie migrieren Sie sauber zur Responses API?

Antwort: Schrittweise: Neue Entwicklungen in der Responses API, bestehende Endpunkte einzeln umgewandelt mit erneuter Prüfung der Prompts – der Vergleich der beiden Formate leitet die Umwandlung.

Verstehen Sie das Veraltete, bauen Sie für das Moderne: Der schrittweise Migrationsplan des Kurses ist Ihre Landkarte – ohne großen Knall.