Uma interface para modelos roteirizados, reproduzidos, locais e hospedados

Cerca de 23 minutos min de leitura, com 4 exemplos em 5 seções.

Edição 2026.11.2 Exemplos aprovados em 20 de nov de 2026 64 de 64 exemplos passam O que mudou

Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros

Traduzido do livro em inglês, edição 2026.11.2. Leia o original

Ao final deste capítulo, você será capaz de executar o mesmo loop com um modelo roteirizado, uma execução reproduzida, um modelo local e um endpoint compatível com a OpenAI, sem alterar o loop. Você também saberá dizer o que cada adaptador retém de uma resposta e o que ele lê do texto da resposta.

O capítulo 1 executou o agente de manutenção para unitcraft com um modelo roteirizado e, em seguida, com uma execução armazenada, e o loop aceitou as duas sem nenhuma alteração. A próxima pergunta é o que um modelo precisa entregar para que isso funcione. Para o T-01, o problema em que format_quantity remove zeros finais, de modo que 3.5 kg é impresso como 3.5 kg quando o padrão de duas casas dá 3.50 kg, cada passo precisa devolver as mesmas três coisas: o texto do modelo, as chamadas de ferramenta que o harness consegue ler desse texto e as contagens de tokens que a requisição e a resposta usaram. Uma lista roteirizada de strings pode fornecer as três. Também podem fazê-lo um arquivo em disco, um modelo carregado na memória ou um endpoint HTTP. O adaptador é o código que faz com que cada uma dessas fontes pareça a mesma para o loop, e o restante deste capítulo examina os quatro adaptadores na ordem em que o loop os encontra.

Faça a mesma pergunta a todos os modelos

O loop precisa de uma coisa de um modelo: dadas as mensagens até aqui e os esquemas das ferramentas do capítulo sobre esquemas, devolver o que o modelo disse. Um Protocol do Python dá nome a esse contrato. Todo adaptador deste livro tem o mesmo método, e todo adaptador devolve o mesmo tipo de valor.

class Model(Protocol):
    def reply(self, messages: list[dict], tools: list[dict]) -> Reply: ...

O Reply é um dataclass pequeno. Ele guarda o text bruto do modelo, as chamadas de ferramenta que o adaptador leu nesse texto, quaisquer blocos malformados que não pôde ler, as contagens de tokens do prompt e da completação, e o motivo de término, que indica se o modelo parou por conta própria ou se esgotou os tokens. Um token, aqui, é a unidade que o capítulo 1 conta, a partir do tokenizador do próprio modelo fixado, de modo que as contagens pertencem a esse modelo e não significam nada para outro. O adaptador nunca edita text. O loop age sobre as chamadas, mas a transcrição mantém o texto como o modelo o escreveu, para que o leitor possa ver o que o modelo de fato disse.

Manter o texto e as chamadas importa porque a análise pode falhar. Uma resposta pode conter um bloco <tool_call> cujo JSON não é analisado, ou um bloco que nunca é fechado. O adaptador não pode converter silenciosamente essa resposta em uma chamada, e não pode descartá-la, porque o loop precisa informar ao modelo o que deu errado. Assim, a análise deixa o texto como está, registra ao lado de cada bloco ruim um motivo curto, e deixa o loop decidir o que o modelo verá em seguida. A seção sobre o modelo local mostra o analisador em funcionamento.

Um Protocol parece uma interface, mas o Python o verifica pela estrutura. A documentação do módulo typing do Python diz que um protocolo runtime_checkable "verificará apenas a presença dos métodos ou atributos exigidos, não as suas assinaturas de tipo ou os tipos". Assim, isinstance pode confirmar que um objeto tem um método reply, e nada mais: uma classe cujo método está escrito como reply(self, prompt) passa, e uma classe sem nenhum reply falha. O Model do próprio livro não é decorado com runtime_checkable, e a mesma documentação diz que isinstance em um protocolo desse tipo levanta um TypeError. Nenhum exemplo deste livro chama isinstance em Model, de modo que as duas afirmações são da documentação e não foram executadas aqui.

Regra prática: Teste cada adaptador chamando reply() com as mensagens e os esquemas de ferramentas que o loop envia, e confira os campos do Reply devolvido. Use isinstance apenas para verificar que um método existe, nunca para mostrar que sua assinatura está correta.

Use um roteiro de respostas, ou reproduza uma execução armazenada

