Skip to content
← Todas las publicaciones
· Delta1 Labs MeteringKeyright

Medir el uso por función con varias bolsas de créditos

Los productos reales miden más de una cosa — tokens de IA, minutos de render, exportaciones — y juntarlo todo en una sola bolsa de créditos oculta el coste y bloquea funciones sin relación cuando una se agota. Así se modelan varias bolsas de créditos independientes en una misma licencia de Keyright: la forma de una bolsa, el consumo idempotente por bolsa que falla cerrado de forma aislada, el orden de consumo desde la cuota incluida hasta la recarga prepago, los consumos atómicos sobre varias bolsas para una operación que gasta dos medidores a la vez, y la reconciliación por bolsa que sigue funcionando sin conexión.

La mayoría de las guías de medición, incluida nuestra propia introducción, te dicen que elijas una unidad facturable y la midas con limpieza. Ese consejo es correcto y es por donde casi todo el mundo empieza. Luego el producto crece. La herramienta de IA para documentos que cobraba por documento procesado ahora también renderiza PDF, llama a un modelo que factura por token y deja exportar a un puñado de formatos bajo un tope mensual. Tres cosas distintas te cuestan dinero, aportan valores distintos y se agotan a ritmos distintos — y una sola bolsa de “créditos” ya no describe ninguna de ellas con honestidad.

Este artículo trata del siguiente paso: medir varios recursos en una misma licencia, cada uno como su propia bolsa de créditos, sin que las bolsas interfieran entre sí.

Conclusión clave: cuando un producto mide más de un recurso, dale a cada uno su propia bolsa en lugar de convertirlo todo en créditos genéricos. Las bolsas separadas mantienen honesto el precio, permiten fijar una cadencia de reinicio y una política de excedente distintas por recurso y — lo más importante — se agotan de forma independiente, de modo que una bolsa de exportaciones vacía nunca bloquea un trabajo de render. El coste es un poco más de maquinaria: consumos idempotentes por bolsa, un orden de consumo explícito cuando las bolsas se solapan y consumos atómicos sobre varias bolsas para una operación que gasta dos medidores a la vez.

Por qué una sola bolsa de créditos no basta

El atajo tentador es un único saldo de “créditos” abstractos, con una lista de precios que dice que un documento vale 1 crédito, un minuto de render 4 y una exportación 10. Se desmorona al contacto con clientes reales:

  • El tipo de cambio es una ficción que mantienes para siempre. En cuanto cambie el coste de tu render, el precio efectivo que cada cliente paga por los documentos también se mueve, porque comparten una sola bolsa. No puedes reprecificar un recurso sin reprecificarlos todos.
  • El agotamiento es todo o nada. Un cliente que quema la bolsa en renders ya no puede exportar un documento que ya pagó por procesar. Una función desbocada deja sin recursos a todas las demás.
  • Nadie puede leer su propio consumo. “Te quedan 4.000 créditos” no responde a ninguna pregunta que el cliente se haga de verdad, que es “¿cuántos informes más puedo exportar este mes?”.

Las bolsas separadas arreglan las tres cosas. Cada recurso tiene su propio saldo, su propia cadencia de reinicio y su propia política de excedente, y agotar uno no afecta a los demás.

Qué es una bolsa

Una bolsa es un saldo consumible con nombre que la licencia transporta junto a sus indicadores y límites. La definen tres propiedades:

  • Tipo. Una bolsa de cuota se recarga con una cadencia (digamos, 2.000 minutos de render que se reinician el día uno de cada mes). Una bolsa prepago es un bloque que el cliente compró, persiste hasta gastarse y nunca se recarga sola.
  • Política de excedente. Qué pasa al llegar a cero — parada en seco, un pequeño margen de cortesía o excedente medido y facturado después. Decídelo por bolsa; una parada en seco en exportaciones y excedente en tokens de IA es una mezcla perfectamente razonable.
  • Reconciliación. Cómo se ajusta el consumo local contra el saldo autoritativo del servidor, lo que más importa en despliegues sin conexión y on-premise.
Una licencia Keyright firmada — tres bolsas independientesrender-minutescuota · reinicio mensual1.240 / 2.000 restantesai-tokensbloque prepago · sin reinicio870k / 1M restantesexportscuota · parada en seco a 00 / 50 restantesUn consumo golpea solo una bolsa:MeterAsync(pool: "render-minutes", amount: 5, idempotencyKey: jobId)debita render-minutesexports sigue en 0, ai-tokensintacto — sin impacto cruzado

