Tutoriel de compactage d'API pour les réponses OCI

Utilisez la trousse SDK Python OpenAI avec l'API pour les réponses OCI pour compacter l'historique de conversation explicitement ou automatiquement, puis poursuivez la conversation avec le contexte retourné.

Aperçu

À mesure qu'une conversation se développe, une application envoie plus d'historique à chaque demande. Le compactage réduit cet historique à une représentation plus petite que le modèle peut utiliser lors de tours ultérieurs. Utilisez-le pour gérer le contexte dans des conversations de longue durée et des flux de travail d'agent.

Dans ce tutoriel, vous apprendrez à décrire une configuration fictive de déploiement, à compacter la conversation et à poser une question de suivi pour vérifier les détails du modèle conservé.

Vous utilisez la trousse SDK Python OpenAI avec une clé d'API du service d'intelligence artificielle générative pour OCI et un point d'extrémité OCI régional. La trousse SDK fournit l'interface client. Les demandes s'authentifient auprès d'OCI et sont envoyées au service d'intelligence artificielle générative pour OCI.

Tous les modèles pris en charge par l'API de réponses OCI, y compris les modèles importés, prennent en charge le compactage explicite et automatique. Le compactage est disponible dans les régions d'IA de l'entreprise et suit la région de chaque modèle et la disponibilité de l'hébergement. Les deux modes sont pris en charge pour l'inférence à la demande et l'hébergement dédié.

Modes de compactage
ModeOpérationQue faire pour envoyer ensuite
Explicite (autonome) Appelez client.responses.compact(...), qui envoie POST /responses/compact, lorsqu'une application est prête à compacter l'historique. Transmettez le tableau output complet retourné, suivi du message d'utilisateur suivant.
Automatique (géré par le serveur) Appelez client.responses.create(...) avec context_management et un seuil de jeton. OCI compacte le contexte pendant POST /responses lorsque le seuil est atteint. Avec store=False, transmettez le dernier élément de compactage et tous les éléments de sortie suivants, suivis du message d'utilisateur suivant. Si aucun élément de compactage n'est retourné, conservez l'historique existant et ajoutez la nouvelle sortie.

Les éléments de compactage contiennent un contexte opaque chiffré. Conservez leurs champs sérialisés et leur ordre. Ne lisez pas, ne modifiez pas ou ne remplacez pas leur contenu par un sommaire de texte.

Note

Le compactage consomme les jetons de modèle et peut perdre des détails lors de la récapitulation. Compacte avant d'atteindre la limite de contexte du modèle, laisse de la place pour la réponse et tourne plus tard. Le compactage explicite est synchrone et ne prend pas en charge le stockage, l'exécution en arrière-plan ou la diffusion en continu.

Les exemples gèrent l'historique dans l'application et définissent store=False sur les demandes de création de réponse. Pour le flux de travail distinct qui utilise l'état de conversation géré par OCI, voir Utiliser la mémoire de l'agent avec l'API de réponses.

Avant de commencer

Pour terminer ce tutoriel, vous devez :

Les exemples utilisent la trousse SDK Python OpenAI avec des données d'identification OCI et une URL de base OCI. Ils ne nécessitent pas de clé d'API OpenAI, de trousse SDK Python pour OCI ou d'interface de ligne de commande OCI.

Ces exemples utilisent l'authentification par clé d'API du service d'intelligence artificielle générative pour OCI. Le compact prend également en charge l'authentification OCI IAM. Pour cette configuration, voir Authentification basée sur IAM du service d'intelligence artificielle générative. Un OCID de projet du service d'intelligence artificielle générative pour OCI est requis avec l'une ou l'autre méthode d'authentification.

1. Préparer l'environnement Python et l'accès à OCI

  1. Dans un répertoire de travail, créez et activez un environnement virtuel, puis installez la trousse SDK Python OpenAI :
    python3 -m venv .venv
    source .venv/bin/activate
    python -m pip install --upgrade 'openai>=2.45.0'

    Si .venv existe déjà, activez-le et exécutez la commande d'installation.

  2. Définissez une URL de base OCI, un ID modèle et un OCID de projet :
    export OCI_BASE_URL='https://inference.generativeai.<REGION>.oci.oraclecloud.com/openai/v1'
    export OCI_MODEL='<MODEL_ID>'
    export OCI_OPENAI_PROJECT='<PROJECT_OCID>'

    Remplacez les paramètres fictifs par leurs valeurs :

    • <REGION> : Identificateur de région OCI pris en charge, par exemple us-chicago-1. L'URL de base doit se terminer par /openai/v1. N'ajoutez pas /responses.
    • <MODEL_ID> : ID d'un modèle sur demande qui prend en charge l'API de réponses OCI et qui est disponible pour votre location dans la région sélectionnée. Utilisez le même modèle dans chaque exemple. Pour utiliser un modèle hébergé dans une grappe dédiée à l'IA, voir Utiliser un modèle hébergé dans une grappe dédiée à l'IA.
    • <PROJECT_OCID> : OCID de votre projet d'intelligence artificielle générative pour OCI. Pour plus d'informations, voir le guide de démarrage rapide.

    Chaque script transmet l'OCID du projet à OpenAI(..., project=...). La trousse SDK ajoute automatiquement l'en-tête de demande OpenAI-Project. Cette valeur identifie un projet OCI.

  3. Préparez votre clé d'API du service d'intelligence artificielle générative pour OCI.
    Chaque script lit OCI_GENAI_API_KEY s'il est défini par votre gestionnaire de clés secrètes ou un autre mécanisme sécurisé. Sinon, il demande la clé sans l'afficher. N'ajoutez pas la clé aux scripts ou ne la validez pas dans un référentiel.