Dois adaptadores não precisam de modelo algum. A execução com roteiro do capítulo 1 usou um modelo com roteiro, e a execução reproduzida usou um modelo armazenado. Os dois funcionam pelo mesmo motivo: o loop é o que está sob teste, e uma lista fixa de respostas mantém o modelo fora dele. Esta seção explica o que os adaptadores acrescentam a isso.

ScriptedModel aceita strings ou objetos Reply. Uma string é convertida em um Reply para você, e suas chamadas de ferramenta são lidas dos blocos <tool_call> no texto. Um objeto Reply é repassado sem alterações. Essa segunda forma permite que um teste defina diretamente as contagens de tokens ou uma entrada malformada, em vez de escrever JSON que precisa falhar exatamente do jeito certo. Se o loop pedir mais respostas do que o roteiro contém, o modelo lança um IndexError, de modo que um roteiro curto falha de forma explícita, em vez de devolver nada. O roteiro também mantém o teste legível. A resposta que provoca um comportamento fica no teste, ao lado da asserção sobre ele, e você não precisa abrir uma gravação para encontrá-la.

ReplayModel lê as linhas de uma execução a partir do replies.jsonl da gravação, na ordem dos passos. Cada linha contém o hash da requisição como foi enviada, o texto da resposta e as contagens de tokens. Quando o loop pede um passo, ReplayModel calcula o hash da requisição que recebeu, o sha256 de suas mensagens e esquemas de ferramentas em JSON canônico, e compara esse hash com o da linha. Uma diferença lança um ReplayMismatch, que indica o passo. As contagens vêm da linha armazenada, de modo que uma reprodução nunca tokeniza novamente.

As linhas vêm de um registrador, não de um roteiro. LoggedModel envolve um modelo ativo e acrescenta cada resposta a um arquivo no formato JSON Lines antes que o loop a veja. Uma execução que para no meio deixa suas linhas no disco, e o script de gravação as remove antes de retomar.

A execução T-01 do capítulo 1 passa pelo loop duas vezes no primeiro exemplo: uma vez com um ScriptedModel que contém os textos de respostas armazenados, e outra vez com o ReplayModel para a mesma execução. As respostas do roteiro são lidas do arquivo armazenado, de modo que as duas execuções partem da mesma fonte.

same-loop-two-models.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""Chapter-1-t01 runs through the loop twice: once with a ScriptedModel holding the stored reply texts, once with aReplayModel. The assert compares the two runs' step lines, and the lines printed below are the replayed run's."""import jsonfrom lib.case import load_tasksfrom lib.loop import run_taskfrom lib.models import RECORDED, ReplayModel, ScriptedModelfrom lib.tools import CH1from lib.trace import IdCountertask = load_tasks(only=["T-01"])[0]rows = [json.loads(line) for line in (RECORDED / "chapter-1-t01" / "replies.jsonl").read_text(encoding="utf-8").splitlines()]def run_once(model):    run = run_task(model, task, CH1, max_steps=CH1.step_cap, ids=IdCounter())  # counter-based IDs, never random (P-3)    try:        return list(run.trace.lines()), run.steps, run.ended    finally:        run.close()scripted = run_once(ScriptedModel([row["text"] for row in rows]))replayed = run_once(ReplayModel("chapter-1-t01", "T-01"))assert scripted == replayed, "the two adapters gave the loop different steps"lines, steps, ended = replayedfor line in lines:    print(line)print(f"steps: {steps}")print(f"ended: {ended}")
Saídapython same-loop-two-models.py
step 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

O loop fez as mesmas chamadas nas duas vezes, e o exemplo para se as duas execuções diferirem em qualquer linha de passo. A execução é a que atingiu o limite de passos no capítulo 1: terminou como step_cap após 8 passos. O loop não consegue distinguir os dois adaptadores, de modo que, o que quer que ele faça com uma resposta, faz o mesmo para qualquer uma das fontes.

O segundo exemplo verifica a própria gravação, em relação ao seu manifesto, e depois a reproduz.

replay-byte-for-byte.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""The stored chapter-1 run is the recording its manifest describes, and replaying it hands the loop each stored reply textexactly. The prompt and the check hash to the manifest's values, the first request hashes to the reply row stored with it,and the stored replies add up to the manifest's counts. The run is then replayed through the loop, which refuses any requestthat differs from its recorded hash, and each replayed text is compared with its stored text. No model file is loaded."""from contextlib import closingfrom lib.case import load_tasksfrom lib.loop import run_taskfrom lib.models import RECORDED_SAMPLING, ReplayModel, TextCapture, first_step, load_recording, request_hash, same_texts, stored_totalsfrom lib.prompts import prompt_sha256from lib.tasks import check_sha256from lib.tools import CH1from lib.trace import IdCountertask = load_tasks(only=["T-01"])[0]manifest, rows = load_recording("chapter-1-t01")messages, tools = first_step(task, CH1)assert manifest["prompt_sha256"] == prompt_sha256(CH1.system, CH1.descriptions()), "the prompt changed since recording"assert manifest["check_sha256"] == check_sha256(task), "the check changed since recording"assert rows[0]["request_sha256"] == request_hash(messages, tools), "the first request differs from the stored reply row"assert len(rows) == manifest["steps"], "the stored replies and the manifest disagree on the step count"prompt_tokens, completion_tokens = stored_totals(manifest, rows)assert manifest["sampling"] == RECORDED_SAMPLING, "the recording's sampling differs from the settings the adapters send"capture = TextCapture(ReplayModel("chapter-1-t01", "T-01"))with closing(run_task(capture, task, CH1, max_steps=CH1.step_cap, ids=IdCounter())) as run:    steps, ended = run.steps, run.endedcompared = same_texts(rows, capture.texts)assert steps == manifest["steps"] and ended == manifest["ended"], "the replay did not end as the manifest records"print(f"stored replies: {len(rows)}")print(f"prompt tokens: {prompt_tokens}")print(f"completion tokens: {completion_tokens}")for key in ("temperature", "top_k", "seed"):    print(f"{key}: {manifest['sampling'][key]}")print(f"reply texts compared exactly: {compared}")print(f"steps: {steps}")print(f"ended: {ended}")
Saídapython replay-byte-for-byte.py
stored 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

