> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Fusion

> Execute uma requisição em um painel de modelos, deixe um juiz ponderar as respostas e retorne uma única resposta sob um único ID de modelo do gateway.

O **Model Fusion** responde a uma requisição com vários modelos ao mesmo tempo, faz com que um juiz compare as respostas e retorna uma única resposta. Quem chama o usa como qualquer outro modelo: um ID de modelo, uma resposta.

## Casos de uso

* **Revisão entre provedores**: coloque modelos de provedores diferentes no painel e leia a lista de contradições do juiz antes de publicar uma resposta ou uma alteração de código.
* **Respostas de alto risco**: o preset **Safety** faz o juiz ponderar riscos físicos, financeiros, jurídicos e médicos e sinalizá-los antes da síntese.
* **Troque modelos sem mexer em quem chama**: a fusion é dona do ID de modelo, então alterar o painel ou o juiz não muda o código do cliente.

## Criar um Model Fusion

Abra **AI Gateway** → **Model Fusion** e selecione <kbd> Model Fusion</kbd> no cabeçalho da página.

| Campo | Significado |
| - | - |
| **Name** | O último segmento da referência de modelo do gateway, `<workspace>@orq/<name>`. |
| **Synthesis mode** | Quem escreve a resposta final: **Analysis** ou **Judge writes final**. |
| **Preset** | A estratégia de julgamento: **General**, **Quality**, **Budget**, **Code** ou **Safety**. |
| **Models** | O painel que responde à requisição, de 1 a 8 modelos de chat. |
| **Judge model** | Compara as respostas do painel e registra onde elas concordam e divergem. |
| **Orchestrator model** | Escreve a resposta final no modo **Analysis**. |
| **Web tools** | Permite que o painel e o juiz chamem ferramentas web. |
| **Include raw panel answers** | Envia as respostas do painel para a síntese junto com a análise do juiz. |
| **Max tool calls** | Chamadas de ferramentas por fase, padrão 8; `0` desativa as ferramentas web. |

A lista pode ser filtrada por **Preset** e **Status**, e o controle na coluna **Status** ativa ou desativa uma fusion sem excluí-la. A página de detalhes traz a telemetria de **Overview**, **Traces** e **Settings**.

> [!NOTE]
>
> Criar ou alterar uma fusion pelo SDK ou pela API exige uma Management Key com acesso a **Model fusions**. A referência do SDK de Model Fusion abrange as chamadas de listar, criar, recuperar, atualizar, ativar, desativar e excluir. As chamadas à fusion pelo gateway usam uma API Key comum.

## Como usar

Passe a fusion ao gateway como `<workspacename>@orq/<name>`, o mesmo formato de referência do [Smart Router](/docs/pt-BR/ai-gateway/smart-router.md).

```bash cURL (Responses API) theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://router.toqan.ai/eu/v3/router/responses' \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "workspace_name@orq/my-fusion",
    "instructions": "You are a helpful assistant.",
    "input": "Summarize the trade-offs."
  }'
```

```typescript TypeScript (Responses API) theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { OpenAI } from 'openai';

const client = new OpenAI({
  baseURL: 'https://router.toqan.ai/eu/v3/router',
  apiKey: process.env.TOQAN_API_KEY,
});

const response = await client.responses.create({
  model: 'workspace_name@orq/my-fusion',
  instructions: 'You are a helpful assistant.',
  input: 'Summarize the trade-offs.',
});

console.log(response.output_text);
```

```python Python (Responses API) theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    base_url='https://router.toqan.ai/eu/v3/router',
    api_key=os.getenv('TOQAN_API_KEY'),
)

response = client.responses.create(
    model='workspace_name@orq/my-fusion',
    instructions='You are a helpful assistant.',
    input='Summarize the trade-offs.',
)

print(response.output_text)
```

```bash cURL (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://router.toqan.ai/eu/v3/router/chat/completions' \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "workspace_name@orq/my-fusion",
    "messages": [{ "role": "user", "content": "Summarize the trade-offs." }]
  }'
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { OpenAI } from 'openai';

const client = new OpenAI({
  baseURL: 'https://router.toqan.ai/eu/v3/router',
  apiKey: process.env.TOQAN_API_KEY,
});

const completion = await client.chat.completions.create({
  model: 'workspace_name@orq/my-fusion',
  messages: [{ role: 'user', content: 'Summarize the trade-offs.' }],
});

console.log(completion.choices[0]?.message?.content);
```

```python Python (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    base_url='https://router.toqan.ai/eu/v3/router',
    api_key=os.getenv('TOQAN_API_KEY'),
)

completion = client.chat.completions.create(
    model='workspace_name@orq/my-fusion',
    messages=[{'role': 'user', 'content': 'Summarize the trade-offs.'}],
)

print(completion.choices[0].message.content)
```

## Modos de síntese

