Inferrail

Visibilidad local de costos de IA sin carga útil para agentes. Realiza un seguimiento del gasto por modelo, ruta, cliente o trabajo etiquetado sin almacenar los cuerpos de las solicitudes o respuestas.

GitHubPrueba este MCPPatrocinado

Documentación

Inferrail logo

Sepa cuánto cuesta tu trabajo de IA.
Sin guardar lo que dijo.

Inferrail es una puerta de enlace que ejecutas tú mismo y que rastrea el uso de tokens y el costo estimado de LLM por cliente, flujo de trabajo o tarea para sus endpoints compatibles con OpenAI y Anthropic.

CI PyPI version Python 3.11+ License: Apache-2.0 Status: developer preview (alpha)

Pruébalo localmente · Cómo funciona · Privacidad · Integraciones · MCP · Estado · Documentación

Código abierto bajo Apache-2.0. Vista previa para desarrolladores: las funciones a continuación están implementadas y probadas, pero las banderas de CLI, la forma de configuración y los campos de recibo pueden cambiar antes de la versión 1.0.

Límite de privacidad

Para cada solicitud compatible, la puerta de enlace escribe un recibo en un archivo local. Este es un recibo real de la demostración sin conexión a continuación.

Ejemplo de recibo: datos sintéticos de demostración, abreviados.

{
  "receipt_id": "ir_4090e812f2ba4d3680e7",
  "route": "default",
  "provider": "demo",
  "model": "demo-small",
  "status": "success",
  "prompt_tokens": 812,
  "completion_tokens": 143,
  "pricing": {
    "input_usd_per_million": "0.20",
    "output_usd_per_million": "0.80",
    "source": "DEMO — a made-up round number, not a real provider price",
    "verified_date": "2026-09-26"
  },
  "estimated_cost_usd": "0.000277",
  "attributes": {"customer": "acme", "workflow": "contract-review", "work_id": "work-contract-1"}
}

Omitidos aquí: request_id, timestamp, total_latency_ms, retry_count. Lista completa de campos: receipts/schema.py.

Qué sucede con tu clave y tu contenido (autohospedado):

  • Tu proceso de puerta de enlace lee la clave del proveedor desde su propio entorno y envía solicitudes al proveedor que configures.
  • Procesa indicaciones y respuestas en memoria para reenviarlas. El proveedor aún recibe el contenido de tu solicitud, bajo sus propias políticas.
  • Los recibos registran uso, evidencia de costo, estado, tiempos y la atribución que proporciones. La ruta del recibo no copia los cuerpos de los mensajes.
  • Las etiquetas de atribución se almacenan exactamente como se envían. Usa identificadores y mantén secretos y contenido de mensajes fuera de ellas.
  • Los eventos de telemetría local son metadatos operativos. La baliza de uso opcional es separada y no envía nada a menos que configures un endpoint de recopilación (detalles).
  • La prueba alojada es un límite diferente: si agregas una clave real allí, el proceso alojado retiene esa clave y maneja tu tráfico.

Compruébalo tú mismo: manejadores de solicitudes · motores de ejecución (OpenAI, Anthropic) · adaptadores de proveedor (OpenAI, Anthropic) · constructor de recibos · sumideros (JSONL, SQLite) · pruebas canarias (OpenAI, streaming y telemetría, Anthropic).

inferrail verify-payload-free imprime el esquema de recibo en vivo y verifica que ningún campo se nombre por contenido de mensaje. Es una verificación de esquema, no una auditoría de seguridad: no puede inspeccionar valores almacenados, registros ni tu proveedor.

Pruébalo sin conexión

Requiere Python 3.11+. La instalación descarga el paquete y sus dependencias; después de eso, la demostración se ejecuta sin conexión.

python -m pip install inferrail
inferrail demo
inferrail report --by customer --receipts ./inferrail-demo-receipts.jsonl

La demostración no necesita clave de API, no realiza llamadas de red y no genera cargos al proveedor. Envía seis solicitudes programadas a través del motor real con un proveedor falso y precios inventados etiquetados como DEMO, luego escribe ./inferrail-demo-receipts.jsonl en tu directorio actual.

Configurar Python o solucionar el error comando no encontrado 
python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install inferrail

Si inferrail aún no se encuentra, el entorno no está activo o pip instaló en un Python diferente. Más en docs/self-hosting.md.

