> ## 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.

# VERL

> Weave에서 VERL rollout을 트레이스하여 RL fine-tuning 중 multi-turn 대화, 도구 Call, reward scoring을 검사하세요.

[VERL](https://github.com/volcengine/verl) (Volcano Engine Reinforcement Learning)은 LLM을 위한 오픈소스 RL Post-training 프레임워크입니다. VERL은 내장된 Weave trace backend를 통해 LLM 생성과 도구 Call을 W\&B가 이미 기록하는 training 메트릭과 함께 트레이스할 수 있게 합니다.

VERL과 함께 Weave를 사용하면 다음을 수행할 수 있습니다:

* 프롬프트, 모델 responses, 도구 invocations를 포함하여 각 rollout 트래젝터리를 단계별로 검사합니다.
* step, sample index, rollout number, experiment name별로 트래젝터리를 필터링합니다.
* training steps 전반에 걸쳐 여러 트래젝터리를 나란히 비교하여 에이전트 behavior를 디버그합니다.

<h2 id="prerequisites">
  사전 요구 사항
</h2>

* CoreWeave Forge 계정 및 [API 키](/ko/products/wandb/platform/app/settings-page/user-settings#api-keys).
* 롤아웃 트레이싱을 지원하는 VERL 설치. 롤아웃 트레이싱은 [verl#2345](https://github.com/volcengine/verl/pull/2345)에서 추가되었습니다.
* 비동기 롤아웃 설정. 트레이싱은 비동기 롤아웃에만 적용되며, 동기 롤아웃은 트레이싱되지 않습니다.

<h2 id="enable-weave-tracing">
  트레이싱 활성화
</h2>

VERL이 CoreWeave Forge 계정으로 인증할 수 있도록 환경에 API 키를 설정하세요:

```bash theme={"system"}
export WANDB_API_KEY=[YOUR-WANDB-API-KEY]
```

그런 다음 VERL 트레이닝 명령어에 다음 플래그를 추가하세요:

* `actor_rollout_ref.rollout.trace.backend=weave`: Weave를 백엔드로 선택합니다.
* `actor_rollout_ref.rollout.mode=async`: vLLM 또는 SGLang의 비동기 롤아웃을 활성화합니다. 트레이싱은 동기 롤아웃에는 영향을 주지 않습니다.
* `trainer.project_name`: 트레이스와 메트릭을 로깅할 프로젝트를 설정합니다.
* `trainer.experiment_name`: 실험 이름을 설정합니다.
* `trainer.logger=['console','wandb']`: Weave와 함께 wandb 로거를 활성화하여 메트릭과 트레이스가 같은 프로젝트에 표시되도록 합니다.

최종 명령어는 다음과 같습니다:

```bash theme={"system"}
python -m verl.trainer.main_ppo \
  actor_rollout_ref.rollout.trace.backend=weave \
  actor_rollout_ref.rollout.mode=async \
  trainer.project_name=[YOUR-PROJECT-NAME] \
  trainer.experiment_name=[YOUR-EXPERIMENT-NAME] \
  trainer.logger=['console','wandb'] \
  # ... 기타 트레이닝 플래그
```

Weave는 Weights & Biases 프로젝트와 실험 이름을 기반으로 자동으로 초기화됩니다. `weave.init()`을 호출할 필요가 없습니다.

<h2 id="tune-trace-volume">
  트레이스 양 조정
</h2>

기본적으로 VERL은 모든 롤아웃의 모든 샘플을 추적하므로 매우 많은 트레이스 데이터가 생성될 수 있습니다. `ppo_trainer.yaml` 설정 파일에서 다음 필드를 설정하여 데이터 양을 제한할 수 있습니다:

* `max_samples_per_step_per_worker`: 워커가 트레이닝 단계마다 추적하는 고유 샘플 수입니다.  기본값은 `null`이며 모든 샘플을 추적합니다.
* `token2text`: `True`로 설정하면 디코딩된 `prompt_text`와 `response_text`가 `ToolAgentLoop.run` 출력에 추가됩니다. 성능을 위해 기본값은 `False`입니다. Weights & Biases UI에서 프롬프트와 완성 응답을 직접 읽으려면 활성화하세요.

파일에서 설정된 필드는 다음과 같습니다:

```yaml theme={"system"}
actor_rollout_ref:
  rollout:
    trace:
      backend: weave
      token2text: False
      max_samples_per_step_per_worker: 5
```

<h2 id="view-traces">
  트레이스 보기
</h2>

트레이닝 중에 생성된 트레이스를 보려면 Weights & Biases 프로젝트 페이지를 열고 **Traces**를 선택하세요. 각 트레이스는 롤아웃 트래젝터리에 해당합니다.

여러 트레이스를 선택하고 Weave의 뷰를 사용하여 트래젝터리 간의 차이를 살펴볼 수 있습니다. 이를 통해 트레이닝 단계나 실험에 따른 에이전트 동작의 변화를 디버깅할 수 있습니다.

<h2 id="trace-additional-functions">
  추가 함수 트레이싱
</h2>

VERL은 기본 트레이스 범위를 확장할 수 있는 두 가지 헬퍼를 제공합니다.

* `rollout_trace_op`: `weave.op`에 매핑되는 데코레이터로, 클래스 인스턴스의 메서드를 트레이싱 대상으로 지정합니다. 기본적으로는 일부 메서드에만 이 데코레이터가 적용되어 있습니다. 맞춤형 에이전트 루프나 도구 구현의 메서드에 이 데코레이터를 추가하면 더 자세한 정보를 캡처할 수 있습니다.
* `rollout_trace_attr`: 트래젝터리의 진입점을 표시하고 트래젝터리 메타데이터(인덱스, step, 롤아웃 번호, 실험 이름)를 첨부하는 컨텍스트 매니저입니다. 새로운 에이전트 유형을 추가하는 경우, 트레이스가 run에 연결되도록 해당 트래젝터리 진입점을 `rollout_trace_attr`로 래핑하세요.

자세한 설정 정보는 [VERL의 롤아웃 트레이스 문서](https://verl.readthedocs.io/en/latest/advance/rollout_trace.html)를 참조하세요.


## Related topics

- [Run veRL on SUNK](/products/sunk/tutorials/verl-on-sunk.md)