Combos e fallback

Um combo é uma lista nomeada e ordenada de modelos. Quando o primeiro não consegue responder, o gateway tenta o seguinte, para que a queda ou o limite de requisições de um provedor não pare o seu trabalho. É uma cadeia de fallback: uma resposta vem de um modelo.

Gerencie os combos#

Todos estes pedem a sua chave de API e só alcançam os seus próprios combos. O combo de outra pessoa é um 404.

GET/api/v1/combos#

{
  "data": [
    {
      "id": 1,
      "user_id": 42,
      "name": "daily driver",
      "mode": "fallback",
      "targets": [
        { "server_key": "anthropic", "model": "claude-sonnet-4-6" },
        { "server_key": "openai", "model": "gpt-4o" }
      ],
      "judge": null,
      "is_active": true,
      "created_at": "2026-10-10T17:00:00.000000Z",
      "updated_at": "2026-10-10T17:00:00.000000Z"
    }
  ]
}

POST/api/v1/combos#

Cria um combo e responde 201 com {"data": {…}}.

Você pode ter 5 combos. O 6º é recusado com 422.

Só o formato é conferido quando você salva. Um alvo que não existe, ou que não tem chave por trás, é aceito e depois pulado quando o combo roda, então teste um combo depois de criá-lo.

PUT/api/v1/combos/{id}#

Substitui name e targets. Responde 200 com o combo.

DELETE/api/v1/combos/{id}#

Responde 200 com {"status": "deleted"}.

Use um combo#

curl -sN "$SHVIA_URL/api/v1/chat" \
  -H "Authorization: Bearer $SHVIA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "message": "Summarize the plan in 3 bullets.", "combo_id": 1 }'

O combo substitui a escolha do modelo. Um combo_id desconhecido, ou que pertence a outra pessoa, é ignorado, e vale a escolha de modelo normal. O seu modelo padrão é acrescentado ao fim de todo combo como último recurso, então um combo cujos alvos não podem ser alcançados costuma responder com o seu modelo padrão em vez de falhar. O stream traz um evento error com codigo igual a combo_sem_modelo só quando nem isso pode ser resolvido.

Como a cadeia roda#

• Um combo tenta os seus alvos em ordem, a partir do primeiro, a cada turno. O gateway passa para o seguinte só se a falha é uma que outro modelo pode resolver e nenhum texto foi enviado ainda. Depois que o primeiro token foi para o stream, aquela resposta é a resposta, mesmo que quebre depois.
• Uma falha que outro modelo pode resolver é, por exemplo, uma cota ou limite de requisições no provedor, um provedor sobrecarregado, uma credencial recusada, um modelo desconhecido, um servidor offline ou uma resposta vazia. Uma requisição que o provedor rejeita como inválida, ou uma longa demais para o contexto do modelo, não passa adiante: outro modelo receberia a mesma requisição.
• Um alvo cuja janela de contexto não comporta o seu prompt, ou que não enxerga imagens quando o turno tem uma, é pulado quando sobra outro alvo.
• Um combo não mantém um prompt nos servidores do operador. Se o primeiro alvo está nos servidores do próprio operador e falha, o seguinte pode ser um provedor de nuvem, e a conversa vai para ele, com os dados pessoais mascarados no texto. Para ter a garantia de que um prompt nunca sai dos servidores do operador, mantenha todos os alvos do combo neles.
• Se qualquer alvo do combo está na nuvem, o gateway deixa o contexto da base de conhecimento e a memória fora do prompt de todos os alvos desse combo, o primeiro inclusive, porque um fallback poderia levá-los para lá. Todo o resto do turno pode chegar a um alvo de nuvem quando a cadeia chega lá: os turnos anteriores da conversa, os seus anexos e imagens (redimensionados para caber nos limites da nuvem), e a persona e as instruções e arquivos de projeto da sua conta, a menos que você tenha ligado a proteção LGPD nas configurações da conta.

Qual modelo respondeu#

O primeiro evento model do stream dá o nome do primeiro alvo. Quando outro modelo assume, um segundo evento model vem em seguida, com target_source igual a combo_fallback e o novo name. Ele chega depois que o texto da resposta já foi para o stream, logo antes de usage e done, então uma tela que rotula a resposta a partir do primeiro evento mostra o modelo errado enquanto o stream corre. Leia o último evento model, ou usage.model.

Notas#

• mode é fallback. A API não deixa você definir outro modo nem um juiz, embora o GET devolva os campos.
• is_active é aceito e devolvido, e não tem efeito hoje.