Aqui o manifesto é a referência, e o exemplo faz quatro verificações. O hash do prompt e o hash da verificação são comparados com os valores do manifesto, sendo que a verificação é o teste oculto H-01, com o qual o capítulo 1 avalia T-01. O hash da primeira requisição é comparado com o que está armazenado em sua linha de resposta em replies.jsonl, porque o manifesto não contém hash de requisição. As respostas armazenadas devem corresponder à contagem de passos e aos totais de tokens do manifesto, e as configurações de amostragem são impressas a partir do manifesto e comparadas com RECORDED_SAMPLING na biblioteca, os valores que loopback_model envia. A execução armazenada tem 8 respostas, 13009 tokens de prompt e 2128 tokens de conclusão. O exemplo imprime as suas configurações de amostragem em linhas próprias, para que você veja a temperatura, o top k e a semente que a gravação usou.

Em seguida, a execução passa pelo loop. ReplayModel recusa qualquer passo cujo hash de requisição difira do de sua linha, e o exemplo compara cada texto reproduzido com o texto armazenado, de forma exata. Ele imprime a quantidade comparada, 8, e a execução termina como o manifesto indica. O manifesto não contém hash para cada resposta, portanto os textos armazenados não são verificados contra um valor independente. A verificação mostra que a reprodução entrega ao loop cada texto armazenado sem alterações. O hash do prompt cobre a mensagem de sistema e as descrições das ferramentas em conjunto, de modo que uma descrição de ferramenta alterada muda a identidade da gravação com a mesma certeza com que uma linha de código alterada a muda.

Regra prática: Reproduza uma execução gravada somente com o prompt e a verificação com que ela foi gravada. Quando qualquer um deles mudar, o hash dela no manifesto deixa de corresponder, o exemplo falha e a execução precisa ser gravada novamente. Alterar uma resposta armazenada para que o exemplo passe oculta a mudança que causou a falha.

Um modelo local, e por que suas configurações são fixas

LlamaModel executa um modelo local. Ele carrega um arquivo GGUF, o formato de arquivo único que o llama.cpp lê, por meio do llama-cpp-python. O adaptador importa a biblioteca somente quando um modelo é construído, de modo que os exemplos nunca a carregam. Nenhum exemplo carrega o arquivo GGUF, e o livro não tem nenhum teste de LlamaModel. A gravação o usou, e os exemplos leem as respostas que a gravação armazenou. Seu reply() chama create_chat_completion com as mensagens e as ferramentas, e lê o texto e o uso a partir da resposta.

Os padrões da biblioteca não são os do livro. Na versão fixada, o create_chat_completion do llama-cpp-python usa temperatura de 0.2 e top k de 40 por padrão. Um adaptador que deixe esses valores como estão amostra de forma diferente deste. LlamaModel passa temperature=0 e top_k=1 em cada chamada, de modo que a amostragem está escrita no código, e não herdada da biblioteca.

