Tutorial de compactación de API de respuestas de OCI

Utilice el SDK de Python OpenAI con la API de respuestas de OCI para compactar el historial de conversaciones de forma explícita o automática y, a continuación, continuar la conversación con el contexto devuelto.

Descripción general

A medida que crece la conversación, una aplicación envía más historial con cada solicitud. La compactación reduce ese historial a una representación más pequeña que el modelo puede utilizar en turnos posteriores. Utilícelo para gestionar el contexto en conversaciones de larga ejecución y flujos de trabajo de agente.

En este tutorial, se describe una configuración de despliegue ficticia, se compacta la conversación y se hace una pregunta de seguimiento para comprobar qué detalles conserva el modelo.

Utiliza el SDK de Python OpenAI con una clave de API de OCI Generative AI y un punto final de OCI regional. El SDK proporciona la interfaz de cliente. Las solicitudes se autentican con OCI y se envían a OCI Generative AI.

Todos los modelos soportados por la API de respuestas de OCI, incluidos los modelos importados, soportan la compactación tanto explícita como automática. La compactación está disponible en regiones de IA empresarial y sigue la región de cada modelo y la disponibilidad de alojamiento. Ambos modos son compatibles para la inferencia bajo demanda y el alojamiento dedicado.

Modos de compactación
Modo	Operación	Qué enviar a continuación
Explícito (independiente)	Llame a `client.responses.compact(...)`, que envía `POST /responses/compact`, cuando una aplicación está lista para compactar el historial.	Transfiera la matriz `output` devuelta completa, seguida del siguiente mensaje de usuario.
Automático (gestionado por el servidor)	Llame a `client.responses.create(...)` con `context_management` y un umbral de token. OCI compacta el contexto durante `POST /responses` cuando se alcanza el umbral.	Con `store=False`, transfiera el último elemento de compactación y todos los siguientes elementos de salida, seguidos del siguiente mensaje de usuario. Si no se devuelve ningún elemento de compactación, conserve el historial existente y agregue la nueva salida.

Los elementos de compactación contienen un contexto cifrado opaco. Conservar sus campos serializados y su orden. No lea, edite ni sustituya su contenido por un resumen de texto.

Nota

La compactación consume tokens de modelo y puede perder detalles durante el resumen. Compacta antes de alcanzar el límite de contexto del modelo, deja espacio para la respuesta y giros posteriores. La compactación explícita es síncrona y no soporta almacenamiento, ejecución en segundo plano ni transmisión.

Los ejemplos gestionan el historial en la aplicación y definen store=False en las solicitudes de creación de respuesta. Para el flujo de trabajo independiente que utiliza el estado de conversación gestionado por OCI, consulte Uso de la memoria del agente con la API de respuestas.

Antes de empezar

Para completar este tutorial, necesita:

Acceso a la API de respuestas de OCI en una región de IA empresarial soportada. Seleccione un modelo de Modelos y regiones soportados que esté disponible para su arrendamiento en la región seleccionada. Para obtener modelos básicos, consulte Modelos por región para conocer la disponibilidad de alojamiento dedicado y bajo demanda.
Una clave de API de OCI Generative AI con acceso al modelo y proyecto seleccionados. Si es necesario, cree una clave de API y agregue sus permisos.
OCID de proyecto de OCI Generative AI. La compactación requiere contexto de proyecto para cada modelo. Si es necesario, cree un proyecto.
Python 3.10 o posterior en macOS, Linux o el subsistema Windows para Linux. Los comandos utilizan un shell compatible con Bash.

En los ejemplos se utiliza el SDK de Python OpenAI con credenciales de OCI y una URL base de OCI. No necesitan una clave de API OpenAI, el SDK de Python de OCI ni la CLI de OCI.

En estos ejemplos se utiliza la autenticación de clave de API de OCI Generative AI. Compaction también soporta la autenticación de OCI IAM. Para esa configuración, consulte Autenticación basada en IAM de IA generativa. Se necesita un OCID de proyecto de OCI Generative AI con cualquiera de los métodos de autenticación.

1. Preparación del entorno de Python y el acceso a OCI

En un directorio de trabajo, cree y active un entorno virtual y, a continuación, instale el SDK de Python OpenAI:
```
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade 'openai>=2.45.0'
```
Si ya existe .venv, actívelo y ejecute el comando de instalación.
Defina una URL base de OCI, un ID de modelo y un OCID de proyecto:
```
export OCI_BASE_URL='https://inference.generativeai.<REGION>.oci.oraclecloud.com/openai/v1'
export OCI_MODEL='<MODEL_ID>'
export OCI_OPENAI_PROJECT='<PROJECT_OCID>'
```
Sustituya los marcadores de posición con sus valores correspondientes:
- <REGION>: identificador de región de OCI soportado, como us-chicago-1. La URL base debe terminar en /openai/v1. No agregue /responses.
- <MODEL_ID>: ID de un modelo a demanda que soporta la API de respuestas de OCI y que está disponible para su arrendamiento en la región seleccionada. Utilice el mismo modelo en cada ejemplo. Para utilizar un modelo alojado en un cluster de IA dedicado, consulte Uso de un modelo alojado en un cluster de IA dedicado.
- <PROJECT_OCID>: OCID de su proyecto OCI Generative AI. Para obtener orientación, consulte la Guía de inicio rápido.
Cada script transfiere el OCID del proyecto a través de OpenAI(..., project=...). El SDK agrega automáticamente la cabecera de solicitud OpenAI-Project. Este valor identifica un proyecto de OCI.
Prepara tu clave de API de OCI Generative AI.
Cada script lee OCI_GENAI_API_KEY si lo define el gestor de secretos u otro mecanismo seguro. De lo contrario, solicita la clave sin mostrarla. No agregue la clave a los scripts ni la confirme en un repositorio.

