컨텍스트 확장

컨텍스트 확장 (Context Extension)

모델이 처리할 수 있는 컨텍스트 길이를 늘리는 방법을 다루는 문서입니다. YARN 방식(rope_parameters)으로 Qwen 모델의 컨텍스트를 늘리는 예제와, OpenAI 호환 API로 확장된 컨텍스트를 서빙하는 방법을 보여줍니다.

출처: 문서

참고: 예전 vLLM 버전에서 쓰던 --rope-scaling 파라미터는 더 이상 지원되지 않습니다. 대신 rope_parameters를 쓰는 --hf-overrides 방식을 사용하세요.

본문

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

context_extension.py 스크립트는 YARN 방식(rope_parameters)으로 Qwen 모델의 컨텍스트 길이를 늘리고 간단한 채팅 예제를 실행하는 방법을 보여줍니다.

사용법 (Usage)

python examples/features/context_extension/context_extension_offline.py

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

클라이언트 예제 (Client Example)

서버를 시작한 뒤에는 OpenAI Python 클라이언트로 상호작용할 수 있습니다.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="token-abc123"  # Dummy API key, required by the client
)

response = client.chat.completions.create(
    model="Qwen/Qwen3-0.6B",
    messages=[
        {"role": "system", "content": "You are a helpful assistant"},
        {"role": "user", "content": "Hello"}
    ],
    max_tokens=128,
    temperature=0.8,
    top_p=0.95
)

print(response.choices[0].message.content)

주요 파라미터 (Key Parameters)

사용 가능한 파라미터는 선택한 rope_type에 따라 달라집니다. 지원되는 모든 RoPE 타입과 그별 파라미터에 대한 자세한 정보는 Hugging Face Transformers RoPE 문서를 참고하세요.

공통 파라미터는 다음과 같습니다.

  • rope_type: RoPE 구현의 타입 (예: "yarn", "linear", "dynamic")
  • factor: 컨텍스트 길이를 늘리는 배율
  • original_max_position_embeddings: 모델의 원래 최대 position embedding 값

다음 파라미터는 vLLM에 특화된 것입니다.

  • max_model_len: 확장 후의 새로운 최대 시퀀스 길이 (원래 길이 * factor). 서빙 시점에 KV 캐시 사전 할당과 요청 제한에 사용됩니다.

더 알아보기 (Learn more)