如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

Oracle 云基础设施(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,并允许与 codex-cloud-environments.chatgpt.com 建立安全 WebSocket 连接。请参阅执行器的网络访问。

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 的名称。

参考资料