O que volta é texto. O servidor da gravação executou o llama-cpp-python fixado como python -m llama_cpp.server sobre o mesmo arquivo de modelo, e devolveu a chamada de ferramenta do primeiro passo dentro do conteúdo da mensagem. O corpo armazenado de a gravação do endpoint tem esse conteúdo e nenhum campo tool_calls:

<tool_call>
{"name": "read_file", "arguments": {"path": "unitcraft/format.py"}}
</tool_call>

Assim, a resposta da biblioteca carrega a chamada como texto, e LlamaModel não lê dela um campo estruturado. Ele analisa o texto.

A análise é feita por uma função, parse_tool_calls. Ela encontra cada bloco <tool_call>, lê-o como JSON com um name e um objeto arguments, e mantém a chamada. Um bloco que não é analisado torna-se uma entrada malformada, com um motivo curto. O laço mostra essa entrada ao modelo como um erro de ferramenta, de modo que uma chamada ruim fica registrada como um passo e não é descartada. A execução T-01 do Capítulo 1, em o que dá errado, mostra isso: depois de seus dois primeiros passos, todo passo é error: malformed call.

O motivo de término importa para o laço. stop significa que o modelo encerrou sua resposta, e length significa que a resposta atingiu o limite de tokens definido pelo adaptador. Uma resposta com length pode parar no meio de um bloco <tool_call>, e por isso o analisador também informa um bloco não fechado como malformado, em vez de lê-lo como completo.

As contagens são as próprias da biblioteca. LlamaModel copia para o Reply as contagens de tokens do prompt e da completação que o llama-cpp-python informa, e a gravação as armazena. Elas descrevem o tokenizador do arquivo fixado, de modo que um arquivo diferente produz contagens diferentes para as mesmas mensagens, e uma contagem de um modelo não pode ser comparada com a de outro.

O construtor recebe o caminho do arquivo, o tamanho do contexto, o número de threads, a semente e o limite de tokens, e nada mais sobre o modelo. A gravação lê seus valores de recordings/local_model.py, de modo que um leitor que queira carregar outro arquivo altera o caminho e essas configurações juntos, e grava novamente. A amostragem é uma escolha, e o cartão do modelo recomenda outra. O cartão do modelo Qwen diz: "Sugerimos usar Temperature=0.7, TopP=0.8, TopK=20 e MinP=0." Essas configurações servem para respostas que variam de uma execução para outra. Este livro grava uma execução uma vez e confere execuções posteriores contra as respostas armazenadas, de modo que usa temperatura 0, top k 1 e uma semente fixa, 4217, como os manifestos registram. Essas configurações dão a uma nova gravação a melhor chance de coincidir, mas temperatura 0 não garante que a saída se repita, e por isso o livro não afirma mais do que seus exemplos mostram. O exemplo do endpoint confere que duas requisições em uma mesma gravação deram o mesmo texto. A reprodução não depende de amostragem alguma, porque lê o texto armazenado.

Regra prática: Grave com a amostragem que o manifesto nomeia, e mantenha o hash do arquivo do modelo no manifesto, ao lado dela. Se você alterar uma configuração, as respostas mudam com ela, então grave a execução novamente em vez de compará-la com a anterior.

Um endpoint no estilo hospedado, testado em loopback

Um servidor que aceita o formato de requisição de chat completions da OpenAI pode ser acessado por um único adaptador, dado um URL base e, quando o host exigir, uma chave. OpenAICompatibleModel envia as mensagens, os esquemas das ferramentas e as configurações de amostragem para /chat/completions. Ele usa o urllib da biblioteca padrão e nenhum SDK. Sem um SDK, nada oculta a requisição: request_body() devolve o corpo que o adaptador serializa e envia, e um teste pode compará-lo com o que foi gravado. O campo top_k é enviado somente quando o adaptador recebeu um valor para ele. O adaptador recusa duas coisas ao ser construído, antes de qualquer requisição: um URL que não seja http ou https, e uma chave enviada por http simples a qualquer host que não seja loopback. Ele também nunca segue um redirecionamento. Um redirecionamento gera um erro, de modo que a chave nunca é enviada a um segundo URL.