2. Compacta una conversación de forma explícita

En este ejemplo se crea una respuesta, se agrega la salida de respuesta completa al historial y se llama a responses.compact. A continuación, sustituye el historial por la salida compactada completa y pregunta sobre la ventana de mantenimiento y retención de copias de seguridad del despliegue.

La breve conversación hace que la secuencia sea fácil de seguir. En una aplicación, llame a la compactación cuando el historial acumulado deba reducirse y aún así se ajuste al límite de contexto del modelo.

Guarde el siguiente código como 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()

Con el entorno virtual activado, ejecute el script:
```
python standalone_compaction.py
```
Revise la salida y la respuesta de seguimiento.

Compaction observed: True indica que se ha devuelto un elemento de compactación. Compruebe que la respuesta de seguimiento retiene la retención de copias de seguridad de 30 días y la ventana de mantenimiento de domingo a las 02:00 UTC. La redacción exacta puede variar.

El script envía todos los elementos de compacted.output a la siguiente solicitud. No guarde solo el elemento cuyo valor type es compaction: la matriz devuelta puede contener otro contexto necesario para la continuación.

3. Activar compactación automática

Para la compactación automática, incluya context_management en una solicitud de creación de respuesta con type: "compaction" y un compact_threshold explícito de al menos tokens 1000. Seleccione un umbral que sea menor que el límite de contexto del modelo y deje espacio para la salida y giros posteriores.

En este ejemplo, se crean 40 intercambios de estado sintéticos localmente para crear un historial más largo. Envía ese historial en una solicitud con un umbral de 1.000 tokens, comprueba la compactación y envía una solicitud de seguimiento. Los 40 intercambios no realizan llamadas de API separadas.

Guarde el siguiente código como 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()

Ejecute el script:
```
python server_compaction.py
```
Compruebe si se ha producido la compactación y revise la respuesta de seguimiento.

El script imprime Compaction observed: True cuando la primera respuesta incluye un elemento de compactación. Compruebe que el seguimiento conserva la ventana de retención y mantenimiento de la copia de seguridad.

Un valor de False significa que no se ha devuelto ningún elemento de compactación. La secuencia de comandos conserva el historial existente y agrega la salida completa para que pueda continuar sin borrar el contexto. Consulte Solución de problemas si esperaba compactación.

El argumento extra_body agrega context_management a la solicitud JSON. Con store=False, repita la misma lógica de manejo de historial después de cada respuesta al ampliar este ejemplo a más turnos.

4. Uso de un modelo alojado en un cluster de IA dedicado (opcional)

Puede utilizar modelos que admitan la API de respuestas de OCI para la inferencia a demanda o alojarlos en clusters de IA dedicados, según las opciones de alojamiento de cada modelo. Ambos modos de compactación funcionan con cualquiera de las opciones de alojamiento. En los ejemplos anteriores se utiliza un ID de modelo bajo demanda. Cuando aloja un modelo en un cluster de IA dedicado, crea un punto final de modelo en ese cluster para llamar al modelo. Transfiera el OCID de ese punto final como valor model de la solicitud.

El cluster de alojamiento proporciona los recursos informáticos para la inferencia. Puede crear varios puntos finales para el mismo modelo alojado, por ejemplo, para proporcionar a diferentes aplicaciones, equipos o centros de costos sus propios puntos de acceso. Cada punto final tiene su propio OCID y los puntos finales comparten los recursos informáticos del cluster. Para obtener más información, consulte Gestión de puntos finales de modelo.

Seleccione un modelo que admita la API de respuestas de OCI y que esté disponible para el alojamiento dedicado en la región en la que desea trabajar.
Compruebe la compatibilidad de API en Modelos y regiones soportados y, a continuación, compruebe las opciones de alojamiento del modelo:
- Modelos fundamentales: OpenAI gpt-oss-20b y OpenAI gpt-oss-120b soportan la inferencia bajo demanda y el alojamiento dedicado en el medio oeste de EE. UU. (Chicago), el centro de Alemania (Fráncfort) y el centro de Japón (Osaka). Para obtener información sobre la disponibilidad en otras regiones, consulte Modelos por región.
- Modelos importados: los modelos importados soportados incluyen Qwen/Qwen3.6-35B-A3B y google/gemma-4-31B-it. Estos modelos requieren la importación de modelos y un punto final en un cluster de IA dedicado de alojamiento. No están disponibles bajo demanda. Siga los enlaces del modelo para conocer las unidades de hardware soportadas y los requisitos de despliegue.
Tanto la compactación explícita como la automática están soportadas por estos modelos fundamentales e importados. Utilice cualquier ejemplo con el punto final de modelo que cree.
Cree o reutilice un punto final de modelo en un cluster de IA dedicado de alojamiento compatible.

