리랭크 모델

리랭크 모델 (Rerank models)

이 페이지는 SGLang의 리랭크 모델 지원을 설명해요. 최적화된 서빙 프레임워크와 유연한 프로그래밍 인터페이스를 통합해 크로스-인코더 리랭킹 작업을 효율적으로 처리하고, 검색 결과 정렬의 정확성과 관련성을 높여요. SGLang의 설계는 리랭커 모델 배포 시 높은 처리량과 낮은 지연 시간을 보장해요.

출처: 문서

본문

SGLang은 최적화된 서빙 프레임워크를 유연한 프로그래밍 인터페이스와 통합해 리랭크 모델을 포괄적으로 지원해요. 이 구성은 크로스-인코더 리랭킹 작업의 효율적인 처리를 가능하게 해, 검색 결과 정렬의 정확성과 관련성을 개선해요. SGLang의 설계는 리랭커 모델 배포에서 높은 처리량과 낮은 지연 시간을 보장해, 대규모 검색 시스템에서 의미 기반 결과 정제에 이상적이에요.

Warning SGLang의 리랭크 모델은 두 가지 범주로 나뉘어요:

  • 크로스-인코더 리랭크 모델: --is-embedding(임베딩 러너)로 실행.
  • 디코더 전용 리랭크 모델: --is-embedding 없이 실행하며 next-token logprob 스코어링(예/아니오) 사용.
    • 텍스트 전용 (예: Qwen3-Reranker)
    • 멀티모달 (예: Qwen3-VL-Reranker): 이미지/비디오 콘텐츠도 지원

일부 모델은 --trust-remote-code가 필요할 수 있어요.

지원 리랭크 모델 (Supported rerank models)

Model Family (Rerank) Example HuggingFace Identifier Chat Template Description
BGE-Reranker (BgeRerankModel) BAAI/bge-reranker-v2-m3 N/A 현재 attention-backend triton과 torch\_native만 지원. BAAI의 고성능 크로스-인코더 리랭커 모델. 의미 관련성 기반 검색 결과 리랭킹에 적합.
Qwen3-Reranker (decoder-only yes/no) Qwen/Qwen3-Reranker-8B examples/chat\_template/qwen3\_reranker.jinja next-token logprob 스코어링으로 라벨(예/아니오)을 매기는 디코더 전용 리랭커. --is-embedding 없이 실행.
Qwen3-VL-Reranker (multimodal yes/no) Qwen/Qwen3-VL-Reranker-2B examples/chat\_template/qwen3\_vl\_reranker.jinja 텍스트, 이미지, 비디오를 지원하는 멀티모달 디코더 전용 리랭커. yes/no logprob 스코어링 사용. --is-embedding 없이 실행.

크로스-인코더 리랭크 (Cross-Encoder Rerank, 임베딩 러너)

실행 명령 (Launch Command)

python3 -m sglang.launch_server \
  --model-path BAAI/bge-reranker-v2-m3 \
  --host 0.0.0.0 \
  --disable-radix-cache \
  --chunked-prefill-size -1 \
  --attention-backend triton \
  --is-embedding \
  --port 30000

예시 클라이언트 요청 (Example Client Request)

import requests

url = "http://127.0.0.1:30000/v1/rerank"

payload = {
    "model": "BAAI/bge-reranker-v2-m3",
    "query": "what is panda?",
    "documents": [
        "hi",
        "The giant panda (Ailuropoda melanoleuca), sometimes called a panda bear or simply panda, is a bear species endemic to China."
    ],
    "top_n": 1,
    "return_documents": True
}

response = requests.post(url, json=payload)
response_json = response.json()

for item in response_json:
    if item.get("document"):
        print(f"Score: {item['score']:.2f} - Document: '{item['document']}'")
    else:
        print(f"Score: {item['score']:.2f} - Index: {item['index']}")

요청 파라미터:

  • query (필수): 문서를 랭킹할 쿼리 텍스트
  • documents (필수): 랭킹할 문서 목록
  • model (필수): 리랭킹에 사용할 모델
  • top_n (선택): 반환할 최대 문서 수. 기본적으로 모든 문서 반환. 지정 값이 전체 문서 수보다 크면 모든 문서 반환.
  • return_documents (선택): 응답에 문서 포함 여부. 기본값 True.

