Merge pull request #13 from saichandrapandraju/vllm-judge

RHOAIENG-23163: Enable LLM-as-a-judge detections from vLLM hosted models

Author: ruivieira

detectors/Dockerfile.judge

@@ -0,0 +1,30 @@
+FROM registry.access.redhat.com/ubi9/ubi-minimal as base
+RUN microdnf update -y && \
+    microdnf install -y --nodocs \
+        python-pip python-devel && \
+    pip install --upgrade --no-cache-dir pip wheel && \
+    microdnf clean all
+
+FROM base as builder
+
+COPY ./common/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY ./llm_judge/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+FROM builder
+
+WORKDIR /app
+ARG CACHEBUST=1
+RUN echo "$CACHEBUST"
+COPY ./common /app/detectors/common
+COPY ./llm_judge/app.py /app/detectors/llm_judge/app.py
+COPY ./llm_judge/detector.py /app/detectors/llm_judge/detector.py
+COPY ./llm_judge/scheme.py /app/detectors/llm_judge/scheme.py
+RUN touch /app/detectors/llm_judge/__init__.py
+
+EXPOSE 8000
+CMD ["uvicorn", "detectors.llm_judge.app:app", "--workers", "4", "--host", "0.0.0.0", "--port", "8000", "--log-config", "/app/detectors/common/log_conf.yaml"]
+
+# gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

detectors/__init__.py

