llmprobe

llmprobe

Monitoreo sintético y pruebas de humo de CI para endpoints de inferencia de LLM. Mide TTFT, latencia, rendimiento y errores. Binario único, cero SDKs.

llmprobe es una herramienta CLI para la fiabilidad del servicio de LLM. Sondea APIs alojadas o servidores de inferencia compatibles con OpenAI, y luego informa las métricas que importan para la experiencia del usuario en producción: tiempo hasta el primer token (TTFT), latencia total, rendimiento de generación (tokens/seg) y tasas de error.

Úsalo como una verificación de salud puntual, un monitor continuo o una puerta de CI que bloquea despliegues cuando tu proveedor de LLM está degradado.

Benchmark público

llm-bench usa llmprobe para ejecutar un benchmark público continuo de las principales APIs de LLM. Publica un panel en vivo en bench.jonathanwrede.de y datos JSONL crudos en Jwrede/llm-bench-data.

Este es el caso de uso previsto: sondas sintéticas repetidas que hacen visibles la latencia de LLM, las regresiones de TTFT, las caídas de rendimiento y la degradación del proveedor antes de que los usuarios las reporten.

Instalación

Descarga un binario precompilado desde la última versión (Linux, macOS, Windows; amd64 y arm64).

O instala desde el código fuente:

go install github.com/Jwrede/llmprobe@latest
llmprobe version

Plugin de Claude Code

Instala como plugin de Claude Code para la habilidad /llmprobe y las herramientas MCP:

claude plugin install Jwrede/llmprobe

O registra el servidor MCP directamente:

claude mcp add --transport stdio llmprobe -- llmprobe mcp

llmprobe se ejecuta localmente y solo contacta los endpoints de LLM que configures. Consulta PRIVACY.md para más detalles.

Inicio rápido

llmprobe funciona con OpenAI, Anthropic, Google, Azure OpenAI, AWS Bedrock y endpoints compatibles con OpenAI como vLLM, Ollama, OpenRouter, Groq, Together AI, Fireworks, DeepSeek y Mistral.

Crea un probes.yml (o copia el ejemplo incluido):

providers:
  - name: openai
    api_key: ${OPENAI_API_KEY}
    models:
      - name: gpt-4o
        thresholds:
          max_ttft: 2s
      - name: gpt-4o-mini
        thresholds:
          max_ttft: 500ms

  - name: anthropic
    api_key: ${ANTHROPIC_API_KEY}
    models:
      - name: claude-sonnet-4-20250514
        thresholds:
          max_ttft: 1s

Ejecuta una sonda:

$ llmprobe probe

Provider   Model                    Status    TTFT    Latency  Tok/s  Tokens  Error
--------   -----                    ------    ----    -------  -----  ------  -----
openai     gpt-4o                   healthy   312ms   2100ms   68.4   42
openai     gpt-4o-mini              healthy   98ms    814ms    112.3  56
anthropic  claude-sonnet-4-20250514 healthy   420ms   2831ms   52.1   38
azure      gpt-4o                   healthy   289ms   1950ms   71.2   44
bedrock    anthropic.claude-3-5...  degraded  1820ms  4510ms   28.1   38

4 healthy, 1 degraded, 0 errors

Qué mide

Métrica	Qué significa
TTFT	Tiempo desde el envío de la solicitud hasta el primer token de contenido. Esto es lo que los usuarios sienten como "retraso" antes de que la respuesta comience a transmitirse.
Latencia	Tiempo total desde la solicitud hasta el cierre del flujo.
Tok/s	Rendimiento de generación: tokens producidos por segundo después del primer token. Calculado como token_count / (latency - ttft).
Tokens	Total de tokens de salida. Prefiere los metadatos de uso del proveedor cuando están disponibles; si no, recurre al conteo de eventos SSE.
Estado	healthy si todos los umbrales pasan, degraded si se excede algún umbral, error si la solicitud falló.

Comandos

llmprobe probe

Verificación de salud puntual. Sondea todos los endpoints configurados e imprime los resultados.