Qwen3-Reranker (decoder-only yes/no rerank)

실행 명령 (Launch Command)

python3 -m sglang.launch_server \
  --model-path Qwen/Qwen3-Reranker-0.6B \
  --trust-remote-code \
  --disable-radix-cache \
  --host 0.0.0.0 \
  --port 8001 \
  --chat-template examples/chat_template/qwen3_reranker.jinja

Note Qwen3-Reranker는 디코더 전용 logprob 스코어링(예/아니오)을 사용해요. --is-embedding으로 실행하지 마세요.

예시 클라이언트 요청 (선택적 instruct, top_n, return_documents 지원)

curl -X POST http://127.0.0.1:8001/v1/rerank \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3-Reranker-0.6B",
    "query": "法国首都是哪里？",
    "documents": [
      "法国的首都是巴黎。",
      "德国的首都是柏林。",
      "香蕉是黄色的水果。"
    ],
    "instruct": "Given a web search query, retrieve relevant passages that answer the query.",
    "top_n": 2,
    "return_documents": true
  }'

요청 파라미터:

  • query (필수): 문서를 랭킹할 쿼리 텍스트
  • documents (필수): 랭킹할 문서 목록
  • model (필수): 리랭킹에 사용할 모델
  • instruct (선택): 리랭커를 위한 지시 텍스트
  • top_n (선택): 반환할 최대 문서 수. 기본적으로 모든 문서 반환. 지정 값이 전체 문서 수보다 크면 모든 문서 반환.
  • return_documents (선택): 응답에 문서 포함 여부. 기본값 True.

응답 형식 (Response Format)

/v1/rerank는 객체 목록을 반환해요(점수 내림차순 정렬):

  • score: float, 높을수록 더 관련성이 높음
  • document: 원본 문서 문자열 (return_documents가 true일 때만 포함)
  • index: 입력 documents의 원본 인덱스
  • meta_info: 선택적 디버그/사용 정보 (일부 모델에 존재할 수 있음)

반환 결과 수는 top_n 파라미터로 제어돼요. top_n이 지정되지 않거나 전체 문서 수보다 크면 모든 문서가 반환돼요.

예시 (return_documents: true):

[
  {"score": 0.99, "document": "法国的首都是巴黎。", "index": 0},
  {"score": 0.01, "document": "德国的首都是柏林。", "index": 1},
  {"score": 0.00, "document": "香蕉是黄色的水果。", "index": 2}
]

예시 (return_documents: false):

[
  {"score": 0.99, "index": 0},
  {"score": 0.01, "index": 1},
  {"score": 0.00, "index": 2}
]

예시 (top_n: 2):

[
  {"score": 0.99, "document": "法国的首都是巴黎。", "index": 0},
  {"score": 0.01, "document": "德国的首都是柏林。", "index": 1}
]

일반적인 함정 (Common Pitfalls)

  • --chat-template이 필수예요. --chat-template examples/chat_template/qwen3_reranker.jinja가 없으면 서버가 모델을 디코더 전용 리랭커로 인식하지 못하고 400 오류를 반환해요: "This model does not appear to be an embedding model by default. Please add --is-embedding...". 해결책은 --is-embedding이 아닌 chat template 플래그를 추가하는 거예요.
  • --is-embedding으로 Qwen3-Reranker를 실행하면 /v1/rerank가 yes/no logprob 점수를 계산할 수 없어요. --is-embedding 없이 다시 실행하세요.
  • "score should be a valid number" 같은 검증 오류가 보이고 백엔드가 목록을 반환했다면, rerank 응답에서 embedding[0]을 score로 강제하는 버전으로 업그레이드하세요.

Qwen3-VL-Reranker (멀티모달 디코더 전용 리랭크)

Qwen3-VL-Reranker는 Qwen3-Reranker를 확장해 멀티모달 콘텐츠를 지원하며, 텍스트, 이미지, 비디오를 포함한 문서를 리랭킹할 수 있어요.

실행 명령 (Launch Command)

