OCIレスポンスAPI圧縮チュートリアル

OCI Responses APIでOpenAI Python SDKを使用して、会話履歴を明示的にまたは自動的に圧縮してから、返されたコンテキストとの会話を続行します。

概要

会話が増えるにつれて、アプリケーションは各リクエストでより多くの履歴を送信します。圧縮により、その履歴が、後でモデルが使用できるより小さな表現に縮小されます。これを使用して、長時間実行される会話およびエージェント・ワークフローのコンテキストを管理します。

このチュートリアルでは、架空のデプロイメント構成について説明し、会話を圧縮し、モデルの保持の詳細を確認するためのフォローアップ質問をします。

OpenAI Python SDKは、OCI生成AI APIキーおよびリージョンOCIエンドポイントとともに使用します。SDKはクライアント・インタフェースを提供します。リクエストはOCIで認証され、OCI生成AIに送信されます。

OCI Responses APIでサポートされているすべてのモデル(インポートされたモデルを含む)は、明示的および自動的な圧縮の両方をサポートしています。圧縮はエンタープライズAIリージョンで使用でき、各モデルのリージョンおよびホスティングの可用性に従います。どちらのモードも、オンデマンド推論および専用ホスティングでサポートされています。

圧縮モード
モード工程次に送信するもの
明示的(スタンドアロン) アプリケーションで履歴を圧縮する準備ができたら、POST /responses/compactを送信するclient.responses.compact(...)をコールします。 返された完全なoutput配列を渡し、その後に次のユーザー・メッセージを渡します。
自動(サーバー管理) context_managementおよびトークンしきい値を指定してclient.responses.create(...)をコールします。OCIは、しきい値に達すると、POST /responses中にコンテキストを圧縮します。 store=Falseを使用して、最新の圧縮項目と次のすべての出力項目を渡し、その後に次のユーザー・メッセージを続けます。圧縮項目が返されない場合は、既存の履歴を保持し、新しい出力を追加します。

圧縮項目には、不透明で暗号化されたコンテキストが含まれます。シリアル化されたフィールドと順序を保持します。コンテンツを読んだり、編集したり、テキスト・サマリーで置き換えたりしないでください。

ノート

圧縮はモデル・トークンを消費し、要約中に詳細を失う可能性があります。モデルのコンテキスト制限に達する前に圧縮し、応答の余地を残して、後で回転します。明示的な圧縮は同期しており、記憶域、バックグラウンド実行またはストリーミングはサポートされません。

この例では、アプリケーションの履歴を管理し、レスポンス作成リクエストにstore=Falseを設定します。OCI管理の会話状態を使用する個別のワークフローについては、レスポンスAPIでのエージェント・メモリーの使用を参照してください。

始める前に

このチュートリアルを完了するには、次のものが必要です。

この例では、OpenAI Python SDKをOCI資格証明およびOCIベースURLとともに使用します。OpenAI APIキー、OCI Python SDKまたはOCI CLIは必要ありません。

これらの例では、OCI生成AI APIキー認証を使用します。コンパクションでは、OCI IAM認証もサポートされます。その設定については、生成AI IAMベースの認証を参照してください。どちらの認証方法でも、OCI生成AIプロジェクトOCIDが必要です。

1.Python環境およびOCIアクセスの準備

  1. 作業ディレクトリで、仮想環境を作成してアクティブ化し、OpenAI Python SDKをインストールします:
    python3 -m venv .venv
    source .venv/bin/activate
    python -m pip install --upgrade 'openai>=2.45.0'

    .venvがすでに存在する場合は、アクティブ化してインストール・コマンドを実行します。

  2. OCIベースURL、モデルIDおよびプロジェクトOCIDを設定します。
    export OCI_BASE_URL='https://inference.generativeai.<REGION>.oci.oraclecloud.com/openai/v1'
    export OCI_MODEL='<MODEL_ID>'
    export OCI_OPENAI_PROJECT='<PROJECT_OCID>'

    プレースホルダをそれぞれの値で置き換えます。

    • <REGION>: サポートされているOCIリージョン識別子(us-chicago-1など)。ベースURLは、/openai/v1で終わる必要があります。/responsesを追加しないでください。
    • <MODEL_ID>: OCI Responses APIをサポートし、選択したリージョンでテナンシが使用できるオンデマンド・モデルのID。各例で同じモデルを使用します。専用AIクラスタでホストされているモデルを使用するには、専用AIクラスタでホストされているモデルの使用を参照してください。
    • <PROJECT_OCID>: OCI Generative AIプロジェクトのOCID。ガイダンスについては、クイック・スタート・ガイドを参照してください。

    各スクリプトは、OpenAI(..., project=...)を介してプロジェクトのOCIDを渡します。SDKは、OpenAI-Projectリクエスト・ヘッダーを自動的に追加します。この値は、OCIプロジェクトを識別します。

  3. OCI Generative AI APIキーを準備します。
    各スクリプトは、シークレット・マネージャまたは別のセキュア・メカニズムによって設定されている場合、OCI_GENAI_API_KEYを読み取ります。それ以外の場合は、キーを表示せずに入力を求められます。スクリプトにキーを追加したり、リポジトリにコミットしないでください。