llmprobe probe                        # table output
llmprobe probe -f json                # JSON output
llmprobe probe --fail-on degraded     # exit 1 if any endpoint is degraded
llmprobe probe -c custom-config.yml   # custom config path

Códigos de salida para CI:

--fail-on	Salida 0	Salida 1
error (predeterminado)	saludable o degradado	cualquier error
degraded	solo saludable	degradado o error
none	siempre	nunca

llmprobe watch

Monitoreo continuo. Sondea todos los endpoints en un intervalo e imprime una línea de resumen por iteración.

llmprobe watch                          # default 60s interval
llmprobe watch --interval 30s           # custom interval
llmprobe watch --tui                    # live terminal dashboard with TTFT chart
llmprobe watch --tui --load data.jsonl  # load historical data into the dashboard
llmprobe watch -f json                  # JSONL output (one line per result)
llmprobe watch --prometheus :9090       # expose Prometheus metrics
llmprobe watch --otel localhost:4317     # export OpenTelemetry metrics via OTLP/gRPC

La bandera --tui lanza un panel de terminal en vivo con un gráfico de TTFT, leyenda de colores y tabla de estadísticas. Usa --load para importar datos JSONL históricos (de llmprobe watch -f json > data.jsonl).

$ llmprobe watch --interval 30s

Watching 4 endpoints every 30s (Ctrl+C to stop)

[14:01:02] All 4 endpoints healthy.
[14:01:32] All 4 endpoints healthy.
[14:02:02] 3 healthy, 1 degraded, 0 errors. DEGRADED: openai/gpt-4o (TTFT 1820ms)
[14:02:32] All 4 endpoints healthy.

llmprobe report

Genera un resumen en Markdown a partir de datos de sonda JSONL con percentiles p50/p95/p99 para TTFT, latencia y rendimiento por endpoint.

llmprobe report data.jsonl

Salida:

| Provider | Model | Probes | Errors | TTFT p50 | TTFT p95 | ... | Tok/s p50 | ...
|----------|-------|--------|--------|----------|----------|-----|-----------|----
| openai   | gpt-4o | 100  | 2      | 115ms    | 188ms    | ... | 46.9      | ...

llmprobe baseline

Crea un archivo de línea base a partir de datos JSONL históricos para la detección de regresiones.

llmprobe baseline data.jsonl -o baseline.json

Referencia la línea base en tu configuración para usar umbrales basados en multiplicadores:

baseline: baseline.json

providers:
  - name: openai
    api_key: ${OPENAI_API_KEY}
    models:
      - name: gpt-4o
        thresholds:
          max_ttft_multiplier: 2.0       # fail if TTFT > 2x baseline p50
          max_latency_multiplier: 2.5    # fail if latency > 2.5x baseline p50

Esto te permite detectar regresiones en relación con tus propios datos históricos en lugar de establecer umbrales absolutos.

llmprobe version

Imprime la versión del binario instalado.

llmprobe version

Integración con CI

Usa llmprobe probe como puerta previa al despliegue:

# .github/workflows/deploy.yml
- name: Check LLM providers
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    go install github.com/Jwrede/llmprobe@latest
    llmprobe probe --fail-on degraded

Esto bloquea el despliegue si algún proveedor de LLM está experimentando rendimiento degradado en este momento.

Cuando una sonda falla, la salida muestra solo los endpoints que fallan:

Failed endpoints (1/4):
  openai/gpt-4o  DEGRADED  TTFT=280ms  Latency=950ms  Tok/s=32.1

Servidor MCP

llmprobe incluye un servidor Model Context Protocol integrado, que permite a Claude Code y otros hosts de MCP verificar la salud de la API de LLM directamente desde un flujo de trabajo de agente.

Ejecutar el servidor

llmprobe mcp

Esto inicia el servidor MCP sobre stdio.

Registro con Claude Code

claude mcp add --transport stdio llmprobe -- llmprobe mcp

Una vez registrado, Claude Code puede llamar a las herramientas de llmprobe durante cualquier conversación.

Herramientas disponibles