Terminal recording of a real, network-blocked run of inferrail demo on synthetic data: six requests, a cost report by customer with one unknown-cost request, a full receipt, and a receipt whose pricing and cost are null

Ejecución real de inferrail demo 0.4.3 con red bloqueada. Datos sintéticos, no facturación del proveedor. Imagen estática · salida capturada · cómo se hizo

En el informe, acme muestra una solicitud con costo desconocido: el modelo de vista previa de la demostración no tiene precio registrado, por lo que su recibo tiene "pricing": null y "estimated_cost_usd": null. La columna COST (USD) suma solo los costos conocidos. No es una factura completa cuando el conteo de desconocidos es mayor que cero.

Envía una solicitud real

Esto usa tu propia cuenta de proveedor, que te factura como de costumbre. Ejecuta la puerta de enlace en una terminal, con la clave configurada en esa terminal, porque la puerta de enlace es el proceso que llama al proveedor:

export OPENAI_API_KEY=...        # and/or ANTHROPIC_API_KEY=...
inferrail serve --quickstart

Luego apunta tu cliente hacia ella desde otra terminal o tu aplicación:

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="not-needed")
client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello in five words."}],
    extra_headers={"X-Inferrail-Attribute-Customer": "acme"},
)

import anthropic

# No /v1 here: the Anthropic SDK adds /v1/messages itself.
client = anthropic.Anthropic(base_url="http://127.0.0.1:8000", api_key="not-needed")
client.messages.create(
    model="claude-haiku-4-5-20251001",
    max_tokens=256,
    messages=[{"role": "user", "content": "Say hello in five words."}],
)

El api_key del cliente es un marcador de posición; la puerta de enlace lo ignora a menos que configures INFERRAIL_GATEWAY_TOKEN. Luego ejecuta inferrail report --by customer en el directorio de la puerta de enlace. La puerta de enlace escucha solo en 127.0.0.1 de forma predeterminada. Configura INFERRAIL_GATEWAY_TOKEN antes de exponerla en cualquier otro lugar (SECURITY.md).

Cómo funciona

Data flow. On your machine, your application sends requests to the Inferrail gateway, which reads the provider API key from its environment, forwards request content and the key to OpenAI or Anthropic, and returns the response. Separately, the gateway writes a metadata receipt (tokens, cost, status, timing, attributes, no message bodies) to a local JSONL or SQLite store that reports, the local dashboard, and MCP tools read. A usage beacon collector receives lifecycle events only if an endpoint is configured.

Cada solicitud se enruta mediante model a un proveedor configurado (enrutamiento), se ejecuta con reintentos y se mide. El costo se calcula solo cuando el proveedor informa uso y hay un precio verificado registrado; de lo contrario, permanece null, nunca un $0 adivinado (calculadora). Arquitectura: docs/ARCHITECTURE.md. Fuente del diagrama: scripts/render_flow_svg.py.

Integraciones

Compatible hoy: POST /v1/chat/completions (compatible con OpenAI, con streaming y llamadas a herramientas), POST /v1/messages (compatible con Anthropic, con streaming y uso de herramientas) y GET /health. Cualquier cliente o marco de trabajo que te permita configurar una URL base y envíe esas formas puede usar la puerta de enlace. Atribución, agrupación de trabajo, ejemplos de marcos y configuración de MCP están en docs/integrations.md.

Agentes de voz. Inferrail no tiene soporte nativo de voz. Una pila de voz puede enrutar su etapa de LLM de texto a través de Inferrail si esa etapa acepta una URL base personalizada compatible con OpenAI o Anthropic y envía una forma de solicitud compatible. Solo se registran los tokens y el costo de esa etapa. El audio, el reconocimiento de voz, la síntesis de voz, la API Realtime y el costo total de la llamada no están cubiertos, y ningún marco de voz ha sido probado por este proyecto (detalles).

MCP

Inferrail incluye un servidor MCP con dos herramientas de solo lectura, para que un agente pueda preguntar cuánto costó su trabajo de IA. Las herramientas leen tu archivo de recibos local. No ejecutan inferencia, no gastan presupuesto del proveedor, no cambian configuración ni escriben ningún archivo. Los recibos de Inferrail almacenan metadatos de uso y costo sin persistir cuerpos de indicaciones o respuestas, por lo que las herramientas no tienen ninguno que devolver. (La puerta de enlace en sí aún maneja indicaciones y respuestas en memoria mientras las reenvía al proveedor; consulta Límite de privacidad).

