OCI Responses API Compaction Tutorial

Verwenden Sie das Python-SDK OpenAI mit der OCI-Responses-API, um die Unterhaltungshistorie explizit oder automatisch zu komprimieren. Fahren Sie dann mit der Unterhaltung mit dem zurückgegebenen Kontext fort.

Überblick

Wenn eine Unterhaltung wächst, sendet eine Anwendung mit jeder Anforderung mehr Historie. Die Komprimierung reduziert diese Historie auf eine kleinere Darstellung, die das Modell in späteren Umdrehungen verwenden kann. Damit können Sie den Kontext in Unterhaltungen und Agent-Workflows mit langer Ausführungszeit verwalten.

In diesem Tutorial beschreiben Sie eine fiktive Deployment-Konfiguration, komprimieren die Unterhaltung und stellen eine Nachfassfrage, um zu prüfen, welche Details das Modell beibehalten hat.

Sie verwenden das Python-SDK OpenAI mit einem OCI Generative AI-API-Schlüssel und einem regionalen OCI-Endpunkt. Das SDK stellt die Clientschnittstelle bereit. Anforderungen authentifizieren sich bei OCI und werden an OCI Generative AI gesendet.

Alle von der OCI Responses-API unterstützten Modelle, einschließlich importierter Modelle, unterstützen sowohl die explizite als auch die automatische Komprimierung. Die Komprimierung ist in Enterprise AI-Regionen verfügbar und folgt der Region jedes Modells und der Hostingverfügbarkeit. Beide Modi werden für On-Demand-Inferenz und dediziertes Hosting unterstützt.

Komprimierungsmodi
ModusArbeitsvorgangAls Nächstes senden
Explizit (Standalone) Rufen Sie client.responses.compact(...) auf, das POST /responses/compact sendet, wenn eine Anwendung zur Komprimierung der Historie bereit ist. Übergeben Sie das vollständig zurückgegebene output-Array, gefolgt von der nächsten Benutzernachricht.
Automatisch (serververwaltet) Rufen Sie client.responses.create(...) mit context_management und einem Tokenschwellenwert auf. OCI komprimiert Kontext während POST /responses, wenn der Schwellenwert erreicht ist. Übergeben Sie mit store=False das letzte Verdichtungselement und alle nächsten Ausgabeelemente, gefolgt von der nächsten Benutzernachricht. Wenn kein Komprimierungselement zurückgegeben wird, behalten Sie die vorhandene Historie bei, und hängen Sie die neue Ausgabe an.

Komprimierungselemente enthalten undurchsichtigen, verschlüsselten Kontext. Behalten Sie die serialisierten Felder und die Reihenfolge bei. Lesen, bearbeiten oder ersetzen Sie ihren Inhalt nicht durch eine Textübersicht.

Hinweis

Die Komprimierung verwendet Modelltoken und kann während der Zusammenfassung Details verlieren. Kompakt, bevor Sie die Kontextgrenze des Modells erreichen, und lassen Sie Platz für die Reaktion und spätere Umdrehungen. Explizite Komprimierung ist synchron und unterstützt weder Speicher, Hintergrundausführung noch Streaming.

In den Beispielen wird die Historie in der Anwendung verwaltet, und store=False wird für Anforderungen zur Antworterstellung festgelegt. Informationen zum separaten Workflow, der den OCI-verwalteten Unterhaltungsstatus verwendet, finden Sie unter Agent-Speicher mit Antwort-API verwenden.

Bevor Sie beginnen

Um dieses Tutorial abzuschließen, benötigen Sie:

In den Beispielen wird das Python-SDK OpenAI mit OCI-Zugangsdaten und einer OCI-Basis-URL verwendet. Sie benötigen keinen OpenAI-API-Schlüssel, das OCI-Python-SDK oder die OCI-CLI.

In diesen Beispielen wird die OCI Generative AI-API-Schlüsselauthentifizierung verwendet. Die Komprimierung unterstützt auch die OCI IAM-Authentifizierung. Informationen zu diesem Setup finden Sie unter IAM-basierte generative KI-Authentifizierung. Eine OCI Generative AI-Projekt-OCID ist mit beiden Authentifizierungsmethoden erforderlich.