A resposta contém a chamada da ferramenta em um de dois lugares. A referência da OpenAI descreve o function.arguments de uma chamada de ferramenta como uma string que o modelo gera em JSON, e orienta quem chama a "Valide os argumentos no seu código antes de chamar sua função." O adaptador interpreta essa string quando a resposta tem um campo estruturado tool_calls. Quando o campo está ausente, ele recorre ao texto <tool_call>, como faz o modelo local. parse_chat_body mantém message.content como o servidor o enviou, trata um conteúdo ausente como texto vazio e copia as contagens de uso para o Reply, de modo que um corpo armazenado é interpretado sempre como o mesmo Reply. Em qualquer dos casos, os argumentos chegam ao loop como um dicionário, e o dicionário ainda não é verificado. O modelo de argumentos da ferramenta, do capítulo sobre esquemas, faz essa verificação.

Nenhum exemplo deste livro envia uma requisição que devolva um campo estruturado tool_calls, por isso o primeiro ramo existe como código e nenhum exemplo o executa. O livro não mostra o que outros provedores devolvem nesse campo, e este capítulo não diz mais do que a referência da OpenAI diz sobre ele.

A gravação usou o mesmo arquivo e a mesma amostragem do modelo local. Ela executou o próprio servidor do llama-cpp-python fixado, em loopback, e enviou o primeiro passo do T-01 pelo adaptador duas vezes. O arquivo armazenado guarda cada requisição como foi enviada e cada corpo de resposta bruto. Um http.server de loopback serve esses corpos na ordem e responde 409 a qualquer requisição cujo corpo difira do gravado. O stub compara o corpo da requisição, cada mensagem e cada configuração. Ele não compara o caminho, o método nem os cabeçalhos, de modo que uma mudança no caminho do endpoint ou no cabeçalho Authorization passaria. Se uma mudança no adaptador alterar o corpo que ele envia, a requisição falha antes que qualquer resposta seja lida. Os corpos armazenados mantêm os campos id e created do próprio servidor. Nada os compara nem os imprime. Como nenhum modelo é carregado, o código HTTP e de interpretação do adaptador é executado sempre que os exemplos do livro são verificados.