Herramienta	Descripción
probe_all	Sondea todos los endpoints configurados desde probes.yml. Devuelve TTFT, latencia, rendimiento y estado de salud para cada modelo. Acepta un parámetro opcional config para una ruta de configuración personalizada.
probe_model	Sondea un solo modelo sin archivo de configuración. Requiere provider, model y api_key_env. Admite base_url opcional para endpoints compatibles con OpenAI y label opcional para visualización.
list_providers	Lista todos los proveedores y modelos en el archivo de configuración con sus umbrales. Úsalo para descubrir modelos disponibles antes de sondear.
get_config	Devuelve la configuración completa analizada, incluidos valores predeterminados, proveedores, modelos y umbrales.

Caso de uso de ejemplo: Un agente llama a list_providers para ver qué modelos están configurados, luego a probe_all para verificar que estén saludables antes de desplegar cambios.

Configuración

defaults:
  prompt: "Hello"                                # probe prompt
  max_tokens: 20                                 # max output tokens
  timeout: 30s                                   # per-probe timeout
  concurrency: 5                                 # max parallel probes

providers:
  - name: openai                    # openai, anthropic, google, azure, bedrock
    label: openai-prod              # optional display name; useful for multiple OpenAI-compatible endpoints
    api_key: ${OPENAI_API_KEY}      # env var expansion
    base_url: https://custom.api    # optional, override endpoint
    models:
      - name: gpt-4o
        prompt: "Say hello."        # override default prompt
        max_tokens: 10              # override default max_tokens
        response_format: json       # optional; OpenAI-compatible JSON mode
        validate_json: true         # optional; mark degraded if returned content is not valid JSON
        thresholds:
          max_ttft: 2s              # alert if TTFT exceeds this
          max_latency: 10s          # alert if total latency exceeds this
          min_tokens_per_sec: 20    # alert if throughput drops below this
          max_ttft_multiplier: 2.0  # optional; compare against baseline p50
          max_latency_multiplier: 2.5

  - name: azure
    api_key: ${AZURE_OPENAI_API_KEY}
    base_url: https://your-resource.openai.azure.com
    api_version: "2024-10-21"       # optional, defaults to 2024-10-21
    models:
      - name: gpt-4o               # deployment name

  - name: bedrock
    access_key: ${AWS_ACCESS_KEY_ID}
    secret_key: ${AWS_SECRET_ACCESS_KEY}
    region: us-east-1
    models:
      - name: anthropic.claude-3-5-sonnet-20241022-v2:0

Las claves de API y las credenciales de AWS admiten la sintaxis ${ENV_VAR}. Solo se expanden los campos de credenciales, por lo que las referencias a variables de entorno en prompts o nombres de modelos se dejan tal cual.

Proveedores compatibles con OpenAI

Muchos proveedores (Groq, Together AI, Fireworks, DeepSeek, Mistral, OpenRouter, Ollama, vLLM) exponen una API compatible con OpenAI. Estos funcionan de inmediato configurando base_url. Usa el campo label para distinguir múltiples bloques compatibles con OpenAI:

providers:
  # Groq
  - name: openai
    label: groq
    api_key: ${GROQ_API_KEY}
    base_url: https://api.groq.com/openai
    models:
      - name: llama-3.3-70b-versatile

  # DeepSeek
  - name: openai
    label: deepseek
    api_key: ${DEEPSEEK_API_KEY}
    base_url: https://api.deepseek.com
    models:
      - name: deepseek-chat

  # Together AI
  - name: openai
    label: together
    api_key: ${TOGETHER_API_KEY}
    base_url: https://api.together.xyz
    models:
      - name: meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo

  # Local Ollama
  - name: openai
    label: ollama
    api_key: unused
    base_url: http://localhost:11434
    models:
      - name: llama3.2

Consulta examples/ para configuraciones listas para usar de vLLM, SGLang y Ollama.

Validación de respuesta JSON

Para endpoints compatibles con OpenAI, configura response_format: json para solicitar modo JSON y validate_json: true para marcar la sonda como degraded si el contenido transmitido no es JSON válido.