1. Python-Umgebung und OCI-Zugriff vorbereiten

  1. Erstellen und aktivieren Sie in einem Arbeitsverzeichnis eine virtuelle Umgebung, und installieren Sie dann das Python-SDK OpenAI:
    python3 -m venv .venv
    source .venv/bin/activate
    python -m pip install --upgrade 'openai>=2.45.0'

    Wenn .venv bereits vorhanden ist, aktivieren Sie es, und führen Sie den Installationsbefehl aus.

  2. Legen Sie eine OCI-Basis-URL, Modell-ID und Projekt-OCID fest:
    export OCI_BASE_URL='https://inference.generativeai.<REGION>.oci.oraclecloud.com/openai/v1'
    export OCI_MODEL='<MODEL_ID>'
    export OCI_OPENAI_PROJECT='<PROJECT_OCID>'

    Ersetzen Sie die Platzhalter mit ihren Werten:

    • <REGION>: Eine unterstützte OCI-Regions-ID, wie us-chicago-1. Die Basis-URL muss auf /openai/v1 enden. Hängen Sie /responses nicht an.
    • <MODEL_ID>: Die ID eines On-Demand-Modells, das die OCI Responses-API unterstützt und für Ihren Mandanten in der ausgewählten Region verfügbar ist. Verwenden Sie in jedem Beispiel dasselbe Modell. Informationen zur Verwendung eines Modells, das in einem dedizierten KI-Cluster gehostet wird, finden Sie unter Modell verwenden, das in einem dedizierten KI-Cluster gehostet wird.
    • <PROJECT_OCID>: Ihre OCI Generative AI-Projekt-OCID. Weitere Informationen finden Sie in der Quick Start Guide.

    Jedes Skript übergibt die Projekt-OCID an OpenAI(..., project=...). Das SDK fügt den Anforderungsheader OpenAI-Project automatisch hinzu. Dieser Wert identifiziert ein OCI-Projekt.

  3. Halten Sie Ihren OCI Generative AI-API-Schlüssel bereit.
    Jedes Skript liest OCI_GENAI_API_KEY, wenn es von Ihrem Secret Manager oder einem anderen sicheren Mechanismus festgelegt wird. Andernfalls wird der Schlüssel angefordert, ohne ihn anzuzeigen. Fügen Sie den Skripten keinen Schlüssel hinzu, oder schreiben Sie ihn nicht in ein Repository fest.

2. Konversation explizit komprimieren

In diesem Beispiel wird eine Antwort erstellt, die vollständige Antwortausgabe zur Historie hinzugefügt und responses.compact aufgerufen. Anschließend wird die Historie durch die vollständige komprimierte Ausgabe ersetzt, und das Backupaufbewahrungs- und Wartungsfenster des Deployments wird angezeigt.

Das kurze Gespräch macht die Sequenz einfach zu folgen. Rufen Sie in einer Anwendung die Komprimierung auf, wenn die akkumulierte Historie reduziert werden muss und dennoch in die Kontextgrenze des Modells passt.

  1. Speichern Sie den folgenden Code unter standalone_compaction.py:
    """Compact a conversation with the OCI Responses API."""
    
    import os
    from getpass import getpass
    
    from openai import OpenAI
    
    
    def main() -> None:
        model = os.environ["OCI_MODEL"]
        api_key = os.environ.get("OCI_GENAI_API_KEY") or getpass(
            "OCI Generative AI API key: "
        )
        client = OpenAI(
            api_key=api_key,
            base_url=os.environ["OCI_BASE_URL"],
            project=os.environ["OCI_OPENAI_PROJECT"],
        )
        history = [{
            "role": "user",
            "content": (
                "Remember our deployment configuration: Frankfurt region, three "
                "application instances, PostgreSQL, daily backups with 30-day "
                "retention, and maintenance on Sunday at 02:00 UTC. "
                "Summarize the configuration."
            ),
        }]
    
        response = client.responses.create(model=model, input=history, store=False)
        print(response.output_text)
        history.extend(
            item.model_dump(mode="json", exclude_none=True)
            for item in response.output
        )
    
        compacted = client.responses.compact(model=model, input=history)
        print("Compaction observed:", any(
            item.type == "compaction" for item in compacted.output
        ))
    
        # Keep the complete compacted output, including any retained messages.
        history = [
            item.model_dump(mode="json", exclude_none=True)
            for item in compacted.output
        ]
        history.append({
            "role": "user",
            "content": "What are our backup retention and maintenance window?",
        })
        response = client.responses.create(model=model, input=history, store=False)
        print(response.output_text)
        client.close()
    
    
    if __name__ == "__main__":
        main()
  2. Wenn die virtuelle Umgebung aktiviert ist, führen Sie das Skript aus:
    python standalone_compaction.py
  3. Überprüfen Sie die Ausgabe und die Folgeantwort.

    Compaction observed: True gibt an, dass ein Komprimierungselement zurückgegeben wurde. Prüfen Sie, ob die Nachsorgeantwort die 30-tägige Backupaufbewahrung und das UTC-Wartungsfenster am Sonntag 02:00 beibehält. Der genaue Wortlaut kann variieren.

    Das Skript sendet alle Elemente in compacted.output an die nächste Anforderung. Behalten Sie nicht nur das Element bei, dessen type compaction ist: Das zurückgegebene Array kann anderen Kontext enthalten, der für die Fortsetzung erforderlich ist.

