Esercitazione sulla compattazione delle API per le risposte OCI

Utilizzare l'SDK Python OpenAI con l'API OCI Responses per compattare in modo esplicito o automatico la cronologia delle conversazioni, quindi continuare la conversazione con il contesto restituito.

Panoramica

Man mano che una conversazione cresce, un'applicazione invia più cronologia ad ogni richiesta. La compattazione riduce la cronologia a una rappresentazione più piccola che il modello può utilizzare in turni successivi. Utilizzarlo per gestire il contesto nelle conversazioni a lungo termine e nei flussi di lavoro degli agenti.

In questa esercitazione viene descritta una configurazione di distribuzione di finzione, viene compattata la conversazione e viene posta una domanda di follow-up per verificare i dettagli del modello conservato.

Puoi utilizzare l'SDK Python OpenAI con una chiave API OCI Generative AI e un endpoint OCI regionale. L'SDK fornisce l'interfaccia client. Le richieste vengono autenticate con OCI e inviate all'AI generativa OCI.

Tutti i modelli supportati dall'API delle risposte OCI, inclusi i modelli importati, supportano la compattazione sia esplicita che automatica. La compattazione è disponibile nelle aree AI aziendali e segue l'area e la disponibilità dell'hosting di ogni modello. Entrambe le modalità sono supportate per l'inferenza su richiesta e l'hosting dedicato.

Modalità compattazione
ModalitàOperationCosa inviare dopo
Esplicito (standalone) Chiamare client.responses.compact(...), che invia POST /responses/compact, quando un'applicazione è pronta per compattare la cronologia. Passare l'array output restituito completo, seguito dal messaggio dell'utente successivo.
Automatico (gestito dal server) Chiamare client.responses.create(...) con context_management e una soglia token. OCI compatta il contesto durante POST /responses quando viene raggiunta la soglia. Con store=False, passare l'elemento di compattazione più recente e tutti gli elementi di output successivi, seguiti dal messaggio utente successivo. Se non viene restituito alcun elemento di compattazione, conservare la cronologia esistente e aggiungere il nuovo output.

Gli elementi di compattazione contengono un contesto cifrato e opaco. Conservare i campi e l'ordine serializzati. Non leggere, modificare o sostituire i loro contenuti con un riepilogo di testo.

Nota

La compattazione utilizza i token del modello e può perdere i dettagli durante la generazione del sintetico. Compatta prima di raggiungere il limite di contesto del modello e lascia spazio alla risposta e ai giri successivi. La compattazione esplicita è sincrona e non supporta lo storage, l'esecuzione in background o lo streaming.

Gli esempi gestiscono la cronologia nell'applicazione e impostano store=False sulle richieste di creazione delle risposte. Per il workflow separato che utilizza lo stato di conversazione gestito da OCI, vedere Usa memoria agente con API risposte.

Informazioni preliminari

Per completare questo tutorial, è necessario:

Gli esempi utilizzano l'SDK Python OpenAI con credenziali OCI e un URL di base OCI. Non richiedono una chiave API OpenAI, l'SDK Python OCI o l'interfaccia CLI OCI.

Questi esempi utilizzano l'autenticazione della chiave API OCI Generative AI. Compaction supporta anche l'autenticazione IAM OCI. Per questa impostazione, vedere Autenticazione basata sull'AI generativa basata su IAM. È necessario un OCID progetto AI generativa OCI con uno dei metodi di autenticazione.

1. Preparare l'ambiente Python e l'accesso OCI

  1. In una directory di lavoro, creare e attivare un ambiente virtuale, quindi installare OpenAI SDK Python:
    python3 -m venv .venv
    source .venv/bin/activate
    python -m pip install --upgrade 'openai>=2.45.0'

    Se .venv esiste già, attivarlo ed eseguire il comando di installazione.

  2. Impostare un URL di base OCI, un ID modello e un OCID progetto:
    export OCI_BASE_URL='https://inference.generativeai.<REGION>.oci.oraclecloud.com/openai/v1'
    export OCI_MODEL='<MODEL_ID>'
    export OCI_OPENAI_PROJECT='<PROJECT_OCID>'

    Sostituire i segnaposto con valori appropriati:

    • <REGION>: identificativo di area OCI supportato, ad esempio us-chicago-1. L'URL di base deve terminare in /openai/v1. Non aggiungere /responses.
    • <MODEL_ID>: l'ID di un modello su richiesta che supporta l'API OCI Responses ed è disponibile per la tenancy nell'area selezionata. Utilizzare lo stesso modello in ogni esempio. Per utilizzare un modello ospitato in un cluster AI dedicato, vedere Utilizzare un modello ospitato in un cluster AI dedicato.
    • <PROJECT_OCID>: OCID del Vostro progetto OCI Generative AI. Per istruzioni, vedere la Guida rapida.

    Ogni script passa l'OCID del progetto tramite OpenAI(..., project=...). L'SDK aggiunge automaticamente l'intestazione della richiesta OpenAI-Project. Questo valore identifica un progetto OCI.

  3. Prepara la tua chiave API OCI Generative AI.
    Ogni script legge OCI_GENAI_API_KEY se è impostato dal gestore dei segreti o da un altro meccanismo sicuro. Altrimenti, richiede la chiave senza visualizzarla. Non aggiungere la chiave agli script né eseguirne il commit in un repository.