2. Compacter explicitement une conversation

Cet exemple crée une réponse, ajoute la sortie de réponse complète à l'historique et appelle responses.compact. Il remplace ensuite l'historique par la sortie compacte complète et pose des questions sur la fenêtre de conservation et de maintenance des sauvegardes du déploiement.

La courte conversation rend la séquence facile à suivre. Dans une application, appelez le compactage lorsque l'historique cumulé doit être réduit et qu'il correspond toujours à la limite de contexte du modèle.

  1. Enregistrez le code suivant sous le nom 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. Lorsque l'environnement virtuel est activé, exécutez le script :
    python standalone_compaction.py
  3. Vérifiez le résultat et la réponse de suivi.

    Compaction observed: True indique qu'un élément de compactage a été retourné. Vérifiez que la réponse de suivi conserve la période de conservation des sauvegardes de 30 jours et la période de maintenance UTC du dimanche 02:00. Le libellé exact peut varier.

    Le script envoie tous les éléments de compacted.output à la demande suivante. Ne conservez pas uniquement l'élément dont type est compaction : le tableau retourné peut contenir un autre contexte nécessaire à la poursuite.

3. Activer le compactage automatique

Pour le compactage automatique, incluez context_management dans une demande de création de réponse avec type: "compaction" et un compact_threshold explicite d'au moins 1000 jetons. Sélectionnez un seuil inférieur à la limite de contexte du modèle et laissez de la place pour la sortie et les rotations ultérieures.

Cet exemple crée 40 échanges de statuts synthétiques localement pour construire une histoire plus longue. Il envoie cet historique en une seule demande avec un seuil de 1 000 jetons, vérifie le compactage et envoie une demande de suivi. Les 40 échanges ne font pas d'appels d'API distincts.

  1. Enregistrez le code suivant sous le nom 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. Exécutez le script :
    python server_compaction.py
  3. Vérifiez si le compactage s'est produit et vérifiez la réponse de suivi.

    Le script imprime Compaction observed: True lorsque la première réponse inclut un élément de compactage. Vérifiez que le suivi conserve la fenêtre de conservation et de maintenance des sauvegardes.

    La valeur False signifie qu'aucun élément de compactage n'a été retourné. Le script conserve l'historique existant et ajoute la sortie complète afin de pouvoir continuer sans supprimer le contexte. Voir Dépannage si le compactage était attendu.

    L'argument extra_body ajoute context_management à la demande JSON. Avec store=False, répétez la même logique de traitement d'historique après chaque réponse lors de l'extension de cet exemple à d'autres tours.

4. Utiliser un modèle hébergé sur une grappe dédiée à l'IA (facultatif)

Vous pouvez utiliser des modèles qui prennent en charge l'API de réponses OCI pour l'inférence sur demande ou les héberger sur des grappes d'IA dédiées, selon les options d'hébergement de chaque modèle. Les deux modes de compactage fonctionnent avec l'une ou l'autre des options d'hébergement. Les exemples précédents utilisent un code de modèle sur demande. Lorsque vous hébergez un modèle sur une grappe dédiée à l'IA, vous créez un point d'extrémité de modèle sur cette grappe pour appeler le modèle. Transmettez l'OCID de ce point d'extrémité en tant que valeur model de la demande.