| Modo | Resposta final |
| - | - |
| **Analysis** | O **Orchestrator model** a escreve a partir da análise do juiz, além das respostas brutas do painel quando **Include raw panel answers** está ativado. |
| **Judge writes final** | O juiz a escreve na mesma chamada, portanto nenhum orquestrador é usado. |

## Presets

O preset muda o que o juiz pondera.

| Preset | Foco do juiz |
| - | - |
| **General** | Concordâncias e contradições no painel. |
| **Quality** | Qualidade do raciocínio e fidelidade às instruções acima do estilo. |
| **Budget** | Sem chamadas de ferramentas e arrays mais curtos, para que a execução custe menos. |
| **Code** | Correção em tempo de execução, uso indevido de APIs e segurança. |
| **Safety** | Riscos físicos, financeiros, jurídicos e médicos. |

## Limites

* O painel aceita de 1 a 8 modelos de chat distintos. Apenas modelos de provedores: outra fusion não pode fazer parte do painel.
* **Max tool calls** varia de 0 a 20 por fase. O preset **Budget** mantém as ferramentas web desativadas independentemente do controle.
* A requisição é respondida com um erro quando todas as chamadas do painel falham ou quando a chamada do juiz ou do orquestrador falha.

Uma requisição de fusion contém a conversa e nada mais: o painel, o juiz e o orquestrador vêm da configuração da fusion. Uma requisição que define um controle de geração, roteamento ou ferramentas é rejeitada com `invalid_model_fusion` (400), em vez de aplicá-lo a uma chamada interna. Remova os campos listados; o painel, o juiz, o orquestrador e as ferramentas web são definidos na fusion.

> [tab] Responses API
>
> | Grupo | Campos rejeitados |
> | - | - |
> | Amostragem e raciocínio | `temperature`, `top_p`, `frequency_penalty`, `presence_penalty`, `top_logprobs`, `max_output_tokens`, `reasoning`, `thinking`, `text.verbosity` |
> | Cache, roteamento, contabilização | `cache_control`, `prompt_cache_key`, `prompt_cache_retention`, `prompt_cache_options`, `service_tier`, `fallbacks`, `load_balancer`, `retry`, `timeout` |
> | Ferramentas e conteúdo de entrada | `tools`, `tool_choice`, `parallel_tool_calls`, `max_tool_calls` e, em `input`: um item de resultado de ferramenta ou uma parte de conteúdo que não seja texto |
> | Formato da saída | Um JSON schema em `text.format`, `include`, `truncation` diferente de `auto`, `stream_options` |
> | Formato da conversa e da requisição | `previous_response_id`, `conversation`, `memory`, `template_engine`, `variables`, `background`, `safety_identifier`, `user`, `integration_id`, `limits`, `context_management`, `moderation`, `prompt` |

> [tab] Chat completions
>
> | Grupo | Campos rejeitados |
> | - | - |
> | Amostragem e raciocínio | `temperature`, `top_p`, `top_k`, `n`, `max_tokens`, `max_completion_tokens`, `frequency_penalty`, `presence_penalty`, `seed`, `logprobs`, `top_logprobs`, `stop`, `reasoning_effort`, `verbosity`, `thinking` |
> | Cache, roteamento, contabilização | `cache_control`, `prompt_cache_key`, `service_tier`, `store: true`, `fallbacks`, `load_balancer`, `retry`, `timeout` |
> | Ferramentas e conteúdo das mensagens | `tools`, `tool_choice`, `parallel_tool_calls`, `max_tool_calls` e, em `messages`: uma mensagem `role: tool`, `tool_calls`, `tool_call_id`, conteúdo de áudio ou uma parte de conteúdo diferente de `text` e `input_text` |
> | Formato da saída | `response_format` diferente de `text`, o parâmetro `audio`, uma entrada não textual em `modalities` |

## Custo

Uma requisição de fusion faz várias chamadas de modelo: uma por modelo do painel, uma chamada do juiz, mais no máximo uma tentativa de correção quando a análise dele não passa na validação e, no modo **Analysis**, uma chamada do orquestrador. Cada chamada paga pelo seu próprio prompt.

* Uma chamada do painel contém a requisição mais um prompt fixo do painel.
* A chamada do juiz contém a requisição mais **todas** as respostas do painel, então sua entrada cresce com o tamanho do painel e com o comprimento das respostas, e não apenas com a requisição.
* A chamada do orquestrador contém a requisição, a análise estruturada do juiz e as respostas brutas do painel quando **Include raw panel answers** está ativado.

O uso e o custo na resposta da fusion somam todas as chamadas internas. O faturamento segue as chamadas internas; o total agregado não é cobrado novamente.

Os Traces mostram a execução em três fases, `panel`, `judge` e `synthesis`, cada uma com um span por chamada de modelo contendo os tokens e o custo dessa chamada.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.