2. Compatta una conversazione in modo esplicito

In questo esempio viene creata una risposta, viene aggiunto l'output completo della risposta alla cronologia e viene richiamato responses.compact. Sostituisce quindi la cronologia con l'output compatto completo e chiede informazioni sulla finestra di conservazione e manutenzione del backup della distribuzione.

La breve conversazione rende la sequenza facile da seguire. In un'applicazione, chiamare la compattazione quando la cronologia accumulata deve essere ridotta e si adatta comunque al limite di contesto del modello.

  1. Salvare il codice seguente come 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. Con l'ambiente virtuale attivato, eseguire lo script:
    python standalone_compaction.py
  3. Esaminare l'output e la risposta di follow-up.

    Compaction observed: True indica che è stato restituito un elemento di compattazione. Verificare che la risposta di follow-up conservi la conservazione del backup di 30 giorni e la finestra di manutenzione di domenica 02:00 UTC. La formulazione esatta può variare.

    Lo script invia tutti gli elementi in compacted.output alla richiesta successiva. Non conservare solo l'elemento il cui type è compaction: l'array restituito può contenere un altro contesto necessario per la continuazione.

3. Abilita compattazione automatica

Per la compattazione automatica, includere context_management in una richiesta di creazione di risposta con type: "compaction" e un compact_threshold esplicito di almeno 1000 token. Selezionare una soglia inferiore al limite di contesto del modello e lasciare spazio all'output e ai turni successivi.

In questo esempio vengono creati 40 scambi di stato sintetici a livello locale per creare una cronologia più lunga. Invia la cronologia in una richiesta con una soglia di 1.000 token, controlla la compattazione e invia una richiesta di follow-up. I 40 exchange non effettuano chiamate API separate.

  1. Salvare il codice seguente come 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. Eseguire lo script:
    python server_compaction.py
  3. Controllare se si è verificata la compattazione ed esaminare la risposta di follow-up.

    Lo script stampa Compaction observed: True quando la prima risposta include un elemento di compattazione. Verificare che il follow-up conservi la finestra di conservazione e manutenzione del backup.

    Il valore False indica che non è stato restituito alcun elemento di compattazione. Lo script conserva la cronologia esistente e aggiunge l'output completo in modo che possa continuare senza eliminare il contesto. Vedere Risoluzione dei problemi se è prevista la compattazione.

    L'argomento extra_body aggiunge context_management alla richiesta JSON. Con store=False ripetere la stessa logica di gestione della cronologia dopo ogni risposta quando si estende questo esempio a più turni.

4. Uso di un modello ospitato su un cluster AI dedicato (facoltativo)

Puoi utilizzare modelli che supportano l'API delle risposte OCI per l'inferenza su richiesta o ospitarli su cluster AI dedicati, in base alle opzioni di hosting di ciascun modello. Entrambe le modalità di compattazione funzionano con entrambe le opzioni di hosting. Gli esempi precedenti utilizzano un ID modello su richiesta. Quando si ospita un modello in un cluster AI dedicato, si crea un endpoint modello su tale cluster per chiamare il modello. Passa l'OCID di tale endpoint come valore model della richiesta.

