esh-pfi-infrastructure/stacks/vllm/compose.yaml

# vLLM — Qwen3 Embedding + Reranker + Skywork Reward-V2 classifier.
#
# Originally created to replace the unmaintained Infinity stack (embed +
# rerank); generalized 2026-05-13 to host any vLLM-served model on fv-ml1,
# starting with the Skywork-Reward-V2-Llama-3.1-8B reward classifier
# (AWQ-quantized locally, served from /tank/aimodels/llm/).
#
# vLLM runs one model per process, so this stack brings up three containers
# sharing a single GPU:
#
#   vllm-embed   — Qwen3-Embedding served as an OpenAI /v1/embeddings server
#   vllm-rerank  — Qwen3-Reranker served as a /rerank + /score server
#   vllm-reward  — Skywork-Reward-V2-Llama-3.1-8B-AWQ served as a /classify scorer
#
# The reranker is a causal-LM checkpoint; --hf-overrides re-maps it to
# Qwen3ForSequenceClassification so vLLM's reranking endpoints work and the
# model only emits two class logits (no/yes) instead of the full 151k vocab.
#
# All tunables live in .env — edit that, not this file.
#
# Pre-download models to avoid first-run delay:
#   scripts/elway fv-ml1 --playbook playbooks/pull-hf-repo.yaml \
#       --var hf_repo=Qwen/Qwen3-Embedding-0.6B
#   scripts/elway fv-ml1 --playbook playbooks/pull-hf-repo.yaml \
#       --var hf_repo=Qwen/Qwen3-Reranker-0.6B
#
# Skywork-Reward-V2-Llama-3.1-8B-AWQ is a locally-quantized model — lives at
# /tank/aimodels/llm/Skywork-Reward-V2-Llama-3.1-8B-AWQ on fv-ml1 and is
# bind-mounted into the reward service at /local-models. Not from HF Hub.