providers:
  - name: openai
    label: vllm-json
    api_key: unused
    base_url: http://localhost:8000
    models:
      - name: meta-llama/Llama-3.1-8B-Instruct
        prompt: 'Return {"ok": true} as JSON.'
        response_format: json
        validate_json: true

Métricas de Prometheus

Ejecuta con --prometheus para exponer métricas para scraping:

llmprobe watch --interval 30s --prometheus :9090

Métricas disponibles en /metrics:

Métrica	Tipo	Etiquetas
llmprobe_ttft_seconds	gauge	provider, model
llmprobe_latency_seconds	gauge	provider, model
llmprobe_tokens_per_second	gauge	provider, model
llmprobe_token_count	gauge	provider, model
llmprobe_status	gauge	provider, model
llmprobe_probes_total	counter	provider, model
llmprobe_errors_total	counter	provider, model
llmprobe_ttft_seconds_hist	histogram	provider, model
llmprobe_latency_seconds_hist	histogram	provider, model
llmprobe_tokens_per_second_hist	histogram	provider, model

El gauge llmprobe_status codifica la salud como: 1 = saludable, 0.5 = degradado, 0 = error. Úsalo para alertas en Grafana o Alertmanager.

Métricas de OpenTelemetry

Ejecuta con --otel para exportar métricas de sonda a un colector OTLP/gRPC.

llmprobe watch --interval 30s --otel localhost:4317

Nombres de métricas exportadas:

Métrica	Descripción
llmprobe.ttft.seconds	Tiempo hasta el primer token en segundos
llmprobe.latency.seconds	Latencia total de la solicitud en segundos
llmprobe.tokens_per_second	Rendimiento de generación
llmprobe.token_count	Conteo de tokens de salida de la última sonda
llmprobe.status	1 = saludable, 0.5 = degradado, 0 = error
llmprobe.probes.total	Total de sondas ejecutadas
llmprobe.errors.total	Total de errores de sonda

Todas las métricas incluyen los atributos provider y model.

Arquitectura

probes.yml
  -> Config loader (YAML + env var expansion)
    -> Probe engine (concurrent goroutines per provider/model)
      -> Provider clients (raw HTTP + SSE parsing, no SDKs)
        -> Results (TTFT, latency, tokens/sec, status)
          -> Output (table, JSON, JSONL)

Cada cliente de proveedor es un envoltorio HTTP delgado que envía una solicitud de transmisión y analiza la respuesta. No se importan SDKs de LLM. El analizador SSE maneja tanto eventos solo de datos (OpenAI, Google) como eventos nombrados (Anthropic). El cliente de Bedrock implementa la firma SigV4 y el análisis del flujo de eventos binarios de AWS desde cero.

El TTFT se mide desde el momento en que se envía la solicitud HTTP hasta el primer evento que contiene texto de contenido real (no asignaciones de roles ni metadatos).

Proveedores

Proveedor	Endpoint	Autenticación	Formato de transmisión
OpenAI	/v1/chat/completions	Authorization: Bearer	SSE, centinela [DONE]
Anthropic	/v1/messages	cabecera x-api-key	SSE de eventos nombrados
Google	/v1beta/models/{model}:streamGenerateContent?alt=sse	parámetro de consulta key	SSE
Azure OpenAI	/openai/deployments/{model}/chat/completions	cabecera api-key	SSE, centinela [DONE]
AWS Bedrock	/model/{model}/converse-stream	SigV4	flujo de eventos binarios de AWS
OpenAI-compat	/v1/chat/completions (base_url personalizado)	Authorization: Bearer	SSE

La compatibilidad con OpenAI cubre: Groq, Together AI, Fireworks, DeepSeek, Mistral, OpenRouter, Ollama, vLLM y cualquier endpoint que hable la API de chat completions de OpenAI.

Hoja de ruta

• Más ejemplos específicos de proveedores para endpoints compatibles con OpenAI autoalojados
• Más formatos de informe para ventanas de monitoreo de larga duración
• Plantillas opcionales de runbook para fallos comunes de endpoints de LLM

Licencia

MIT