Il cluster di hosting fornisce le risorse di calcolo per l'inferenza. È possibile creare diversi endpoint per lo stesso modello hosted, ad esempio per fornire ad applicazioni, team o centri di costo diversi i propri punti di accesso. Ogni endpoint ha il proprio OCID e gli endpoint condividono le risorse di computazione del cluster. Per ulteriori informazioni, vedere Gestione degli endpoint del modello.

  1. Selezionare un modello che supporti l'API OCI Responses ed è disponibile per l'hosting dedicato nell'area in cui si desidera lavorare.

    Verificare la compatibilità delle API in Modelli e aree supportati, quindi verificare le opzioni di hosting del modello.

    • Modelli di base: OpenAI gpt-oss-20b e OpenAI gpt-oss-120b supportano sia l'inferenza on-demand che l'hosting dedicato nel Midwest degli Stati Uniti (Chicago), in Germania centrale (Francoforte) e in Giappone centrale (Osaka). Per informazioni sulla disponibilità in altre aree, vedere Modelli per area.
    • Modelli importati: i modelli importati supportati includono Qwen/Qwen3.6-35B-A3B e google/gemma-4-31B-it. Questi modelli richiedono l'importazione del modello e un endpoint su un cluster AI dedicato in hosting. Non sono disponibili su richiesta. Seguire i collegamenti del modello per le forme hardware supportate e i requisiti di distribuzione.

    La compattazione esplicita e automatica è supportata da questi modelli di base e importati. Utilizzare uno degli esempi con l'endpoint del modello creato.

  2. Crea o riutilizza un endpoint modello in un cluster AI dedicato hosting compatibile.

    Se hai bisogno di un cluster di hosting, segui Creazione di un cluster AI dedicato per i modelli di hosting. Dopo l'attivazione del cluster, attenersi alla procedura Creazione di un endpoint per selezionare il modello e il cluster di hosting. Attendere che l'endpoint del modello diventi attivo.

  3. Copiare l'OCID dell'endpoint del modello dalla relativa pagina dei dettagli.
    Se il cluster dispone di più endpoint, selezionare l'endpoint che si desidera utilizzare per l'applicazione. Vedere Recupero dei dettagli di un endpoint.
  4. Impostare l'URL di base OCI dell'area dell'endpoint e aggiornare le variabili del modello e del progetto:
    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>'

    Sostituire <INFERENCE_ENDPOINT_OCID> con l'OCID dell'endpoint del modello copiato. Lo script passa questo valore come model. Impostare <REGION> nell'area dell'endpoint e <PROJECT_OCID> nell'OCID del progetto AI generativa OCI. Il client continua a utilizzare l'URL di base dell'API OCI Responses regionale. Utilizza una chiave API OCI Generative AI autorizzata ad accedere all'endpoint e al progetto.

  5. Eseguire l'esempio di compattazione esplicita o automatica:

    Per una compattazione esplicita, eseguire:

    python standalone_compaction.py

    Per la compattazione automatica, eseguire:

    python server_compaction.py

    Entrambi gli script utilizzano l'OCID dell'endpoint di inferenza come modello per tutte le richieste. Rivedere l'indicatore di compattazione restituito e la risposta di follow-up come descritto nell'esempio di compattazione esplicita o compattazione automatica.

Controllare i risultati

Un elemento di compattazione restituito conferma che si è verificata la compattazione. Non stabilisce che ogni dettaglio sia stato conservato. Rivedere la risposta di follow-up rispetto alla configurazione originale.

Per valutare la compattazione per un'applicazione, utilizzare conversazioni rappresentative con fatti e istruzioni importanti per il flusso di lavoro. Confronta la stessa domanda di follow-up con la storia completa, con la compattazione esplicita e con la compattazione automatica. Controllare i fact conservati, le istruzioni seguenti, il formato di output e qualsiasi chiamata di strumento richiesta dal flusso di lavoro.

Eseguire diversi esempi e regolare la soglia di compattazione in base a ciò che si osserva. La compattazione stessa utilizza i token modello, quindi un contesto più piccolo non garantisce un minore utilizzo totale dei token o risposte più rapide per ogni richiesta.

Risoluzione dei problemi

SintomoCosa controllare
Uno script segnala una variabile di ambiente mancante.Impostare OCI_BASE_URL, OCI_MODEL e OCI_OPENAI_PROJECT nella shell in cui viene eseguito lo script.
401 o 403Confermare che si sta utilizzando una chiave API OCI Generative AI e l'endpoint OCI regionale corretto. Controllare la validità della chiave, le autorizzazioni di progetto e l'accesso all'endpoint del modello o dell'inferenza.
404 per /responses/compactVerificare che l'URL di base termini in /openai/v1. Verificare che l'ID modello o l'OCID endpoint di inferenza siano corretti e disponibili nell'area selezionata.
Contesto progetto mancante in una richiesta.Impostare OCI_OPENAI_PROJECT sull'OCID del progetto AI generativa OCI e passarlo tramite project= durante la creazione del client SDK. Il contesto del progetto è obbligatorio per ogni modello.
La compattazione automatica non restituisce un elemento di compattazione.Verificare che la richiesta includa context_management con type: "compaction" e una soglia di almeno 1000 token. Usa una cronologia più lunga o riduci una soglia più grande mantenendola pari o superiore a 1.000.
L'SDK non dispone di un metodo responses.compact.Attivare l'ambiente virtuale e installare openai>=2.45.0. Controllare la versione installata con python -m pip show openai.
Una risposta di follow-up perde i dettagli previsti.Per la compattazione esplicita, passare l'array output restituito completo. Per la compattazione automatica, conservare l'elemento di compattazione più recente e tutti gli elementi di output successivi. Se non viene restituito alcun elemento di compattazione, conservare la cronologia esistente e il nuovo output. La interazione può comportare la perdita dei dettagli, pertanto è possibile anche valutare il modello e la soglia mediante conversazioni rappresentative.