Oracle Cloud Infrastructure

Oracle Cloud Infrastructure (OCI)

이 가이드는 Oracle의 베타 Python 예시를 따르며 **애플리케이션 관리형 프로비저닝(application-managed provisioning)**을 사용해요. 애플리케이션이 Agents API 세션과 OCI 샌드박스를 모두 만들고 삭제해요.

출처: 문서

본문

OpenAI Cookbook의 애플리케이션 관리형 예시를 참고하세요.

프로비저닝 모드와 연결 동작은 샌드박스 수명주기를 참고하세요.

OCI GenAI 샌드박스는 베타 단계예요. 계정 접근을 요청하려면 Oracle 계정 담당자에게 문의하세요.

시작하기 전에 (Before you begin)

샌드박스가 활성화된 Generative AI 프로젝트를 만드세요. OCI ID에 해당 컴파트먼트의 프로젝트와 샌드박스를 관리할 권한을 부여하세요. 이 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이 없다면 호환되는 커스텀 런타임을 선택하세요.

프로젝트가 아웃바운드 트래픽을 제한한다면, Codex 설치용 registry.npmjs.org HTTPS, api.openai.com HTTPS, 그리고 codex-cloud-environments.chatgpt.com으로의 보안 WebSocket 연결을 허용하세요. 실행기 네트워크 접근을 참고하세요.

1. OCI CLI와 베타 SDK 설치하기

가상 환경을 만들고 OCI CLI를 설치하세요:

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

그다음 온보딩 과정에서 Oracle이 제공한 베타 Python SDK를 설치하세요:

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

베타 SDK는 CLI 이후에 설치하세요. 그 후에 oci-cli를 설치하거나 업그레이드하면 PyPI의 oci 패키지로 바뀔 수 있으니, 그런 경우 베타 wheel을 다시 설치하세요. 베타 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로 프로필의 보안 토큰과 개인 키를 사용하세요. oci.generative_ai_sandbox의 GenerativeAiSandboxClient로 샌드박스 클라이언트를 만들고, 선택한 리전과 엔드포인트를 사용하세요.

3. 애플리케이션 관리형 세션 실행하기

Agents API 요청과 실행기 시작 명령은 자체 호스팅 연결 가이드를 사용하세요. Oracle 예시와 같은 흐름을 따르세요:

  1. 작업 디렉터리를 /workspace로 하는 자체 호스팅 Agents API 세션을 만들고 세션 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이 지정한 베타 SDK 버전을 사용하세요. 미리보기 릴리스는 샌드박스 API 이름을 바꿀 수 있어요.

참고 자료 (References)

더 알아보기 (Learn more)