README_kr.md

# Arena-Lite (구 Arena-Lite)
아레나-라이트는 테스트셋 명령어별로 비교할 모델들의 토너먼트를 수행하여 정확하게 모델들의 순위를 매깁니다. 이것은 reference 아웃풋과 비교하여 승률을 매기는 방법보다 정확하며 조금 더 저렴합니다.

더 자세한 내용에 대해서는 아래의 링크를 참조하시면 됩니다.
* [논문](https://arxiv.org/abs/2411.01281)
* [엔씨소프트 테크블로그 (KR)](https://ncsoft.github.io/ncresearch/12cc62c1ea0d981971a8923401e8fe6a0f18563d)


## Quickstart
### 로컬에서 스트림릿 앱으로 시작하기 (추천!)
```bash
git clone [THIS_REPO]
# install requirements below. we recommend miniforge to manage environment
cd streamlit_app_local
bash run.sh
```
더 자세한 내용은 `[THIS_REPO]/streamlit_app_local/README.md` 을 참조하세요!

### CLI 사용
* cli와 웹 앱은 서로 같은 코드를 활용하며, 아래의 디렉토리에 있습니다.
  * `varco_arena/`
* vscode 상에서 디버깅을 위한 프리셋 프롬프트별 테스트 명령어는 다음 파일에 적혀있습니다.
  * `varco_arena/.vscode/launch.json`
```bash
## gpt-4o-mini as a judge
python main.py -i "./some/dirpath/to/jsonl/files" -o SOME_REL_PATH_TO_CREATE -m tournament -e "gpt-4o-mini"
## vllm-openai served LLM as a judge
python main.py -i "./some/dirpath/to/jsonl/files" -o SOME_REL_PATH_TO_CREATE -e SOME_MODEL_NAME_SERVED -m tournament -u "http://url_to/your/vllm_openai_server:someport"

# dbg lines
## openai api judge dbg
python main.py -i "rsc/inputs_for_dbg/dbg_400_error_inputs/" -o SOME_WANTED_TARGET_DIR -e gpt-4o-mini
## other testing lines
python main.py -i "rsc/inputs_for_dbg/[SOME_DIRECTORY]/" -o SOME_WANTED_TARGET_DIR -e gpt-4o-mini
## dummy judge dbg (checking errors without api requests)
python main.py -i "rsc/inputs_for_dbg/dbg_400_error_inputs/" -o SOME_WANTED_TARGET_DIR -e debug
```

## Requirements
`python = 3.11.9` 상에서 테스트  함. `requirements.txt`
```
openai>=1.17.0
munch
pandas
numpy
tqdm>=4.48.0
plotly
scikit-learn
kaleido
tiktoken>=0.7.0
pyyaml
transformers
streamlit>=1.40.2
openpyxl
fire==0.6.0
git+https://github.com/shobrook/openlimit.git#egg=openlimit # do not install this by pypi

# Linux인 경우
uvloop
# Windows인 경우
winloop
```

#### Argument
- -i, --input : 입력 파일 or 디렉토리 or 파일명에 대한 정규 표현식
- -o, --output_dir : 출력 파일이 저장되는 디렉토리
- -e, --evaluation : 평가 모델 (e.g. "gpt-4o-2024-05-13", "gpt-4o-mini", vllm에서 띄운 모델 명 등)
- -m, --matching_method: 매치 방식 (기본값 "tournament", "league" (비추천) )
- -k, --openai_api_key : OpenAI API Key
- -u, --openai_url: 로컬 vLLM OpenAI 서버 사용 시 URL(ip주소+포트)

#### advanced
- -j, --n_jobs : asyncio.semaphore()에 전달될 인자. Arena가 진행되지 않는다면 기본값인 32 이하로 내려보자
- -p, --evalprompt : [해당 디렉토리 참조](./varco_arena/prompts/*.yaml)
- -lr, --limit_requests : vLLM OpenAI 서버 요청 제한 (default: 7,680)
- -lt, --limit_tokens : vLLM OpenAI 서버 토큰 제한 (default: 15,728,640)

#### Input Data Format
[input jsonl 가이드 링크](./streamlit_app_local/guide_mds/input_jsonls_kr.md)



## Contributing & Customizing
#### git clone 및 dependency 설치 후에 할 일
```bash
pip install pre-commit
pre-commit install
```
#### commit 하기 전에 할 일
```bash
bash precommit.sh # 이게 코드들을 다 리포맷해줄거임
```

### 📝 커스텀 프롬프트 추가하기

새로운 평가 프롬프트를 추가하는 과정은 다음과 같습니다. 최근 Judge 로직이 `parsed_output` 메소드만 사용하도록 간소화되어 이전보다 쉽게 프롬프트를 추가할 수 있습니다.

가장 간단한 방법은 `llmbar_brief.py`와 `llmbar_brief.yaml` 파일을 복사하여 자신만의 프롬프트를 만드는 것입니다.

#### 1. 프롬프트 `.py` 및 `.yaml` 파일 생성

-   `varco_arena/varco_arena_core/prompts/` 경로에 `my_prompt.py`와 `my_prompt.yaml`처럼 파일을 생성합니다.
-   **`my_prompt.py`**:
    -   `ComparisonPromptBase`를 상속받는 클래스를 정의합니다.
    -   `parsed_output(self, response)` 메소드를 반드시 구현해야 합니다. 이 함수는 LLM Judge의 응답(`response`)을 받아, 승자를 나타내는 결정 토큰(예: `'a'`, `'b'`)을 반환해야 합니다.
-   **`my_prompt.yaml`**:
    -   `sampling_parameters`, `decision_tokens`, `prompt_template` 등 프롬프트에 필요한 요소들을 정의합니다.
    -   `prompt_template` 에 들어가는 문자열은 `string.Template`으로 처리되며 `BasePrompt.complete_prompt()` 함수를 통해 `eval_utils.py`에서 최종 완성됩니다.
    -   `${task}, ${generated}, ${model_id}`를 `prompt_template`에 사용하지 마세요. 예약된 키워드들입니다.

#### 2. `prompts/__init__.py`에 프롬프트 등록

-   생성한 프롬프트 클래스를 `import` 합니다.
    ```python
    from .my_prompt import MyPrompt
    ```
-   `NAME2PROMPT_CLS` 딕셔너리에 새 프롬프트 이름과 클래스 객체를 추가합니다.
    ```python
    NAME2PROMPT_CLS = dict(
        # ... 기존 프롬프트들
        my_prompt=MyPrompt(),
    )
    ```
-   `load_prompt` 함수의 `promptname` 인자의 `Literal` 타입 힌트에 새 프롬프트 이름을 추가합니다.
    ```python
    def load_prompt(
        promptname: Literal[
            # ... 기존 프롬프트 이름들
            "my_prompt",
        ],
        # ...
    ):
    ```

#### 3. `eval_prompt_list.txt`에 프롬프트 추가

-   프로젝트 루트의 `eval_prompt_list.txt` 파일을 열고, 새 프롬프트의 이름(`my_prompt`)을 새 줄에 추가합니다.

#### 4. (권장) 테스트 및 디버깅

-   프롬프트가 의도대로 작동하는지 확인하기 위해 디버깅을 권장합니다.
-   `.vscode/launch.json` 파일의 `"VA"` 설정에서 `args`를 다음과 같이 수정합니다.
    -   `"-p", "translation_fortunecookie"` 부분을 `"-p", "my_prompt"`로 변경합니다.
    -   필요시 `"-i", "..."` 부분에 새 프롬프트에 적합한 테스트 데이터 경로를 지정합니다.
-   VS Code의 `Run and Debug` 탭(Ctrl+Shift+D)으로 이동하여 "VA" 설정을 선택하고 F5 키를 눌러 디버거를 실행합니다.
-   `-o` 뒤에 명시한 output 디렉토리 안에서 `result.json` 를 찾아서 원하는대로 동작했는지 확인해보세요. 모든 judge와 매치에 활용된 프롬프트 정보가 담겨있습니다. 

문의: 손선일
* 내가 만든 프롬프트를 사용하고 싶어요
  * [`./varco_arena/prompts/`](./varco_arena_core/prompts/__init__.py) 에선 각종 프롬프트 클래스 및 `yaml` 파일 형태로 정의된 프롬프트를 로드합니다. 프리셋을 참조하여 작성하시면 됩니다.
* 테스트셋 별로 다른 평가 프롬프트를 사용하고 싶어요 (e.g. 작업에 따라 다른 프롬프트를 사용하고 싶어요)
  * 위 걸어드린 링크의 `load_prompt` 를 통해서 `promptname` + `task` 형태로 [`./varco_arena_core/manager.py:async_run`](./varco_arena_core/manager.py) 프롬프트가 로드되도록 해놓았습니다.


## Special Thanks to (contributors)
- 이민호 (@대화모델팀, NCSOFT) [github](https://github.com/minolee/)
  - query wrapper
  - rag prompt
- 오주민 (@생성모델팀, NCSOFT)
  - overall prototyping of the system in haste

## Citation
저희 작업물이 도움이 되었다면 저희도 도움을 받아볼 수 있을까요?😉
```
@misc{son2024varcoarenatournamentapproach,
      title={VARCO Arena: A Tournament Approach to Reference-Free Benchmarking Large Language Models},
      author={Seonil Son and Ju-Min Oh and Heegon Jin and Cheolhun Jang and Jeongbeom Jeong and Kuntae Kim},
      year={2024},
      eprint={2411.01281},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2411.01281},
}
```