임베딩 사용법

임베딩 사용법 (Embedding Usages)

임베딩 모델을 vLLM에서 쓰는 방법을 하나씩 짚어볼게요. vLLM은 문장 전체를 하나의 벡터로 만드는 시퀀스 임베딩(sequence embedding)을 지원해서, 검색·유사도 계산·RAG 같은 작업에 바로 활용할 수 있어요. 이 페이지에서는 오프라인 API부터 온라인 서빙까지, 임베딩 모델을 실제로 굴리는 전 과정을 살펴봐요.

출처: vLLM 공식 문서 — models/pooling_models/embed

한눈에 보는 요약 (Summary)

임베딩 사용 방식을 정리하면 이렇게 돼요.

  • 모델 사용 방식: (시퀀스) 임베딩
  • 풀링 태스크 (Pooling Task): embed
  • 오프라인 API:
    • LLM.embed(...)
    • LLM.encode(..., pooling_task="embed")
    • LLM.score(...)
  • 온라인 API:

많은 임베딩 모델이 시퀀스 임베딩과 토큰 임베딩을 동시에 지원해요. 토큰 임베딩에 대한 자세한 내용은 이 페이지를 참고하세요.

지원되는 모델 (Supported Models)

텍스트 전용 모델 (Text-only Models)

텍스트만 처리하는 임베딩 모델을 지원해요. 이때 BAAI/bge-m3 모델은 sparse 임베딩과 colbert 임베딩용 추가 가중치를 갖고 있어서, 자세한 내용은 이 페이지를 확인해야 해요.

멀티모달 모델 (Multimodal Models)

이미지처럼 여러 종류의 입력을 함께 처리하는 임베딩 모델도 지원해요. C 표시가 붙은 모델은 --convert embed 옵션으로 자동으로 임베딩 모델로 변환돼요. 변환된 모델의 기능 지원 범위는 원래 모델과 동일해요.

오프라인 추론 (Offline Inference)

풀링 파라미터 (Pooling Parameters)

오프라인에서 쓰는 풀링 파라미터들이 지원돼요.

LLM.encode

임베딩 모델에서 LLM.encode를 쓸 때는 pooling_task="embed"로 설정해주면 돼요.

LLM.score

임베딩 태스크를 지원하는 모든 모델은 score API도 지원해요. 두 입력 프롬프트의 임베딩 사이의 코사인 유사도(cosine similarity)를 계산해서 유사도 점수를 내줘요.

온라인 서빙 (Online Serving)

OpenAI 호환 Embeddings API

vLLM의 Embeddings API는 OpenAI의 Embeddings API와 호환되기 때문에, 공식 OpenAI Python 클라이언트를 그대로 사용할 수 있어요.

예제 (Examples)

모델에 챗 템플릿이 있다면 inputs 대신 messages 리스트를 넘길 수도 있어요. 이 메시지 스키마는 Chat API와 동일해요.

멀티모달 입력 (Multi-modal inputs)

서버에 커스텀 챗 템플릿을 정의하고 요청에 messages 리스트를 넘기면, 임베딩 모델에 이미지 같은 멀티모달 입력을 전달할 수 있어요. 예를 들어 VLM2Vec 모델을 서빙할 때는 이렇게 해요.

vllm serve TIGER-Lab/VLM2Vec-Full --runner pooling \
  --trust-remote-code \
  ...

중요 (확인 필요): MrLight/dse-qwen2-2b-mrl-v1 모델은 텍스트 쿼리 임베딩을 위한 최소 크기의 placeholder 이미지가 필요해요. 전체 코드 예시를 꼭 확인하세요.

Cohere Embed API

텍스트와 이미지 혼합 입력 (Mixed text and image inputs)

멀티모달 모델에서는 base64 데이터 URI를 넘겨 이미지를 임베딩할 수 있어요. inputs 필드는 텍스트와 이미지 내용이 섞인 객체 리스트를 받아요.

입력 타입과 프롬프트 접두사 (Input type and prompt prefixes)

예를 들어 Snowflake/snowflake-arctic-embed-xs는 "query" 입력 타입을 정의해요. input_type: "query"로 설정하면 "Represent this sentence for searching relevant passages: " 같은 접두사가 자동으로 붙어요.

지원 기능 (Supported Features)

Matryoshka Embeddings

dimensions 파라미터를 지원하는 Matryoshka 임베딩 방식도 쓸 수 있어요. 다만 BAAI/bge-m3 모델처럼 dimensions를 지원하지 않는 모델에서 이 파라미터를 설정하면 오류가 발생할 수 있어요.

더 알아보기 (Learn more)