Pular para conteúdo

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.

Executando N réplicas

Todo processo do Loom é uma réplica completa. Execute quantas precisar em um único serviço ClickHouse, atrás de uma única URL, sem sessões fixas: cada uma atende a todas as ops, verifica todos os tokens e grava no serviço compartilhado. O trabalho que deve acontecer uma única vez roda no processo que detém o lease do ClickHouse e muda de processo quando aquele para:

Uma vez por deployment Onde roda
Migrações de schema o primeiro processo a iniciar um build com migrações pendentes, sob o lease de migração; os demais esperam por ele
Workers em segundo plano o detentor do lease workers_supervisor (implantação)
Publicação da configuração do deployment o mesmo detentor do lease (abaixo)

Cada processo mantém seus próprios espelhos git (uma leitura de histórico clona um espelho ausente; LOOM_CODE_HISTORY_CLONE_ON_READ), seus próprios caches e seus próprios buckets de limite de taxa.

Um mesmo env para todas

Inicie todas as réplicas a partir do mesmo env, com LOOM_DEPLOYMENT=1:

LOOM_DEPLOYMENT=1
LOOM_CH_HOST=...                 # the one ClickHouse service
LOOM_CH_PORT=8443
LOOM_CH_USER=...
LOOM_CH_PASSWORD=...
LOOM_JWT_SECRET=...              # the same root secret on every replica
LOOM_EMBEDDING_MODEL=...         # the same model and width on every replica
LOOM_EMBEDDING_DIM=...
OPENAI_API_KEY=...               # each replica makes its own provider calls
LOOM_TRUSTED_PROXIES=...         # the load balancer, so per-client limits see the client

LOOM_JWT_SECRET assina com o kid default e sela todas as outras chaves de assinatura e todas as credenciais armazenadas; com um único valor, todo token funciona em todas as réplicas. Chaves de assinatura, revogações, grants e contas de serviço são linhas no serviço compartilhado; uma rotação ou revogação chega a todas as réplicas dentro de LOOM_JWT_KEYRING_REFRESH_SECONDS e LOOM_JWT_REVOCATION_CACHE_TTL_SECONDS.

Divergência de configuração

Cada processo grava uma linha de heartbeat em loom.instances a cada LOOM_INSTANCE_HEARTBEAT_SECONDS (10 s por padrão): seu build, uma impressão digital de suas configurações MUST_MATCH (o espaço de embedding: LOOM_EMBEDDING_PROVIDER, _MODEL, _DIM, _BASE_URL e _SEND_DIMENSIONS), uma impressão digital de seu segredo raiz e seu horário de início. Uma linha não renovada por três intervalos, ou marcada como parada pelo próprio processo no desligamento, não está ativa.

O detentor do lease publica sua configuração em loom.deployment_config: as configurações MUST_MATCH e uma impressão digital HMAC de seu segredo raiz. Todo processo se compara com esse snapshot na inicialização e a cada heartbeat. Um segredo raiz diferente (seus tokens e credenciais armazenadas não abririam em outro lugar) ou um valor MUST_MATCH diferente (seus vetores ficariam em outro espaço) é divergência: o processo não fica pronto, de modo que o balanceador de carga não envia nada a ele, e /v1/health reporta o problema config_drift com o que difere. Como não estar pronto só impede novas conexões, o processo também responde a toda chamada de API, MCP e login com 503 CONFIG_DRIFT e fecha a conexão: a nova tentativa do cliente cai em uma réplica que concorda. Os valores comparados são os do env: uma troca de modelo feita pelo painel é do deployment (toda réplica a lê do ClickHouse), portanto não é divergência, e uma réplica iniciada com o mesmo env depois dela fica pronta. deployment_config em /v1/health mostra a última verificação e os hosts ativos.

O detentor do lease nunca publica por cima de um snapshot do qual diverge: uma réplica com o segredo raiz ou o modelo de embedding errado que ganhe o lease continua não pronta, e as réplicas com o env publicado continuam prontas. Um snapshot com o qual ele concorda só é reescrito quando nenhuma outra réplica ativa executa o armazenado, de modo que os snapshots de formatos diferentes de N-1 e N durante um rollout nunca alternem de um para o outro.

Alterar uma configuração MUST_MATCH ou LOOM_JWT_SECRET não pode ser feito de forma gradual: as réplicas com o novo valor não ficam prontas enquanto as réplicas com o antigo atendem. Pare todas as réplicas, altere o env, execute loom deployment publish --yes com o novo env (ele lista o que muda) e inicie-as novamente (uma alteração de embedding é seguida de um re-embed completo, loom reembed). Após uma troca de segredo, emita os tokens novamente e armazene as credenciais de novo.

Processos sem LOOM_DEPLOYMENT (um servidor de branch ou de teste A/B no mesmo serviço) também enviam heartbeat, mas nunca publicam, nunca são verificados e não contam como réplicas.

Limites de taxa

Os limites configurados valem para o deployment inteiro. A parcela de cada réplica é o limite dividido pelos hosts com uma linha ativa em loom.instances, portanto adicionar ou remover uma réplica redimensiona todos os buckets em até um heartbeat. LOOM_REPLICA_COUNT é o piso dessa contagem e a contagem usada enquanto as linhas não podem ser lidas. Os web workers de um mesmo host compartilham uma tabela de buckets (implantação).

Repositórios de código

Todo processo relê loom.code_repos a cada LOOM_CODE_REPOS_REFRESH_SECONDS (30 s por padrão), portanto um repositório adicionado ou restringido em uma réplica vale em todas as réplicas dentro desse tempo.

Um host que não deve servir histórico git (uma borda sem disco para espelhos) define LOOM_GIT_HISTORY=none: blame, verificações de commit e histórico de PR passam a responder sem ele.

Parando uma réplica

Pare-a de forma graciosa (docker stop, SIGTERM): ela marca sua linha de heartbeat como parada e retira sua linha de participante do provider. Uma interrupção forçada deixa ambas; a linha de heartbeat deixa de contar após três intervalos. Um processo que reinicia no mesmo container retira por conta própria a linha de participante do processo morto. Se uma reconfiguração do provider estiver esperando pela linha de um processo morto vinda de outro lugar, retire-a com o participant_id que o /v1/health dele reportou, depois de confirmar que ele não existe mais (o comando recusa uma linha cujo heartbeat está recente ou cujas consultas ainda estão em execução):

loom participant retire --participant <participant_id> --yes