本指南依循 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 範例的流程操作:
- 建立自託管的 Agents API 工作階段,並將
/workspace設為工作目錄。儲存工作階段 ID 和環境 ID。 - 建立 OCI GenAI 沙盒,並等待其狀態變為
RUNNING。 - 安裝 Codex,並在沙盒中寫入
/workspace/brief.txt檔案。 - 使用工作階段的環境 ID 和環境金鑰啟動
codex exec-server。 - 開啟工作階段的事件串流,然後傳送訊息,要求智慧體根據
brief.txt擬定遷移計畫。等待任務完成,再讀取產生的/workspace/plan.md檔案。 - 停止並刪除 OCI 沙盒,然後刪除 Agents API 工作階段。即使其中一項清理作業失敗,仍須嘗試執行另一項。
若要繼續後續回合,請讓工作階段和沙盒都保持運作,並在刪除沙盒前取回檔案。請使用 Oracle 指定的 Beta 版 SDK 版本,因為預覽版本可能會變更沙盒 API 的名稱。