← Volver al listado de tecnologías ← Índice de Bifrost

Introducción y arquitectura de Bifrost

Por: Artiko
bifrostai-gatewayllmarquitecturamaxim

Introducción y arquitectura de Bifrost

Bienvenido al primer capítulo de este tutorial “de 0 a héroe” sobre Bifrost. Antes de instalar nada o lanzar tu primer request, conviene entender qué es esta pieza de software, qué problema resuelve y cómo está construida por dentro. Si dominas el mapa mental de su arquitectura desde el principio, todo lo que venga después —la instalación, la configuración, los fallbacks, el semantic caching, el MCP Gateway— encajará en su lugar sin que tengas que memorizar comandos sueltos.

Este capítulo es puramente conceptual. No vas a escribir código todavía (eso llega en el capítulo 2: Instalación y tu primer request), pero al terminar tendrás claro por qué Bifrost existe, cuándo te conviene usarlo y cómo fluye una petición por dentro.

¿Qué es Bifrost?

Bifrost es un AI gateway de alto rendimiento desarrollado por Maxim AI. En una sola frase: es un servicio que se coloca entre tu aplicación y los proveedores de modelos de lenguaje (LLM), y unifica el acceso a 20+ proveedores —OpenAI, Anthropic, AWS Bedrock, Google Vertex, Azure y muchos más— a través de una única API compatible con OpenAI.

Su código está escrito en Go, lo que le permite ofrecer cifras de rendimiento muy ajustadas (las veremos más abajo), y se distribuye bajo licencia Apache 2.0, es decir, software libre y de uso comercial permitido.

Las ideas clave que debes retener de su propuesta:

Entre las capacidades open source que trae de fábrica destacan: failover automático entre proveedores, load balancing con distribución ponderada de claves API, virtual keys para governance, semantic caching y observabilidad integrada con Prometheus y OpenTelemetry. Cada una de estas tiene su propio capítulo más adelante.

El problema que resuelve

Para apreciar a Bifrost hay que entender el dolor que elimina. Cuando una aplicación empieza a usar LLMs en producción, casi siempre tropieza con los mismos cuatro problemas:

1. Fragmentación de SDKs y proveedores

Cada proveedor tiene su propio SDK, su propio formato de request, sus propios nombres de campos y su propia forma de gestionar errores. Integrar OpenAI, Anthropic y Bedrock significa mantener tres clientes distintos, tres conjuntos de tipos y tres rutas de código. Cada vez que quieres probar un modelo nuevo de otro proveedor, tienes que escribir un adaptador.

2. Vendor lock-in

Si toda tu lógica está acoplada al SDK de un único proveedor, migrar a otro —por precio, por disponibilidad o por calidad— se vuelve un proyecto en sí mismo. Quedas atado al vendor no por contrato, sino por fricción técnica.

3. Fallbacks y control de costo “caseros”

¿Qué pasa cuando OpenAI devuelve un 429 o se cae? Sin un gateway, terminas escribiendo a mano la lógica de reintentos, los fallbacks a un proveedor alternativo, el balanceo entre varias claves API y el control de presupuesto. Es código crítico, difícil de probar y que se duplica en cada servicio.

4. Falta de observabilidad unificada

Saber cuánto gastas, qué latencia tienes por proveedor o qué requests fallaron requiere instrumentar cada SDK por separado.

Bifrost resuelve los cuatro de un golpe: centraliza el acceso, desacopla tu código del proveedor, ofrece resiliencia y governance como configuración (no como código), y expone métricas estándar.

flowchart LR
    subgraph Antes["Sin gateway"]
        A1[Tu app] --> S1[SDK OpenAI]
        A1 --> S2[SDK Anthropic]
        A1 --> S3[SDK Bedrock]
        A1 -.fallbacks caseros.-> A1
    end
    subgraph Despues["Con Bifrost"]
        B1[Tu app] -->|API OpenAI| BF[Bifrost]
        BF --> P1[OpenAI]
        BF --> P2[Anthropic]
        BF --> P3[Bedrock]
    end

Cifras de rendimiento reales

Una de las razones por las que Bifrost está escrito en Go es el rendimiento. Estas son las cifras publicadas en su documentación de benchmarking (no estimaciones nuestras), medidas en instancias de AWS EC2:

Para situar estos números, las dos instancias de referencia del benchmark son:

Metricat3.medium (2 vCPU, 4 GB)t3.xlarge (4 vCPU, 16 GB)
Overhead Bifrost59 µs11 µs
Latencia media2,12 s1,61 s
Espera en cola47,13 µs1,67 µs
Pico de memoria1.312,79 MB3.340,44 MB
Buffer size15.00020.000
Pool size10.00015.000