La grappe d'hébergement fournit les ressources de calcul pour l'inférence. Vous pouvez créer plusieurs points d'extrémité pour le même modèle hébergé, par exemple, pour donner à différentes applications, équipes ou centres de coûts leurs propres points d'accès. Chaque point d'extrémité a son propre OCID et les points d'extrémité partagent les ressources de calcul de la grappe. Pour plus d'informations, voir Gestion des points d'extrémité de modèle.

  1. Sélectionnez un modèle qui prend en charge l'API de réponses OCI et qui est disponible pour l'hébergement dédié dans la région dans laquelle vous voulez travailler.

    Vérifiez la compatibilité des API avec les modèles et régions pris en charge, puis vérifiez les options d'hébergement du modèle :

    • Modèles fondamentaux : OpenAI gpt-oss-20b et OpenAI gpt-oss-120b prennent en charge l'inférence sur demande et l'hébergement dédié dans le Midwest américain (Chicago), le centre de l'Allemagne (Francfort) et le centre du Japon (Osaka). Pour connaître la disponibilité dans d'autres régions, voir Modèles par région.
    • Modèles importés : Modèles importés pris en charge incluent Qwen/Qwen3.6-35B-A3B et google/gemma-4-31B-it. Ces modèles nécessitent une importation de modèle et un point d'extrémité sur une grappe d'IA dédiée à l'hébergement. Ils ne sont pas disponibles sur demande. Suivez les liens du modèle pour connaître les formes matérielles prises en charge et les exigences de déploiement.

    Le compactage explicite et automatique est pris en charge par ces modèles fondamentaux et ces modèles importés. Utilisez l'un ou l'autre des exemples avec le point d'extrémité de modèle que vous créez.

  2. Créez ou réutilisez un point d'extrémité de modèle sur une grappe d'IA dédiée à l'hébergement compatible.

    Si vous avez besoin d'une grappe d'hébergement, suivez Création d'une grappe dédiée à l'IA pour les modèles d'hébergement. Une fois la grappe active, suivez Création d'un point d'extrémité pour sélectionner le modèle et la grappe d'hébergement. Attendez que le point d'extrémité du modèle soit actif.

  3. Copiez l'OCID du point d'extrémité du modèle à partir de sa page de détails.
    Si la grappe comporte plusieurs points d'extrémité, sélectionnez le point d'extrémité que cette application doit utiliser. Voir Obtention des détails d'un point d'extrémité.
  4. Définissez l'URL de base OCI de la région du point d'extrémité et mettez à jour les variables de modèle et de projet :
    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>'

    Remplacez <INFERENCE_ENDPOINT_OCID> par l'OCID du point d'extrémité du modèle que vous avez copié. Le script transmet cette valeur en tant que model. Réglez <REGION> à la région du point d'extrémité et <PROJECT_OCID> à l'OCID du projet d'IA générative OCI. Le client continue d'utiliser l'URL de base de l'API régionale pour les réponses OCI. Utilisez une clé d'API du service d'intelligence artificielle générative pour OCI autorisée à accéder au point d'extrémité et au projet.

  5. Exécutez l'exemple de compactage explicite ou automatique :

    Pour un compactage explicite, exécutez :

    python standalone_compaction.py

    Pour le compactage automatique, exécutez :

    python server_compaction.py

    Les deux scripts utilisent l'OCID du point d'extrémité d'inférence comme modèle pour toutes les demandes. Vérifiez l'indicateur de compactage retourné et la réponse de suivi, comme décrit dans l'exemple de compaction explicite ou de compaction automatique.

Vérifiez les résultats

Un élément de compactage retourné confirme que le compactage s'est produit. Il n'est pas établi que chaque détail a été préservé. Vérifiez la réponse de suivi par rapport à la configuration initiale.

Pour évaluer le compactage d'une application, utilisez des conversations représentatives avec des faits et des instructions importants pour le flux de travail. Comparez la même question de suivi à l'historique complet, au compactage explicite et au compactage automatique. Vérifiez les faits conservés, les instructions suivantes, le format de sortie et tout appel d'outil requis par le flux de travail.

Exécutez plusieurs exemples et ajustez le seuil de compactage en fonction de ce que vous observez. Le compactage lui-même utilise des jetons de modèle, de sorte qu'un contexte plus petit ne garantit pas une utilisation totale moindre des jetons ou des réponses plus rapides pour chaque demande.

Dépannage

SymptômeQue vérifier
Un script signale une variable d'environnement manquante.Définissez OCI_BASE_URL, OCI_MODEL et OCI_OPENAI_PROJECT dans l'interpréteur de commandes où vous exécutez le script.
401 ou 403Confirmez que vous utilisez une clé d'API du service d'intelligence artificielle générative pour OCI et le point d'extrémité OCI régional approprié. Vérifiez la validité de la clé, les autorisations de projet et l'accès au modèle ou au point d'extrémité d'inférence.
404 pour /responses/compactVérifiez que l'URL de base se termine par /openai/v1. Vérifiez que l'ID modèle ou l'OCID du point d'extrémité d'inférence est correct et disponible dans la région sélectionnée.
Une demande signale un contexte de projet manquant.Réglez OCI_OPENAI_PROJECT à l'OCID du projet d'intelligence artificielle générative pour OCI et transmettez-le au moyen de project= lors de la création du client de trousse SDK. Le contexte du projet est requis pour chaque modèle.
Le compactage automatique ne retourne pas d'élément de compactage.Confirmez que la demande inclut context_management avec type: "compaction" et un seuil d'au moins 1000 jetons. Utilisez un historique plus long ou réduisez un seuil plus élevé tout en le maintenant à plus de 1 000.
La trousse SDK n'a pas de méthode responses.compact.Activez l'environnement virtuel et installez openai>=2.45.0. Vérifiez la version installée avec python -m pip show openai.
Une réponse de suivi perd les détails attendus.Pour un compactage explicite, transmettez le tableau output retourné complet. Pour le compactage automatique, conservez le dernier élément de compactage et tous les éléments de sortie ultérieurs. Si aucun élément de compactage n'est retourné, conservez l'historique existant et la nouvelle sortie. Le compactage peut perdre des détails, alors évaluez le modèle et le seuil avec des conversations représentatives.