services:
  vllm-embed:
    image: vllm/vllm-openai:${VLLM_VERSION}
    container_name: vllm-embed
    restart: unless-stopped
    ipc: host
    ports:
      - "${EMBED_PORT}:8000"
    volumes:
      - /tank/aimodels/huggingface:/hfcache
    environment:
      - HF_HOME=/hfcache
      - HF_HUB_CACHE=/hfcache/hub
      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN:-}
      - VLLM_API_KEY=${API_KEY:-}
    command:
      - ${EMBED_MODEL}
      - --served-model-name
      - ${EMBED_MODEL}
      - --runner
      - pooling
      - --host
      - 0.0.0.0
      - --port
      - "8000"
      - --gpu-memory-utilization
      - ${EMBED_GPU_MEM_UTIL}
      - --max-model-len
      - ${EMBED_MAX_MODEL_LEN}
      - --dtype
      - auto
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids:
                - "${GPU_ID}"
              capabilities:
                - gpu
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 180s
    networks:
      - tnet
    labels:
      - homepage.group=AI - Eval & Retrieval
      - homepage.name=vLLM Embed (Qwen3)
      - homepage.icon=mdi-vector-arrange-below
      - homepage.description=Qwen3 Embedding via vLLM (fv-ml1)
      - homepage.href=http://10.251.50.54:${EMBED_PORT}/docs

  # THE fleet reranker. Backs the LiteLLM `reranker` alias, which is what every
  # consumer should name — never the model, never a bake-off arm name.
  #
  # It won the Brokkr R43 bake-off (docs/pfi/reranker-selection-ledger.md) and
  # replaced Qwen3-Reranker-0.6B, which was measured HARMING 80/90 fleet queries
  # (no-reranker beat it 89/90 vs 56/90). The R42 v13 acceptance gate went
  # 56/90 -> 90/90 on the cutover, its first-ever PASS.
  #
  # Promoted from a throwaway `docker run` to this service 2026-08-20 (the
  # ledger's own open follow-up). It carried the bake-off's arm name from the
  # start and KEEPS it: the ledger, persistent-memory and the R43 record all say
  # `vllm-rerank-a3`, and renaming for tidiness would orphan every one of those
  # references. The name carries its provenance.
  #
  # Retired alongside this promotion: `vllm-rerank` (Qwen3-Reranker-0.6B, :8002 —
  # the rollback path, kept warm 13 days) and `vllm-rerank-a4`
  # (gte-reranker-modernbert, :8014 — a documented throughput fallback that was
  # never given a gateway alias, so it was unreachable the whole time).
  vllm-rerank-a3:
    image: vllm/vllm-openai:${VLLM_VERSION}
    container_name: vllm-rerank-a3
    restart: unless-stopped
    ipc: host
    ports:
      - "${RERANK_PORT}:8000"
    volumes:
      - /tank/aimodels/huggingface:/hfcache
    environment:
      - HF_HOME=/hfcache
      - HF_HUB_CACHE=/hfcache/hub
      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN:-}
      - VLLM_API_KEY=${API_KEY:-}
    command:
      - ${RERANK_MODEL}
      - --served-model-name
      - ${RERANK_MODEL}
      - --runner
      - pooling
      # No --hf-overrides here. The Qwen reranker needed one to be coerced into a
      # sequence-classification head; bge-reranker-v2-m3 is natively a
      # cross-encoder and vLLM resolves it directly.
      - --host
      - 0.0.0.0
      - --port
      - "8000"
      - --gpu-memory-utilization
      - ${RERANK_GPU_MEM_UTIL}
      - --max-model-len
      - ${RERANK_MAX_MODEL_LEN}
      - --dtype
      - auto
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids:
                - "${GPU_ID}"
              capabilities:
                - gpu
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 180s
    networks:
      - tnet
    labels:
      - homepage.group=AI - Eval & Retrieval
      - homepage.name=vLLM Rerank (bge-v2-m3)
      - homepage.icon=mdi-sort-variant
      - homepage.description=BAAI bge-reranker-v2-m3 — the fleet reranker, backs the `reranker` alias (fv-ml1)
      - homepage.href=http://10.251.50.54:${RERANK_PORT}/docs

  vllm-reward:
    image: vllm/vllm-openai:${VLLM_VERSION}
    container_name: vllm-reward
    restart: unless-stopped
    ipc: host
    ports:
      - "${REWARD_PORT}:8000"
    volumes:
      # AWQ output lives in the legacy llama-swap models tree, not the HF cache
      # — bind-mount the LLM models dir read-only so the reward service can
      # load it as a local-path HF-format model.
      - /tank/aimodels/llm:/local-models:ro
    environment:
      - VLLM_API_KEY=${API_KEY:-}
    command:
      - /local-models/Skywork-Reward-V2-Llama-3.1-8B-AWQ
      - --served-model-name
      - Skywork/Skywork-Reward-V2-Llama-3.1-8B-AWQ
      # vLLM 0.19.1 deprecated --task in favor of --runner. The model's
      # config.json declares `LlamaForSequenceClassification` so the
      # pooling runner uses it as a classifier (single-label reward score)
      # without needing an explicit task flag.
      - --runner
      - pooling
      - --host
      - 0.0.0.0
      - --port
      - "8000"
      - --gpu-memory-utilization
      - ${REWARD_GPU_MEM_UTIL}
      - --max-model-len
      - ${REWARD_MAX_MODEL_LEN}
      - --dtype
      - auto
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids:
                - "${GPU_ID}"
              capabilities:
                - gpu
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 240s
    networks:
      - tnet
    labels:
      - homepage.group=AI - Eval & Retrieval
      - homepage.name=vLLM Reward (Skywork)
      - homepage.icon=mdi-scale-balance
      - homepage.description=Skywork-Reward-V2 8B classifier via vLLM (fv-ml1)
      - homepage.href=http://10.251.50.54:${REWARD_PORT}/docs

  # vllm-granite (ibm-granite/granite-4.1-8b-fp8, :8004) — RETIRED 2026-08-12,
  # service block removed 2026-08-20. It was the fleet summarizer until the
  # `summarizer` and `classifier` aliases were repointed at the gen seat; the
  # container was stopped then and sat Exited for 8 days while this block still
  # claimed it as production.
  #
  # ⚠️ Retiring the SEAT did not retire its CONSUMERS, and nobody checked. The
  # `granite-4.1-8b` gateway alias was deleted at the same time, but `nevermore`
  # was still pinned to that alias by name — so its LLM summarization pass failed
  # 67 consecutive times over 8 days, 0 tokens, entirely silently, because a
  # failed gateway call still returns 200-shaped spend-log rows and nothing
  # alerts on status=failure. Found 2026-08-20 only because someone asked an
  # unrelated question about reranker VRAM.
  #
  # The rule this earns: RETIRING A MODEL IS A TWO-SIDED OPERATION. Grep every
  # consumer's config for the alias BEFORE deleting it, and prefer that consumers
  # pin stable ALIASES (`summarizer`) over model names (`granite-4.1-8b`) so the
  # gateway can repoint them without anyone editing a downstream .env.

  vllm-coder:
    image: vllm/vllm-openai:${VLLM_VERSION}
    container_name: vllm-coder
    restart: unless-stopped
    ipc: host
    ports:
      - "${CODER_PORT}:8000"
    volumes:
      - /tank/aimodels/huggingface:/hfcache
    environment:
      - HF_HOME=/hfcache
      - HF_HUB_CACHE=/hfcache/hub
      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN:-}
      - VLLM_API_KEY=${API_KEY:-}
    command:
      # Qwen2.5-Coder-1.5B (BASE) — FIM code-completion seat for Zed edit-predictions
      # (deep-research pick 2026-07-27). Native fill-in-the-middle: <|fim_prefix|> /
      # <|fim_suffix|> / <|fim_middle|> (IDs 151659/151660/151661); Zed sends the
      # FIM-formatted prompt to /v1/completions and vLLM passes it through (the FIM
      # special tokens live in the tokenizer). BASE not -Instruct (FIM is a
      # pretraining objective; base completions are cleaner). Apache-2.0. Runner-up =
      # Qwen2.5-Coder-3B (higher HumanEval-FIM but non-commercial Qwen-Research license).
      - ${CODER_MODEL}
      - --served-model-name
      - ${CODER_SERVED_NAME}
      - --host
      - 0.0.0.0
      - --port
      - "8000"
      - --gpu-memory-utilization
      - ${CODER_GPU_MEM_UTIL}
      - --max-model-len
      - ${CODER_MAX_MODEL_LEN}
      - --max-num-seqs
      - ${CODER_MAX_NUM_SEQS}
      - --dtype
      - auto
      - --kv-cache-dtype
      - ${CODER_KV_CACHE_DTYPE}
      - --enable-prefix-caching
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids:
                - "${CODER_GPU_ID}"
              capabilities:
                - gpu
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 300s
    networks:
      - tnet
    labels:
      - homepage.group=AI - Inference
      - homepage.name=vLLM Qwen2.5-Coder 1.5B (FIM)
      - homepage.icon=mdi-code-braces
      - homepage.description=Qwen2.5-Coder-1.5B FIM code-completion (fv-ml1, Zed edit-predictions)
      - homepage.href=http://10.251.50.54:${CODER_PORT}/docs

  # vllm-lfm25 (LiquidAI/LFM2.5-2.6B, :8021) — RETIRED PERMANENTLY 2026-08-20 by
  # operator directive. It was an EVAL-ONLY bake-off seat against granite-4.1-8b
  # (brokkr R-target, 2026-08-10) that never received the operator ruling it was
  # pending. Its comparator is gone (granite retired from the roster 2026-08-15),
  # it was deliberately never wired into any default/fallback routing chain, and
  # LiteLLM spend logs showed 0 calls in the 4-day window ending 2026-08-21.
  # Freed 8,772 MiB on fv-ml1 GPU1. The `lfm2.5-2.6b` gateway alias was removed
  # in the same pass so the name 404s cleanly rather than erroring against a dead
  # backend. Weights remain in the shared HF cache; nothing was deleted from disk.

networks:
  tnet:
    name: traefik-net
    external: true