Este modelo foi contribuído para o Hugging Face Transformers em 2026-10-16.

Beam

Visão geral

Beam é o primeiro modelo de pesos abertos da Reflection, um modelo de linguagem do tipo mixture-of-experts (MoE) esparsa com 501B de parâmetros totais e 23B de parâmetros ativos por token, projetado para cargas de trabalho de codificação, raciocínio e agentes. Ele foi pré-treinado em 23,8T de tokens e pós-treinado com aprendizado por reforço assíncrono em larga escala. O Beam é apenas de texto e raciocina antes de cada resposta. Uma configuração de esforço de raciocínio no template de chat controla a intensidade desse raciocínio.

O Beam possui 52 camadas de decodificador e combina os seguintes recursos:

• Atenção deslizante híbrida e atenção completa. A cada sexta camada e a última camada usam atenção completa, e as demais prestam atenção aos sliding_window (512) tokens mais recentes. layer_types define o padrão.
• RoPE nas camadas deslizantes, NoPE nas camadas completas. rope_parameters é indexado pelo tipo de camada, e None indica um tipo de camada sem codificação posicional. As camadas de atenção completa escalam as consultas (softmax escalável): a consulta na posição n (base 1) é multiplicada por (1 + n / 2048) ** 0.1, o que impede que a atenção se aplane à medida que o contexto cresce.
• Atenção com portão (gated attention). Atenção de consulta agrupada (grouped-query attention) com 48 cabeças de consulta e 8 cabeças de chave/valor, e RMSNorm em cada cabeça de consulta e chave. Um portão sigmoide calculado a partir da entrada da atenção, com um viés aprendido por cabeça, escala a saída da atenção elemento a elemento antes da projeção de saída.
• MoE esparsa. As 3 primeiras camadas usam um MLP SwiGLU denso, e as 49 camadas restantes roteiam cada token para 8 de 256 especialistas, sem especialista compartilhado (mlp_layer_types define o padrão). O roteador pontua os especialistas com uma sigmoid, equilibra a carga com um viés aprendido por especialista em vez de uma perda auxiliar, e restringe cada token aos melhores topk_group de n_group grupos de especialistas. Os pesos de roteamento são normalizados, e a saída do MoE é escalada por routed_scaling_factor.
• Normas em sanduíche com resíduos escalados pela profundidade. Cada bloco de atenção e MLP é envolvido por um RMSNorm antes e depois. As adições de resíduo são reescaladas de modo que, após k contribuições (contando os embeddings como a primeira), o fluxo de resíduo seja a soma delas dividida por sqrt(k).
• Limitação suave dos logits finais. Os logits são limitados com 30 * tanh(logits / 30) (final_logit_softcapping).

A implementação calcula o escalonamento do RMSNorm, a ativação SwiGLU, o RoPE, o escalonamento da query, o roteamento e o softcapping em FP32 para corresponder à numérica com a qual o Beam foi treinado e servido. Os pesos do roteador e o viés dos especialistas são mantidos em FP32 no momento do carregamento, e os logits retornados são sempre em FP32.

Você pode encontrar todos os checkpoints originais do Beam na organização Reflection.

Este modelo foi contribuído por yonigozlan.

Exemplos de uso

O chat template do Beam formata conversas no formato Harmony do Beam, e seu response template interpreta o texto gerado de volta em uma mensagem com os campos thinking, content e tool_calls. Os exemplos abaixo geram uma resposta com Pipeline ou com a classe AutoModelForCausalLM.

O checkpoint BF16 tem cerca de 1 TB, portanto os exemplos o dividem em 8 dispositivos, alocando especialistas roteados inteiros em cada dispositivo com parallelismo de especialistas. Inicie-os com torchrun --nproc-per-node 8 <script.py>.

from transformers import DistributedConfig, pipeline

pipe = pipeline(
    task="text-generation",
    model="reflection/Beam-1.0-501B-A23B",
    model_kwargs={"distributed_config": DistributedConfig(tp_size=8, ep_size=8)},
)

messages = [{"role": "user", "content": "Explain in one sentence why the sky is usually blue."}]
output = pipe(messages, max_new_tokens=2048)
reply = output[0]["generated_text"][-1]
print(reply["thinking"])
print(reply["content"])

from transformers import AutoModelForCausalLM, AutoTokenizer, DistributedConfig

model_id = "reflection/Beam-1.0-501B-A23B"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, distributed_config=DistributedConfig(tp_size=8, ep_size=8))

messages = [{"role": "user", "content": "Explain in one sentence why the sky is usually blue."}]
inputs = tokenizer.apply_chat_template(
    messages, add_generation_prompt=True, return_tensors="pt", return_dict=True, reasoning_effort="low"
).to(model.device)