3. Automatische Verdichtung aktivieren

Um die automatische Komprimierung durchzuführen, nehmen Sie context_management in eine Antworterstellungsanforderung mit type: "compaction" und einer expliziten compact_threshold von mindestens 1000 Token auf. Wählen Sie einen Schwellenwert aus, der kleiner als das Kontextlimit des Modells ist, und lassen Sie Platz für die Ausgabe und spätere Umdrehungen.

In diesem Beispiel werden 40 synthetische Statusbörsen lokal erstellt, um eine längere Historie zu erstellen. Sie sendet diese Historie in einer Anforderung mit einem 1.000-Token-Schwellenwert, prüft auf Komprimierung und sendet eine Folgeanforderung. Die 40 Börsen führen keine separaten API-Aufrufe durch.

  1. Speichern Sie den folgenden Code unter server_compaction.py:
    """Use automatic compaction with the OCI Responses API."""
    
    import os
    from getpass import getpass
    
    from openai import OpenAI
    
    
    def main() -> None:
        model = os.environ["OCI_MODEL"]
        api_key = os.environ.get("OCI_GENAI_API_KEY") or getpass(
            "OCI Generative AI API key: "
        )
        client = OpenAI(
            api_key=api_key,
            base_url=os.environ["OCI_BASE_URL"],
            project=os.environ["OCI_OPENAI_PROJECT"],
        )
        context_management = [{"type": "compaction", "compact_threshold": 1000}]
        history = [{
            "role": "user",
            "content": (
                "Remember our deployment configuration: Frankfurt region, three "
                "application instances, PostgreSQL, daily backups with 30-day "
                "retention, and maintenance on Sunday at 02:00 UTC."
            ),
        }]
    
        # Build synthetic history locally. These exchanges don't call the API.
        for day in range(1, 41):
            history.extend([
                {
                    "role": "user",
                    "content": (
                        f"Day {day}: health checks passed, database connections "
                        "are stable, and the daily backup completed. "
                        "Keep the deployment configuration unchanged."
                    ),
                },
                {
                    "role": "assistant",
                    "content": [{
                        "type": "output_text",
                        "text": (
                            f"Day {day} status recorded. "
                            "The deployment configuration remains unchanged."
                        ),
                    }],
                },
            ])
        history.append({
            "role": "user",
            "content": "Summarize our deployment configuration.",
        })
    
        response = client.responses.create(
            model=model,
            input=history,
            store=False,
            extra_body={"context_management": context_management},
        )
        print(response.output_text)
        output = [
            item.model_dump(mode="json", exclude_none=True)
            for item in response.output
        ]
        boundaries = [
            index for index, item in enumerate(output)
            if item["type"] == "compaction"
        ]
        print("Compaction observed:", bool(boundaries))
    
        # Keep the latest compaction item and everything after it.
        # Without a new compaction item, retain history and append all output.
        history = output[boundaries[-1]:] if boundaries else history + output
        history.append({
            "role": "user",
            "content": "What are our backup retention and maintenance window?",
        })
        response = client.responses.create(
            model=model,
            input=history,
            store=False,
            extra_body={"context_management": context_management},
        )
        print(response.output_text)
        client.close()
    
    
    if __name__ == "__main__":
        main()
  2. Führen Sie das Skript aus:
    python server_compaction.py
  3. Prüfen Sie, ob eine Verdichtung aufgetreten ist, und prüfen Sie die Nachsorgeantwort.

    Das Skript gibt Compaction observed: True aus, wenn die erste Antwort ein Kompaktionselement enthält. Stellen Sie sicher, dass das Backupaufbewahrungs- und Wartungsfenster in der Nachverfolgung beibehalten wird.

    Der Wert False bedeutet, dass kein Komprimierungselement zurückgegeben wurde. Das Skript behält die vorhandene Historie bei und hängt die gesamte Ausgabe an, sodass sie fortgesetzt werden kann, ohne den Kontext zu löschen. Informationen zur erwarteten Verdichtung finden Sie unter Fehlerbehebung.

    Das Argument extra_body fügt der JSON-Anforderung context_management hinzu. Wiederholen Sie bei store=False nach jeder Antwort dieselbe Logik zur Historienverarbeitung, wenn Sie dieses Beispiel auf weitere Umdrehungen erweitern.

