> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 웜 풀 구현하기

> Python 웜 풀 레시피를 사용하여 들어오는 작업에 대비해 샌드박스를 준비 완료 상태로 유지하세요.

샌드박스가 시작될 때까지 기다리지 않고 요청을 실행 중인 샌드박스에서 바로 처리해야 한다면
웜 풀을 사용하세요. [웜 풀 레시피](https://github.com/coreweave/cwsandbox-recipes/tree/main/recipes/warm-pool)는 미리 준비된 샌드박스 버퍼를 유지하면서
각 워크로드에 전용 샌드박스를 부여하고, 백그라운드에서 버퍼를 다시 채웁니다.
단, 유휴 샌드박스는 작업을 기다리는 동안에도 컴퓨팅 리소스를 소비합니다.

<h2 id="how-the-pool-works">
  풀의 작동 방식
</h2>

레시피의 `WarmPool` 헬퍼는 설정된 수만큼 샌드박스를 시작하고
각 샌드박스에서 준비 상태 검사를 실행합니다. 각 샌드박스의 메인 프로세스는 명령어 사이에도 계속 실행 상태를 유지합니다.
주기적인 ping은 필요하지 않습니다.

각 워크로드는 준비 완료된 샌드박스 하나를 클레임하며, 이를 계기로 대체 샌드박스 준비가 트리거됩니다.
해당 클레임 내의 모든 `exec()`는 동일한 샌드박스와 파일을 공유합니다.
워크로드가 종료되거나 실패하면 헬퍼가 해당 샌드박스를 중지합니다. 이후 워크로드에는
별도의 샌드박스가 할당되므로 이전 워크로드의 로컬 상태를 물려받지 않습니다.

<h2 id="run-the-recipe">
  레시피 실행
</h2>

Python 3.11 이상, [`uv`](https://docs.astral.sh/uv/getting-started/installation/),
그리고 [서버리스 액세스 및 사용자 인증 정보](/ko/products/sandboxes/get-started#run-a-sandbox-on-serverless-capacity)가 필요합니다.

1. [레시피 저장소](https://github.com/coreweave/cwsandbox-recipes/tree/main/recipes/warm-pool)를 다운로드하거나 복제한 다음
   `recipes/warm-pool`을 여세요. 의존성을 설치하고 환경 파일을 생성하세요.

   ```bash theme={"system"}
   uv sync --frozen
   cp .env.example .env
   ```

2. `.env` 파일과 `demo.py` 상단에서 사용자 인증 정보를 설정하세요.

   <Tabs>
     <Tab title="Forge API 키">
       `.env`에 Forge API 키를 추가하세요.

       ```bash theme={"system"}
       FORGE_API_KEY="[FORGE-API-KEY]"
       ```

       `demo.py`에 다음 import 문을 추가하고 기존 `AUTH` 할당문을 교체하세요.

       ```python theme={"system"}
       import os
       from cwsandbox import AuthHeaders

       AUTH = AuthHeaders(
           headers={"x-wandb-api-key": os.environ["FORGE_API_KEY"]},
           strategy="wandb_api_key",
       )
       ```

       이 코드는 `FORGE_API_KEY`를 명시적으로 읽고 SDK에서 지원하는 인증 헤더를 사용합니다. 헤더 이름과 전략 이름은 호환성을 위한 식별자일 뿐이며, 실제 사용자 인증 정보는 Forge API 키입니다. 선택적 의존성인 `wandb`는 설치하지 않아도 됩니다.
     </Tab>

     <Tab title="CoreWeave API 액세스 토큰">
       `.env`에 토큰을 추가하세요.

       ```bash theme={"system"}
       CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"
       ```

       레시피의 기본 `AUTH` 설정은 그대로 두세요.

       ```python theme={"system"}
       from cwsandbox import AuthStrategy

       AUTH = AuthStrategy.COREWEAVE_API_KEY
       ```
     </Tab>
   </Tabs>

3. 비교를 실행하세요.

   ```bash theme={"system"}
   uv run --frozen --env-file .env demo.py
   ```

이 데모는 온디맨드 방식으로 생성하는 요청 4개와 풀을 사용하는 요청 4개를 비교합니다.
초기 풀 준비 시간은 요청 시간과 별도로 보고되며, 모든 워크로드가
각각 고유한 샌드박스를 할당받는지도 확인합니다. 마지막에 다음 메시지가 표시되어야 합니다.

```text theme={"system"}
Verified 8 distinct workload sandboxes; all sandboxes stopped.
```

<h2 id="adapt-the-pool-to-your-workload">
  워크로드에 맞게 풀 조정하기
</h2>

`demo.py`의 상수를 수정하세요.

```python theme={"system"}
POOL_SIZE = 2     # 유지할 유휴 샌드박스 목표 개수
CONCURRENCY = 2   # 실행 중인 워크로드 최대 개수
REQUESTS = 4      # 비교 모드별 요청 수
```

이 기본값으로는 샌드박스를 동시에 최대 4개까지 실행할 수 있습니다. 실행 중인 워크로드 2개에
더해 버퍼 샌드박스 2개를 유지하는 구성입니다. 각 샌드박스는 vCPU 2개와 4 GiB RAM을 요청합니다.
버퍼가 비면 요청은 버퍼가 다시 채워질 때까지 대기합니다. 실행 중 한도에
도달하면 워크로드가 종료될 때까지 대기합니다. 버퍼를 늘리기 전에 실제 요청 유입 패턴으로
먼저 측정해 보세요.

`demo.py`의 `WORKLOAD`를 직접 작성한 코드로 바꾸세요. 공통 설정은 `warm_pool.py`의 `prepare()`에
추가하고, 애플리케이션에 맞는 준비 상태 검사 방식을 사용하세요.
비동기 워크로드 핸들러 안에서 여러 명령어를 실행하려면 레시피의 클레임 컨텍스트를
사용하세요.

```python theme={"system"}
async with pool.claim() as sandbox:
    await sandbox.exec(["sh", "-c", "echo hello > /tmp/result.txt"], check=True)
    result = await sandbox.exec(["cat", "/tmp/result.txt"], check=True)
    print(result.stdout)
```

클레임을 해제하기 전에 출력을 수집하세요. 고객 입력과 사용자 인증 정보는 클레임한 후에 제공하고,
공유 외부 저장소는 해당 고객으로 범위를 제한하세요.

<h2 id="keep-the-pool-running">
  풀 계속 실행하기
</h2>

요청을 받는 동안에는 풀과 이를 감싸는 `Session` 컨텍스트를 열어 두세요.
각 Python 프로세스는 자체 풀을 따로 가집니다. 데모에서는 비교가 끝나면 둘 다 닫습니다.

헬퍼는 5분 동안 유휴 상태인 샌드박스를 교체합니다. 각 샌드박스의 수명은 10분입니다.
풀은 컨텍스트가 열려 있는 동안 계속 보충됩니다. 이 기본값을 사용할 때는
작업이 5분 안에 여유 있게 끝나도록 하세요. 샌드박스를 클레임해도 기한은
재설정되지 않습니다. 더 긴 작업을 위한 설정과 중단된 run 이후의 정리 작업은
[레시피](https://github.com/coreweave/cwsandbox-recipes/tree/main/recipes/warm-pool)를 참조하세요.

일시적인 준비 실패는 최대 세 번까지 시도합니다. 시도 횟수를 모두 소진하거나
준비 중 재시도할 수 없는 오류가 발생하면, 준비 완료 상태의 샌드박스가 남아 있더라도
이후의 모든 클레임이 실패합니다. 풀과 `Session` 컨텍스트를 종료하여 정리한 다음,
근본 원인을 해결한 후 새 풀을 생성하세요.

보충 시간을 줄이려면 자주 바뀌지 않는 의존성을 이미지에 미리 포함하거나, 준비된
워크스페이스 파일을 [파일 시스템 스냅샷](/ko/products/sandboxes/file-system-snapshots)에서 복원하세요.
스냅샷은 설정된 마운트의 파일을 캡처합니다. 애플리케이션 프로세스는 여전히
별도로 시작해야 합니다. [샌드박스 템플릿](/ko/products/sandboxes/profiles/templates)에
공유 이미지와 스냅샷 설정을 저장할 수 있습니다.