Una sola interfaz para modelos con guion, reproducidos, locales y alojados
Unos 19 minutos de lectura, con 4 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.2. Lee el original
Al terminar este capítulo podrás ejecutar el mismo bucle sobre un modelo con guion, una ejecución reproducida, un modelo local y un endpoint compatible con OpenAI, sin cambiar el bucle. También podrás decir qué conserva cada adaptador de una respuesta y qué lee del texto de esa respuesta.
El capítulo 1 ejecutó el agente de mantenimiento de unitcraft sobre un modelo con guion y luego sobre una ejecución almacenada, y el bucle admitió ambos sin ningún cambio. La siguiente pregunta es qué tiene que entregar un modelo para que eso funcione. Para T-01, el problema en el que format_quantity elimina los ceros finales, de modo que 3.5 kg se imprime como 3.5 kg donde el valor predeterminado de dos decimales da 3.50 kg, cada paso necesita devolver tres cosas: el texto del modelo, las llamadas a herramientas que el arnés puede leer de ese texto y los recuentos de tokens que usaron la petición y la respuesta. Una lista de cadenas con guion puede proporcionar las tres. También pueden hacerlo un archivo en disco, un modelo cargado en memoria o un endpoint HTTP. El adaptador es el código que hace que cada una de esas fuentes se vea igual para el bucle, y el resto de este capítulo recorre los cuatro adaptadores en el orden en que el bucle los encuentra.
Pregunta a todos los modelos lo mismo
El bucle necesita una sola cosa de un modelo: dados los mensajes hasta ahora y los esquemas de herramientas de el capítulo sobre esquemas, devolver lo que el modelo dijo. Un Protocol de Python nombra ese contrato. Cada adaptador de este libro tiene el mismo método, y cada adaptador devuelve el mismo tipo de valor.
class Model(Protocol):
def reply(self, messages: list[dict], tools: list[dict]) -> Reply: ...
El Reply es una pequeña dataclass. Contiene el text sin procesar del modelo, las llamadas a herramientas que el adaptador leyó de ese texto, cualquier bloque malformado que no pudo leer, los recuentos de tokens del prompt y de la respuesta, y el motivo de finalización, que indica si el modelo se detuvo por sí mismo o se quedó sin tokens. Aquí un token es la unidad que el capítulo 1 cuenta, a partir del tokenizador propio del modelo fijado, así que los recuentos pertenecen a ese modelo y no significan nada para otro. El adaptador nunca edita text. El bucle actúa sobre las llamadas, pero la transcripción conserva el texto tal como lo escribió el modelo, para que el lector pueda ver lo que el modelo realmente dijo.
Conservar tanto el texto como las llamadas importa porque el análisis puede fallar. Una respuesta puede contener un bloque <tool_call> cuyo JSON no se analiza, o un bloque que nunca se cierra. El adaptador no puede convertir en silencio esa respuesta en una llamada, y tampoco puede descartarla, porque el bucle tiene que decirle al modelo qué salió mal. Por eso el análisis deja el texto como está, registra junto a él un motivo breve para cada bloque defectuoso, y deja que el bucle decida qué ve el modelo después. La sección sobre el modelo local muestra el analizador en funcionamiento.
Un Protocol parece una interfaz, pero Python lo comprueba por su forma. La documentación de typing de Python dice que un protocolo runtime_checkable "solo comprobará la presencia de los métodos o atributos requeridos, no sus firmas de tipo ni sus tipos". Así, isinstance puede confirmar que un objeto tiene un método reply, y nada más: una clase cuyo método está escrito como reply(self, prompt) pasa, y una clase sin reply falla. El propio Model del libro no está decorado con runtime_checkable, y la misma documentación indica que isinstance sobre un protocolo así lanza un TypeError. Ningún ejemplo de este libro llama a isinstance sobre Model, así que ambas afirmaciones son de la documentación y no se ejecutan aquí.
Regla práctica: Prueba cada adaptador llamando a reply() con los mensajes y los esquemas de herramientas que envía el bucle, y comprueba los campos del Reply que se devuelve. Usa isinstance solo para ver que existe un método, nunca para demostrar que su firma es correcta.
Programa las respuestas, o reproduce una ejecución guardada
Dos adaptadores no necesitan ningún modelo real. La ejecución programada del capítulo 1 usó un modelo programado, y su ejecución reproducida usó uno guardado. Ambos funcionan por la misma razón: el bucle es lo que se prueba, y una lista fija de respuestas deja al modelo fuera de él. Esta sección explica qué añaden los adaptadores a eso.
ScriptedModel acepta cadenas u objetos Reply. Una cadena se convierte en un Reply por ti, y sus llamadas a herramientas se leen de los bloques <tool_call> del texto. Un objeto Reply se pasa sin cambios. Esa segunda forma permite que una prueba fije los recuentos de tokens o una entrada malformada directamente, en lugar de escribir JSON que debe fallar exactamente de la manera correcta. Si el bucle pide más respuestas de las que contiene el guion, el modelo lanza un IndexError, así que un guion corto falla de forma visible en lugar de devolver nada. El guion también mantiene la prueba legible. La respuesta que provoca un comportamiento está en la prueba junto a la aserción sobre él, y el lector no tiene que abrir una grabación para encontrarla.
ReplayModel lee las filas de una ejecución desde el replies.jsonl de la grabación, en orden de paso. Cada fila contiene el hash de la solicitud tal como se envió, el texto de la respuesta y los recuentos de tokens. Cuando el bucle pide un paso, ReplayModel calcula el hash de la solicitud que recibió, el sha256 de sus mensajes y esquemas de herramientas en JSON canónico, y compara ese hash con el de la fila. Una diferencia lanza ReplayMismatch, que indica el paso. Los recuentos provienen de la fila guardada, así que una reproducción nunca vuelve a tokenizar.
Las filas provienen de un registrador, no de un guion. LoggedModel envuelve un modelo en vivo y añade cada respuesta a un archivo JSON-lines antes de que la vea el bucle. Una ejecución que se detiene a mitad deja sus filas en disco, y el guion de grabación las elimina antes de reanudar la grabación.
La ejecución T-01 del capítulo 1 pasa por el bucle dos veces en el primer ejemplo: una vez con un ScriptedModel que contiene los textos de respuesta guardados, y otra con el ReplayModel para la misma ejecución. Las respuestas programadas se leen del archivo guardado, así que ambas ejecuciones parten del mismo origen.
1"""Chapter-1-t01 runs through the loop twice: once with a ScriptedModel holding the stored reply texts, once with a2ReplayModel. The assert compares the two runs' step lines, and the lines printed below are the replayed run's."""3import json45from lib.case import load_tasks6from lib.loop import run_task7from lib.models import RECORDED, ReplayModel, ScriptedModel8from lib.tools import CH19from lib.trace import IdCounter1011task = load_tasks(only=["T-01"])[0]12rows = [json.loads(line) for line in (RECORDED / "chapter-1-t01" / "replies.jsonl").read_text(encoding="utf-8").splitlines()]131415def run_once(model):16 run = run_task(model, task, CH1, max_steps=CH1.step_cap, ids=IdCounter()) # counter-based IDs, never random (P-3)17 try:18 return list(run.trace.lines()), run.steps, run.ended19 finally:20 run.close()212223scripted = run_once(ScriptedModel([row["text"] for row in rows]))24replayed = run_once(ReplayModel("chapter-1-t01", "T-01"))25assert scripted == replayed, "the two adapters gave the loop different steps"26lines, steps, ended = replayed27for line in lines:28 print(line)29print(f"steps: {steps}")30print(f"ended: {ended}")
python same-loop-two-models.pystep 1: read_file: 23 lines
step 2: run_tests: 8 failed, 22 passed
step 3: malformed: error: malformed call
step 4: malformed: error: malformed call
step 5: malformed: error: malformed call
step 6: malformed: error: malformed call
step 7: malformed: error: malformed call
step 8: malformed: error: malformed call
steps: 8
ended: step_cap
El bucle hizo las mismas llamadas en ambas ocasiones, y el ejemplo se detiene si las dos ejecuciones difieren en alguna línea de paso. La ejecución es la que alcanzó el límite de pasos en el capítulo 1: terminó como step_cap tras 8 pasos. El bucle no puede distinguir entre los dos adaptadores, así que lo que haga con una respuesta lo hace igual sea cual sea el origen.
El segundo ejemplo comprueba la propia grabación, contra su manifiesto, y luego la reproduce.
1"""The stored chapter-1 run is the recording its manifest describes, and replaying it hands the loop each stored reply text2exactly. The prompt and the check hash to the manifest's values, the first request hashes to the reply row stored with it,3and the stored replies add up to the manifest's counts. The run is then replayed through the loop, which refuses any request4that differs from its recorded hash, and each replayed text is compared with its stored text. No model file is loaded."""5from contextlib import closing67from lib.case import load_tasks8from lib.loop import run_task9from lib.models import RECORDED_SAMPLING, ReplayModel, TextCapture, first_step, load_recording, request_hash, same_texts, stored_totals10from lib.prompts import prompt_sha25611from lib.tasks import check_sha25612from lib.tools import CH113from lib.trace import IdCounter1415task = load_tasks(only=["T-01"])[0]16manifest, rows = load_recording("chapter-1-t01")17messages, tools = first_step(task, CH1)18assert manifest["prompt_sha256"] == prompt_sha256(CH1.system, CH1.descriptions()), "the prompt changed since recording"19assert manifest["check_sha256"] == check_sha256(task), "the check changed since recording"20assert rows[0]["request_sha256"] == request_hash(messages, tools), "the first request differs from the stored reply row"21assert len(rows) == manifest["steps"], "the stored replies and the manifest disagree on the step count"22prompt_tokens, completion_tokens = stored_totals(manifest, rows)23assert manifest["sampling"] == RECORDED_SAMPLING, "the recording's sampling differs from the settings the adapters send"2425capture = TextCapture(ReplayModel("chapter-1-t01", "T-01"))26with closing(run_task(capture, task, CH1, max_steps=CH1.step_cap, ids=IdCounter())) as run:27 steps, ended = run.steps, run.ended28compared = same_texts(rows, capture.texts)29assert steps == manifest["steps"] and ended == manifest["ended"], "the replay did not end as the manifest records"30print(f"stored replies: {len(rows)}")31print(f"prompt tokens: {prompt_tokens}")32print(f"completion tokens: {completion_tokens}")33for key in ("temperature", "top_k", "seed"):34 print(f"{key}: {manifest['sampling'][key]}")35print(f"reply texts compared exactly: {compared}")36print(f"steps: {steps}")37print(f"ended: {ended}")
python replay-byte-for-byte.pystored replies: 8
prompt tokens: 13009
completion tokens: 2128
temperature: 0
top_k: 1
seed: 4217
reply texts compared exactly: 8
steps: 8
ended: step_cap
Aquí el manifiesto es la referencia, y el ejemplo realiza cuatro comprobaciones. El hash del prompt y el de la comprobación se comparan con los valores del manifiesto, donde la comprobación es la prueba oculta, H-01, con la que el capítulo 1 califica T-01. El hash de la primera solicitud se compara con el que está guardado en su fila de respuesta en replies.jsonl, porque el manifiesto no contiene un hash de solicitud. Las respuestas guardadas deben coincidir con el número de pasos y los totales de tokens del manifiesto, y la configuración de muestreo se imprime desde el manifiesto y se compara con RECORDED_SAMPLING de la biblioteca, los valores que envía loopback_model. La ejecución guardada tiene 8 respuestas, 13009 tokens de prompt y 2128 tokens de completado. El ejemplo imprime su configuración de muestreo en líneas propias, para que el lector vea la temperatura, el top k y la semilla que usó la grabación.
Después la ejecución pasa por el bucle. ReplayModel rechaza cualquier paso cuyo hash de solicitud difiera de su fila, y el ejemplo compara cada texto reproducido con su texto guardado, exactamente. Imprime el número que comparó, 8, y la ejecución termina como indica el manifiesto. El manifiesto no contiene un hash para cada respuesta, así que los textos guardados no se verifican contra un valor independiente. La comprobación muestra que la reproducción entrega al bucle cada texto guardado sin cambios. El hash del prompt cubre juntos el mensaje del sistema y las descripciones de las herramientas, así que una descripción de herramienta modificada cambia la identidad de la grabación igual que cambiaría una línea de código.
Regla práctica: Reproduce una ejecución grabada solo con el prompt y la comprobación con que se grabó. Cuando cualquiera de los dos cambia, su hash en el manifiesto ya no coincide, el ejemplo falla y la ejecución debe volver a grabarse. Cambiar una respuesta guardada para que el ejemplo pase oculta el cambio que causó el fallo.
Un modelo local, y por qué sus ajustes están fijados
LlamaModel ejecuta un modelo local. Carga un archivo GGUF, el formato de un solo archivo que lee llama.cpp, a través de llama-cpp-python. El adaptador importa la biblioteca solo cuando se construye un modelo, de modo que los ejemplos nunca la cargan. Ningún ejemplo carga el archivo GGUF, y el libro no tiene ninguna prueba de LlamaModel. La grabación lo usó, y los ejemplos leen las respuestas que esa grabación almacenó. Su reply() llama a create_chat_completion con los mensajes y las herramientas, y lee el texto y el uso de la respuesta.
Los valores predeterminados de la biblioteca no son los del libro. En la versión fijada, create_chat_completion de llama-cpp-python usa por defecto una temperatura de 0.2 y un top k de 40. Un adaptador que deja esos valores como están muestrea de forma distinta a este. LlamaModel pasa temperature=0 y top_k=1 en cada llamada, de modo que el muestreo queda escrito en el código y no heredado de la biblioteca.
Lo que se devuelve es texto. El servidor de la grabación ejecutó la versión fijada de llama-cpp-python como python -m llama_cpp.server sobre el mismo archivo de modelo, y devolvió la llamada a herramienta del primer paso dentro del contenido del mensaje. El cuerpo almacenado de la grabación del endpoint tiene ese contenido y ningún campo tool_calls:
<tool_call>
{"name": "read_file", "arguments": {"path": "unitcraft/format.py"}}
</tool_call>
Así, la respuesta de la biblioteca lleva la llamada como texto, y LlamaModel no lee de ella un campo estructurado. Analiza el texto.
El análisis es una sola función, parse_tool_calls. Encuentra cada bloque <tool_call>, lo lee como JSON con un name y un objeto arguments, y conserva la llamada. Un bloque que no se analiza se convierte en una entrada malformada con un motivo breve. El bucle muestra esa entrada al modelo como un error de herramienta, de modo que una llamada incorrecta queda registrada como un paso y no se descarta. La ejecución T-01 del capítulo 1, en qué sale mal, lo muestra: tras sus dos primeros pasos, cada paso es error: malformed call.
El motivo de finalización importa para el bucle. stop significa que el modelo terminó su respuesta, y length significa que la respuesta alcanzó el límite de tokens que fijó el adaptador. Una respuesta con length puede detenerse a mitad de un bloque <tool_call>, por eso el analizador también informa de un bloque sin cerrar como malformado, en lugar de leerlo como completo.
Los recuentos son los propios de la biblioteca. LlamaModel copia en Reply los recuentos de tokens del prompt y de la respuesta que informa llama-cpp-python, y la grabación los almacena. Describen el tokenizador del archivo fijado, de modo que un archivo distinto da recuentos distintos para los mismos mensajes, y un recuento de un modelo no puede compararse con uno de otro.
El constructor recibe la ruta del archivo, el tamaño del contexto, el número de hilos, la semilla y el límite de tokens, y nada más sobre el modelo. La grabación toma sus valores de recordings/local_model.py, así que si quieres cargar otro archivo, cambias la ruta y esos ajustes juntos, y vuelves a grabar. El muestreo es una elección, y la tarjeta del modelo recomienda otra. La tarjeta del modelo Qwen dice: «Sugerimos usar Temperature=0.7, TopP=0.8, TopK=20 y MinP=0». Esos ajustes convienen a respuestas que varían de una ejecución a otra. Este libro graba una ejecución una vez y comprueba las ejecuciones posteriores frente a las respuestas almacenadas, así que usa temperatura 0, top k 1 y una semilla fija, 4217, tal como registran los manifiestos. Esos ajustes dan a una nueva grabación su mejor oportunidad de coincidir, pero la temperatura 0 no garantiza que la salida se repita, así que el libro no afirma más de lo que muestran sus ejemplos. El ejemplo del endpoint comprueba que dos peticiones sobre una misma grabación dieron el mismo texto. La reproducción no depende del muestreo en absoluto, porque lee el texto almacenado.
Regla práctica: Graba con el muestreo que indica el manifiesto, y guarda en el manifiesto, junto a él, el hash del archivo del modelo. Si cambias un ajuste, las respuestas cambian con él, así que vuelve a grabar la ejecución en lugar de compararla con la anterior.
Un endpoint de tipo alojado, probado en loopback
Un servidor que acepta la forma de solicitud de chat-completions de OpenAI puede ser usado por un único adaptador, indicando una URL base y, cuando el host lo exige, una clave. OpenAICompatibleModel envía los mensajes, los esquemas de herramientas y la configuración de muestreo a /chat/completions. Utiliza urllib de la biblioteca estándar y ningún SDK. Sin un SDK, nada oculta la solicitud: request_body() devuelve el cuerpo que el adaptador serializa y envía, y una prueba puede compararlo con lo que se grabó. El campo top_k solo se envía cuando el adaptador recibió un valor para él. El adaptador rechaza dos cosas al construirse, antes de cualquier solicitud: una URL que no sea http o https, y una clave enviada por http sin cifrar a cualquier host que no sea loopback. Tampoco sigue nunca una redirección. Una redirección provoca un error, de modo que una clave nunca se envía a una segunda URL.
La respuesta contiene la llamada a la herramienta en uno de dos lugares. La referencia de OpenAI describe el function.arguments de una llamada a herramienta como una cadena que el modelo genera en JSON, y le indica a quien llama que "valide los argumentos en su código antes de llamar a su función". El adaptador analiza esa cadena cuando la respuesta tiene un campo estructurado tool_calls. Cuando el campo no existe, recurre al texto <tool_call>, como hace el modelo local. parse_chat_body conserva message.content tal como lo envió el servidor, trata un contenido ausente como texto vacío y copia los recuentos de uso en Reply, de modo que un cuerpo almacenado se analiza siempre hasta el mismo Reply. En ambos casos, los argumentos llegan al bucle como un diccionario, y el diccionario todavía no está comprobado. El modelo de argumentos de la herramienta, del capítulo sobre el esquema, realiza esa comprobación.
Ningún ejemplo de este libro envía una solicitud que devuelva un campo estructurado tool_calls, así que la primera rama existe como código y ningún ejemplo la ejecuta. El libro no muestra lo que otros proveedores devuelven en ese campo, y este capítulo no dice más de lo que dice la referencia de OpenAI.
La grabación usó el mismo archivo y la misma configuración de muestreo que el modelo local. Ejecutó el servidor propio de llama-cpp-python fijado a una versión, en loopback, y envió el primer paso de T-01 a través del adaptador dos veces. El archivo almacenado contiene cada solicitud tal como se envió y cada cuerpo de respuesta sin procesar. Un http.server de loopback sirve esos cuerpos en orden, y responde 409 a cualquier solicitud cuyo cuerpo difiera del grabado. El simulador compara el cuerpo de la solicitud, cada mensaje y cada ajuste. No compara la ruta, el método ni las cabeceras, así que un cambio en la ruta del endpoint o en la cabecera Authorization pasaría sin problema. Si un cambio en el adaptador altera el cuerpo que envía, la solicitud falla antes de que se lea ninguna respuesta. Los cuerpos almacenados conservan los propios campos id y created del servidor. Nada los compara ni los imprime. Como no se carga ningún modelo, el código HTTP y de análisis del adaptador se ejecuta cada vez que se comprueban los ejemplos del libro.
1"""The OpenAI-compatible adapter, run live against a loopback stub that serves the bodies recorded from llama.cpp's own2server. The line that matters is "raw text": the server put the call in the message content as text, with no tool_calls3field, so the adapter parses the text, and the tool's own model accepts the arguments. Needs4recordings/openai_compatible.py to have been run; until then this raises."""5import json67from lib.case import load_tasks8from lib.models import first_step, loopback_model, serve_recorded9from lib.tools import CH11011task = load_tasks(only=["T-01"])[0]12messages, tools = first_step(task, CH1)13bodies: list[str] = []14with serve_recorded("openai-compatible") as base_url:15 model = loopback_model(base_url, on_body=bodies.append)16 first = model.reply(messages, tools)17 second = model.reply(messages, tools)18assert first.text.lstrip().startswith("<tool_call>"), "the server should return the call as text"19assert "tool_calls" not in json.loads(bodies[0])["choices"][0]["message"], "the recorded body has a structured tool_calls field"20assert len(first.tool_calls) == 1 and first.tool_calls[0]["name"] == "read_file", "the first step is one read_file call"21assert not first.malformed, "the call should parse"22CH1.get("read_file").args.model_validate(first.tool_calls[0]["arguments"]) # raises if the arguments do not fit the tool23assert first.text == second.text, "the two recorded responses differ"24print(f"requests: {len(bodies)}")25print("raw text:", json.dumps(first.text))26print("structured tool_calls field: absent")27print(f"tool calls: {len(first.tool_calls)}")28print("call:", first.tool_calls[0]["name"], json.dumps(first.tool_calls[0]["arguments"], sort_keys=True))29print(f"malformed: {len(first.malformed)}")30print(f"prompt tokens: {first.prompt_tokens}")31print(f"completion tokens: {first.completion_tokens}")32print(f"finish reason: {first.finish_reason}")
python openai-compatible-loopback.pyrequests: 2
raw text: "<tool_call>\n{\"name\": \"read_file\", \"arguments\": {\"path\": \"unitcraft/format.py\"}}\n</tool_call>"
structured tool_calls field: absent
tool calls: 1
call: read_file {"path": "unitcraft/format.py"}
malformed: 0
prompt tokens: 501
completion tokens: 22
finish reason: stop
El adaptador recibe una llamada read_file como texto. Comprobar sus argumentos frente al modelo de la herramienta corresponde a quien llama, y esa comprobación es el punto central de esta sección, así que el ejemplo la hace explícita. La respuesta contiene un bloque de llamada de herramienta 1 y un bloque 0 mal formado, y la solicitud usó 501 tokens de entrada. La respuesta termina con stop, lo que significa que el modelo terminó su respuesta por sí mismo y no se quedó sin tokens.
El auxiliar que construye el adaptador para las grabaciones y el ejemplo, loopback_model, fija el alias del modelo con el que se inició el servidor, un límite de 1024 tokens por respuesta, temperatura 0 y top_k 1. Quien quiera otra configuración construye OpenAICompatibleModel directamente, y el cuerpo de la solicitud que envía será distinto, lo que el simulador rechazará.
El proxy funciona como lo haría para cualquier solicitud de urllib, salvo en los hosts de loopback, 127.0.0.1, ::1 y localhost, a los que se accede directamente. Una URL remota http pasa por el proxy que indique el entorno. Un simulador hace las veces del proxy en el ejemplo de rechazo, y muestra ambas mitades: las solicitudes de loopback nunca llegan a él, y la solicitud remota llega con su URL completa.
1"""The OpenAI-compatible adapter refuses a redirect, a key over plain http to a remote host, and a non-http scheme. It sends2a remote URL through the environment's proxy and a loopback URL around it. Every request goes to a stub on 127.0.0.1, which3stands in for both the endpoint and the proxy, so no network is used. Each refusal prints one labelled line."""4from lib.models import OpenAICompatibleModel, proxy_env, refusal, stub_endpoint56REMOTE = "http://remote-host.invalid/v1"7MESSAGES = [{"role": "user", "content": "ping"}]89with stub_endpoint(200) as proxy, stub_endpoint(302) as target, proxy_env(proxy):10 loopback = f"{target.url}/v1"11 model = OpenAICompatibleModel(loopback, "model", max_tokens=8, api_key="DUMMY-KEY")12 reason = refusal(lambda: model.reply(MESSAGES, []))13 assert target.seen == ["/v1/chat/completions"], "a redirect was followed"14 print("redirect 302 on loopback:", reason)15 target.code = 30716 reason = refusal(lambda: model.reply(MESSAGES, []))17 print("redirect 307 on loopback:", reason)18 assert target.seen == ["/v1/chat/completions"] * 2, "a redirect was followed"19 print(f"requests to the redirect target: {target.seen.count('/collect')}")20 print(f"loopback requests through the proxy: {len(proxy.seen)}")2122 remote = OpenAICompatibleModel(REMOTE, "model", max_tokens=8)23 reply = remote.reply(MESSAGES, [])24 assert reply.text == "ok" and proxy.seen == ["http://remote-host.invalid/v1/chat/completions"]25 print("remote request through the proxy:", proxy.seen[0])26 print("remote reply text:", reply.text)2728 reason = refusal(lambda: OpenAICompatibleModel(REMOTE, "model", max_tokens=8, api_key="DUMMY-KEY"))29 print("key over plain http to a remote host:", reason)30 assert len(proxy.seen) == 1, "a request was made for the refused key"31 OpenAICompatibleModel("https://remote-host.invalid/v1", "model", max_tokens=8, api_key="DUMMY-KEY")32 print("key over https to a remote host: accepted, no request made")33 OpenAICompatibleModel(loopback, "model", max_tokens=8, api_key="DUMMY-KEY")34 print("key over http to loopback: accepted")35 reason = refusal(lambda: OpenAICompatibleModel("file:///v1", "model", max_tokens=8))36 print("file URL:", reason)
python adapter-refuses-unsafe-endpoints.pyredirect 302 on loopback: the endpoint answered 302 with a redirect, and the adapter does not follow redirects
redirect 307 on loopback: the endpoint answered 307 with a redirect, and the adapter does not follow redirects
requests to the redirect target: 0
loopback requests through the proxy: 0
remote request through the proxy: http://remote-host.invalid/v1/chat/completions
remote reply text: ok
key over plain http to a remote host: the adapter sends an API key over https, or over http to a loopback host only
key over https to a remote host: accepted, no request made
key over http to loopback: accepted
file URL: the scheme 'file' is not http or https
El ejemplo también muestra cada rechazo: una redirección, una clave enviada por http sin cifrar a un host remoto y una dirección de archivo. El destino de la redirección no recibe ninguna solicitud, y los otros dos casos se rechazan antes de establecer cualquier conexión. Cada rechazo imprime la regla que lo provocó.
Este capítulo no llama a ningún proveedor alojado. Si apuntas el adaptador a uno, usa https, que una clave requiere de todos modos, y aporta tu propia cuenta y clave. El libro no proporciona ninguna de las dos cosas, y sus ejemplos nunca llaman a un modelo ni a un host remoto.
Regla práctica: Analiza function.arguments como JSON, comprueba el resultado frente al modelo de argumentos de la herramienta y devuelve un fallo al modelo como resultado de la herramienta. Un endpoint que aplica un esquema estricto hace que estos fallos sean menos frecuentes, pero la comprobación se ejecuta igualmente.
Esta parte aún no está traducida, así que está en inglés.
One loop, several models
The loop does not change between adapters. It calls reply(), reads the calls from the Reply, runs the first one, and writes the result into the next step. The adapters differ in where the reply comes from and in what they do with its text, and the loop sees only the Reply each one returns.
| Adapter | Where the reply comes from | Calls are read from | Shown by |
|---|---|---|---|
ScriptedModel |
strings written in the code | the text | same-loop-two-models |
ReplayModel |
the stored replies of one run | the text | same-loop-two-models, replay-byte-for-byte |
LlamaModel |
a local GGUF file, through llama-cpp-python | the text | none; see the local model |
OpenAICompatibleModel |
an HTTP endpoint, on loopback in this book | the structured field if present, else the text | openai-compatible-loopback, adapter-refuses-unsafe-endpoints |
Each row says what an adapter does, and the last column names the examples that run it. Two examples drive ScriptedModel and ReplayModel through the loop, and two call OpenAICompatibleModel's reply() directly.
Production breaks an adapter in three places, and the reader should know which one they are looking at. The first is the transport. urllib raises on an error status, and the adapter does not catch that. The adapter refuses redirects on purpose, so a redirect raises as well. Either way no Reply exists for that step, and the run stops with the error. The second is the reply's shape: a reply can parse and still name a tool the loop does not have, and the name check in chapter 3 refuses it as a tool error. The third is the stored run. If the prompt changes, replay-byte-for-byte fails at its first assertion, before any step runs. If a later version of the loop asks a different question at some step, ReplayModel raises ReplayMismatch at that step, and the message names the step. A malformed tool call from a live model is different again: it is an expected event, and the loop counts it and shows it to the model.
What holds the loop steady is one parser and one Reply. Every adapter, live or stored, hands the loop the same fields, the text stays as the model wrote it, and a request hash stored with each reply makes a changed question fail at the step where it changed. The endpoint adapter is the one that touches a network, and its rules are the ones to re-check before it points at a real host: no redirects, no key over plain http, and the proxy for remote URLs only.
Adding a fifth adapter takes three steps. Write a class with a reply() method that takes the loop's messages and tools. Build its Reply with the same parser the others use, make_reply for text or parse_chat_body for a response body, so every adapter reads tool calls the same way. Then give it the test that the protocol section describes. The loop does not change, and neither does any other adapter.
Working rule: An adapter keeps the raw text and the counts, reads the tool calls in one place, and returns a Reply. It never hands the loop an SDK object. Give each adapter a test that calls reply() with the loop's arguments, and treat a changed prompt or a changed request as a reason to record again.
Este capítulo, en esta edición
Edición 2026.11.2Ejemplos verificados el 20 de nov de 2026Superan la prueba 4 de 4 ejemplos ejemplos de este capítulo
Traducido del libro en inglés, edición 2026.11.2.