4. In einem dedizierten KI-Cluster gehostetes Modell verwenden (optional)

Sie können Modelle verwenden, die die OCI-Responses-API für Inferenzen bei Bedarf unterstützen, oder sie auf dedizierten KI-Clustern hosten, je nach den Hostingoptionen jedes Modells. Beide Compaction-Modi funktionieren mit beiden Hosting-Optionen. In den vorherigen Beispielen wird eine On-Demand-Modell-ID verwendet. Wenn Sie ein Modell in einem dedizierten KI-Cluster hosten, erstellen Sie einen Modellendpunkt in diesem Cluster, um das Modell aufzurufen. Übergeben Sie die OCID dieses Endpunkts als Wert für model der Anforderung.

Das Hostingcluster stellt die Compute-Ressourcen für Inferenz bereit. Sie können mehrere Endpunkte für dasselbe gehostete Modell erstellen, um beispielsweise verschiedenen Anwendungen, Teams oder Kostenstellen ihre eigenen Zugriffspunkte zu geben. Jeder Endpunkt verfügt über eine eigene OCID, und die Endpunkte verwenden die Compute-Ressourcen des Clusters gemeinsam. Weitere Informationen finden Sie unter Modellendpunkte verwalten.

  1. Wählen Sie ein Modell aus, das die OCI-Antworten-API unterstützt und für dediziertes Hosting in der Region verfügbar ist, in der Sie arbeiten möchten.

    Prüfen Sie die API-Kompatibilität unter Unterstützte Modelle und Regionen, und prüfen Sie dann die Hostingoptionen des Modells:

    • Grundlagenmodelle: OpenAI gpt-oss-20b und OpenAI gpt-oss-120b unterstützen sowohl On-Demand-Inferenz als auch dediziertes Hosting in US Midwest (Chicago), Germany Central (Frankfurt) und Japan Central (Osaka). Informationen zur Verfügbarkeit in anderen Regionen finden Sie unter Modelle nach Region.
    • Importierte Modelle: Unterstützte importierte Modelle umfassen Qwen/Qwen3.6-35B-A3B und google/gemma-4-31B-it. Für diese Modelle sind Modellimport und ein Endpunkt in einem dedizierten KI-Hostcluster erforderlich. Sie sind auf Anfrage nicht verfügbar. Befolgen Sie die Modelllinks für unterstützte Hardwareausprägungen und Deployment-Anforderungen.

    Sowohl explizite als auch automatische Verdichtung werden von diesen Grundlagen- und importierten Modellen unterstützt. Verwenden Sie ein Beispiel für den Modellendpunkt, den Sie erstellen.

  2. Erstellen Sie einen Modellendpunkt in einem kompatiblen dedizierten KI-Cluster, oder verwenden Sie ihn erneut.

    Wenn Sie ein Hostingcluster benötigen, folgen Sie Dediziertes KI-Cluster für Hostingmodelle erstellen. Nachdem das Cluster aktiv wurde, wählen Sie unter Endpunkt erstellen das Modell und das Hostingcluster aus. Warten Sie, bis der Modellendpunkt aktiv wird.

  3. Kopieren Sie die OCID des Modellendpunkts von der Detailseite.
    Wenn das Cluster mehrere Endpunkte enthält, wählen Sie den Endpunkt aus, den diese Anwendung verwenden soll. Informationen hierzu finden Sie unter Details zu einem Endpunkt abrufen.
  4. Legen Sie die OCI-Basis-URL der Endpunktregion fest, und aktualisieren Sie die Modell- und Projektvariablen:
    export OCI_BASE_URL='https://inference.generativeai.<REGION>.oci.oraclecloud.com/openai/v1'
    export OCI_MODEL='<INFERENCE_ENDPOINT_OCID>'
    export OCI_OPENAI_PROJECT='<PROJECT_OCID>'

    Ersetzen Sie <INFERENCE_ENDPOINT_OCID> durch die Modellendpunkt-OCID, die Sie kopiert haben. Das Skript übergibt diesen Wert als model. Setzen Sie <REGION> auf die Region des Endpunkts und <PROJECT_OCID> auf die OCI Generative AI-Projekt-OCID. Der Client verwendet weiterhin die regionale API-Basis-URL für OCI-Antworten. Verwenden Sie einen OCI Generative AI-API-Schlüssel, der für den Zugriff auf den Endpunkt und das Projekt autorisiert ist.

  5. Beispiel für eine explizite oder automatische Komprimierung ausführen:

    Führen Sie zum expliziten Verdichten folgenden Befehl aus:

    python standalone_compaction.py

    Führen Sie für die automatische Verdichtung folgenden Befehl aus:

    python server_compaction.py

    Beide Skripte verwenden die Inferenzendpunkt-OCID als Modell für alle Anforderungen. Prüfen Sie den zurückgegebenen Komprimierungsindikator und die Folgeantwort, wie im Beispiel Explizite Komprimierung oder Automatische Komprimierung beschrieben.

