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.
| Modus | Arbeitsvorgang | Als 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.
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:
- Zugriff auf die OCI-Antworten-API in einer unterstützten KI-Region für Unternehmen. Wählen Sie unter Unterstützte Modelle und Regionen ein Modell aus, das für Ihren Mandanten in der ausgewählten Region verfügbar ist. Für Basismodelle prüfen Sie die Verfügbarkeit von On-Demand- und dediziertem Hosting unter Modelle nach Region.
- Ein OCI Generative AI-API-Schlüssel mit Zugriff auf das ausgewählte Modell und Projekt. Falls erforderlich erstellen Sie einen API-Schlüssel und fügen Sie dessen Berechtigungen hinzu.
- Eine OCI Generative AI-Projekt-OCID. Komprimierung erfordert Projektkontext für jedes Modell. Falls erforderlich erstellen Sie ein Projekt.
- Python 3.10 oder höher auf macOS, Linux oder Windows-Subsystem für Linux. Die Befehle verwenden eine Bash-kompatible Shell.
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
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.
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.
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.
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
| Symptom | Was 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 403 | Bestä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/compact | Vergewissern 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. |
Nächste Schritte
- Unter Kontext mit Komprimierung verwalten finden Sie das API-Verhalten und die Limits.
- Weitere Informationen zur OCI-verwalteten Unterhaltungshistorie.
- Die kompatible SDK-Schnittstelle finden Sie im OpenAI Compaction Guide. Verwenden Sie die OCI-spezifischen Anforderungen in diesem Tutorial für OCI-Anforderungen.