Si necesita un cluster de alojamiento, siga Creación de un cluster de IA dedicado para alojar modelos. Una vez que el cluster esté activo, siga Creación de un punto final para seleccionar el modelo y el cluster de alojamiento. Espere a que el punto final del modelo se active.
Copie el OCID del punto final del modelo desde su página de detalles.
Si el cluster tiene varios puntos finales, seleccione el punto final que desea que utilice esta aplicación. Consulte Obtención de detalles de un punto final.
Defina la URL base de OCI de la región del punto final y actualice el modelo y las variables de proyecto:
```
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>'
```
Sustituya <INFERENCE_ENDPOINT_OCID> por el OCID de punto final de modelo que ha copiado. El script transfiere este valor como model. Defina <REGION> en la región del punto final y <PROJECT_OCID> en el OCID del proyecto de OCI Generative AI. El cliente sigue utilizando la URL base de la API de respuestas de OCI regional. Utilice una clave de API de OCI Generative AI autorizada para acceder al punto final y al proyecto.
Ejecute el ejemplo de compactación explícita o automática:
Para la compactación explícita, ejecute:
```
python standalone_compaction.py
```
Para la compactación automática, ejecute:
```
python server_compaction.py
```
Ambos scripts utilizan el OCID de punto final de inferencia como modelo para todas las solicitudes. Revise el indicador de compactación devuelto y la respuesta de seguimiento como se describe en el ejemplo de compactación explícita o compactación automática.

Comprobar los resultados

Un elemento de compactación devuelto confirma que se ha producido la compactación. No establece que todos los detalles se hayan conservado. Revise la respuesta de seguimiento con respecto a la configuración original.

Para evaluar la compactación de una aplicación, utilice conversaciones representativas con hechos e instrucciones que sean importantes para el flujo de trabajo. Compare la misma pregunta de seguimiento con la historia completa, con la compactación explícita y con la compactación automática. Compruebe los hechos retenidos, las instrucciones siguientes, el formato de salida y cualquier herramienta que llame al flujo de trabajo.

Ejecute varios ejemplos y ajuste el umbral de compactación según lo que observe. La compactación en sí misma utiliza tokens de modelo, por lo que un contexto más pequeño no garantiza un uso de token menos total ni respuestas más rápidas para cada solicitud.

Solución de problemas


Síntoma	Qué comprobar
Un script informa que falta una variable de entorno.	Defina `OCI_BASE_URL`, `OCI_MODEL` y `OCI_OPENAI_PROJECT` en el shell en el que ejecuta el script.
`401` o `403`	Confirme que está utilizando una clave de API de OCI Generative AI y el punto final regional de OCI correcto. Compruebe la validez de la clave, los permisos del proyecto y el acceso al punto final de modelo o inferencia.
`404` para `/responses/compact`	Confirme que la URL base termina en `/openai/v1`. Compruebe que el ID de modelo o el OCID de punto final de inferencia son correctos y están disponibles en la región seleccionada.
Una solicitud informa que falta contexto de proyecto.	Defina `OCI_OPENAI_PROJECT` en el OCID del proyecto de OCI Generative AI y transfiéralo a través de `project=` al crear el cliente SDK. El contexto del proyecto es necesario para cada modelo.
La compactación automática no devuelve un elemento de compactación.	Confirme que la solicitud incluye `context_management` con `type: "compaction"` y un umbral de al menos tokens `1000`. Utilice un historial más largo o reduzca un umbral mayor mientras lo mantiene en o más de 1.000.
El SDK no tiene ningún método `responses.compact`.	Active el entorno virtual e instale `openai>=2.45.0`. Compruebe la versión instalada con `python -m pip show openai`.
Una respuesta de seguimiento pierde los detalles esperados.	Para la compactación explícita, transfiera la matriz `output` devuelta completa. Para la compactación automática, mantenga el último elemento de compactación y todos los elementos de salida posteriores. Si no se devuelve ningún elemento de compactación, conserve el historial existente y la nueva salida. La compactación puede perder detalles, por lo que también puede evaluar el modelo y el umbral con conversaciones representativas.

Siguientes pasos

Revise Gestionar contexto con compactación para conocer el comportamiento y los límites de la API.
Obtén más información sobre el historial de conversaciones gestionadas por OCI.
Consulte la guía de compactación OpenAI para obtener la interfaz de SDK compatible. Utilice los requisitos específicos de OCI de este tutorial para solicitudes de OCI.

Documentación de Oracle Cloud Infrastructure