Medir contra una bolsa con nombre

Con una sola bolsa la llamada del SDK nombraba una unidad; con varias, nombra la bolsa. Todo lo demás de la medición con una bolsa sigue valiendo — contar en el punto de estrangulamiento, pasar una clave de idempotencia estable y fallar cerrado — pero ahora cada una de esas reglas aplica por bolsa.

var client = KeyrightClient.Initialize(options);

// At the single point where render minutes are consumed.
var draw = await client.MeterAsync(
    pool: "render-minutes",
    amount: job.Minutes,
    idempotencyKey: job.Id);   // stable: a retry never double-charges

if (!draw.Allowed)
{
    // This pool is empty. Fail closed — do not render — but say which pool.
    ShowTopUpPrompt(pool: "render-minutes", message: draw.Message);
    return;
}

RunRenderJob(job);             // only runs when a render minute was actually metered

MeterAsync devuelve un MeterResult que lleva Allowed, un Message legible y Remaining, para que puedas pintar un aviso de saldo bajo sin una segunda llamada. Como en cualquier comprobación de Keyright, un consumo contra una bolsa desconocida o agotada falla cerrado — Allowed es false — así que la vía de denegación es la predeterminada, no algo que debas recordar codificar.

El agotamiento independiente es el objetivo

Como el consumo está acotado a una bolsa, una bolsa vacía detiene solo sus propias operaciones. En la figura de arriba la bolsa de exportaciones está a cero, pero un render sigue teniendo éxito, porque el consumo de render nunca toca el saldo de exportaciones. Lee los saldos directamente cuando necesites mostrar estado o avisar con antelación:

PoolBalance exports = client.GetBalance("exports");

// ResetsAt is non-null for a quota pool, null for a prepaid block.
if (exports.Remaining == 0)
    DisableExportButton(reason: $"Export quota resets {exports.ResetsAt:d}.");
else if (exports.Remaining <= exports.Limit * 0.2)
    ShowLowBalanceBanner(exports);   // warn at 20% — a surprise is a support ticket

Ocultar el botón de exportar es UX, no cumplimiento: la comprobación autoritativa es el consumo con MeterAsync en el punto donde se produce la exportación. El aviso solo hace que el cliente se entere de una bolsa vacía antes de chocar con ella a mitad de tarea.

Orden de consumo: cuota incluida antes que recarga prepago

Las bolsas se ponen interesantes cuando dos de ellas pueden pagar la misma operación. Una forma común: todo plan incluye una cuota mensual de minutos de render, y los clientes pueden comprar bloques prepago para lo que exceda. Quieres gastar primero los minutos incluidos — caducan a fin de mes, los prepago no — para que el cliente nunca queme dinero que podría haber usado gratis.

Exprésalo como un recorrido ordenado de las bolsas candidatas:

// Spend the resetting quota first, then fall back to the prepaid block.
static async Task<MeterResult> MeterWithFallbackAsync(
    KeyrightClient client, string[] poolsInOrder, long amount, string idempotencyKey)
{
    foreach (var pool in poolsInOrder)
    {
        var draw = await client.MeterAsync(pool, amount, idempotencyKey);
        if (draw.Allowed) return draw;         // first pool with room wins
    }
    return MeterResult.Denied("All matching pools exhausted. Top up to continue.");
}

var draw = await MeterWithFallbackAsync(
    client,
    poolsInOrder: ["render-minutes-included", "render-minutes-prepaid"],
    amount: job.Minutes,
    idempotencyKey: job.Id);

La única idempotencyKey representa la operación entera, no una bolsa concreta, así que un intento denegado no debita nada y un reintento reproduce el resultado asentado sin importar qué bolsa acabó pagando. Si prefieres no llevar el orden en el código del cliente, decláralo una vez en el servidor como un grupo de bolsas — un conjunto ordenado que el SDK resuelve por ti — y vuelve a un simple MeterAsync(pool: "render-minutes", …) que recorre incluida-luego-prepago por debajo.

Una operación, dos bolsas: consumos atómicos sobre varias bolsas

El caso difícil es una única operación lógica que gasta de más de una bolsa a la vez. Un trabajo de render podría consumir minutos de render y los tokens de IA que quema su paso de subtitulado. Debitarlos con dos llamadas separadas a MeterAsync es una trampa: si la primera tiene éxito y la segunda falla, has cobrado una bolsa por un trabajo que estás a punto de abandonar, y no hay forma limpia de devolver ese crédito.