Ergebnisse prüfen

Ein zurückgegebenes Verdichtungselement bestätigt, dass die Verdichtung erfolgt ist. Es stellt nicht fest, dass jedes Detail bewahrt wurde. Prüfen Sie die Antwort der Nachsorge anhand der ursprünglichen Konfiguration.

Um die Komprimierung für eine Anwendung zu bewerten, verwenden Sie repräsentative Unterhaltungen mit Fakten und Anweisungen, die für den Workflow wichtig sind. Vergleichen Sie dieselbe Nachfassfrage mit der vollständigen Historie, mit expliziter Verdichtung und mit automatischer Verdichtung. Prüfen Sie beibehaltene Fakten, Anweisungen, Ausgabeformat und alle für den Workflow erforderlichen Toolaufrufe.

Führen Sie mehrere Beispiele aus, und passen Sie den Verdichtungsschwellenwert entsprechend Ihrer Beobachtung an. Die Komprimierung selbst verwendet Modelltoken, sodass ein kleinerer Kontext keine geringere Gesamttokenverwendung oder schnellere Antworten für jede Anforderung garantiert.

Fehlerbehebung

SymptomWas zu überprüfen ist
Ein Skript meldet eine fehlende Umgebungsvariable.Legen Sie OCI_BASE_URL, OCI_MODEL und OCI_OPENAI_PROJECT in der Shell fest, in der Sie das Skript ausführen.
401 oder 403Bestätigen Sie, dass Sie einen OCI Generative AI-API-Schlüssel und den richtigen regionalen OCI-Endpunkt verwenden. Prüfen Sie die Gültigkeit des Schlüssels, die Projektberechtigungen und den Zugriff auf das Modell oder den Inferenzendpunkt.
404 für /responses/compactVergewissern Sie sich, dass die Basis-URL auf /openai/v1 endet. Prüfen Sie, ob die Modell-ID oder Inferenzendpunkt-OCID korrekt und in der ausgewählten Region verfügbar ist.
In einer Anforderung wird ein fehlender Projektkontext gemeldet.Setzen Sie OCI_OPENAI_PROJECT auf die OCI Generative AI-Projekt-OCID, und übergeben Sie sie beim Erstellen des SDK-Clients an project=. Projektkontext ist für jedes Modell erforderlich.
Die automatische Verdichtung gibt kein Verdichtungselement zurück.Stellen Sie sicher, dass die Anforderung context_management mit type: "compaction" und einem Schwellenwert von mindestens 1000-Token enthält. Verwenden Sie eine längere Historie oder reduzieren Sie einen größeren Schwellenwert, während Sie ihn auf 1.000 oder mehr belassen.
Das SDK enthält keine responses.compact-Methode.Aktivieren Sie die virtuelle Umgebung, und installieren Sie openai>=2.45.0. Prüfen Sie die installierte Version mit python -m pip show openai.
Eine Nachsorgeantwort verliert die erwarteten Details.Zur expliziten Komprimierung übergeben Sie das vollständige zurückgegebene output-Array. Behalten Sie für die automatische Verdichtung das neueste Verdichtungselement und alle späteren Ausgabeelemente bei. Wenn kein Verdichtungselement zurückgegeben wird, behalten Sie die vorhandene Historie und die neue Ausgabe bei. Durch die Komprimierung können Details verloren gehen. Bewerten Sie daher auch das Modell und den Schwellenwert mit repräsentativen Unterhaltungen.