python3 -m sglang.launch_server \
  --model-path Qwen/Qwen3-VL-Reranker-2B \
  --trust-remote-code \
  --disable-radix-cache \
  --host 0.0.0.0 \
  --port 30000 \
  --chat-template examples/chat_template/qwen3_vl_reranker.jinja

Note Qwen3-VL-Reranker는 Qwen3-Reranker처럼 디코더 전용 logprob 스코어링(예/아니오)을 사용해요. --is-embedding으로 실행하지 마세요.

텍스트 전용 리랭킹 (백워드 호환)

import requests

url = "http://127.0.0.1:30000/v1/rerank"

payload = {
    "model": "Qwen3-VL-Reranker-2B",
    "query": "What is machine learning?",
    "documents": [
        "Machine learning is a branch of artificial intelligence that enables computers to learn from data.",
        "The weather in Paris is usually mild with occasional rain.",
        "Deep learning is a subset of machine learning using neural networks with many layers.",
    ],
    "instruct": "Retrieve passages that answer the question.",
    "return_documents": True
}

response = requests.post(url, json=payload)
results = response.json()

for item in results:
    print(f"Score: {item['score']:.4f} - {item['document'][:60]}...")

이미지 리랭킹 (텍스트 쿼리, 이미지/혼합 문서)

import requests

url = "http://127.0.0.1:30000/v1/rerank"

payload = {
    "query": "A woman playing with her dog on a beach at sunset.",
    "documents": [
        # Document 1: Text description
        "A woman shares a joyful moment with her golden retriever on a sun-drenched beach at sunset.",
        # Document 2: Image URL
        [
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://example.com/beach_dog.jpeg"
                }
            }
        ],
        # Document 3: Text + Image (mixed)
        [
            {"type": "text", "text": "A joyful scene at the beach:"},
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://example.com/beach_dog.jpeg"
                }
            }
        ]
    ],
    "instruct": "Retrieve images or text relevant to the user's query.",
    "return_documents": False
}

response = requests.post(url, json=payload)
results = response.json()

for item in results:
    print(f"Index: {item['index']}, Score: {item['score']:.4f}")

멀티모달 쿼리 리랭킹 (이미지 포함 쿼리)

import requests

url = "http://127.0.0.1:30000/v1/rerank"

payload = {
    # Query with text and image
    "query": [
        {"type": "text", "text": "Find similar images to this:"},
        {
            "type": "image_url",
            "image_url": {
                "url": "https://example.com/reference_image.jpeg"
            }
        }
    ],
    "documents": [
        "A cat sleeping on a couch.",
        "A woman and her dog enjoying the sunset at the beach.",
        "A busy city street with cars and pedestrians.",
        [
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://example.com/similar_image.jpeg"
                }
            }
        ]
    ],
    "instruct": "Find images or descriptions similar to the query image."
}

response = requests.post(url, json=payload)
results = response.json()

for item in results:
    print(f"Index: {item['index']}, Score: {item['score']:.4f}")

요청 파라미터 (멀티모달, Request Parameters)

  • query (필수): 문자열(텍스트 전용) 또는 콘텐츠 파트 목록일 수 있음:
    • {"type": "text", "text": "..."} — 텍스트용
    • {"type": "image_url", "image_url": {"url": "..."}} — 이미지용
    • {"type": "video_url", "video_url": {"url": "..."}} — 비디오용
  • documents (필수): 각 문서가 문자열 또는 콘텐츠 파트 목록(쿼리와 동일한 형식)인 목록
  • instruct (선택): 리랭커를 위한 지시 텍스트
  • top_n (선택): 반환할 최대 문서 수
  • return_documents (선택): 응답에 문서 포함 여부 (기본값: false)

일반적인 함정 (Common Pitfalls)

  • Qwen3-VL-Reranker에는 항상 --chat-template examples/chat_template/qwen3_vl_reranker.jinja를 사용해요.
  • --is-embedding으로 실행하지 마세요.
  • 최상의 결과를 위해 --disable-radix-cache를 사용해 멀티모달 콘텐츠의 캐싱 문제를 피하세요.
  • Note: 현재 Qwen3-VL-Reranker-2B만 테스트되어 지원돼요. 8B 모델은 동작이 다를 수 있으며 이 템플릿과 함께 동작한다고 보장되지 않아요.

더 알아보기