---
title: "Modelli"
description: "Come Beeuni sceglie un modello e come funziona la fatturazione per i modelli gestiti e per quelli con la tua chiave."
---
Beeuni esegue ogni [session](/docs/it/work/sessions) su un modello. Questa pagina
spiega la differenza tra modelli gestiti e la tua chiave del provider (BYOK), come Beeuni sceglie
automaticamente un modello e due aspetti della fatturazione da conoscere.
Questa pagina si applica ai progetti con LLM Gateway attivo. LLM Gateway è un
[feature flag](/docs/it/feature-flags) sperimentale, **attivo per impostazione predefinita** dove la
piattaforma lo offre — puoi verificarlo o modificarlo in Settings → Feature flags .
Disattivare il flag è un percorso completamente supportato. Il progetto utilizza quindi la
**gestione nativa dei modelli di harness standard**. Ogni sessione del progetto esegue l'
[harness](/docs/it/work/harnesses) di harness standard: harness sperimentale chiama i modelli solo tramite il gateway.
- Le chiavi API dei tuoi provider (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
`OPENROUTER_API_KEY`, …) vengono iniettate nella sandbox come normali variabili
d'ambiente — aggiungile nella pagina delle impostazioni Model oppure come
[secrets](/docs/it/project/secrets). harness standard connette automaticamente ogni provider usando la relativa
chiave.
- Gli ID dei modelli sono riferimenti `provider/model` nativi di harness standard, come
`anthropic/claude-opus-4-8`. Gli ID semplici gestiti e i riferimenti `beeuni/…` non
esistono al di fuori del gateway.
- Il selettore dei modelli mostra lo stesso elenco prima e dopo l'avvio della sandbox: i
provider a cui si connettono le tue chiavi, più i modelli gratuiti di OpenCode Zen (OpenCode
vi si connette senza una chiave). Il livello di ragionamento è il controllo del ragionamento
del compositore (le varianti proprie del modello); le impostazioni predefinite Generation del
gateway non si applicano.
- Le funzionalità del gateway mostrate in questa pagina — modelli gestiti, catena dei modelli
predefiniti, budget, log — non si applicano; OpenCode risolve il modello predefinito nella
sandbox.
## Modelli gestiti e BYOK
Un ID modello ha una delle tre forme seguenti:
- **Gestito** — un ID semplice, come `glm-5.2`, `deepseek-v4-pro-0813` o
`grok-4.6`. Beeuni
fornisce le credenziali. Gli account Cloud pagano con i crediti Beeuni.
- **BYOK** — un ID `provider/model`, come `anthropic/claude-opus-4-8`. Fornisci tu la
chiave. Paga il tuo account del provider.
- **ChatGPT** — un ID `codex/`. Colleghi una volta il tuo piano ChatGPT tramite
OAuth, che provvede al pagamento.
Collega una chiave BYOK nella pagina delle impostazioni Model del progetto oppure imposta
direttamente la variabile d'ambiente del provider come [secret](/docs/it/project/secrets).
Ogni provider legge la propria chiave. Alcuni provider condividono una variabile d'ambiente su
models.dev; per esempio, OpenCode Zen (`opencode`) e OpenCode Go
(`opencode-go`) elencano entrambi `OPENCODE_API_KEY`. Il provider proprietario del nome
lo mantiene. Ogni altro provider legge `_API_KEY`: OpenCode Go legge
`OPENCODE_GO_API_KEY`, Z.ai Coding Plan legge `ZAI_CODING_PLAN_API_KEY` e
Moonshot China legge `MOONSHOTAI_CN_API_KEY`. Pertanto una chiave Zen non elenca mai i
modelli Go. Il modulo di connessione e `beeuni providers set` usano il nome corretto.
### OpenCode Zen e Go (accedi con OpenCode)
Collega OpenCode Zen o OpenCode Go con una chiave API oppure accedi con il tuo account
OpenCode Console:
1. Apri **Customize → Models → Providers** e trova **OpenCode Go**.
2. Scegli **Sign in with OpenCode**. Copia il codice, scegli **Open auth page**
e approva il dispositivo nel tuo workspace OpenCode.
3. Il campo della chiave mostra il provider come connesso. Rimuovi la chiave per disconnetterti.
Dalla CLI: `beeuni providers login opencode-go` oppure `beeuni providers
login opencode` per Zen. I modelli Zen vengono utilizzati tramite ID, ad esempio
`opencode/glm-5.3-flash`; il selettore non li elenca. Zen e Go conservano ciascuno il proprio accesso,
quindi accedere a uno non connette mai l'altro. L'accesso dura 30 giorni e Beeuni lo rinnova
prima della scadenza. Quando OpenCode rifiuta un accesso, Beeuni lo rinnova una volta e
ripete la richiesta. Se anche il rinnovo fallisce, la richiesta restituisce `provider_reauth_required`:
accedi di nuovo.
### Modelli gestiti da Beeuni
Il selettore li elenca sotto **Beeuni**, con le relative tariffe per token. La piattaforma
fornisce le credenziali tramite il gateway dei modelli configurato.
| Modello | ID |
| --- | --- |
| GPT-6 Astra | `gpt-6-astra` |
| GPT-6 Sol (predefinito della piattaforma) | `gpt-6-sol` |
Usa altri modelli tramite una chiave BYOK o un piano ChatGPT. Una chiave BYOK offre l'intero
catalogo del relativo provider, ad esempio `anthropic/claude-opus-5-5` con una chiave Anthropic. Un
piano ChatGPT offre tutti i modelli che Codex mette a disposizione di un account ChatGPT, ad
esempio `codex/gpt-6.1-sol`. Per impostazione predefinita, il selettore mostra il modello harness sperimentaleù
recente di ogni famiglia.
Entrambi gli elenchi si aggiornano automaticamente. L'API legge [models.dev](https://models.dev)
e l'elenco dei modelli pubblicato dalla CLI di Codex ogni ora, quindi una nuova versione appare
entro un'ora dalla sua pubblicazione, senza una versione di Beeuni. Quando colleghi un provider,
il suo modello stabile harness sperimentaleù recente con supporto alle chiamate agli strumenti diventa il modello
predefinito.
## Disattivare provider o modelli
Apri **Customize → Models → Providers**. Apri il menu **⋯** nella riga **Beeuni** e scegli
**Disable provider** per usare solo i tuoi provider. Beeuni appare nello stesso elenco degli altri
provider, con il numero di modelli e la descrizione della fatturazione tramite crediti. Ogni
provider usa lo stesso menu. Solo i provider disattivati mostrano un badge di stato. Scegli
**Enable provider** dal menu per ripristinare l'accesso.
Apri la scheda **Models** per attivare o disattivare singoli modelli. Un provider disattivato
blocca tutti i suoi modelli, compresi quelli aggiunti in seguito. Riattivando il provider,
le scelte relative ai singoli modelli vengono mantenute. Le credenziali restano salvate per tutto
il tempo.
Il modello predefinito del progetto e il relativo provider non possono essere disattivati. Seleziona
prima un altro modello predefinito attivo. I responsabili del progetto possono modificare
l'accesso; i lettori possono consultarlo.
Questi controlli si applicano alle nuove richieste tramite il gateway Beeuni, incluse le selezioni
salvate nelle sessioni e i candidati di fallback. Una richiesta già inviata a un upstream termina
normalmente. Le destinazioni disattivate restituiscono `provider_disabled` o `model_disabled`; scegli
un modello attivo per continuare. La modalità nativa di harness standard non utilizza questa policy del
gateway.
Le preferenze di visibilità esistenti, limitate al selettore, restano separate. Il ripristino
dell'elenco dei modelli non rimuove le restrizioni di accesso esplicite.
## Livello di ragionamento
Il controllo del ragionamento del compositore imposta la **variante** del modello della sessione
in entrambe le modalità. Le opzioni sono i livelli pubblicati dal modello (models.dev
`reasoning_options`), mai una scala fissa; un modello senza controllo non mostra alcuna
opzione. `Auto` rimuove la variante.
- Nativo (gateway desativado): o harness standard aplica a variante como campo de solicitação próprio do provedor.
- Gateway ativado: a solicitação contém `reasoning_effort`; o gateway faz o mapeamento conforme o provedor upstream (OpenAI → `reasoning_effort`, Claude → thinking adaptativo, OpenAI no Amazon Bedrock → campo de solicitação `reasoning.effort` do Bedrock). Para um provedor upstream que ainda não consegue mapear (Nova, Grok no Bedrock atualmente), o valor é descartado e o modelo é executado com seu padrão.
- O Amazon Bedrock rejeita o ID regional simples da maioria dos modelos atuais ("on-demand throughput isn't supported"). O seletor prioriza o ID de `global.` / perfil de inferência regional quando o catálogo o inclui, e o gateway tenta novamente um ID simples rejeitado uma vez por prefixo de perfil (`global.`, `us.`).
- A cada inicialização, o sandbox obtém da API o conjunto de modelos que o projeto pode servir (`GET /v1/llm/models?scope=picker`, a mesma composição do seletor da web), para que um modelo oferecido pelo seletor sempre esteja disponível no runtime.
- Um padrão do projeto por modelo fica em Customize → Models → Routing → Advanced → **Generation defaults** (`model_generation_config`). Ele preenche apenas um campo não definido pela solicitação, portanto a variante da sessão sempre prevalece.
## Como o modo automático escolhe um modelo
Não defina um modelo, e o Beeuni resolverá um seguindo até cinco camadas, nesta ordem. (O ID `auto` abrange esse mesmo comportamento, mas ainda não é uma opção selecionável no seletor de modelos.)
1. Uma fixação explícita — o campo `model:` da própria sessão, canal ou gatilho.
2. O padrão do [agente](/docs/it/project/agents) para este projeto.
3. O padrão do projeto.
4. O padrão da conta.
5. O padrão da plataforma.
O Beeuni usa a primeira camada que tenha um valor que ainda possa servir. Um padrão salvo que deixe de funcionar — uma chave desconectada, um modelo descontinuado — é ignorado automaticamente. Uma sessão nunca deixa de funcionar por causa de um padrão desatualizado. Consulte a [referência do manifesto](/docs/it/project/manifest) para o campo `model:` do gatilho.
:::warning[Surpresas de cobrança ao usar BYOK]
Dois custos são fáceis de ignorar em uma conta de nuvem paga:
- I crediti coprono le chiamate ai modelli, gli strumenti e l’utilizzo del computer. Consulta Billing per il saldo e Usage per i dettagli.
- **Failover silencioso.** Se sua chave BYOK atingir um limite de taxa ou apresentar um erro de cobrança no meio de um turno, o Beeuni tenta novamente com um modelo gerenciado e cobra seus créditos em vez de encerrar a sessão com erro.
Se houver cobranças de créditos em um projeto que usa somente BYOK, verifique essas duas causas antes de relatar um erro de cobrança.
:::
Quando um modelo de fallback responde, a sessão informa isso. O compositor mostra **Running on** e o nome do modelo ao lado do seletor de modelos. Os detalhes de cada turno informam qual modelo respondeu, qual modelo ele substituiu e quanto o Beeuni cobrou pelo turno. **Customize → Models → Costs** contabiliza esse gasto no modelo que respondeu.
## Ativação de modelos por projeto
O projeto controla quais modelos seus seletores oferecem. Por padrão, o modelo mais recente de cada família é oferecido automaticamente. Os modelos gerenciados pelo Beeuni e todos os modelos referenciados pelos padrões ou pela política de roteamento do projeto são sempre oferecidos — uma regra de proteção nunca os remove.
Você pode substituir o padrão de modelos individuais na página **Manage models** (Customize → Models). A exceção é armazenada por projeto e entra em vigor imediatamente. O seletor de modelos da sessão e a paleta de comandos ocultam tudo que você desativar; novos modelos permanecem ativados por padrão conforme o catálogo cresce.
A ativação determina o que é oferecido, não o que é servido: uma solicitação que especifique diretamente um modelo desativado (por exemplo, pela API bruta) ainda será executada. Não é possível desativar o modelo padrão do projeto — primeiro defina outro modelo como padrão.
## Chaves de provedores e acesso de membros
Com **Pooled provider secrets** desativado, uma chave de provedor conectada se aplica ao projeto inteiro. Substituições pessoais para esses segredos do projeto retornam `llm_credentials_project_wide`.
Ative **Pooled provider secrets** e **LLM Gateway** em Settings → Feature flags para usar recursos de segredos de provedores. Acesse **Customize → Models → Providers** e escolha **Add key** ao lado de um provedor. Dê um rótulo exclusivo a cada chave. O valor é somente para gravação; as telas seguintes mostram o rótulo e a lista de acesso.
As novas chaves pertencem a este projeto. Por padrão, **Everyone in this project** pode usá-las. Abra **⋯ → Manage access** de uma chave e escolha **Specific members** para restringir o acesso. Os recursos legados para toda a conta mantêm as permissões de membros existentes.
Ainda se aplicam a associação à conta, as permissões do projeto, as permissões do agente para acessar segredos e a seleção da sessão.
A autorização de um membro permite usar a chave sem revelá-la. A rotação de uma chave preserva o acesso e as seleções de sessão. A exclusão remove o acesso de todos.
### Escolher chaves para uma sessão
Abra **Session overrides → Provider keys** no compositor. Escolha um provedor e selecione até dez chaves. Escolha **Save changes** no rodapé do painel.
Em uma nova sessão, a seleção é enviada com o primeiro prompt.
- Sem uma seleção explícita, a chave existente do projeto permanece disponível.
- Selecionar nenhuma chave desativa esse provedor para a sessão. Isso não restaura a chave do projeto.
- **Reset to project default** remove a seleção explícita.
- Chaves revogadas ou inativas aparecem como indisponíveis. Remova-as da seleção, escolha outra chave ou redefina a seleção.
- A exclusão da última chave selecionada deixa o conjunto vazio. As configurações da sessão ainda mostram esse provedor para que você possa redefini-lo.
- Uma falha de leitura mostra **Try again**. Ela nunca aparece como uma seleção herdada.
Se ocorrer um limite de taxa antes do início da saída, o gateway tentará outra chave selecionada. Ele nunca reproduz uma resposta parcial usando outra chave. Se todas as chaves atingirem o limite de taxa, tente novamente após o cooldown mais curto, limitado a 60 segundos. Um conjunto explícito não toma emprestada silenciosamente a chave de outro membro nem a credencial legada do projeto.
### Contas do ChatGPT
Escolha **Add account** em **ChatGPT Plus/Pro**. Cada autorização cria uma conexão com nome próprio neste projeto. Por padrão, **Everyone in this project** pode usá-la. Use **Manage access → Specific members** para restringir o acesso.
Uma sessão pode selecionar várias contas do ChatGPT autorizadas. Sem uma seleção, a conexão utilizável mais recente do membro é usada como padrão. A conexão compartilhada de outro membro requer uma seleção explícita. O login legado do projeto continua disponível quando o membro não tem uma conexão própria utilizável. Uma chave compartilhada do gateway não pode usar emprestada a conexão privada do ChatGPT de quem a criou.
Com o gateway ativado, as chaves da API do Google Gemini usam o endpoint compatível com OpenAI do Google. O modo nativo do harness standard continua usando os segredos do projeto.
Modelos ocultos por preferências antigas do seletor exibem **Hidden from picker**. Solicitações diretas continuam permitidas. Abra o menu do modelo e escolha **Disable model** para também bloquear a inferência.
Os links de contagem de modelos do provedor abrem a guia **Models**. Todos os grupos de provedores aparecem juntos na mesma lista usada para ativar ou desativar modelos e definir padrões. A pesquisa filtra a lista. Conecte um provedor antes de gerenciar seus modelos.
Le selezioni dei provider restano come bozze finché non fai clic su **Save changes** nel harness sperimentaleè di pagina delle sostituzioni di sessione. In questo modo vengono salvate le modifiche per tutti i provider, incluso il ripristino dei valori predefiniti. Puoi passare da una sezione all'altra o chiudere e riaprire il pannello senza perdere queste bozze. Ricaricando la pagina, le modifiche non salvate vengono scartate.
Se il salvataggio non riesce, il pannello rimane aperto e mostra l'errore. Correggi la selezione o riprova. I provider già salvati restano salvati; le modifiche incomplete rimangono nel pannello.
## Budget
Un budget del gateway limita la spesa di un progetto, o di un singolo membro al suo interno, per i modelli, su base giornaliera, settimanale o mensile. **Block** rifiuta le nuove richieste al raggiungimento del limite; **Warn only** le lascia passare. Imposta i budget nella pagina Models del progetto.
Quando si raggiunge l'80% e il 100% del limite di un budget, Beeuni invia un'email ai proprietari e agli amministratori dell'account e ai responsabili del progetto, una volta per soglia per periodo.
## Usare il gateway da Claude Code
Il gateway espone l'API Anthropic Messages all'indirizzo `POST /v1/messages`. Claude
Code e gli SDK Anthropic possono usarlo per chiamare qualsiasi modello del gateway.
1. Crea una chiave in **Customize → Gateway**, scheda **Gateway**.
2. Avvia Claude Code impostando il gateway come endpoint API:
```bash
ANTHROPIC_BASE_URL=https://gateway.beeuni.ai \
ANTHROPIC_AUTH_TOKEN=beeuni_gw_... \
claude --model kimi-k3
```
Il gateway legge la chiave da `Authorization: Bearer` o da `x-api-key`, quindi
funziona anche `ANTHROPIC_API_KEY`.
Il gateway traduce questi campi di Claude Code per ogni provider:
- `thinking: {type: "adaptive"}` con `output_config.effort` diventa
`reasoning_effort`. Vedi [Thinking effort](#thinking-effort).
- L'utilizzo nell'ultimo `message_delta` include `input_tokens`,
`cache_read_input_tokens` e `cache_creation_input_tokens`. Claude Code li
usa per `/context` e la compattazione automatica.
- Le immagini restituite da uno strumento, ad esempio `Read` di uno screenshot, arrivano al modello in un messaggio utente dopo il risultato dello strumento.
- Se uno stream del provider termina prima del completamento, restituisce un evento `api_error`,
così Claude Code riprova il turno.
Limiti:
- `/v1/messages/count_tokens` restituisce `404`. Claude Code stima quindi
il conteggio in base ai caratteri.
- Il testo di ragionamento non viene restituito in blocchi `thinking`.
- I modelli ChatGPT (`codex/*`) richiedono una connessione ChatGPT condivisa con
**Everyone in this project**. Una chiave del gateway non può usare una connessione privata.
- Claude Code non può impostare una finestra di contesto per ogni modello. Imposta
`CLAUDE_CODE_MAX_CONTEXT_TOKENS` sulla finestra harness sperimentaleù piccola che usi.