Nota de precisión: la latencia media (1,61 s / 2,12 s) corresponde al tiempo total del request, dominado por la respuesta del propio proveedor LLM. El overhead de Bifrost es la fracción de microsegundos que el gateway añade a esa latencia, y es la cifra relevante para juzgar su eficiencia. Verlo así evita confundir “lo que tarda el modelo” con “lo que cuesta el gateway”.

Profundizaremos en cómo reproducir estos benchmarks y ajustar buffer size y pool size en el capítulo 14: Despliegue en producción.

Las dos formas de usar Bifrost

Bifrost se puede consumir de dos maneras, y elegir la correcta depende de tu stack y de cuánto control necesites.

Opción A: Gateway HTTP (con Web UI)

Despliegas Bifrost como un servidor HTTP independiente con una interfaz web integrada para configuración visual y monitoreo en tiempo real. Tu aplicación —en cualquier lenguaje— le habla por HTTP usando el formato de OpenAI. Es la forma recomendada para la mayoría de los casos.

Arrancarlo es tan simple como:

npx -y @maximhq/bifrost

O con Docker:

docker run -p 8080:8080 maximhq/bifrost

Luego abres http://localhost:8080 en el navegador para la Web UI, y tu primer request es un simple curl:

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o-mini", "messages": [{"role": "user", "content": "Hello, Bifrost!"}]}'

Cuándo elegir el Gateway HTTP: si tu aplicación no está en Go, si quieres una capa de gateway compartida por varios servicios, si valoras la Web UI para configurar proveedores sin tocar código, o si despliegas como infraestructura central.

Opción B: Go SDK embebido

Integras Bifrost directamente dentro de tu aplicación Go, como una librería, para “máximo rendimiento y control”. Aquí no hay HTTP de por medio: las llamadas son funciones Go con validación de tipos en tiempo de compilación.

go get github.com/maximhq/bifrost/core

La inicialización y un request se ven así:

client, initErr := bifrost.Init(context.Background(), schemas.BifrostConfig{
    Account: &MyAccount{},
})

response, err := client.ChatCompletionRequest(
    schemas.NewBifrostContext(context.Background(), schemas.NoDeadline),
    &schemas.BifrostChatRequest{
        Provider: schemas.OpenAI,
        Model:    "gpt-4o-mini",
        Input:    messages,
    },
)

Tu MyAccount implementa la interfaz Account con tres métodos: GetConfiguredProviders(), GetKeysForProvider() y GetConfigForProvider(). Toda esta vía la cubre el capítulo 13: Go SDK.

Cuándo elegir el Go SDK: si tu aplicación ya es Go, si necesitas eliminar incluso el salto de serialización HTTP, o si quieres máximo control sobre la configuración en código.

flowchart TD
    Q{¿Tu app es Go y quieres maximo control?}
    Q -- No --> H[Gateway HTTP + Web UI]
    Q -- Si --> G[Go SDK embebido]
    H --> R1[Cualquier lenguaje habla HTTP/OpenAI]
    G --> R2[Llamadas Go sin overhead de HTTP]

Arquitectura modular

Bifrost está organizado en módulos con responsabilidades bien separadas. Esta separación es la que permite, por ejemplo, usar la misma lógica de proveedores tanto desde el Gateway HTTP como desde el Go SDK embebido.

flowchart TB
    subgraph transports["transports/ (bifrost-http)"]
        T[Transport HTTP / FastHTTP]
    end
    subgraph ui["ui/"]
        U[Web UI]
    end
    subgraph core["core/"]
        E[Engine + Providers]
        K[KeySelector]
        W[ProviderWorkerPool]
    end
    subgraph framework["framework/"]
        CS[ConfigStore]
        LS[LogStore]
        VS[VectorStore]
        MC[Model Catalog / Pricing]
    end
    subgraph plugins["plugins/"]
        PL[Plugins pre/post]
    end
    T --> E
    U --> CS
    E --> K
    E --> W
    E --> PL
    E --> framework

core/ — lógica y providers

Es el corazón. Contiene el engine de Bifrost y las implementaciones de cada provider (la traducción del formato unificado al de OpenAI, Anthropic, Bedrock, etc.). Aquí viven piezas como el KeySelector (selección ponderada de claves, ~10 ns) y el ProviderWorkerPool (los pools de workers por proveedor). El Go SDK se instala precisamente desde aquí: go get github.com/maximhq/bifrost/core.

framework/ — almacenamiento y utilidades compartidas

El framework es, según la documentación, un “paquete SDK de almacenamiento y utilidades compartidas” que ofrece interfaces de base de datos comunes para el ecosistema de plugins. Lo componen:

Se instala por separado con go get github.com/maximhq/bifrost/framework y es lo que da soporte a features como gestión de proveedores, logging de requests, semantic caching y governance.

transports/ — bifrost-http