openai-compatible-loopback.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""The OpenAI-compatible adapter, run live against a loopback stub that serves the bodies recorded from llama.cpp's ownserver. The line that matters is "raw text": the server put the call in the message content as text, with no tool_callsfield, so the adapter parses the text, and the tool's own model accepts the arguments. Needsrecordings/openai_compatible.py to have been run; until then this raises."""import jsonfrom lib.case import load_tasksfrom lib.models import first_step, loopback_model, serve_recordedfrom lib.tools import CH1task = load_tasks(only=["T-01"])[0]messages, tools = first_step(task, CH1)bodies: list[str] = []with serve_recorded("openai-compatible") as base_url:    model = loopback_model(base_url, on_body=bodies.append)    first = model.reply(messages, tools)    second = model.reply(messages, tools)assert first.text.lstrip().startswith("<tool_call>"), "the server should return the call as text"assert "tool_calls" not in json.loads(bodies[0])["choices"][0]["message"], "the recorded body has a structured tool_calls field"assert len(first.tool_calls) == 1 and first.tool_calls[0]["name"] == "read_file", "the first step is one read_file call"assert not first.malformed, "the call should parse"CH1.get("read_file").args.model_validate(first.tool_calls[0]["arguments"])  # raises if the arguments do not fit the toolassert first.text == second.text, "the two recorded responses differ"print(f"requests: {len(bodies)}")print("raw text:", json.dumps(first.text))print("structured tool_calls field: absent")print(f"tool calls: {len(first.tool_calls)}")print("call:", first.tool_calls[0]["name"], json.dumps(first.tool_calls[0]["arguments"], sort_keys=True))print(f"malformed: {len(first.malformed)}")print(f"prompt tokens: {first.prompt_tokens}")print(f"completion tokens: {first.completion_tokens}")print(f"finish reason: {first.finish_reason}")
Saídapython openai-compatible-loopback.py
requests: 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

O adaptador recebe de volta uma chamada read_file, como texto. Verificar os argumentos contra o modelo da ferramenta cabe a quem chama, e essa verificação é o ponto central desta seção, por isso o exemplo a torna explícita. A resposta contém 1 chamada de ferramenta e 0 blocos malformados, e a requisição usou 501 tokens de prompt. A resposta termina com stop, o que significa que o modelo concluiu a resposta por conta própria e não ficou sem tokens.

O auxiliar que monta o adaptador para as gravações e para o exemplo, loopback_model, fixa o alias do modelo com que o servidor foi iniciado, um limite de 1024 tokens para cada resposta, temperatura 0 e top_k 1. Quem quiser outras configurações cria OpenAICompatibleModel diretamente, e o corpo da requisição enviado então difere, o que o stub recusará.

O proxy funciona como funciona para qualquer requisição urllib, exceto para os hosts de loopback, 127.0.0.1, ::1 e localhost, que são acessados diretamente. Um URL http remoto passa pelo proxy que o ambiente indica. Um stub substitui o proxy no exemplo de recusas, e ele mostra as duas metades: as requisições de loopback nunca chegam a ele, e a requisição remota chega com o URL completo.

adapter-refuses-unsafe-endpoints.py Python 3.12.15 Aprovado
"""The OpenAI-compatible adapter refuses a redirect, a key over plain http to a remote host, and a non-http scheme. It sendsa remote URL through the environment's proxy and a loopback URL around it. Every request goes to a stub on 127.0.0.1, whichstands in for both the endpoint and the proxy, so no network is used. Each refusal prints one labelled line."""from lib.models import OpenAICompatibleModel, proxy_env, refusal, stub_endpointREMOTE = "http://remote-host.invalid/v1"MESSAGES = [{"role": "user", "content": "ping"}]with stub_endpoint(200) as proxy, stub_endpoint(302) as target, proxy_env(proxy):    loopback = f"{target.url}/v1"    model = OpenAICompatibleModel(loopback, "model", max_tokens=8, api_key="DUMMY-KEY")    reason = refusal(lambda: model.reply(MESSAGES, []))    assert target.seen == ["/v1/chat/completions"], "a redirect was followed"    print("redirect 302 on loopback:", reason)    target.code = 307    reason = refusal(lambda: model.reply(MESSAGES, []))    print("redirect 307 on loopback:", reason)    assert target.seen == ["/v1/chat/completions"] * 2, "a redirect was followed"    print(f"requests to the redirect target: {target.seen.count('/collect')}")    print(f"loopback requests through the proxy: {len(proxy.seen)}")    remote = OpenAICompatibleModel(REMOTE, "model", max_tokens=8)    reply = remote.reply(MESSAGES, [])    assert reply.text == "ok" and proxy.seen == ["http://remote-host.invalid/v1/chat/completions"]    print("remote request through the proxy:", proxy.seen[0])    print("remote reply text:", reply.text)    reason = refusal(lambda: OpenAICompatibleModel(REMOTE, "model", max_tokens=8, api_key="DUMMY-KEY"))    print("key over plain http to a remote host:", reason)    assert len(proxy.seen) == 1, "a request was made for the refused key"    OpenAICompatibleModel("https://remote-host.invalid/v1", "model", max_tokens=8, api_key="DUMMY-KEY")    print("key over https to a remote host: accepted, no request made")    OpenAICompatibleModel(loopback, "model", max_tokens=8, api_key="DUMMY-KEY")    print("key over http to loopback: accepted")    reason = refusal(lambda: OpenAICompatibleModel("file:///v1", "model", max_tokens=8))    print("file URL:", reason)
Saídapython adapter-refuses-unsafe-endpoints.py
redirect 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

O exemplo também mostra cada recusa: um redirecionamento, uma chave enviada por http simples a um host remoto e um endereço de arquivo. O destino do redirecionamento não recebe nenhuma requisição, e as outras duas são recusadas antes de qualquer conexão ser feita. Cada recusa imprime a regra que a causou.

Este capítulo não chama nenhum provedor hospedado. Se você apontar o adaptador para um deles, use https, que uma chave exige de qualquer forma, e traga sua própria conta e sua própria chave. O livro não fornece nenhuma das duas, e seus exemplos nunca chamam um modelo nem um host remoto.

Regra prática: Interprete function.arguments como JSON, verifique o resultado contra o modelo de argumentos da ferramenta e envie uma falha de volta ao modelo como resultado da ferramenta. Um endpoint que impõe um esquema estrito torna essa falha menos comum, mas a verificação continua sendo feita.

Esta parte ainda não foi traduzida, por isso está em 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, nesta edição

Edição 2026.11.2Exemplos aprovados em 20 de nov de 20264 de 4 exemplos exemplos deste capítulo passam

Traduzido do livro em inglês, edição 2026.11.2.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 4 de 12: Uma interface para modelos roteirizados, reproduzidos, locais e hospedados

  1. Faça a mesma pergunta a todos os modelos
  2. Use um roteiro de respostas, ou reproduza uma execução armazenada
  3. Um modelo local, e por que suas configurações são fixas
  4. Um endpoint no estilo hospedado, testado em loopback
  5. One loop, several models

Voltar ao topoTodos os capítulos