La solución es un consumo múltiple de todo o nada. Describe cada bolsa que la operación toca y deja que el SDK las compruebe todas, las debite juntas o no debite ninguna:

var plan = new[]
{
    new MeterDraw(pool: "render-minutes", amount: job.Minutes),
    new MeterDraw(pool: "ai-tokens",      amount: job.CaptionTokens),
};

// Every pool must have room, or nothing is debited.
var result = await client.MeterManyAsync(plan, idempotencyKey: job.Id);

if (!result.Allowed)
{
    // ShortfallPool names the first pool that could not cover its draw.
    ShowTopUpPrompt(pool: result.ShortfallPool, message: result.Message);
    return;
}

RunRenderJob(job);   // both pools debited together, under one idempotency key

Es el equivalente en medición de una transacción: la invariante es que los saldos del cliente y el trabajo entregado nunca se contradicen. ShortfallPool te dice qué medidor bloqueó el trabajo, de modo que el aviso de recarga apunta a la bolsa correcta en lugar de a un genérico “sin créditos”.

Reinicios, reconciliación y sin conexión

Cada bolsa se reconcilia según sus propios términos. Una bolsa de cuota se recarga con su cadencia; el servidor reinicia Remaining a Limit en el límite del periodo y el SDK lo refleja en la siguiente reconciliación. Una bolsa prepago solo baja hasta que el cliente compra otro bloque.

Para despliegues sin conexión aplica el mismo mecanismo de bloques firmados de la medición con una bolsa, una vez por bolsa. El servidor emite un saldo firmado criptográficamente para cada bolsa — “esta licencia tiene 2.000 minutos de render y 1.000.000 de tokens de IA” — que el cliente verifica contra su clave pública incrustada y consume localmente, sin llamada de red por consumo. Cuando la máquina vuelve a conectarse reconcilia cada bolsa de forma independiente: informa de lo consumido, el servidor ajusta cada saldo y reemite bloques firmados nuevos. Un cliente aislado u on-premise puede medir varios recursos a la vez sin estar nunca en línea durante un consumo.

El límite honesto no cambia respecto a cualquier medidor del lado del cliente: un atacante decidido con un descompilador puede intentar parchear un saldo local, así que el recuento autoritativo permanece en un servidor que tú controlas, los bloques firmados se reconcilian contra él y haces que el cliente sea difícil de parchear — véase proteger tus comprobaciones de licencia. La medición por bolsa sin conexión es una extensión controlada de la confianza para uso desconectado legítimo, no una garantía contra la manipulación.

Hacerlo con Keyright

Keyright trata cada bolsa como parte de primera clase de la licencia, junto a los asientos, los indicadores de función y los límites numéricos. Declaras una bolsa por recurso medido — su tipo, cadencia de reinicio y política de excedente —, vendes cuotas y bloques prepago contra ella, y el SDK (.NET, Node, Python, Java) mide cada bolsa de forma independiente, idempotente y fallando cerrado. Los grupos de bolsas te dejan declarar el orden de consumo una sola vez; MeterManyAsync mantiene atómica una operación sobre varias bolsas; y los bloques firmados por bolsa llevan todo esto sin conexión, reconciliando cuando una máquina vuelve a conectarse. Como es la misma licencia que ya gestiona tus pruebas, asientos y permisos, medir varios recursos es parte de la licencia, no un sistema de facturación atornillado al lado.

La Community Edition es gratuita y autoalojada, así que puedes modelar un producto con varias bolsas y cablearlo de principio a fin antes de comprometerte — consulta los precios o lee la documentación de Keyright para conocer la superficie exacta de medición. Si el precio por uso por función es central en tu producto, el resumen de funciones profundiza en bolsas, cuotas y excedentes.

Conclusión: una sola bolsa de créditos es el modelo correcto para exactamente un recurso medido. En cuanto midas un segundo, dale su propia bolsa — saldo independiente, reinicio independiente, agotamiento independiente — y recurre al consumo ordenado cuando las bolsas se solapen y a un consumo múltiple atómico cuando una operación gaste dos medidores a la vez.

Prueba Nebula.NET

Endurece tu código .NET en minutos — empieza con la edición gratuita.