如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

Oracle Cloud Infrastructure (OCI)

將 OCI GenAI 沙盒連線至 Agents API 工作階段。

本指南依循 Oracle 的 Beta 版 Python 範例,採用由應用程式管理佈建的方式。Agents API 工作階段和 OCI 沙盒都由你的應用程式負責建立及刪除。

請參閱 OpenAI Cookbook 中由應用程式管理佈建的範例。

如需瞭解佈建模式和連線方式,請參閱沙盒生命週期。

OCI GenAI 沙盒目前為 Beta 版。請聯絡你的 Oracle 客戶經理,為你的帳戶申請存取權。

開始之前

建立已啟用沙盒的生成式 AI 專案。授予你的 OCI 身分管理該專案所在區間內專案和沙盒的權限。請將下列 IAM 原則中的預留位置替換為實際名稱:

allow group <group-name> to manage generative-ai-sandbox in compartment <compartment-name>
allow group <group-name> to manage generative-ai-project in compartment <compartment-name>

請使用包含 Node.js 和 npm 的沙盒執行環境。Oracle 的範例預設會要求使用 python-3.11。如果該執行環境未包含 npm,請選擇相容的自訂執行環境。

如果你的專案限制對外流量,請允許透過 HTTPS 連線至 registry.npmjs.org 以安裝 Codex,也請允許透過 HTTPS 連線至 api.openai.com,以及透過安全的 WebSocket 連線至 codex-cloud-environments.chatgpt.com。請參閱執行器的網路存取權。

1. 安裝 OCI CLI 和 Beta 版 SDK

建立虛擬環境並安裝 OCI CLI:

uv venv --python 3.14
source .venv/bin/activate
uv pip install --upgrade oci-cli

接著安裝 Oracle 在導入期間提供的 Beta 版 Python SDK:

uv pip install "/path/to/oci-<beta-version>-py3-none-any.whl"

請在安裝 CLI 之後再安裝 Beta 版 SDK。如果之後安裝或升級 oci-cli,PyPI 上的 oci 套件可能會取代 Beta 版 SDK。遇到這種情況時,請重新安裝 Beta 版 wheel 套件。Beta 版 SDK 必須包含 oci.generative_ai_sandbox。

2. 設定 OCI 環境

在你的帳戶已啟用的區域中,為使用安全權杖的設定檔進行身分驗證:

oci session authenticate --profile-name Sandbox --region us-chicago-1

設定專案 OCID 和 OpenAI 憑證,請勿將這些值提交至程式碼庫:

export OCI_SANDBOX_PROJECT_ID="ocid1.generativeaiproject..."
export OPENAI_API_KEY="..."
export OPENAI_EXECUTOR_API_KEY="..."

應用程式發送請求時,請使用 OPENAI_API_KEY。將 OPENAI_EXECUTOR_API_KEY 設為環境金鑰,並僅將這把金鑰傳入沙盒,作為 CODEX_API_KEY。

Oracle 的範例會讀取 Sandbox 設定檔,並使用 us-chicago-1 區域。若要覆寫預設值,請設定下列環境變數:

export OCI_SANDBOX_PROFILE="my-profile"
export OCI_SANDBOX_REGION="us-chicago-1"

範例也支援下列選用設定:

設定 預設值
OCI_SANDBOX_ENDPOINT https://inference.generativeai.<region>.oci.oraclecloud.com
OCI_SANDBOX_RUNTIME python-3.11
OCI_SANDBOX_SHAPE SMALL
OCI_SANDBOX_EXPIRATION PT30M(30 分鐘)

設定自己的應用程式時,請搭配設定檔中的安全權杖和私密金鑰使用 oci.auth.signers.SecurityTokenSigner。接著使用 GenerativeAiSandboxClient(來自 oci.generative_ai_sandbox)建立沙盒用戶端,並指定所選的區域和端點。

3. 執行由應用程式管理的工作階段

如需 Agents API 請求和啟動執行器的指令,請參閱自託管連線指南。請依照 Oracle 範例的流程操作:

  1. 建立自託管的 Agents API 工作階段,並將 /workspace 設為工作目錄。儲存工作階段 ID 和環境 ID。
  2. 建立 OCI GenAI 沙盒,並等待其狀態變為 RUNNING。
  3. 安裝 Codex,並在沙盒中寫入 /workspace/brief.txt 檔案。
  4. 使用工作階段的環境 ID 和環境金鑰啟動 codex exec-server。
  5. 開啟工作階段的事件串流,然後傳送訊息,要求智慧體根據 brief.txt 擬定遷移計畫。等待任務完成,再讀取產生的 /workspace/plan.md 檔案。
  6. 停止並刪除 OCI 沙盒,然後刪除 Agents API 工作階段。即使其中一項清理作業失敗,仍須嘗試執行另一項。

若要繼續後續回合,請讓工作階段和沙盒都保持運作,並在刪除沙盒前取回檔案。請使用 Oracle 指定的 Beta 版 SDK 版本,因為預覽版本可能會變更沙盒 API 的名稱。

參考資料