@@ -0,0 +1,8 @@
+# LLM Judge Detector
+
+The LLM Judge detector integrates the [vLLM Judge](https://github.com/saichandrapandraju/vllm_judge) into the Guardrails Detector ecosystem.
+
+```
+oc apply -f deploy/servingruntime.yaml
+oc apply -f deploy/isvc.yaml
+```

detectors/llm_judge/README.md

@@ -0,0 +1,70 @@
+from contextlib import asynccontextmanager
+from typing import Annotated, Dict
+
+from fastapi import Header
+from prometheus_fastapi_instrumentator import Instrumentator
+
+from detectors.common.app import DetectorBaseAPI as FastAPI
+from detectors.llm_judge.detector import LLMJudgeDetector
+from detectors.llm_judge.scheme import (
+    ContentAnalysisHttpRequest,
+    ContentsAnalysisResponse,
+    MetricsListResponse,
+    Error,
+)
+
+detector_objects: Dict[str, LLMJudgeDetector] = {}
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan management."""
+    try:
+        detector_objects["detector"] = LLMJudgeDetector()
+        yield
+    finally:
+        # Clean up resources
+        if "detector" in detector_objects:
+            await detector_objects["detector"].close()
+        detector_objects.clear()
+
+
+app = FastAPI(lifespan=lifespan, dependencies=[])
+Instrumentator().instrument(app).expose(app)
+
+
+@app.post(
+    "/api/v1/text/contents",
+    response_model=ContentsAnalysisResponse,
+    description="""LLM-as-Judge detector that evaluates content using various metrics like safety, toxicity, accuracy, helpfulness, etc. \
+                    The metric parameter allows you to specify which evaluation criteria to use. \
+                    Supports all built-in vllm_judge metrics including safety, accuracy, helpfulness, clarity, and many more.""",
+    responses={
+        404: {"model": Error, "description": "Resource Not Found"},
+        422: {"model": Error, "description": "Validation Error"},
+    },
+)
+async def detector_unary_handler(
+    request: ContentAnalysisHttpRequest,
+    detector_id: Annotated[str, Header(example="llm_judge_safety")],
+):
+    """Analyze content using LLM-as-Judge evaluation."""
+    return ContentsAnalysisResponse(root=await detector_objects["detector"].run(request))
+
+
+@app.get(
+    "/api/v1/metrics",
+    response_model=MetricsListResponse,
+    description="List all available metrics for LLM Judge evaluation",
+    responses={
+        404: {"model": Error, "description": "Resource Not Found"},
+    },
+)
+async def list_metrics():
+    """List all available evaluation metrics."""
+    detector = detector_objects.get("detector")
+    if not detector:
+        return {"metrics": [], "total": 0}
+    
+    metrics = detector.list_available_metrics()
+    return MetricsListResponse(metrics=metrics, total=len(metrics))

detectors/llm_judge/__init__.py

@@ -0,0 +1,23 @@
+apiVersion: serving.kserve.io/v1beta1
+kind: InferenceService
+metadata:
+  name: guardrails-detector-llm-judge
+  namespace: model-namespace
+  labels:
+    opendatahub.io/dashboard: 'true'
+  annotations:
+    openshift.io/display-name: guardrails-detector-llm-judge
+    security.opendatahub.io/enable-auth: 'true'
+    serving.knative.openshift.io/enablePassthrough: 'true'
+    sidecar.istio.io/inject: 'true'
+    sidecar.istio.io/rewriteAppHTTPProbers: 'true'
+    serving.kserve.io/deploymentMode: RawDeployment
+spec:
+  predictor:
+    maxReplicas: 1
+    minReplicas: 1
+    model:
+      modelFormat:
+        name: guardrails-detector-llm-judge
+      name: ''
+      runtime: guardrails-detector-runtime-judge

detectors/llm_judge/app.py

@@ -0,0 +1,45 @@
+apiVersion: serving.kserve.io/v1alpha1
+kind: ServingRuntime
+metadata:
+  name: guardrails-detector-runtime-judge
+  namespace: model-namespace
+  annotations:
+    openshift.io/display-name: Guardrails LLM Judge Detector ServingRuntime for KServe
+  labels:
+    opendatahub.io/dashboard: 'true'
+spec:
+  annotations:
+    prometheus.io/port: '8080'
+    prometheus.io/path: '/metrics'
+  multiModel: false
+  supportedModelFormats:
+    - autoSelect: true
+      name: guardrails-detector-llm-judge
+  containers:
+    - name: kserve-container
+      image: quay.io/spandraj/guardrails-detector-judge:latest
+      command:
+        - uvicorn
+        - detectors.llm_judge.app:app
+      args:
+        - "--workers"
+        - "1"
+        - "--host"
+        - "0.0.0.0"
+        - "--port"
+        - "8000"
+        - "--log-config"
+        - "/app/detectors/common/log_conf.yaml"
+      env:
+        - name: VLLM_BASE_URL
+          value: "http://qwen2-predictor:8080" # <-- Change this to your vLLM URL
+      ports:
+        - containerPort: 8000
+          protocol: TCP
+      resources:
+        requests:
+          memory: "5Gi"
+          cpu: "1"
+        limits:
+          memory: "10Gi"
+          cpu: "2"

detectors/llm_judge/deploy/isvc.yaml

@@ -0,0 +1,123 @@
+import os
+from typing import List, Dict, Any
+
+from vllm_judge import Judge, EvaluationResult, BUILTIN_METRICS
+from vllm_judge.exceptions import MetricNotFoundError
+from detectors.common.app import logger
+from detectors.llm_judge.scheme import (
+    ContentAnalysisHttpRequest,
+    ContentAnalysisResponse,
+    ContentsAnalysisResponse,
+)
+
+
+class LLMJudgeDetector:
+    """LLM-as-Judge detector for evaluating content using vllm_judge."""
+    
+    def __init__(self) -> None:
+        """Initialize the LLM Judge Detector."""
+        self.judge = None
+        self.available_metrics = set(BUILTIN_METRICS.keys())
+        
+        # Get configuration from environment
+        self.vllm_base_url = os.environ.get("VLLM_BASE_URL")
+        
+        if not self.vllm_base_url:
+            raise ValueError("VLLM_BASE_URL environment variable is required")
+        
+        logger.info(f"Initializing LLM Judge with URL: {self.vllm_base_url}")
+        
+        self._initialize_judge()
+    
+    def _initialize_judge(self) -> None:
+        """Initialize the vLLM Judge."""
+        try:
+            self.judge = Judge.from_url(base_url=self.vllm_base_url)
+            logger.info(f"LLM Judge initialized successfully with model: {self.judge.config.model} and base url: {self.judge.config.base_url}")
+            logger.info(f"Available metrics: {', '.join(sorted(self.available_metrics))}")
+            
+        except Exception as e:
+            logger.error(f"Failed to detect model: {e}")
+            raise
+    
+    async def evaluate_single_content(self, content: str, params: Dict[str, Any]) -> ContentAnalysisResponse:
+        """
+        Evaluate a single piece of content using the specified metric.
+        
+        Args:
+            content: Text content to evaluate
+            params: vLLM Judge parameters for the evaluation
+            
+        Returns:
+            ContentAnalysisResponse with evaluation results
+        """
+        if "metric" not in params:
+            if "criteria" not in params:
+                params["metric"] = "safety" # Default to safety
+            elif "scale" not in params:
+                params["scale"] = (0, 1) # Default to 0-1 scale
+        
+        if "metric" in params:
+            if params["metric"] not in self.available_metrics:
+                raise MetricNotFoundError(
+                    f"Metric '{params['metric']}' not found. Available metrics: {', '.join(sorted(self.available_metrics))}"
+                )
+            judge_metric = BUILTIN_METRICS[params["metric"]]
+            if judge_metric.scale is None:
+                params["scale"] = (0, 1) # Default to 0-1 scale
+
+        evaluation_params = {
+            "content": content,
+            **params
+        }
+        
+        # Perform evaluation
+        result: EvaluationResult = await self.judge.evaluate(
+            **evaluation_params
+        )
+        
+        # Convert to response format
+        score = None
+        if isinstance(result.decision, (int, float)) or result.score is not None:
+            # Numeric result
+            score = float(result.score if result.score is not None else result.decision)
+        
+        return ContentAnalysisResponse(
+            start=0,
+            end=len(content),
+            detection=str(result.decision),
+            detection_type="llm_judge",
+            score=score,
+            text=content,
+            evidences=[],
+            metadata={"reasoning": result.reasoning}
+        )
+
+    async def run(self, request: ContentAnalysisHttpRequest) -> ContentsAnalysisResponse:
+        """
+        Run content analysis for each input text.
+        
+        Args:
+            request: Input request containing texts and metric to analyze
+            
+        Returns:
+            ContentsAnalysisResponse: The aggregated response for all input texts
+        """
+
+        contents_analyses = []
+        
+        for content in request.contents:
+            analysis = await self.evaluate_single_content(content, request.detector_params)
+            contents_analyses.append([analysis])  # Wrap in list to match schema
+        
+        return contents_analyses
+            
+    
+    async def close(self):
+        """Close the judge client."""
+        if self.judge:
+            await self.judge.close()
+    
+    def list_available_metrics(self) -> List[str]:
+        """Return list of available metrics."""
+        return sorted(list(self.available_metrics))

detectors/llm_judge/deploy/servingruntime.yaml

@@ -0,0 +1,2 @@
+vllm-judge==0.1.6
+pyyaml==6.0.2

detectors/llm_judge/detector.py

@@ -0,0 +1,74 @@
+from enum import Enum
+from typing import List, Optional, Dict, Any
+from pydantic import BaseModel, Field, RootModel
+
+
+class Evidence(BaseModel):
+    source: str = Field(
+        title="Source",
+        example="https://en.wikipedia.org/wiki/IBM",
+        description="Source of the evidence, it can be url of the evidence etc",
+    )
+
+
+class EvidenceType(str, Enum):
+    url = "url"
+    title = "title"
+
+
+class EvidenceObj(BaseModel):
+    type: EvidenceType = Field(
+        title="EvidenceType",
+        example="url",
+        description="Type field signifying the type of evidence provided. Example url, title etc",
+    )
+    evidence: Evidence = Field(
+        description="Evidence object, currently only containing source, but in future can contain other optional arguments like id, etc",
+    )
+
+
+class ContentAnalysisHttpRequest(BaseModel):
+    contents: List[str] = Field(
+        min_length=1,
+        title="Contents",
+        description="Field allowing users to provide list of texts for analysis. Note, results of this endpoint will contain analysis / detection of each of the provided text in the order they are present in the contents object.",
+        example=[
+            "Martians are like crocodiles; the more you give them meat, the more they want"
+        ],
+    )
+    detector_params: Optional[Dict[str, Any]] = Field(
+        default_factory=dict, 
+        description="Detector parameters for evaluation (e.g., metric, criteria, etc.)",
+        example={"metric": "safety"}
+    )
+
+
+class ContentAnalysisResponse(BaseModel):
+    start: int = Field(example=0)
+    end: int = Field(example=75)
+    text: str = Field(example="This is a safe and helpful response")
+    detection: str = Field(example="vllm_model")
+    detection_type: str = Field(example="llm_judge")
+    score: float = Field(example=0.8)
+    evidences: Optional[List[EvidenceObj]] = Field(
+        description="Optional field providing evidences for the provided detection",
+        default=[],
+    )
+    metadata: Optional[Dict[str, Any]] = Field(default_factory=dict, description="Additional metadata from evaluation")
+
+
+class ContentsAnalysisResponse(RootModel):
+    root: List[List[ContentAnalysisResponse]] = Field(
+        title="Response Text Content Analysis LLM Judge"
+    )
+
+
+class Error(BaseModel):
+    code: int
+    message: str
+
+
+class MetricsListResponse(BaseModel):
+    """Response for listing available metrics."""
+    metrics: List[str] = Field(description="List of available metric names")
+    total: int = Field(description="Total number of available metrics")