커스텀 인자

커스텀 인자 (Custom Arguments)

vLLM의 SamplingParams나 REST API 명세에는 없는 인자를 전달하고 싶을 때가 있어요. 그럴 때 쓰는 게 커스텀 인자(custom arguments) 예요. 커스텀 인자는 딕셔너리(dictionary) 형태로 전달되기 때문에, 커스텀 인자를 추가하거나 제거한다고 vLLM을 다시 컴파일할 필요가 없어요.

출처: vLLM 공식 문서 — custom_arguments

어떤 경우에 유용할까요? 예를 들어 커스텀 로짓 프로세서를 vLLM 소스 코드를 수정하지 않고 사용하고 싶다면, 커스텀 인자를 통해 그 값을 넘겨줄 수 있어요.

!!! note 커스텀 로짓 프로세서가 커스텀 인자를 위해 validate_params를 구현했는지 확인하세요. 그렇지 않으면 유효하지 않은 커스텀 인자 때문에 예상치 못한 동작이 일어날 수 있어요.

오프라인 커스텀 인자 (Offline Custom Arguments)

SamplingParams.extra_args에 dict로 넘긴 커스텀 인자는, SamplingParams에 접근할 수 있는 어떤 코드에서든 보여요.

SamplingParams(extra_args={"your_custom_arg_name": 67})

이렇게 하면 SamplingParams에 이미 포함되지 않은 인자도 요청의 일부로 LLM에 전달할 수 있어요.

온라인 커스텀 인자 (Online Custom Arguments)

OpenAI 호환 REST API와 Anthropic 호환 /v1/messages 엔드포인트는 vllm_xargs를 통해 커스텀 인자를 vLLM 서버로 전달할 수 있어요. 아래 예제는 vLLM REST API 요청에 커스텀 인자를 통합하는 모습이에요.

curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen2.5-1.5B-Instruct",
        ...
        "vllm_xargs": {"your_custom_arg": 67}
    }'

추가로, OpenAI SDK 사용자는 extra_body 인자를 통해 vllm_xargs에 접근할 수 있어요.

batch = await client.completions.create(
    model="Qwen/Qwen2.5-1.5B-Instruct",
    ...,
    extra_body={
        "vllm_xargs": {
            "your_custom_arg": 67
        }
    }
)

!!! note vllm_xargs는 내부적으로 SamplingParams.extra_args에 할당돼요. 그래서 SamplingParams.extra_args를 사용하는 코드는 온라인과 오프라인 두 경우 모두와 호환돼요.

더 알아보기 (Learn more)