2. 会話を明示的に圧縮する

この例では、レスポンスを作成し、完全なレスポンス出力を履歴に追加して、responses.compactをコールします。次に、履歴を圧縮された完全な出力に置き換え、デプロイメントのバックアップ保存およびメンテナンス・ウィンドウについて尋ねます。

短い会話により、シーケンスを簡単にフォローできます。アプリケーションでは、累積された履歴を縮小する必要があり、モデルのコンテキスト制限内に収まる場合に圧縮をコールします。

  1. 次のコードを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. 仮想環境がアクティブ化された状態で、スクリプトを実行します。
    python standalone_compaction.py
  3. 出力とフォローアップの回答を確認します。

    Compaction observed: Trueは、圧縮アイテムが返されたことを示します。フォローアップの回答で、30日間のバックアップ保存期間と日曜日の02:00 UTCメンテナンス期間が保持されていることを確認します。正確な表現は異なる場合があります。

    スクリプトは、compacted.output内のすべての項目を次のリクエストに送信します。typeがcompactionのアイテムのみを保持しないでください。返される配列には、継続に必要な他のコンテキストを含めることができます。

3. 自動圧縮の有効化

自動圧縮の場合、type: "compaction"を使用したレスポンス作成リクエストにcontext_management、および少なくとも1000トークンの明示的なcompact_thresholdを含めます。モデルのコンテキスト制限より小さいしきい値を選択し、出力と後の回転の余地を残します。

この例では、40個の合成ステータス交換をローカルに作成して、より長い履歴を作成します。1,000トークンしきい値を持つ1つのリクエストでその履歴を送信し、圧縮をチェックして、フォローアップ・リクエストを送信します。40の交換では、個別のAPI呼び出しは行われません。

  1. 次のコードを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. スクリプトを実行します。
    python server_compaction.py
  3. 圧縮が発生したかどうかを確認し、フォローアップの回答をレビューします。

    スクリプトは、最初のレスポンスに圧縮アイテムが含まれている場合にCompaction observed: Trueを出力します。フォローアップがバックアップの保存期間とメンテナンス期間を保持していることを確認します。

    値Falseは、圧縮アイテムが返されなかったことを意味します。スクリプトは既存の履歴を保持し、完全な出力を追加するため、コンテキストを削除せずに続行できます。圧縮が必要な場合は、トラブルシューティングを参照してください。

    extra_body引数は、context_managementをJSONリクエストに追加します。store=Falseでは、この例をさらに回転に拡張するときに、各レスポンスの後に同じ履歴処理ロジックを繰り返します。

4. 専用AIクラスタでホストされるモデルの使用(オプション)

OCI Responses APIをサポートするモデルを使用して、オンデマンドで推論したり、各モデルのホスティング・オプションに従って専用AIクラスタでホストしたりできます。どちらの圧縮モードも、どちらのホスティングオプションでも機能します。前述の例では、オンデマンド・モデルIDを使用しています。専用AIクラスタでモデルをホストする場合は、そのクラスタにモデル・エンドポイントを作成してモデルをコールします。そのエンドポイントのOCIDをリクエストのmodel値として渡します。

