프롬프트 임베딩 입력

프롬프트 임베딩 입력 (Prompt Embedding Inputs)

이 페이지는 vLLM에 프롬프트 임베딩 입력을 전달하는 방법을 알려줘요. 기존 방식은 텍스트→토큰 id(토크나이저 경유)→프롬프트 임베딩 순으로 진행되는데, vLLM은 학습된 임베딩 행렬을 조회하는 대신 이미 임베딩된 프롬프트 텐서를 직접 입력으로 받을 수 있습니다.

출처: 문서

본문

프롬프트 임베딩이란? (What are prompt embeddings?)

대규모 언어 모델의 전통적인 텍스트 데이터 흐름은 텍스트에서 토큰 id(토크나이저 경유), 그다음 토큰 id에서 프롬프트 임베딩으로 진행됩니다. 전통적인 디코더 전용 모델(예: meta-llama/Llama-3.1-8B-Instruct)에서 토큰 id를 프롬프트 임베딩으로 변환하는 단계는 학습된 임베딩 행렬에서의 look-up을 통해 일어나지만, 모델은 반드시 토큰 어휘에 해당하는 임베딩만 처리할 수 있는 것은 아닙니다.

오프라인 추론 (Offline Inference)

멀티모달 데이터를 입력하려면 vllm.inputs.EmbedsPrompt 의 스키마를 따르세요.

prompt_embeds: 프롬프트/토큰 임베딩의 시퀀스를 나타내는 torch 텐서입니다. 형태는 (sequence_length, hidden_size) 입니다. sequence length는 토큰 임베딩의 수이고 hidden_size는 모델의 hidden size(임베딩 크기)입니다.

Hugging Face Transformers 입력

Hugging Face Transformers 모델의 프롬프트 임베딩을 다음 예시처럼 프롬프트 임베딩 딕셔너리의 'prompt_embeds' 필드에 전달할 수 있어요.

examples/features/prompt_embed/prompt_embed_offline.py

온라인 서빙 (Online Serving)

OpenAI 호환 서버는 Completions API 와 Chat Completions API 를 통해 프롬프트 임베딩 입력을 받습니다. 둘 다 vllm serve 의 --enable-prompt-embeds 플래그로 활성화됩니다.

Completions API

프롬프트 임베딩 입력은 JSON 요청 본문의 'prompt_embeds' 키로 추가됩니다.

단일 요청에 'prompt_embeds' 와 'prompt' 입력이 섞여 제공되면, 프롬프트 임베딩이 항상 먼저 반환됩니다.

프롬프트 임베딩은 base64 인코딩된 torch 텐서로 전달됩니다.

Completions 엔드포인트는 prompt_embeds 에 채팅 템플릿을 적용하지 않습니다. 모델이 어떤 채팅 템플릿을 가정한다면, 호출자가 이미 템플릿이 적용된 전체 프롬프트에 대한 임베딩을 생성할 책임이 있어요. 채팅 템플릿을 적용한 다음 결과 토큰 ID를 임베딩하세요. 모델이 보통 필요로 하는 것(시스템 프롬프트, 역할 마커, 생성 프롬프트 등)은 모두 이미 임베딩된 토큰에 포함되어 있어야 합니다.

Chat Completions API

프롬프트 임베딩은 텍스트와 섞어서 채팅 메시지의 콘텐츠 파트로 포함할 수 있습니다.

{
  "messages": [
    {
      "role": "system",
      "content": [
        {"type": "text", "text": "You are a helpful assistant."},
        {"type": "prompt_embeds", "data": "<base64_encoded_tensor>"}
      ]
    },
    {
      "role": "user",
      "content": [
        {"type": "prompt_embeds", "data": "<base64_encoded_tensor>"},
        {"type": "text", "text": "Summarize the above."}
      ]
    }
  ]
}

각 prompt_embeds 콘텐츠 파트는 (num_tokens, hidden_size) 형태의 base64 인코딩 torch.Tensor 를 담은 data 필드를 포함합니다. 여러 prompt_embeds 파트는 어떤 메시지에도, 텍스트 파트 기준 어떤 위치에도 나타날 수 있습니다. 서버는 채팅 템플릿 렌더링 중 각 파트를 올바른 수의 플레이스홀더 토큰으로 확장한 다음, 사전 계산된 임베딩을 해당 위치의 모델 입력에 스플라이스합니다.

Completions API와 달리, prompt_embeds 콘텐츠 파트는 템플릿이 적용된 대화가 아니라 오직 콘텐츠만 인코딩해야 합니다. 서버는 요청 시점에 임베딩된 콘텐츠 주위에 채팅 템플릿을 감싸는데, 이는 일반 텍스트 content 문자열에 하는 것과 같습니다. 여기에 전체 템플릿 대화를 임베딩하면 템플릿이 이중 적용되어 모델에 잘못된 입력을 만들어냅니다.

경고: 잘못된 형태의 임베딩을 전달하면 vLLM 엔진이 충돌할 수 있습니다. 이 플래그는 신뢰할 수 있는 사용자에게만 활성화하세요!

OpenAI 클라이언트를 통한 Transformers 입력

먼저 OpenAI 호환 서버를 시작합니다.

vllm serve meta-llama/Llama-3.2-1B-Instruct --runner generate \
  --max-model-len 4096 --enable-prompt-embeds

그런 다음 OpenAI 클라이언트를 다음과 같이 사용할 수 있습니다.

examples/features/prompt_embed/prompt_embed_inference_with_openai_client.py

프롬프트 임베딩 입력