HerramientaQué responde
get_spendCosto conocido, tokens y conteos de solicitudes agrupados por provider, model, route o cualquier atributo con el que etiquetes solicitudes (customer, workflow, work_id), opcionalmente dentro de una ventana de tiempo. Las solicitudes con precios desconocidos se cuentan por separado, no como $0.
get_healthSi la puerta de enlace responde GET /health, más el recibo más reciente.

No hay herramientas separadas de cliente, flujo de trabajo o trabajo. get_spend agrupa por las etiquetas que lleven tus solicitudes, por lo que agrupar por customer, workflow o work_id (una unidad de trabajo etiquetado, como un trabajo) solo cubre solicitudes que se enviaron con esa etiqueta (atribución).

El servidor habla stdio y lo inicia tu cliente MCP:

uvx inferrail mcp        # or: pip install inferrail && inferrail mcp

Configuración del cliente (Claude Desktop, Cursor y otros clientes que usan mcpServers; VS Code usa la misma entrada bajo servers):

{
  "mcpServers": {
    "inferrail": {
      "command": "uvx",
      "args": ["inferrail", "mcp"],
      "env": {
        "INFERRAIL_RECEIPTS_PATH": "/absolute/path/to/inferrail-receipts.jsonl"
      }
    }
  }
}

Claude Code: claude mcp add inferrail -e INFERRAIL_RECEIPTS_PATH=/absolute/path/to/inferrail-receipts.jsonl -- uvx inferrail mcp

Configura INFERRAIL_RECEIPTS_PATH a tu archivo de recibos. Los clientes inician el servidor desde su propio directorio de trabajo, por lo que el ./inferrail-receipts.jsonl predeterminado rara vez es el lugar correcto. Para serve --app-mode, apúntalo a receipts.db en el directorio de datos de Inferrail (~/.local/share/inferrail en Linux, ~/Library/Application Support/inferrail en macOS, %APPDATA%\inferrail en Windows).

Luego pregunta, por ejemplo: "¿Cuánto costó el trabajo etiquetado contract_review_42?" Si tus solicitudes llevaban work_id=contract_review_42, el agente llama a get_spend con by: "work_id" y lee ese grupo. Contrato completo de la herramienta: inferrail-mcp/README.md.

Estado

CapacidadEstado
Puerta de enlace de LLM de texto, recibos de costo, informes, atribuciónDisponible en la vista previa para desarrolladores 0.4.3 en PyPI
Agrupación de trabajo y resultados declarados por la aplicaciónDisponible. Informa solo costo conocido y cuenta recibos de costo desconocido por separado
Verificaciones de presupuestoDisponible, opcional. Se aplica solo a solicitudes compatibles a través de esta puerta de enlace; los modelos sin precio no se verifican (detalles)
Panel local (serve --app-mode), herramientas MCP de solo lecturaDisponible. Ambos se incluyen en el paquete de PyPI (MCP)
Recuperación de excepciones de facturas AP (inferrail ap demo)Experimental flujo de trabajo con un contrato limitado (docs)
Prueba alojada de puerta de enlace de costos (tryinferrail.com/try)Vista previa. Con una clave real, el proceso alojado la retiene en memoria, y la prueba expira dentro de las 4 horas posteriores a agregarla (manejo de claves)
Economía de trabajo alojada y Autoridad EconómicaExperimental, solo red de pruebas Base Sepolia. Economía de trabajo: docs, ejemplo. Autoridad Económica: docs, ejemplo
Recompensas por referidos, niveles pagosPlanificado. No es parte del paquete
Audio, reconocimiento de voz, síntesis de voz, API Realtime, embeddings, imágenes, loteNo compatible
Proveedores más allá de las API compatibles con OpenAI y Anthropic (Gemini, Bedrock nativo)No compatible

Inferrail no contabiliza todo el gasto en una cuenta de proveedor, solo las solicitudes compatibles que pasan por una puerta de enlace en ejecución. Alcance completo y no objetivos: docs/PRODUCT.md.

Documentación

Comentarios, seguridad, licencia