컨텍스트 확장

컨텍스트 확장 (Context Extension)

모델이 한 번에 처리할 수 있는 문맥 길이에는 한계가 있어요. 그런데 가끔은 이 한계를 넘어 더 긴 컨텍스트를 다뤄야 할 때가 있죠. vLLM의 컨텍스트 확장(Context Extension) 기능을 사용하면, 모델의 컨텍스트 길이를 늘려 더 긴 입력을 처리할 수 있습니다.

출처: vLLM 공식 문서 — context_extension

먼저 알아둘 것

📌 참고: 구버전 vLLM에서 사용하던 --rope-scaling 파라미터는 더 이상 지원되지 않아요. 대신 rope_parameters와 함께 --hf-overrides 방식을 사용하세요.

이 디렉토리(섹션)는 vLLM을 사용해 모델의 컨텍스트 길이를 확장하는 예시들을 담고 있어요.

오프라인 추론 예시 (Offline Inference Example)

context_extension.py 스크립트는 YARN 방식(rope_parameters)을 사용해 Qwen 모델의 컨텍스트 길이를 확장하고, 간단한 채팅 예시를 실행하는 방법을 보여줘요. 오프라인에서 Python 코드로 직접 추론할 때 참고하면 좋아요.

OpenAI 온라인 방식 (OpenAI Online Method)

vLLM의 OpenAI 호환 API를 사용해서도 확장된 컨텍스트 길이의 모델을 서빙할 수 있습니다.

사용법 (Usage)

다음 명령으로 vLLM 서버를 실행하면 YARN을 사용해 컨텍스트 길이를 확장할 수 있어요.

vllm serve Qwen/Qwen3-0.6B \
  --hf-overrides '{"rope_parameters": {"factor": 4.0, "original_max_position_embeddings": 32768, "rope_theta": 1000000, "rope_type": "yarn"}}' \
  --max-model-len 131072

이 예시에서는 factor: 4.0으로 컨텍스트를 4배 확장해서, 원래 32768이던 최대 위치 임베딩을 --max-model-len 131072로 사용할 수 있게 만들었어요.

핵심 파라미터 (Key Parameters)

사용 가능한 파라미터는 선택한 rope_type에 따라 달라집니다. 지원되는 모든 RoPE 유형과 그 구체적인 파라미터에 대한 자세한 내용은 Hugging Face Transformers RoPE 문서를 참고하세요.

공통적으로 쓰이는 파라미터는 이렇습니다.

파라미터	설명
`rope_type`	RoPE 구현의 종류 (예: `"yarn"`, `"linear"`, `"dynamic"`)
`factor`	컨텍스트 길이를 확장하는 배수
`original_max_position_embeddings`	모델의 원래 최대 위치 임베딩 값

vLLM에 특화된 파라미터로는 다음이 있어요.

파라미터	설명
`max_model_len`	확장 후의 새 최대 시퀀스 길이 (원본 × factor). KV 캐시 사전 할당과 서빙 시점의 요청 제한에 사용돼요.

즉, max_model_len은 순수한 모델 내부 설정이라기보다, KV 캐시를 어느 정도 미리 잡고 요청을 어디까지 받을지를 결정하는 서빙 관점의 값이에요. 컨텍스트를 확장할 때는 이 값까지 함께 맞춰줘야 실제로 긴 문맥을 서빙할 수 있답니다.

컨텍스트 확장