ホスティング・クラスタは、推論のためのコンピュート・リソースを提供します。たとえば、異なるアプリケーション、チームまたはコスト・センターに独自のアクセス・ポイントを付与するために、同じホスト・モデルに対して複数のエンドポイントを作成できます。各エンドポイントには独自のOCIDがあり、エンドポイントはクラスタのコンピュート・リソースを共有します。詳細は、モデル・エンドポイントの管理を参照してください。

  1. OCI Responses APIをサポートし、作業するリージョンで専用ホスティングに使用できるモデルを選択します。

    サポートされているモデルおよびリージョンでAPIの互換性を確認し、モデルのホスティング・オプションを確認します:

    • 基盤モデル: OpenAI gpt-oss-20bおよびOpenAI gpt-oss-120bは、米国中西部(シカゴ)、ドイツ中央部(フランクフルト)および日本中央部(大阪)でのオンデマンド推論と専用ホスティングの両方をサポートしています。他のリージョンの可用性については、リージョン別モデルを参照してください。
    • インポートされたモデル: サポートされているインポートされたモデルには、Qwen/Qwen3.6-35B-A3Bおよびgoogle/gemma-4-31B-itが含まれます。これらのモデルには、モデル・インポートとホスティング専用AIクラスタ上のエンドポイントが必要です。オンデマンドでは使用できません。サポートされているハードウェア・シェイプおよびデプロイメント要件については、モデル・リンクに従ってください。

    これらの基本モデルおよびインポート済モデルでは、明示的および自動的圧縮の両方がサポートされています。作成するモデル・エンドポイントでいずれかの例を使用します。

  2. 互換性のあるホスティング専用AIクラスタでモデル・エンドポイントを作成または再利用します。

    ホスティングクラスタが必要な場合は、Creating a Dedicated AI Cluster for Hosting Modelsに従ってください。クラスタがアクティブになったら、「エンドポイントの作成」に従ってモデルを選択し、クラスタをホストします。モデル・エンドポイントがアクティブになるまで待機します。

  3. モデル・エンドポイントのOCIDをその詳細ページからコピーします。
    クラスタに複数のエンドポイントがある場合は、このアプリケーションで使用するエンドポイントを選択します。エンドポイント詳細の取得を参照してください。
  4. エンドポイントのリージョンのOCIベースURLを設定し、モデル変数およびプロジェクト変数を更新します:
    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>'

    <INFERENCE_ENDPOINT_OCID>を、コピーしたモデル・エンドポイントOCIDに置き換えます。スクリプトは、この値をmodelとして渡します。<REGION>をエンドポイントのリージョンに設定し、<PROJECT_OCID>をOCI生成AIプロジェクトのOCIDに設定します。クライアントは引き続き、リージョナルOCIレスポンスAPIベースURLを使用します。エンドポイントおよびプロジェクトへのアクセスを許可されたOCI生成AI APIキーを使用します。

  5. 明示的または自動的な圧縮の例を実行します。

    明示的な圧縮の場合は、次を実行します。

    python standalone_compaction.py

    自動圧縮の場合は、次を実行します。

    python server_compaction.py

    どちらのスクリプトも、推論エンドポイントOCIDをすべてのリクエストのモデルとして使用します。明示的圧縮または自動圧縮の例で説明されているように、返された圧縮インジケータとフォローアップ・アンサーを確認します。

結果の確認

戻された圧縮項目によって、圧縮が発生したことが確認されます。全ての詳細が保存されているとは限りません。元の構成に対するフォローアップの回答を確認します。

アプリケーションの圧縮を評価するには、ワークフローにとって重要なファクトおよび指示との代表的な会話を使用します。同じフォローアップ質問を完全な履歴、明示的な圧縮および自動圧縮と比較します。保持されているファクト、次の指示、出力形式、およびワークフローに必要なツール・コールを確認します。

いくつかの例を実行して、観察した内容に基づいて圧縮しきい値を調整します。コンパクション自体はモデル・トークンを使用するため、小さいコンテキストでは、すべてのリクエストの合計トークン使用またはレスポンスの高速化が保証されません。

トラブルシューティング

現象確認項目
スクリプトによって、欠落している環境変数が報告されます。スクリプトを実行するシェルで、OCI_BASE_URL、OCI_MODELおよびOCI_OPENAI_PROJECTを設定します。
401または403OCI生成AI APIキーと正しいリージョンOCIエンドポイントを使用していることを確認します。キーの有効性、プロジェクト権限、およびモデルまたは推論エンドポイントへのアクセスを確認してください。
/responses/compactの場合は404ベースURLが/openai/v1で終わることを確認します。モデルIDまたは推論エンドポイントOCIDが正しいこと、および選択したリージョンで使用可能であることを確認してください。
要求により、欠落しているプロジェクト・コンテキストがレポートされます。OCI_OPENAI_PROJECTをOCI生成AIプロジェクトのOCIDに設定し、SDKクライアントの作成時にproject=を渡します。プロジェクト・コンテキストはすべてのモデルに必要です。
自動圧縮では、圧縮項目は返されません。リクエストにtype: "compaction"を含むcontext_managementと、少なくとも1000トークンのしきい値が含まれていることを確認します。1,000以上を維持しながら、より長い履歴を使用するか、より大きなしきい値を減らします。
SDKにはresponses.compactメソッドがありません。仮想環境をアクティブ化し、openai>=2.45.0をインストールします。インストールされているバージョンをpython -m pip show openaiで確認します。
フォローアップの回答で、予想される詳細が失われます。明示的な圧縮の場合は、返された完全なoutput配列を渡します。自動圧縮の場合は、最新の圧縮項目とそれ以降のすべての出力項目を保持します。圧縮項目が返されない場合は、既存の履歴と新しい出力を保持します。圧縮によって詳細が失われる可能性があるため、代表的な会話でモデルとしきい値を評価することもできます。

次のステップ