Sirve el router en una CPU, con la derivación dentro de la ruta
Unos 19 minutos de lectura, con 2 ejemplos en 5 secciones.
Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros
Traducido del libro en inglés, edición 2026.11.9. Lee el original
Al terminar este capítulo, podrás servir el router como un único endpoint POST /route que devuelve un equipo, una confianza y una marca de derivación para cada mensaje. También podrás comprobar que la ruta nunca devuelve un equipo para un mensaje que se ha derivado.
La ruta es el punto donde la regla de derivación se cumple o falla. El capítulo 1 presentó los equipos, y el capítulo 5 construyó una cabeza que entrega un equipo y una confianza en una sola pasada hacia adelante, y eligió el umbral que decide cuándo un mensaje pasa a una persona. Este capítulo pone ese modelo detrás de una ruta HTTP, que es por donde el software de la bandeja envía un mensaje y recibe de vuelta un equipo o una derivación.
Si quien llama a la ruta puede obtener un equipo para un mensaje que el router ha marcado, la marca no sirve de nada, por muy cuidadosamente que el capítulo 5 haya elegido su umbral. Por eso la ruta calcula la marca por sí misma, a partir de la misma respuesta que el equipo, y solo devuelve un equipo cuando la marca es falsa. Ninguna otra parte de este capítulo es tan importante como esa regla.
Este capítulo sirve el adaptador float32 que el capítulo 5 tomó de la grabación tal como estaba. El capítulo 7 crea una copia int8 solo de pesos, banking77-lora-v1-int8, y mide esa copia. Este capítulo no lo hace. Tampoco mide nada sobre la velocidad. Esa comparación proviene de una grabación en el capítulo 10, y nada de lo que se explica aquí permite predecirla.
Una ruta que devuelve la derivación
Una ruta es una función que el framework web llama cuando llega una solicitud a una ruta con un método. El framework aquí es FastAPI, fijado en 0.163.2 en examples/requirements.txt. El router tiene una sola ruta, POST /route. Quien llama envía un objeto JSON con un solo campo, message, que contiene el texto de un mensaje de la bandeja de entrada. La ruta responde con un objeto JSON de cinco campos: team, confidence, handed_off, adapter y version.
Cada campo tiene una sola fuente, y eso importa para la derivación. El confidence es la probabilidad softmax del equipo que el modelo eligió, que es el significado que el capítulo 5 le dio. La marca handed_off es el resultado de handoff(confidence, threshold), que es verdadera cuando la confianza está por debajo del umbral. La comparación está escrita como not confidence >= threshold, de modo que una confianza que no es un número, incluido NaN, también se deriva. El umbral no se escribe a mano en la ruta. La ruta lo lee del manifiesto del adaptador, donde el capítulo 5 escribió el valor que eligió en la partición de desarrollo, así que la ruta y el capítulo no pueden estar en desacuerdo sobre el número. El team es None cuando handed_off es verdadera, y es la etiqueta del equipo en caso contrario. Los campos adapter y version le indican a quien llama qué modelo respondió. El manifiesto no tiene un campo para la versión del adaptador, así que la versión es el sufijo del nombre del adaptador: banking77-lora-v1 informa v1.
La ruta llama al clasificador una vez por solicitud. Un solo paso hacia adelante da el equipo y la confianza juntos, y la marca se calcula a partir de esa misma confianza. Las dos no pueden venir de dos llamadas distintas y separarse. Un lector que abra el módulo encontrará una sola ruta propia y un solo camino hacia un equipo, la respuesta que la ruta construye después de fijar la marca. FastAPI añade sus páginas de documentación, que no devuelven ningún equipo. Recomendamos que un router conserve esta forma: una ruta, una llamada al modelo, una marca, y el equipo leído solo después de la marca. Una segunda ruta que omita la marca sería la forma más rápida de deshacer el trabajo del capítulo 5, y sería difícil de notar, porque seguiría devolviendo equipos correctos para los mensajes que no deriva.
Cada mensaje de test_40, una muestra fija de 40 que el libro usa para comprobaciones rápidas, se envía a la ruta, y la prueba cuenta las marcas y los equipos. Imprime recuentos y nunca el texto de un mensaje.
1"""Send the test_40 messages to the one POST /route through TestClient, in process, and print counts that tie the2hand-off flag to the team. The prose's point rests on the "handed off, team is None" line and the "not handed off,3team is the gold label" line; the last checks show the route's answer to a body with no message."""45import os67os.environ["HF_HUB_OFFLINE"] = "1"8os.environ["TRANSFORMERS_OFFLINE"] = "1"910import torch # noqa: E4021112torch.set_num_threads(2)1314from fastapi.testclient import TestClient # noqa: E4021516import router_lib # noqa: E4021718router_lib.setup_runtime() # seeds, deterministic algorithms and float32, so the counts repeat19client = TestClient(router_lib.make_app(router_lib.HERE / "data" / "recorded" / "lora-full")) # checks the files, loads the model once, and reads the hand-off threshold from the adapter's manifest2021test = router_lib.read_rows("test") # each row is (message, gold label index)22sample = router_lib.read_sample("test_40") # row numbers of the committed sample23replies = [client.post("/route", json={"message": test[i][0]}) for i in sample]24bodies = [r.json() for r in replies]25gold = [test[i][1] for i in sample] # gold label indexes; LABELS turns one into a team name2627print(f"responses: {len(replies)}")28print(f"status codes: {sorted({r.status_code for r in replies})}")29print(f"response keys: {sorted(bodies[0])}")30print(f"handed off: {sum(b['handed_off'] for b in bodies)}/{len(bodies)}")31print(f"team names outside the list: {sum(b['team'] is not None and b['team'] not in router_lib.LABELS for b in bodies)}")3233sure = [k for k, b in enumerate(bodies) if not b["handed_off"]] # kept: the route returned a team34unsure = [k for k, b in enumerate(bodies) if b["handed_off"]] # flagged: the route returned no team35print(f"not handed off, team is the gold label: {sum(bodies[k]['team'] == router_lib.LABELS[gold[k]] for k in sure)}/{len(sure)}")36print(f"handed off, team is None: {sum(bodies[k]['team'] is None for k in unsure)}/{len(unsure)}")37print(f"adapter: {bodies[0]['adapter']}")38print(f"version: {bodies[0]['version']}")3940bad = client.post("/route", json={}) # a body with no message field, which the route's body model requires41detail_is_list = isinstance(bad.json()["detail"], list)42assert detail_is_list, "a body with no message should get a 422 whose detail is a list"43print(f"status on an empty body: {bad.status_code}")44print(f"detail is a list: {'yes' if detail_is_list else 'no'}")
python serve-route-testclient.pyresponses: 40
status codes: [200]
response keys: ['adapter', 'confidence', 'handed_off', 'team', 'version']
handed off: 8/40
team names outside the list: 0
not handed off, team is the gold label: 30/32
handed off, team is None: 8/8
adapter: banking77-lora-v1
version: v1
status on an empty body: 422
detail is a list: yes
La marca y el equipo coinciden en esta muestra. La ruta respondió a todas las solicitudes, y el recuento de derivaciones es 8/40. Cada mensaje marcado volvió sin equipo: 8/8. De los mensajes que la ruta conservó, 30/32 tienen el equipo etiquetado, la etiqueta de referencia contra la que este libro evalúa. Ese recuento de conservados es la medida que el capítulo 2 llama exactitud sobre los mensajes no derivados: los mensajes correctos entre los que la ruta no marcó. Un mensaje derivado no tiene equipo que evaluar, así que queda fuera de ese recuento. El último recuento comprueba el conjunto de etiquetas: el número de nombres de equipo fuera de la lista es 0.
La salida muestra la forma de la regla: un mensaje marcado no tiene equipo, y un mensaje conservado sí lo tiene. Eso se cumple para los 40 mensajes de la muestra, lo cual es evidencia, no una demostración sobre cada solicitud. La demostración está en el código. La prueba de la ruta comprueba que el código hace lo que dice la regla, sobre una muestra que el lector puede volver a ejecutar.
Regla práctica: Calcula la marca en la ruta, a partir de la misma confianza que el equipo, con handoff, y devuelve un equipo solo cuando la marca sea falsa. No añadas una segunda ruta, un campo ni una opción que devuelva un equipo para un mensaje que la marca ha señalado. Si quien llama necesita un equipo para cada mensaje, la respuesta para los mensajes que la marca señala es una persona, no un equipo devuelto por la ruta.
Cargar el modelo una vez al iniciar
Una ruta que cargara el modelo en cada solicitud repetiría el mismo trabajo con cada mensaje. La ruta de este capítulo no lo hace, y la razón está en dónde se encuentra el código. Antes de cargar nada, la función make_app comprueba los archivos del adaptador frente a su manifiesto, y comprueba la revisión del modelo base frente a la versión fijada que registra el manifiesto. Si hay alguna discrepancia, lanza un error y no construye la aplicación. La comprobación es la del capítulo 9, y este capítulo depende de ella. Tras la comprobación, make_app lee el manifiesto, después carga el tokenizador y el modelo con load_classifier, y solo entonces define la ruta. La función de la ruta únicamente llama a classify y, después, a handoff. Por tanto, el modelo se carga al construir la aplicación, y cada solicitud usa el modelo que ya está en memoria.
La prueba de la ruta construye la aplicación una sola vez y envía los 40 mensajes a esa única aplicación, de modo que las 40 solicitudes comparten una sola carga. La carga forma parte de la construcción de la aplicación, no es un paso que deba dar quien la llama, y quien llama no puede hacer que la ruta cargue una segunda copia enviando una solicitud.
Los hilos son el otro ajuste que pertenece al arranque. make_app toma el número de hilos como argumento threads, cuyo valor por defecto es dos, y llama a torch.set_num_threads con ese número antes de cargar el modelo. Así, cada proceso que construye la aplicación fija sus hilos antes de la primera llamada al modelo. La documentación de PyTorch indica que la llamada establece el número de hilos intra-operación en la CPU, y que "set_num_threads must be called before running eager, JIT or autograd code" si el número debe mantenerse (documentación de torch 2.15.0+cpu).
El ajuste set_num_threads controla los hilos usados dentro de una operación, los hilos intra-operación que menciona la documentación. Dos hilos es una elección del libro, no el mejor valor medido. Los ejemplos del libro tienen un presupuesto de dos vCPU, por lo que el libro fija dos hilos para ellos, y quien use otra máquina debe elegir un número de hilos y medirlo. La elección se indica como del libro, porque ninguna salida de este capítulo compara un número de hilos con otro.
Regla práctica: Construye la aplicación una vez por proceso, con el número de hilos que ese proceso debe usar, y antes de la primera solicitud. Con un presupuesto de dos vCPU, como usa este libro, mantén el valor por defecto de dos hilos, y elige otro número solo después de medir tu propia máquina con tus propios mensajes.
Conoce lo que la ruta no puede puntuar
Hay dos tipos de solicitud que no se pueden puntuar, y la ruta las trata de forma distinta. El primero es una solicitud que carece del campo que la ruta necesita. La ruta declara su cuerpo como un modelo con un único campo obligatorio, message. Un cuerpo sin ese campo recibe el estado 422. La prueba de la ruta termina enviando un cuerpo así, y el campo detail de la respuesta es una lista, lo que la prueba verifica. Quien reciba un 422 no tiene respuesta que leer, y no debe buscar un equipo en ese cuerpo.
El segundo tipo de solicitud es un mensaje demasiado largo para leerlo completo. El modelo lee un mensaje como tokens, que son fragmentos de texto, y un mensaje largo tiene más de ellos. La función classify llama al tokenizador con truncamiento activado y max_length fijado en 128. Un mensaje de más de 128 tokens se corta en 128 antes de que el modelo lo lea. La ruta no comprueba la longitud, y su respuesta no indica que se produjo un corte. El mismo 128 se usó durante el entrenamiento: el script que registró banking77-lora-v1, recordings/lora_full.py, entrena con max_length fijado en 128. Por tanto, el corte en el servicio es el mismo corte con el que se entrenó el modelo, y esa es la razón por la que la ruta lo usa.
Un corte más corto, en 64 tokens, es una elección habitual, y el recuento siguiente muestra a qué afectaría en la muestra de prueba de 200 mensajes, la misma muestra con la que el capítulo 5 comparó modelos. El ejemplo muestra cuántos de los 200 mensajes superan cada corte. Aquí solo se carga el tokenizador, y no se ejecuta ningún modelo.
1"""Count the test_200 messages over 64 tokens and over the 128 that classify() cuts at, then show the cut on one long2message. The prose's point rests on the 128-token line and the before and after lengths; only the tokenizer loads."""34import os56os.environ["HF_HUB_OFFLINE"] = "1"7os.environ["TRANSFORMERS_OFFLINE"] = "1"89import json # noqa: E4021011import torch # noqa: E4021213torch.set_num_threads(2)1415from transformers import AutoTokenizer # noqa: E4021617import router_lib # noqa: E4021819router_lib.setup_runtime()20RECORDED = router_lib.HERE / "data" / "recorded" / "lora-full"21repo = json.loads((RECORDED / "adapter" / "adapter_config.json").read_text())["base_model_name_or_path"] # the adapter's base model22tokenizer = AutoTokenizer.from_pretrained(repo, revision=router_lib.pinned_revision(repo)) # the pinned revision the model uses2324test = router_lib.read_rows("test") # each row is (message, gold label index)25sample = router_lib.read_sample("test_200") # row numbers of the committed sample26lengths = [len(tokenizer(test[i][0]).input_ids) for i in sample] # full length in tokens, before any cut27n = len(lengths)28print(f"messages over 64 tokens: {sum(x > 64 for x in lengths)}/{n}")29print(f"messages over 128 tokens where classify() cuts: {sum(x > 128 for x in lengths)}/{n}")3031# The cut itself: repeat the text of the first test_200 message until it is longer than 128 tokens,32# then tokenize it with classify()'s settings (truncation on, max_length 128).33long_text = test[sample[0]][0]34while len(tokenizer(long_text).input_ids) <= 128: # repeat the first message until it runs past the 128-token cut35 long_text = long_text + " " + test[sample[0]][0]36before = len(tokenizer(long_text).input_ids)37after = len(tokenizer(long_text, truncation=True, max_length=128).input_ids) # the settings classify() passes38print(f"repeated message tokens before the cut: {before}")39print(f"repeated message tokens after the cut: {after}")40print(f"truncation side: {tokenizer.truncation_side}") # "right" cuts from the end of the text
python truncation-count.pymessages over 64 tokens: 1/200
messages over 128 tokens where classify() cuts: 0/200
repeated message tokens before the cut: 132
repeated message tokens after the cut: 128
truncation side: right
En esta muestra, un corte en 64 tokens afectaría a 1/200 mensajes, y el corte en 128 tokens, el que aplica classify, afectaría a 0/200. Como en la prueba de la ruta, esta es una sola muestra. No indica con qué frecuencia aparecen mensajes largos en otro buzón, y esa proporción hay que contarla con los mensajes propios del lector.
La segunda mitad del ejemplo muestra lo que hace el corte con un mensaje largo. Repite el texto del primer mensaje test_200 hasta que el texto supera los 128 tokens, y luego lo tokeniza con la configuración que usa classify. El mensaje llega al modelo como 128 tokens, frente a 132. El lado de truncamiento del tokenizador es right, de modo que el corte elimina el final del texto y conserva su inicio.
Un lector cuyos mensajes sean más largos que esta muestra debe contarlos antes de poner el servicio en marcha, porque la ruta no los contará por él. La ruta no rechaza un mensaje largo. Lo corta, puntúa lo que queda y devuelve un equipo cuando la marca es falsa, y nada en la respuesta muestra que hubo un corte. Por eso la comprobación corresponde hacerla antes de la ruta, en manos de quien hace la llamada. Recomendamos tratar un mensaje que la ruta cortaría como un mensaje para una persona, fuera de la ruta, y no como un mensaje que se adivina. Un equipo adivinado parecería un mensaje enrutado y no llevaría marca, así que nadie sabría que debe revisarlo. Un mensaje afectado por el corte se puntúa solo por su inicio, y la persona que hace la llamada no se entera. Es un fallo silencioso, y el lector debe decidir qué ocurre con esos mensajes antes de que la ruta los tome. El resultado seguro, que este libro recomienda, es que un mensaje largo vaya a una persona, fuera de la ruta, con el recuento informado junto al resto de resultados.
Regla práctica: Cuenta los mensajes más largos que el corte antes de poner en marcha un conjunto de mensajes, con el tokenizador del modelo base del adaptador y el mismo corte que usa la ruta. La ruta corta un mensaje más largo en 128 tokens y puntúa solo lo que queda, así que, cuando el recuento sea mayor que cero, envía esos mensajes a una persona fuera de la ruta e informa del recuento junto con la tasa de derivación.
Prueba la ruta en el mismo proceso
La regla de la ruta, un equipo solo cuando la bandera es falsa, tiene que comprobarse con respuestas reales, y el cliente de pruebas de FastAPI permite hacerlo sin iniciar un servidor. El tutorial de pruebas de FastAPI indica que su cliente de pruebas se usa como httpx, y que las llamadas a él son llamadas ordinarias, sin await (tutorial de pruebas de FastAPI 0.163.2). Así, una prueba es un bucle ordinario de Python, y cada llamada devuelve una respuesta que se puede leer.
La prueba de la ruta usa ese cliente. Construye la ruta a partir de la carpeta registrada, envía a esta cada uno de los 40 mensajes de test_40 y lee el JSON de cada respuesta. No inicia uvicorn y no imprime el texto de los mensajes. Todas las respuestas llegaron con estado 200, y la prueba imprime las claves de la primera respuesta, que son los cinco campos enumerados en la primera sección. Los recuentos que imprime son los que predice la regla de la ruta: el número de mensajes derivados, los mensajes marcados sin equipo, los mensajes conservados con el equipo de referencia y los nombres de equipo fuera de la lista. También envía un cuerpo sin message, imprime el estado de esa respuesta y afirma que su campo detail es una lista.
La prueba no inicia un servidor, y eso es una decisión. Un servidor iniciado dentro de una prueba necesitaría un puerto libre, una espera al arrancar y un apagado limpio, y cada una de esas cosas puede fallar por razones que no tienen nada que ver con la regla de derivación. Un lector que quiera una comprobación contra un servidor en ejecución puede enviar los mismos 40 mensajes a ese servidor y comparar sus recuentos con estos. La salida es la misma en cada ejecución, porque setup_runtime, que la prueba llama antes de construir la ruta, fija las semillas, exige algoritmos deterministas y establece el tipo por defecto como float32. Un lector que vuelva a ejecutar la prueba y obtenga recuentos distintos ha encontrado un cambio en el modelo, los datos o el entorno, y debe detenerse y averiguar cuál antes de confiar en la ruta.
La bandera y el equipo se comprueban juntos, para cada respuesta de la muestra: una respuesta marcada no tiene equipo, y una respuesta conservada sí lo tiene. Una prueba que comprobara solo el código de estado aprobaría una ruta que devolviera un equipo para cada mensaje, y pasaría por alto la bandera por completo. Por eso la prueba imprime ambos recuentos.
Regla práctica: Prueba la ruta a través del cliente de pruebas sobre una muestra incluida en el repositorio, e imprime los recuentos que vinculan la bandera con el equipo: el número de mensajes derivados, el número de esos sin equipo y el número de nombres de equipo fuera de la lista. Una prueba que solo comprueba el código de estado no demuestra que la regla de derivación se cumpla. Cada afirmación que haga la prueba debe tener una línea impresa que la respalde, porque la línea es lo que el libro puede citar y lo que un lector puede volver a ejecutar. Una afirmación sin línea es una afirmación que el lector tiene que aceptar sin comprobarla.
Qué sale mal en producción
Una ruta que pasa su prueba puede seguir fallando una vez que se ejecuta bajo un servidor, y la prueba no muestra estos fallos. La prueba se ejecuta una vez, sobre una muestra confirmada, con el código tal como está. La producción funciona mientras dure el servicio, con mensajes que nadie ha muestreado, y a menudo con más de un proceso. Cada uno de los fallos siguientes es una manera en que la muestra puede estar bien mientras el servicio no lo está. El primero son las copias del modelo. La página de despliegue de uvicorn, el servidor bajo el que está previsto que se ejecute la ruta de este capítulo, dice que "A diferencia de gunicorn, uvicorn no usa pre-fork, sino spawn" (guía de despliegue de uvicorn 0.54.0). Un worker creado con spawn es un proceso nuevo de Python. El módulo siguiente construye la aplicación cuando uvicorn lo importa, así que cada worker que lo importa carga su propia copia del modelo. Interpretamos la cita sobre spawn en ese sentido, y el capítulo no mide la memoria que cuesta cada copia. Debes contar las copias: el número de procesos worker, multiplicado por la huella del modelo en tu propia máquina, antes de elegir cuántos workers ejecutar.
Ejecutado desde la carpeta de ejemplos, donde están router_lib y data, el módulo que importa uvicorn son una línea de configuración y una línea de aplicación:
# serve_route.py
import router_lib
app = router_lib.make_app("data/recorded/lora-full", threads=2)
El comando es uvicorn serve_route:app. uvicorn toma su aplicación como "<module>:<attribute>", y su página de configuración en la misma etiqueta da APP en esa forma.
El segundo es un conflicto entre dos opciones. La misma página dice: "Los argumentos --reload y --workers son mutuamente excluyentes." Quien desarrolla con recarga automática no puede ejecutar varios workers en el mismo comando. Quien ejecuta varios workers lo hace sin recarga, así que un cambio en el código necesita un reinicio. Ambos hechos vienen de la propia página del servidor, y ambos deben figurar en tu manual de operaciones.
El tercero son los hilos. Cada proceso worker establece el número de hilos que pide su llamada a make_app, así que el total de hilos crece con el número de workers. En las dos vCPU que este libro presupuesta, dos hilos por worker significan un solo worker. Recomendamos que cuentes el total de hilos antes de añadir un worker, y que mantengas el total igual o por debajo de los núcleos que tiene la máquina. Es una regla orientativa. Este capítulo no mide qué ocurre cuando el total supera el número de núcleos, y no da una cifra para ese caso.
El cuarto es la tasa de derivación. La marca depende del umbral que el capítulo 5 eligió sobre la partición de desarrollo, y de los mensajes que envía la bandeja de entrada. La ruta devuelve la marca en cada respuesta, así que la tasa de mensajes marcados se puede contar a partir de la propia salida de la ruta. Si la tasa cambia, la ruta no puede decir por qué. Sus respuestas no muestran si cambiaron los mensajes de la bandeja, si cambió el modelo o si se editó el umbral. El capítulo 9 vigila esta tasa, y añade versiones y un respaldo en personas.
El quinto son los mensajes largos, de los que se ocupa la sección sobre lo que la ruta no puede puntuar. El corte en 128 tokens no se anuncia por sí solo, así que el recuento anterior debe repetirse sobre los mensajes que la ruta recibe de verdad.
El sexto es la falta de registro. Una ruta que devuelve la marca pero solo registra el código de estado no puede mostrar, tras un cambio, cómo se movió la tasa de derivación. Recomendamos que cada respuesta se registre con su marca, su adaptador y su versión, de modo que la tasa pueda contarse desde los registros además de desde la prueba.
Lo que fijó el capítulo:
- La ruta devuelve la marca en cada respuesta, y un equipo solo cuando la marca es falsa (no se cambia).
- La ruta sirve
banking77-lora-v1en float32, con el umbral leído de su manifiesto. - Antes de cargar el modelo,
make_appcomprueba los archivos del adaptador y su pin base frente al manifiesto, y no construye ninguna aplicación si hay discrepancia (capítulo 9). - La ruta corta cada mensaje en 128 tokens, la longitud con la que se entrenó el modelo.
- Cada proceso worker mantiene un modelo y lo construye con dos hilos, la elección del libro para un presupuesto de dos vCPU.
- La versión que reporta la ruta es el sufijo del nombre del adaptador.
La derivación se sostiene o falla en la ruta, así que la ruta calcula la marca.
Regla práctica: Ejecuta un modelo por proceso worker, construido con el número de hilos que hayas medido para tu máquina. Mantén dos hilos por worker, como hace este libro, hasta que tu propia medición diga otra cosa. Cuenta los procesos worker antes de contar la memoria del modelo en la máquina, y mantén --reload y --workers por separado. Vigila la tasa de derivación que devuelve la ruta, junto a sus errores, desde el primer día en que la ruta sirva mensajes.
Este capítulo, en esta edición
Edición 2026.11.9Ejemplos verificados el 20 de nov de 2026Superan la prueba 2 de 2 ejemplos ejemplos de este capítulo
Traducido del libro en inglés, edición 2026.11.9.