As páginas sem tradução abrem em inglês e são identificadas como inglês.
Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.
Configurar modelos e chaves de API
Seu agente de código, o LLM interno do Loom e o modelo de embeddings do Loom são escolhas separadas. Você pode conectar o Claude Code a um servidor Loom que usa modelos da OpenAI, ou o Codex a um servidor que usa Claude. O agente não precisa usar o mesmo provedor que o Loom.
| Escolha | O que faz | Onde configurar |
|---|---|---|
| Seu agente: Claude Code, Codex ou outro cliente | Executa seu fluxo de trabalho de código ou de assistente e chama as ferramentas do Loom. | No próprio cliente; conecte-o com um token do Loom. |
| LLM do Loom | Extrai fatos, resume sessões e gera respostas dentro do Loom. | As configurações de provedor, modelo e chave de API do servidor. |
| Modelo de embeddings do Loom | Torna memórias, documentos e código pesquisáveis por significado. | O modelo de embeddings, as dimensões e a chave do provedor no servidor. |
LOOM_API_KEY é um token para acessar o Loom. Ele é diferente de
OPENAI_API_KEY, ANTHROPIC_API_KEY e GEMINI_API_KEY, que pagam pelas chamadas de modelo do
servidor. Mantenha as chaves dos provedores no servidor; conectar um agente não transfere as credenciais
de assinatura nem as chaves de API dele para o Loom.
O que funciona sem chaves de provedor?
A instalação Docker lançada faz embeddings com local (bge-small, 384 dimensões, em CPU, a partir de arquivos que a imagem já traz) e seleciona o LLM fake-echo-1, a menos que o instalador tenha configurado um servidor de modelo local (um servidor de modelo na sua máquina). Ela inicia sem chaves de provedor e sem rede: o armazenamento, o painel, a indexação estrutural de código e a busca semântica funcionam, embora um embedder hospedado recupere melhor em perguntas com muita paráfrase. O LLM falso não produz fatos extraídos, resumos nem respostas geradas que façam sentido. O .env de um checkout seleciona os embeddings fake-ngram-3072, que correspondem por sobreposição de caracteres. Uma instalação atualizada mantém o embedder indicado no seu ~/.loom/.env; trocá-lo para local é uma mudança de modelo como qualquer outra e gera novamente os embeddings do que está armazenado.
Para uma recuperação mais forte em conteúdo com muita paráfrase, configure um provedor de embeddings hospedado. Para extração automática de fatos, resumos e respostas geradas, configure também um LLM. Um LLM sozinho não substitui um modelo de embeddings; um modelo de embeddings sozinho não gera respostas. Sem nenhum embedding configurado, o servidor de um checkout usa seu embedder falso; ele não deixa de gerar embeddings.
Alguns provedores hospedados também recorrem a versões falsas quando a chave está ausente. Verifique fake_embedding, fake_llm, providers_degraded e problems em /v1/health, depois salve e recupere um fato de teste e experimente uma resposta. Uma chave inválida ou um modelo inacessível ainda pode fazer as chamadas ao provedor falharem; um servidor em execução não é prova de que o acesso ao modelo funciona. Use LOOM_REQUIRE_REAL_PROVIDERS=true em implantações baseadas em variáveis de ambiente para que provedores falsos ou sem chave passem a ser uma condição de saúde degradada.
Escolha uma configuração
| O que sua organização tem | LLM do Loom | Embeddings |
|---|---|---|
| Acesso à API da OpenAI | Um modelo da OpenAI disponível | OpenAI; uma única chave de API pode atender às duas funções. |
| Anthropic mais um provedor de embeddings aprovado | Um modelo Claude disponível | OpenAI, Gemini ou um endpoint compatível, com a respectiva chave. |
| Acesso apenas à API da Anthropic | Um modelo Claude disponível | Adicione um provedor de embeddings e a respectiva chave de API. |
| Nenhuma chave de provedor; um servidor de modelos na máquina | Um modelo local (local) |
O embedder local que a imagem inclui. |
Uma única chave de API da OpenAI é suficiente para as duas funções; uma chave da Anthropic não é necessária. Em Models & keys, escolha um LLM principal e deixe as substituições por tarefa em branco. Todas as tarefas de LLM habilitadas usam esse modelo, incluindo verificação e avaliação. As substituições avançadas são opcionais e exigem a chave de outro provedor somente quando você seleciona um explicitamente.
Escolha OpenAI, Google Gemini ou um endpoint de embeddings compatível com a OpenAI. Os embeddings da OpenAI usam
um modelo de embeddings, como text-embedding-3-large, e não um modelo de chat GPT.
O Claude pode executar as tarefas de LLM do Loom, mas exige um provedor de embeddings e uma chave separados.
A Anthropic não oferece um modelo de embeddings próprio; a Voyage não é um provedor integrado do Loom.
Orientações de embeddings da Anthropic
As tarefas internas de modelo do Loom usam chaves de API de provedores, não logins de CLI de agentes de código nem credenciais de assinatura. A escolha de provedor do seu agente externo é independente.
Definir a configuração do servidor
Recomendado: usar o painel
Como administrador da plataforma, abra Settings → Models & keys (também disponível durante o Setup).
Escolha seu provedor de LLM e de embeddings, informe os IDs dos modelos e as chaves de API e, em seguida, clique em
Test & apply. Deixe os overrides por job em branco para usar um único LLM em todos os jobs habilitados.
As configurações salvas no painel substituem o ambiente e são criptografadas no ClickHouse.
Não é necessário reiniciar o Docker nem executar um comando do Compose. As atualizações de chave e de LLM são aplicadas em tempo real;
as mudanças de embedding iniciam a reconstrução descrita abaixo. Use environment
configuration remove esses overrides e restaura as configurações de inicialização deste servidor;
isso não recarrega um arquivo .env editado. Alterar o espaço de embeddings exige uma reconstrução.
As opções de embedding do painel são provedores hospedados. Para manter o embedder
local da stack lançada e adicionar um LLM real, defina apenas as linhas do LLM em ~/.loom/.env
(Claude para o LLM mostra quais são) e recrie o contêiner: o
espaço de embeddings não muda, então nada é reindexado.
Nas mudanças de embedding feitas pelo painel, o Loom enfileira a reconstrução automaticamente e mantém
as requisições do plano de dados pausadas até que a verificação, a publicação e a limpeza terminem.
Models & keys mostra a fase e o progresso; um job que falhou permanece pausado e oferece
nova tentativa a partir do cursor salvo. Mantenha o volume do ClickHouse e o
LOOM_JWT_SECRET original, que protege as chaves de provedor armazenadas, ao recriar os contêineres. As reconstruções fazem chamadas ao provedor e podem
levar tempo e gerar custos proporcionais ao conteúdo indexado. A reconstrução publica
apenas em tabelas MergeTree locais. A primeira escolha de embedding em uma instalação sem
vetores armazenados, como uma instalação nova que ainda não armazenou nada, muda
diretamente, sem reconstrução. Quando já existem vetores em armazenamento replicado ou compartilhado,
como o ClickHouse Cloud, Models & keys bloqueia
os campos de embedding e o servidor recusa uma mudança de embedding antes de pausar
qualquer coisa: altere o modelo de embedding no ambiente e reindexe cada
índice conforme descrito acima. A recuperação de processos remotos perdidos continua sendo uma limitação documentada em
reconfiguração de provedores.
As configurações de token são separadas: elas configuram o acesso dos agentes ao Loom, não as credenciais do provedor de modelos.
Alternativa: configurar o ambiente
Em implantações automatizadas, edite ~/.loom/.env (ou o diretório selecionado com
LOOM_INSTALL_DIR). Em um checkout do código-fonte, edite o .env do repositório.
Substitua as entradas existentes em vez de acrescentar chaves duplicadas. Essas configurações são a
base de inicialização; os overrides salvos no painel têm precedência. As edições no ambiente exigem
a recriação do contêiner ou a reinicialização do servidor nativo, conforme descrito abaixo.
OpenAI para as duas funções
LOOM_LLM_PROVIDER=openai
LOOM_LLM_MODEL=gpt-6-luna
OPENAI_API_KEY=<your OpenAI API key>
LOOM_EMBEDDING_PROVIDER=openai
LOOM_EMBEDDING_MODEL=text-embedding-3-large
LOOM_EMBEDDING_DIM=3072
LOOM_REQUIRE_REAL_PROVIDERS=true
Os exemplos usam os modelos padrão que acompanham o Loom. Escolha um modelo habilitado para a sua conta de API. Definir apenas uma chave não altera a configuração padrão do instalador, que nomeia seus provedores explicitamente (o embedder local e o LLM fake).
Claude para o LLM
LOOM_LLM_PROVIDER=anthropic
LOOM_LLM_MODEL=claude-haiku-4-5
ANTHROPIC_API_KEY=<your Anthropic API key>
LOOM_REQUIRE_REAL_PROVIDERS=true
Em seguida, escolha uma configuração de embeddings:
# OpenAI embeddings
LOOM_EMBEDDING_PROVIDER=openai
LOOM_EMBEDDING_MODEL=text-embedding-3-large
LOOM_EMBEDDING_DIM=3072
OPENAI_API_KEY=<your OpenAI API key>
# Or Gemini embeddings
LOOM_EMBEDDING_PROVIDER=gemini
LOOM_EMBEDDING_MODEL=gemini-embedding-001
LOOM_EMBEDDING_DIM=3072
GEMINI_API_KEY=<your Gemini API key>
Para outro serviço que implemente a API de embeddings da OpenAI, configure a raiz da API, o ID do modelo e a largura nativa de saída:
LOOM_EMBEDDING_PROVIDER=compatible
LOOM_EMBEDDING_BASE_URL=https://embedding-provider.example/v1
LOOM_EMBEDDING_MODEL=your-embedding-model
LOOM_EMBEDDING_DIM=768
LOOM_EMBEDDING_API_KEY=<your embedding provider API key>
# Enable only if the endpoint accepts the optional dimensions parameter:
LOOM_EMBEDDING_SEND_DIMENSIONS=false
A URL base é a raiz da API; o Loom acrescenta /embeddings. Use HTTPS para serviços
remotos. HTTP é aceito para endpoints privados autohospedados, mas transmite a
chave e o conteúdo sem criptografia. A compatibilidade exige respostas indexadas com arrays de floats
da largura configurada; um provedor que use outra API precisa de um adaptador próprio.
Alterar o endpoint, o modelo ou a largura exige reconstruir os embeddings existentes.
Se a sua organização tem hoje apenas acesso à API da Anthropic, obtenha acesso a um provedor de embeddings antes de habilitar a busca semântica.
Manter todos os jobs de LLM no provedor escolhido
O Loom permite usar modelos diferentes para jobs diferentes, mas você não precisa de contas em
vários provedores de LLM. Adicione estas configurações depois de LOOM_LLM_MODEL para que os jobs
normalmente específicos de um provedor usem o modelo que você selecionou:
LOOM_MEMORY_EXTRACT_VERIFY_MODELS=${LOOM_LLM_MODEL}
LOOM_SESSION_BRIEF_LLM_MODEL=
LOOM_CODE_BISECT_LLM_RERANK_MODEL=
LOOM_TRACKER_DUPCHECK_RERANK_MODEL=
LOOM_RETRIEVAL_JUDGE_MODEL=
O Compose e o carregador de dotenv do Loom expandem o modelo do verificador a partir da entrada anterior. Os valores vazios acima herdam o LLM principal. Isso mantém o verificador de captura habilitado; uma lista de verificadores vazia o desabilitaria. Remova quaisquer outros overrides de modelo entre provedores que você tenha adicionado antes, incluindo modelos de fallback, de síntese e de reranking.
Essas configurações importam: alguns padrões avançados incluídos nomeiam explicitamente modelos da Claude ou da OpenAI, e um override sem chave de provedor pode recorrer ao cliente fake. Usar um único modelo em todos os jobs é uma configuração de conveniência, não a configuração por trás de cada benchmark publicado. Ajuste jobs individuais depois usando modelos por job.
Um servidor de modelos na sua máquina, sem chave de API
LOOM_LLM_PROVIDER=local executa os jobs de LLM do Loom em um servidor de chat-completions que você mantém:
página do Ollama, o llama-server do llama.cpp ou qualquer servidor que fale o
formato de chat-completions da OpenAI. O Loom não envia nenhuma chave a ele. Com o embedder local da
stack lançada, nada sai da máquina.
Uma instalação nova executada em um terminal oferece isso quando o Ollama responde em localhost:11434;
LOOM_LOCAL_MODELS=ollama antes de sh loom-install.sh define isso sem perguntar, em
uma instalação nova ou em uma existente, e LOOM_LOCAL_MODELS=off nunca oferece. Ele grava:
LOOM_LLM_PROVIDER=local
LOOM_LLM_MODEL=qwen2.5:3b
LOOM_LOCAL_LLM_BASE_URL=http://host.docker.internal:11434/v1
LOOM_ASSISTANT_PROVIDER=local
LOOM_ASSISTANT_MODEL=qwen2.5:3b
LOOM_ASSISTANT_ANSWER_CEILING_USD=0
LOOM_MEMORY_EXTRACT_VERIFY_MODELS=
LOOM_MEMORY_CONFLICT_RESOLVER_ENABLED=false
LOOM_LLM_REQUEST_TIMEOUT_S=900
LOOM_LLM_RETRY_ATTEMPTS=1
LOOM_EXTRACTION_QUEUE_MAX_BATCHES_PER_PASS=1
LOOM_EXTRACTION_QUEUE_MAX_PASS_SECONDS=3600
LOOM_EXTRACTION_QUEUE_MAX_ATTEMPTS=2
LOOM_ENTITY_EXTRACT_ENABLED=false
LOOM_SESSION_BRIEF_LLM_MODEL=
LOOM_CODE_BISECT_LLM_RERANK_MODEL=
LOOM_TRACKER_DUPCHECK_RERANK_MODEL=
LOOM_RETRIEVAL_JUDGE_MODEL=
O preset desativa os dois jobs que removem fatos com base no julgamento de um modelo, cujos
limites foram definidos em modelos hospedados: o verificador de captura, que descarta um fato que todos
os modelos verificadores consideram não durável, e o
resolvedor de conflitos em segundo plano,
que aposenta uma linha mais antiga que ele julga ter sido substituída. Um julgamento errado de um modelo pequeno nesses jobs
faria perder fatos. As gravações continuam sinalizando conflitos para a fila de Review; defina
LOOM_MEMORY_CONFLICT_RESOLVER_ENABLED=true com a chave de
LOOM_CONFLICT_RESOLVER_MODEL (gpt-6.1-sol, OpenAI) para julgá-los. Em uma instalação
existente, uma configuração salva em Models & keys prevalece sobre o .env: após a reinicialização,
escolha Use environment configuration ali para que o preset seja aplicado.
Baixe o modelo primeiro (ollama pull qwen2.5:3b, cerca de 2 GB) e dê ao Ollama uma janela de contexto
que comporte os prompts do Loom: a extração envia cerca de 15,000 tokens, e o Ollama corta um
prompt mais longo para caber na janela sem emitir erro, então execute-o com
OLLAMA_CONTEXT_LENGTH=32768 (a janela que o qwen2.5 aceita). Uma CPU pode levar minutos para
ler um prompt tão longo, por isso o preset espera LOOM_LLM_REQUEST_TIMEOUT_S=900 segundos por
uma resposta, em vez dos 300 padrão dos modelos hospedados, e tenta uma única vez
(LOOM_LLM_RETRY_ATTEMPTS=1): um servidor que estourou o tempo limite não responde mais rápido na segunda vez.
O worker que reprocessa as capturas enviadas pelos plugins de codificação dá um prazo a cada passada, então
o preset permite que uma passada de extração adiada dure uma hora em um único lote
(LOOM_EXTRACTION_QUEUE_MAX_PASS_SECONDS, por padrão quatro dos seus intervalos, no mínimo 60 s
e no máximo 900; o lease de um lote é mantido pelo menos um minuto a mais). Em um provedor local,
uma captura interrompida (nesse prazo ou pelo desligamento do Loom) ou cuja chamada esgotou
o tempo limite consome uma de suas LOOM_EXTRACTION_QUEUE_MAX_ATTEMPTS=2 tentativas, de modo que uma sessão
longa demais para a máquina termina como failed (memory.extraction_status mostra cancelled ou
o timeout) em vez de travar a fila: uma sessão longa pode precisar de várias chamadas
seguidas, cada uma com até o tempo limite. Em um servidor que responde a uma requisição por vez, o tempo limite
também conta a espera atrás de outras chamadas, e o assistente e o memory.ask compartilham o
servidor, então o uso intenso deles durante uma captura também pode fazê-la falhar; aumente
LOOM_EXTRACTION_QUEUE_MAX_ATTEMPTS se isso acontecer. A marcação de entidades
(LOOM_ENTITY_EXTRACT_ENABLED) fica desativada: ela entraria na fila atrás da extração em um servidor que
responde a uma requisição por vez, e sua passada, cortada no prazo, não grava nada, então a
busca fica sem correspondências de entidades. Os outros workers que
chamam um modelo não são ajustados para um modelo local: a extração de observe (desativada por padrão), cuja
passada de até 10 sessões é cortada em 900 s e recomeça pela sessão mais recente, e
os títulos de conversas e os perfis estruturados, que rodam quando o registro de conversas ou um
esquema de perfil é configurado.
Para o llama.cpp, aponte LOOM_LOCAL_LLM_BASE_URL para a raiz /v1 dele
(http://host.docker.internal:8080/v1) e defina LOOM_LLM_MODEL com o nome que ele serve;
para um assistente local, defina também LIBRECHAT_LOCAL_LLM_BASE_URL com essa raiz e
LOOM_ASSISTANT_MODEL com esse nome. Um servidor executado a partir de um checkout alcança o modelo em
localhost, o padrão da configuração (http://localhost:11434/v1).
Um modelo por job cujo nome comece com gpt, o1, o3, o4, chatgpt ou claude vai para
esse provedor hospedado, seja qual for o valor de LOOM_LLM_PROVIDER; um modelo local com esse tipo de nome
(gpt-oss) roda localmente como LOOM_LLM_MODEL e, em uma configuração por job, só quando
essa configuração nomeia o mesmo modelo.
- Acesso ao host. Os contêineres alcançam a máquina como
host.docker.internal. O Docker Desktop encaminha isso para serviços em loopback; com o Docker Engine no Linux, o Ollama precisa escutar além do loopback (OLLAMA_HOST=0.0.0.0, com a porta 11434 fechada para a rede). Com o Helm chart enetworkPolicy.enabled, adicione a porta do servidor anetworkPolicy.extraEgress. - O assistente.
LOOM_ASSISTANT_PROVIDER=localmove o agente do assistente para o endpointlocaldo LibreChat, que chamaLIBRECHAT_LOCAL_LLM_BASE_URL(padrãohttp://host.docker.internal:11434/v1), e exigeLOOM_ASSISTANT_MODEL. O assistente responde chamando as ferramentas do Loom, então escolha um modelo que o servidor execute com chamadas de ferramenta (o Ollama as indica). Um modelo local não tem preço, então cada resposta contaLOOM_ASSISTANT_ANSWER_CEILING_USD($0.10 por padrão) contra a parcela do assistente no limite diário de custo de modelo do namespace, como qualquer modelo sem preço: no limite e na parcela padrão, cinco respostas por dia. O preset define o teto como0, então as respostas locais não custam nada; esse também é o custo de uma resposta cortada antes de o uso chegar, então mantenha o valor padrão quando um modelo hospedado atender o assistente. Com o Helm chart, adicioneLOCAL_LLM_BASE_URLao Secret do assistente; a política do chart permite que o LibreChat alcance apenas DNS, seu banco de dados, o Loom e TCP 443, então o servidor de modelos precisa de uma NetworkPolicy própria que selecione o pod do LibreChat. - Qualidade e velocidade. Os prompts e limites do Loom são ajustados em modelos hospedados, e nenhum
benchmark publicado cobre um modelo local, então trate um modelo pequeno como uma forma de experimentar o Loom
sem chave ou de manter tudo na máquina, não como um equivalente: espere que a extração,
as respostas do
memory.aske o uso de ferramentas pelo assistente sejam mais fracos, em uma medida que ninguém mediu. Um modelo pequeno em uma CPU é lento com prompts longos, como a extração, então uma fila de captura ocupada acumula atraso; uma GPU, ou um modelo maior em uma máquina com memória suficiente, ajuda. Para um servidor de equipe, um modelo hospedado responde melhor.
Por meio de um gateway de inferência
Um gateway que fale a API da OpenAI ou da Anthropic na frente dos provedores (para orçamentos, atribuição de custos ou uma única chave para vários serviços) recebe as chamadas do Loom assim que as raízes de API apontam para ele; os nomes dos modelos continuam sendo os que o gateway serve:
LOOM_OPENAI_BASE_URL=https://gateway.example/v1 # chat and embeddings
LOOM_ANTHROPIC_BASE_URL=https://gateway.example # Messages: <root>/v1/messages
OPENAI_API_KEY=<the key the gateway issued for Loom>
Fora do padrão, a chave da Anthropic também é enviada como Authorization: Bearer, o
esquema que os gateways aceitam. Com uma chave de gateway, exija o gateway, para que uma raiz errada nunca
possa enviar prompts e a chave para outro lugar. Uma troca de token já o exige por si só.
LOOM_INFERENCE_GATEWAY_REQUIRED=true
LOOM_INFERENCE_GATEWAY_HOSTS=gateway.example # comma-separated; exact names, any case
Enquanto o gateway é exigido, as chamadas de modelo e o conteúdo de memória que o Loom envia
a classificadores e rerankers vão apenas para os hosts que LOOM_INFERENCE_GATEWAY_HOSTS
lista. Um host corresponde exatamente: sem curinga, e gateway.example não
admite api.gateway.example nem gateway.example.attacker.test; um endereço IP
só corresponde se estiver listado.
- Na inicialização, o Loom se recusa a carregar sem
LOOM_INFERENCE_GATEWAY_HOSTS, ou enquantoLOOM_OPENAI_BASE_URL,LOOM_ANTHROPIC_BASE_URL,LOOM_EMBEDDING_BASE_URL,LOOM_INFERENCE_TOKEN_URL(eLOOM_LOCAL_LLM_BASE_URLenquantoLOOM_LLM_PROVIDER=local) ou uma entrada deLOOM_RERANK_ENDPOINTS_JSONnomear outro host, enquanto o embedder for o do Gemini, ou enquantoLOOM_CODE_SEARCH_RERANK_DEFAULTouLOOM_KNOWLEDGE_SEARCH_RERANK_DEFAULTforbuiltin:cohere. As duas raízes de API contam, inclusive a de um provedor que você não usa (os padrões delas são as APIs dos próprios provedores): um modelo nomeado por requisição pode ser de qualquer um dos provedores. - No momento da chamada, uma chamada de modelo para qualquer outro host é recusada antes de
sair, também em cada salto de redirecionamento, seja qual for a origem do nome: um modelo nomeado por
requisição, uma entrada de
LOOM_CODE_SEARCH_VECTOR_MODELS. Uma chamada recusada não é repetida, e/v1/healthinforma que o provedor está falhando. - Namespaces:
namespace.registerrecusa umclassify_endpointque não seja https na porta padrão de um host listado (422), e um armazenado antes nunca é chamado: memory.set mantém o tipo do chamador, com um aviso no log.builtin:cohereé recusado como escolha de rerank (422), e um namespace que o tenha armazenado faz rerank com nada, com um aviso no log. - Painel: salvar uma configuração de modelo com um endpoint em outro host
(ou o embedder do Gemini) responde 422, e a verificação do modelo responde
gateway_required. Uma configuração armazenada que a verificação recusa não é aplicada, incluindo suas definições de vetor em uso, e/v1/healthinformamodel_configuration_refused. A verificação lê apenas o embedding, então uma configuração recusada sempre gera embeddings diferentes das definições em vigor, e as tabelas de vetores podem conter esse outro espaço: toda requisição do plano de dados nesse servidor é recusada (503GATEWAY_REQUIRED, que nenhum dos dois SDKs tenta de novo, semRetry-After) e o servidor não fica pronto, até que uma configuração que a verificação aceite a substitua ou ela seja redefinida para a do ambiente. Uma reinicialização gradual então para nesse servidor: substitua a configuração antes de fazer o rolling. - Implantação gradual: uma build anterior ignora as duas definições, então ative-as
somente depois que todas as réplicas executarem esta. Uma implantação que já troca um token
se recusa a iniciar nesta build até que
LOOM_INFERENCE_GATEWAY_HOSTSliste o seu gateway, e enquanto ela gera embeddings com Gemini, indica um endpoint de rerank em outro host ou definebuiltin:coherecomo padrão da busca de código; requisições que indicambuiltin:cohererecebem 422, e namespaces que armazenaram esse valor ou umclassify_endpointfora do gateway deixam de fazer rerank ou classificação até que ele seja alterado. Defina os hosts e mova o embedder para trás do gateway (LOOM_EMBEDDING_PROVIDER=compatible,LOOM_EMBEDDING_BASE_URLapontando para o gateway) primeiro, ou a implantação para na primeira réplica atualizada.
Um gateway que aceita identidade de workload (troca de token RFC 8693) não precisa de chave alguma: o Loom troca ali o token OIDC do seu workload, renova a resposta cinco minutos antes de expirar (na metade do prazo, para um token que vive menos de dez minutos) e a envia em cada chamada. Sem uma chave da qual inferi-los, indique o provedor e os modelos:
LOOM_INFERENCE_TOKEN_URL=https://gateway.example/oauth/token # https
LOOM_INFERENCE_GATEWAY_HOSTS=gateway.example # every root's host
LOOM_INFERENCE_WORKLOAD_TOKEN_FILE=/var/run/secrets/tokens/gateway # rotated by the platform
LOOM_INFERENCE_TOKEN_SCOPE="chat embeddings" # if the gateway asks for one
LOOM_OPENAI_BASE_URL=https://gateway.example/v1 # both roots required:
LOOM_ANTHROPIC_BASE_URL=https://gateway.example # the token is the gateway's
LOOM_LLM_PROVIDER=openai
LOOM_LLM_MODEL=gpt-6-luna
LOOM_EMBEDDING_MODEL=text-embedding-3-large
O Loom se recusa a iniciar enquanto a raiz de qualquer um dos provedores, ou o endpoint de token,
estiver em um host que LOOM_INFERENCE_GATEWAY_HOSTS não lista: um modelo indicado por
requisição pode ser de qualquer um dos provedores, e o token do gateway iria para lá. No
painel, as alterações de modelo também são verificadas por meio do gateway.
No Kubernetes, o arquivo de token é um token de service account projetado, com a audiência
do gateway; o gateway deve confiar no emissor OIDC do cluster e corresponder à service account
do Loom (system:serviceaccount:<namespace>:<name>), e não apenas ao emissor,
já que todo pod do cluster pode obter um token dele.
Um gateway que verifica o próprio token do workload o recebe como bearer, sem troca: defina o modo bearer em vez de um endpoint de token. O Loom lê o arquivo no máximo uma vez por minuto, e de novo imediatamente quando o gateway responde 401, de modo que um token rotacionado seja captado sem reiniciar:
LOOM_INFERENCE_WORKLOAD_TOKEN_MODE=bearer
LOOM_INFERENCE_WORKLOAD_TOKEN_FILE=/var/run/secrets/tokens/gateway # sent as it is
LOOM_INFERENCE_GATEWAY_HOSTS=gateway.example # required, as with the exchange
LOOM_OPENAI_BASE_URL=https://gateway.example/v1
LOOM_ANTHROPIC_BASE_URL=https://gateway.example
LOOM_EMBEDDING_PROVIDER=compatible # embeddings through the gateway too
LOOM_EMBEDDING_BASE_URL=https://gateway.example/v1
Indique o provedor e os modelos como no exemplo de troca. O token vai somente para os
hosts do gateway: o modo bearer exige o gateway, assim como a troca. Um endpoint de
embedding compatível que receba sua própria LOOM_EMBEDDING_API_KEY envia essa chave no lugar.
Indicando o cliente em cada chamada
Um gateway que mede ou define orçamento por cliente lê o cliente de um cabeçalho. Indique os cabeçalhos, e toda requisição de chat, embedding, rerank e classify carrega a org cujos dados ela contém e a funcionalidade que a originou:
LOOM_INFERENCE_CUSTOMER_HEADER=X-Customer-Id # the org
LOOM_INFERENCE_FEATURE_HEADER=X-Feature # optional, with the customer header: hyde, memory.search, worker.embedding
LOOM_INFERENCE_SYSTEM_CUSTOMER=loom # calls that belong to no org
LOOM_INFERENCE_CUSTOMER_REQUIRED=true # a cell serving several customers: refuse to start without the header
LOOM_INFERENCE_CUSTOMER_FORMAT='cloud:{org}' # the gateway's customer id for an org; default the org id
LOOM_INFERENCE_FEATURE_MAP_JSON='{"hyde": "search", "*": "memory"}' # Loom's feature names to the gateway's
- Uma requisição indica a org que ela endereça, conforme autorizado para o seu token; um chamador não pode indicar uma org que o seu token não alcança.
- Um job em segundo plano indica a org das linhas em que trabalha e faz uma chamada
por org: o worker de embedding,
loom reembede uma reconstrução de modelo dividem seus lotes por org. - As chamadas da própria implantação (a verificação do embedder na inicialização, os pares fixos
do worker de recalibração, a verificação de provedor do painel) indicam
LOOM_INFERENCE_SYSTEM_CUSTOMER. - O juiz de recuperação por amostragem (
LOOM_RETRIEVAL_JUDGE_SAMPLE_RATE) envia a consulta e as memórias da org julgada, então cada busca julgada adiciona uma chamada que indica essa org. - Com o cabeçalho de cliente definido, uma chamada de modelo que não indica org é recusada
(
MODEL_CALL_UNATTRIBUTED) em vez de ser enviada: é um caminho de chamada que esqueceu sua org, e o gateway não a cobraria de ninguém. - Um id de org é enviado com codificação percentual onde for necessário.
Respostas em cache não fazem chamada: um embedding ou uma resposta de modelo servida do cache do Loom não é medida de novo. O cliente ainda é verificado antes do cache, então um caminho que não indica nenhum é recusado mesmo em um acerto.
Indicando o agente em cada chamada
Um gateway que cobra ou limita cada agente lê para quem uma chamada se destina a partir de cabeçalhos. Mapeie cada cabeçalho para um template, e toda requisição de chat, embedding, rerank e classify ao gateway o carrega:
LOOM_INFERENCE_IDENTITY_HEADERS_JSON='{"X-Tenant": "{tenant}", "X-Agent": "{agent}", "X-Actor": "{email}"}'
LOOM_INFERENCE_GATEWAY_HOSTS=gateway.example # required: identity headers go only to these hosts
LOOM_INFERENCE_TENANT_CLAIM=tenant_id # the workload trust claim {tenant} names (the default)
- Os placeholders são
{org},{namespace},{subject},{user_id},{agent}(o agente do token de uma workload trust,sa:<trust>:<agent>),{tenant}(o valor que essa trust exige em sua claimLOOM_INFERENCE_TENANT_CLAIM) e{email}(o endereço de uma pessoa autenticada). - Um cabeçalho cujo template resulta vazio não é enviado: com placeholders simples, uma chamada sem
agente por trás (a de uma pessoa, ou a da própria implantação) não carrega cabeçalho de agente. Os cabeçalhos
que citam
{agent}ou{tenant}vão juntos ou não vão, de modo que um agente nunca vai sem seu tenant. - Uma chamada que não indica org é recusada (
MODEL_CALL_UNATTRIBUTED), a menos que seja da própria implantação: execute os comandosloomque chamam modelos com--org, e com--namespaceenquanto os cabeçalhos indicarem o agente (uma chamada sem namespace é recusada em vez de ser cobrada do agente padrão do gateway). - Jobs em segundo plano indicam a identidade das linhas em que trabalham: o autor de uma memória ou de uma extração adiada, ou então o agente em cujo namespace próprio a linha está. Um job que processa linhas em lote faz uma chamada por identidade.
- Nenhum outro host recebe os cabeçalhos de identidade: um reranker, um classificador ou um provedor fora de
LOOM_INFERENCE_GATEWAY_HOSTSnunca descobre para quem uma chamada se destina. -
LOOM_INFERENCE_IDENTITY_REFUSALS_JSONlista as respostas que o seu gateway dá para uma identidade, cada uma por seu status e pelocode,typeoumessageexato do seu corpo de erro (emerror). Compare porcodequando o gateway fornecer um. O padrão corresponde aos códigos por agente de um proxy de inferência e à recusa de orçamento da medição por trás dele:{ "refused": [ { "status": 429, "code": "budget_exceeded" }, { "status": 429, "type": "rate_limit_error", "message": "budget exceeded" }, { "status": 403, "code": "agent_denied" }, { "status": 400, "code": "identity_incomplete" }, { "status": 400, "code": "identity_malformed" } ], "wait": [{ "status": 429, "code": "agent_request_limit" }] }A segunda entrada é correspondida por type e message porque a resposta da medição no formato Anthropic em
/v1/messagesnão traz code.
- Nunca liste uma resposta que o gateway também dá para uma falha própria:
token_unavailable(ele não consegue obter uma credencial, o que uma queda do serviço de credenciais também responde) ouidentity_missing(a requisição não indicou agente e o gateway não tem padrão, um problema de configuração). Se listadas,/v1/healthdeixaria de ver a queda ou a configuração incorreta. Respostas no nível da implantação também continuam sendo falhas do provedor:caller_*,scope_not_granted(uma rota que os escopos do token não cobrem),route_not_found,upstream_*,misconfigured,no_identity. - Uma resposta em
refusedfaz essa requisição responder 403MODEL_CALL_REFUSED, e uma emwaitresponder 503MODEL_CALL_DEFERREDcom oRetry-Afterdo gateway; uma espera de dois segundos ou menos é aguardada uma vez primeiro, e a chamada é feita de novo. Nada tenta de novo nenhuma das respostas,/v1/healthnão as lê como falha do provedor, e os jobs em segundo plano seguram as chamadas dessa identidade ao mesmo modelo, porLOOM_INFERENCE_REFUSAL_COOLDOWN_SECONDS(10 minutos por padrão) após uma recusa e peloRetry-Afterapós uma espera, enquanto o outro trabalho continua. Qualquer resposta que a tabela não liste é do provedor, como sempre. - Como cada valor é encontrado: cabeçalhos de identidade.
Desligando as chamadas de modelo de uma org
Um admin da org pode interromper toda chamada de modelo para os dados da org, com ou sem gateway, pela página Guardrails do painel ou pela API:
curl -s -X POST "$LOOM_BASE_URL/v1/org.set_model_calls" -H "Authorization: Bearer $ORG_ADMIN_TOKEN" \
-d '{"org":"acme","enabled":false,"reason":"customer turned AI off"}'
- Enquanto desligado, nenhuma requisição de chat, embedding, rerank ou classify é enviada para a
org, e nenhum vetor ou resposta em cache é servido a ela também: o desligamento é um
kill switch. Uma requisição que precise de uma chamada é recusada (403
MODEL_CALLS_DISABLED):memory.setde uma memória que recebe embedding na escrita, ou em um namespace com um endpoint classify,memory.search, etracker.similar,tracker.duplicate_checkecode.bisect_candidatesquando fazem embedding, julgamento ou rerank, entre elas. Uma leitura por chave (memory.get) e uma exclusão não fazem chamada de modelo e respondem normalmente. O embedder local roda no próprio processo e não envia nada, mas também é desligado. Uma chamada que indica a org é verificada mesmo quando o Loom a faz para si mesmo; apenas as chamadas próprias que não indicam org (a verificação de inicialização, a calibração) continuam. "enabled": trueo liga de novo, e o trabalho em espera é executado.- O bloqueio de um admin da plataforma. Um admin da plataforma pode adicionar
"locked": true: os próprios admins da org ainda podem desligá-lo, mas religá-lo ou desbloqueá-lo é recusado (403, indicando quem o bloqueou) até que um admin da plataforma envie"locked": false. Uma alteração de admin da plataforma que não envielockedmantém o bloqueio.org.model_callslê a configuração, o bloqueio e quem os definiu. - O offboarding de uma org é manual: um admin da plataforma envia
"enabled": false, "locked": true. Os vetores de consulta em cache da org expiram após 30 dias. Nenhum caminho do Loom desliga uma org por conta própria. - Todo servidor aplica uma alteração dentro de
LOOM_MODEL_CALLS_POLICY_REFRESH_SECONDS(padrão 10; o processo que a recebeu, na sua próxima chamada). Um servidor que não consegue ler o desligamento por mais deLOOM_MODEL_CALLS_POLICY_MAX_STALE_SECONDS(padrão 60, de 15 a 300) não faz nenhuma chamada de modelo para nenhuma org até conseguir. - Desligue uma org somente depois que todas as réplicas executarem uma build que conheça o desligamento: uma mais antiga continua chamando modelos para a org.
O que espera, e por quanto tempo, enquanto uma org está desligada:
| Trabalho | Enquanto a org está desligada |
|---|---|
| Embeddings de memória (o worker de embedding) | Não são selecionados: as memórias permanecem, sem vetor, e recebem embedding quando a org voltar a ser ligada. Nunca são descartadas. |
| Requisições de extração (a fila de extração) | Ficam pendentes, sem serem reivindicadas. Quando uma requisição esperou LOOM_MODEL_CALLS_OFF_MAX_WAIT_DAYS (padrão 7, de 1 a 29) desde que entrou na fila e desde que a org foi desligada, ela é marcada como falha com um registro em memory_drops, motivo model_calls_off. O registro é escrito de forma síncrona antes: uma requisição cujo registro não possa ser escrito continua pendente. O limite fica abaixo de 30 dias porque o TTL de 30 dias da fila removeria a requisição antes, sem registro. |
| Marcação de entidades, consolidações de perfil, resumos de período, títulos de conversa, reflexões, destilação de observações | Não são selecionados; feitos quando a org voltar a ser ligada. Derivam de linhas que permanecem, então nada é descartado. |
| Reparos de projeção | Não são varridos; tentados de novo quando a org voltar a ser ligada. |
| Julgamentos de conflito pendentes | Não são julgados novamente. Um julgamento mais antigo que a hora da varredura quando a organização volta já ficou para trás da varredura, como um julgamento perdido em uma interrupção: a escrita permanece como foi feita. |
| Ingestão de código, resumos de código, recuperação de embeddings de código | Os repositórios da organização são ignorados, então todo o seu índice de código, inclusive a busca lexical, permanece como estava. Um stub que a varredura de recuperação deixou para trás é encontrado pela sua varredura completa periódica. |
| Julgamentos de links de código | Continuam pendentes. |
| Embeddings do tracker, pontuação de links do tracker | O namespace é ignorado antes que o seu cursor avance. |
| Amostras do juiz de recuperação | Descartadas: uma amostra não é um trabalho devido. |
loom reembed |
As linhas da organização são deixadas de fora, contadas (skipped_switched_off) e informadas; execute-o novamente quando a organização for religada. --delete-old mantém os vetores antigos de toda organização cujas linhas foram deixadas de fora. |
| A reconstrução após uma troca de modelo | É concluída; as linhas da organização são preparadas sem vetor e contadas no progresso da reconstrução (rows_waiting). Quando a organização for religada, os embeddings de memória, os chunks de código e os resumos de código são gerados novamente pelos seus workers de recuperação; uma linha de qualquer outra tabela fica sem vetor até ser escrita de novo ou até que uma reconstrução posterior a cubra. |
Sem um token de workload
Onde a plataforma não fornece um token ao Loom (uma VM, um host de contêineres), o Loom assina o seu próprio: defina uma audiência no lugar do arquivo de token, e o gateway passa a confiar no Loom como emissor.
LOOM_INFERENCE_TOKEN_URL=https://gateway.example/oauth/token
LOOM_INFERENCE_GATEWAY_HOSTS=gateway.example
LOOM_INFERENCE_TOKEN_AUDIENCE=loom-inference # what the gateway's entry for Loom names
LOOM_PUBLIC_BASE_URL=https://loom.example # the issuer is <this>/v1
LOOM_OPENAI_BASE_URL=https://gateway.example/v1
LOOM_ANTHROPIC_BASE_URL=https://gateway.example
LOOM_LLM_PROVIDER=openai
LOOM_LLM_MODEL=gpt-6-luna
LOOM_EMBEDDING_MODEL=text-embedding-3-large
Cada troca envia um novo token que vive cinco minutos: emissor <LOOM_PUBLIC_BASE_URL>/v1, subject loom, a audiência acima, assinado com RS256 usando a chave RS256 mais recente do keyring de assinatura. Crie uma antes com loom
signing-key rotate --algorithm RS256, a menos que LOOM_JWT_SECRET seja uma chave RSA, que já assina como RS256. A partir daí, essa chave também assina os próprios tokens do Loom, que todo Loom da implantação verifica; um segredo HS256 nunca é usado, pois o gateway não conseguiria verificá-lo. O gasto é atribuído a esse único subject.
A entrada do gateway para o Loom informa esse emissor, a audiência, o subject loom, RS256 e as chaves em <LOOM_PUBLIC_BASE_URL>/v1/.well-known/jwks.json (a descoberta OIDC está em /v1/.well-known/openid-configuration). O gateway precisa conseguir buscar essa URL por https; onde ele não consegue alcançar o Loom, publique uma cópia do conjunto de chaves em algum lugar que ele alcance. Cada Loom publica uma chave na próxima atualização do keyring depois que rotate a grava, e a chave só assina --activate-in depois (300 s por padrão): faça o rotate com um --activate-in maior do que o tempo que o gateway mantém a sua cópia das chaves, ou do que o tempo necessário para copiá-las. Uma chave desativada continua confiável no gateway até que a sua cópia seja atualizada. loom signing-key retire se recusa a desativar a última chave RS256 ativa quando LOOM_INFERENCE_TOKEN_AUDIENCE está definido no seu próprio ambiente, então execute-o com o ambiente dos servidores. O Loom (o servidor e todo comando loom) recusa essas configurações sem um LOOM_PUBLIC_BASE_URL https, com LOOM_JWT_AUDIENCE como audiência, ou com um emissor em que o seu próprio verificador confia, e o seu próprio verificador nunca aceita um token com a audiência do gateway.
Aplicar as alterações e verificar o resultado
Alterações feitas no painel: aguarde até que Models & keys informe a configuração ativa. Se uma reconstrução estiver em andamento, acompanhe o progresso ali mesmo; tente novamente um job com falha a partir da mesma página. Não recrie os containers para aplicar uma alteração feita no painel.
Somente alterações de ambiente: para a stack publicada, recrie o container do servidor:
docker compose --project-directory "$HOME/.loom" up -d --force-recreate loom
docker compose --project-directory "$HOME/.loom" exec loom loom doctor
curl -fsS http://localhost:7777/v1/health
Use o seu diretório de instalação e a sua porta, se forem diferentes. Recrie o container: um simples docker compose restart não recarrega o ambiente a partir de .env. Servidores nativos devem ser reiniciados com o ambiente atualizado. Para a stack do checkout, execute docker compose --env-file .env -f compose.yaml -f dev/docker-compose.dev.yml --profile bundled up -d --build --force-recreate loom.
O health informa fake_llm, fake_embedding, providers_degraded e problems acionáveis. Com os dois providers reais configurados, as flags fake devem ser false. Isso verifica a configuração e a saúde do servidor; salve e recupere também um fato de teste e experimente uma resposta para confirmar que a sua conta consegue chamar os modelos escolhidos.
Alterar o LLM ou rotacionar uma chave de API não exige reconstruir os embeddings. Alterar o modelo de embedding exige, mesmo quando as dimensões continuam as mesmas. No caso de alterações de ambiente (em vez do fluxo pelo painel), os índices existentes de memória, documentos, tracker e código precisam dos respectivos procedimentos de re-embedding ou de nova ingestão; loom reembed sozinho não é uma reconstrução universal de todos os índices. Se as dimensões mudarem, verifique as restrições de vetor do schema existente antes de aplicar a nova configuração. Preserve os seus dados e siga manutenção e operações do índice de código.