outputs = model.generate(**inputs, max_new_tokens=2048)
generated = tokenizer.decode(outputs[0, inputs["input_ids"].shape[1] :])
message = tokenizer.parse_response(generated, prefix=inputs["input_ids"][0])
print(message["thinking"])
print(message["content"])

Prefira isso em vez de device_map="auto", que coloca camadas inteiras em cada dispositivo, as executa um dispositivo por vez e pode esgotar a memória durante o carregamento.

Gere amostras com a temperature=0.7 e a top_p=0.99 recomendadas pela Beam, que a GenerationConfig do checkpoint define como padrões. Passe do_sample=False para decodificar de forma gulosa.

Esforço de raciocínio

Passe reasoning_effort para apply_chat_template() para controlar o quanto o Beam raciocina. Ele aceita um orçamento inteiro ou um dos rótulos abaixo. O Beam não foi treinado com esforços abaixo de 8, portanto, valores menores não são respeitados.

Quando reasoning_effort não está definido, o modelo usa max. Se max_new_tokens se esgotar durante o raciocínio, a mensagem analisada terá thinking, mas não terá content.

Conversas de múltiplas rodadas

Anexe a mensagem analisada ao histórico como está. A saída do Beam se degrada sem seu raciocínio anterior, que o modelo de chat lê de thinking (reasoning_content e reasoning também são aceitos). Por padrão, uma resposta do assistente sem raciocínio é renderizada com um bloco de raciocínio vazio. Passe allow_missing_thinking=False para gerar um erro em vez disso quando add_generation_prompt=True, o que é recomendado ao servir o Beam.

messages.append(message)
messages.append({"role": "user", "content": "And why are sunsets red?"})
inputs = tokenizer.apply_chat_template(
    messages, add_generation_prompt=True, return_tensors="pt", return_dict=True
).to(model.device)

Chamada de ferramentas

Passe tools tanto para apply_chat_template() quanto para parse_response(). Com tools, os argumentos analisados são convertidos para os tipos definidos no esquema de cada ferramenta; sem ele, todos os argumentos são strings.

def get_weather(city: str):
    """
    Get the current weather in a city.

    Args:
        city: The city name.
    """
    return "Sunny, 22 C"


messages = [{"role": "user", "content": "What's the weather like in Paris right now?"}]
inputs = tokenizer.apply_chat_template(
    messages, tools=[get_weather], add_generation_prompt=True, return_tensors="pt", return_dict=True
).to(model.device)
outputs = model.generate(**inputs, max_new_tokens=2048)
generated = tokenizer.decode(outputs[0, inputs["input_ids"].shape[1] :])
message = tokenizer.parse_response(generated, prefix=inputs["input_ids"][0], tools=[get_weather])
print(message["tool_calls"])
# [{'type': 'function', 'function': {'name': 'get_weather', 'arguments': {'city': 'Paris'}}}]

messages.append(message)
for call in message["tool_calls"]:
    result = get_weather(**call["function"]["arguments"])
    messages.append({"role": "tool", "name": call["function"]["name"], "content": result})

Em seguida, gere novamente a partir de messages para obter a resposta final. As chamadas de ferramentas analisadas não possuem id, e o formato corresponde os resultados às chamadas por posição, portanto, retorne os resultados das ferramentas na ordem das chamadas. A geração é interrompida após uma resposta final (<|return|>) ou uma chamada de ferramenta (<|call|>); generation_config.json lista ambos.

Para streaming, get_response_parser() retorna um parser ao qual você feed() os blocos de texto conforme são gerados. Consulte Response parsing para mais detalhes.

Observações

• Argumentos de template. Além de reasoning_effort, o template de chat aceita model_identity (substitui a primeira linha da mensagem de sistema), builtin_tools e allow_missing_thinking. builtin_tools deve nomear apenas as ferramentas search e browse, e somente com as definições com as quais o Beam foi treinado. Outras ferramentas precisam apenas de tools. As mensagens system e developer são renderizadas apenas no início da conversa.
• Treinamento. O modelo de chat marca a saída do assistente para apply_chat_template(..., return_dict=True, return_assistant_tokens_mask=True), de modo que o SFTConfig(assistant_only_loss=True) do TRL treina apenas nos tokens do assistente. A máscara cobre o raciocínio, a resposta e as chamadas de ferramenta de cada turno do assistente.
• Sem perda auxiliar. O roteador equilibra a carga dos especialistas por meio do seu viés, portanto BeamForCausalLM não calcula nenhuma perda de balanceamento de carga. output_router_logits=True ainda retorna os logits do roteador.

BeamConfig

>>> from transformers import BeamConfig

>>> # Initializing a Beam configuration
>>> configuration = BeamConfig()

BeamModel

BeamForCausalLM