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でのエージェント・メモリーの使用を参照してください。
始める前に
このチュートリアルを完了するには、次のものが必要です。
- サポートされているエンタープライズAIリージョンのOCIレスポンスAPIにアクセスします。選択したリージョンでテナンシで使用可能な「サポートされているモデルおよびリージョン」からモデルを選択します。基本モデルの場合は、リージョン別モデルでオンデマンドおよび専用ホスティングの可用性を確認してください。
- 選択したモデルおよびプロジェクトにアクセスできるOCI生成AI APIキー。必要に応じて、APIキーを作成し、権限を追加します。
- OCI生成AIプロジェクトOCID。圧縮では、すべてのモデルにプロジェクト・コンテキストが必要です。必要に応じて、プロジェクトを作成します。
- Python 3.10以降(macOS、LinuxまたはWindows Subsystem for Linuxの場合)。このコマンドは、Bash互換シェルを使用します。
この例では、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アクセスの準備
2. 会話を明示的に圧縮する
この例では、レスポンスを作成し、完全なレスポンス出力を履歴に追加して、responses.compactをコールします。次に、履歴を圧縮された完全な出力に置き換え、デプロイメントのバックアップ保存およびメンテナンス・ウィンドウについて尋ねます。
短い会話により、シーケンスを簡単にフォローできます。アプリケーションでは、累積された履歴を縮小する必要があり、モデルのコンテキスト制限内に収まる場合に圧縮をコールします。
3. 自動圧縮の有効化
自動圧縮の場合、type: "compaction"を使用したレスポンス作成リクエストにcontext_management、および少なくとも1000トークンの明示的なcompact_thresholdを含めます。モデルのコンテキスト制限より小さいしきい値を選択し、出力と後の回転の余地を残します。
この例では、40個の合成ステータス交換をローカルに作成して、より長い履歴を作成します。1,000トークンしきい値を持つ1つのリクエストでその履歴を送信し、圧縮をチェックして、フォローアップ・リクエストを送信します。40の交換では、個別のAPI呼び出しは行われません。
4. 専用AIクラスタでホストされるモデルの使用(オプション)
OCI Responses APIをサポートするモデルを使用して、オンデマンドで推論したり、各モデルのホスティング・オプションに従って専用AIクラスタでホストしたりできます。どちらの圧縮モードも、どちらのホスティングオプションでも機能します。前述の例では、オンデマンド・モデルIDを使用しています。専用AIクラスタでモデルをホストする場合は、そのクラスタにモデル・エンドポイントを作成してモデルをコールします。そのエンドポイントのOCIDをリクエストのmodel値として渡します。
ホスティング・クラスタは、推論のためのコンピュート・リソースを提供します。たとえば、異なるアプリケーション、チームまたはコスト・センターに独自のアクセス・ポイントを付与するために、同じホスト・モデルに対して複数のエンドポイントを作成できます。各エンドポイントには独自のOCIDがあり、エンドポイントはクラスタのコンピュート・リソースを共有します。詳細は、モデル・エンドポイントの管理を参照してください。
結果の確認
戻された圧縮項目によって、圧縮が発生したことが確認されます。全ての詳細が保存されているとは限りません。元の構成に対するフォローアップの回答を確認します。
アプリケーションの圧縮を評価するには、ワークフローにとって重要なファクトおよび指示との代表的な会話を使用します。同じフォローアップ質問を完全な履歴、明示的な圧縮および自動圧縮と比較します。保持されているファクト、次の指示、出力形式、およびワークフローに必要なツール・コールを確認します。
いくつかの例を実行して、観察した内容に基づいて圧縮しきい値を調整します。コンパクション自体はモデル・トークンを使用するため、小さいコンテキストでは、すべてのリクエストの合計トークン使用またはレスポンスの高速化が保証されません。
トラブルシューティング
| 現象 | 確認項目 |
|---|---|
| スクリプトによって、欠落している環境変数が報告されます。 | スクリプトを実行するシェルで、OCI_BASE_URL、OCI_MODELおよびOCI_OPENAI_PROJECTを設定します。 |
401または403 | OCI生成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配列を渡します。自動圧縮の場合は、最新の圧縮項目とそれ以降のすべての出力項目を保持します。圧縮項目が返されない場合は、既存の履歴と新しい出力を保持します。圧縮によって詳細が失われる可能性があるため、代表的な会話でモデルとしきい値を評価することもできます。 |
次のステップ
- APIの動作と制限については、「Manage Context with Compaction」を参照してください。
- OCI管理の会話履歴について学習します。
- 互換性のあるSDKインタフェースについては、OpenAI圧縮ガイドを参照してください。OCIリクエストについては、このチュートリアルのOCI固有の要件を使用してください。