Es la capa que expone Bifrost por la red. El transport principal es bifrost-http, construido sobre FastHTTP: recibe el POST a /v1/chat/completions, parsea cabeceras, valida el JSON y lo transforma en un objeto interno (BifrostRequest) que el core entiende. El Go SDK, en cambio, omite por completo esta serialización HTTP.

ui/ — la Web UI

La interfaz web integrada para configurar proveedores y claves, y monitorear en tiempo real. Es opcional pero muy cómoda; la recorreremos en el capítulo 3: Configuración.

plugins/ — extensibilidad

El sistema de plugins que se engancha en el flujo de cada request mediante pre-hooks y post-hooks. Autenticación, rate limiting, transformación de payloads, logging, caching y métricas se implementan como plugins. Lo cubre el capítulo 12: Plugins y extensibilidad.

El flujo de un request

Veamos cómo viaja una petición por dentro. La documentación describe el pipeline en etapas claras, desde que el cliente envía el request hasta que recibe la respuesta. El patrón es: transport -> pre-hooks -> provider -> post-hooks -> respuesta.

sequenceDiagram
    participant C as Cliente
    participant T as Transport (FastHTTP)
    participant R as Routing / KeySelector
    participant Pre as Plugins (pre-hooks)
    participant WP as ProviderWorkerPool
    participant P as Proveedor (OpenAI...)
    participant Post as Plugins (post-hooks)

    C->>T: POST /v1/chat/completions
    T->>T: Parseo y validacion -> BifrostRequest
    T->>R: Seleccion de clave (~10 ns) + health check
    R->>Pre: ExecutePreHooks() (secuencial)
    Pre->>WP: Encolar job (sync.Pool, canales)
    WP->>P: ProviderWorker.ExecuteRequest()
    P-->>WP: Respuesta del proveedor
    WP->>Post: ExecutePostHooks() (secuencial)
    Post-->>C: Respuesta JSON (HTTP) o struct (SDK)

Etapa por etapa, según la documentación:

  1. Transport: FastHTTP recibe el POST, parsea cabeceras (~2,1 µs), valida el esquema JSON (~400 ns) y construye un BifrostRequest. El Go SDK se salta esto con llamadas directas tipadas.
  2. Routing y load balancing: se comprueba que el modelo esté disponible; KeySelector hace selección aleatoria ponderada sobre el pool de claves (~10 ns) y un health check (~50 ns) decide si el proveedor está listo. Si no, el circuit breaker activa la lógica de fallback.
  3. Pre-hooks: PluginManager.ExecutePreHooks() itera secuencialmente los plugins registrados (autenticación, rate limiting, transformación, monitoreo). Cada plugin puede rechazar o dejar pasar el request.
  4. MCP (si está habilitado): MCPManager.EnhanceRequest() descubre herramientas disponibles, aplica filtros de inclusión/exclusión y las inyecta en los parámetros del request. Más en el capítulo 10: MCP Gateway.
  5. Pools de memoria: se toman objetos preasignados con sync.Pool para minimizar allocations.
  6. Worker pool: el job se encola en ProviderWorkerPool; un Worker libre lo procesa de forma asíncrona en una goroutine y vuelve al pool al terminar.
  7. Comunicación con el proveedor: ProviderWorker.ExecuteRequest() prepara la petición HTTP, añade cabeceras de autenticación, revisa el circuit breaker y ejecuta contra el proveedor externo con timeout configurable.
  8. Tool execution: si la respuesta trae tool calls, MCPProcessor.ProcessToolCalls() los extrae y ejecuta concurrentemente contra los servidores MCP.
  9. Post-hooks y respuesta: PluginManager.ExecutePostHooks() corre los plugins de post-procesado (logging, caching, métricas) y, finalmente, la respuesta se serializa a JSON (HTTP) o se devuelve como struct de Go (SDK).

Concurrencia a alto nivel

El rendimiento de Bifrost no es magia: se apoya en un modelo de concurrencia con worker pools aislados por proveedor, basado en goroutines de Go. Las ideas centrales:

Estos parámetros —tamaño de los pools, buffers de cola, políticas de backpressure— son los que se ajustan para escalar, y los retomaremos en el capítulo 7: Retries, fallbacks y load balancing y en el de despliegue.

OSS vs Enterprise

Bifrost es open source (Apache 2.0) y la mayor parte de lo que necesitas en producción está en la versión libre. Hay, sin embargo, capacidades reservadas a Enterprise. A grandes rasgos:

Incluido en open source:

Exclusivo de Enterprise (según la documentación):

El detalle de qué aporta cada plan, y el camino para adoptar Enterprise, lo veremos en el capítulo 14: Despliegue en producción y camino a Enterprise.

Resumen

En este capítulo construimos el mapa mental de Bifrost:

Con este panorama claro, ya estamos listos para ensuciarnos las manos: instalar Bifrost y lanzar la primera petición real.

Siguiente: Instalación y tu primer request

← Volver al listado de tecnologías ← Índice de Bifrost