Treine a IA

Treinar e exportar

Rode o treino com PPO e self-play, acompanhe pelos gráficos, avalie e leve o modelo para a sua sala.

Rodar o treino

bash
python treinar.py --passos 5000000 --envs 4

O que aparece no terminal:

text
[salvo] 100000 passos, estágio 1
[currículo] passou para o estágio 2 (822320 passos)
[currículo] passou para o estágio 3 (870212 passos)
...
OpçãoPadrãoO que faz
--passos5 milhõesQuantos passos treinar nesta rodada
--envs4Simulações em paralelo (use 2, 4 ou 8)
--visaoagoraComo a IA vê o jogo; precisa combinar com a sala (por quê)
--novo—Começa do zero (o checkpoint antigo é ignorado, não apagado)
--salvar100 milDe quantos em quantos passos grava o checkpoint
--rival-a-cada250 milDe quantos em quantos passos a IA de agora entra na "liga" de adversários

Pode parar com Ctrl+C quando quiser: ele salva antes de sair. Rodando python treinar.py de novo, continua de onde parou (o estágio do currículo fica em checkpoints/estado.json).

Quanto tempo leva

Medido num PC comum com --envs 4 (~750 passos/s):

MarcoPassosTempo
Sai do estágio 1 (acha a bola e faz golo sem guarda-redes)~820 mil~18 min
Sai do estágio 2 (adversário parado no caminho)~870 mil~1 min depois
Contra o script mais forte: 78 golos, 21 sofridos em 100 lances2 milhões~45 min
Modelo publicado: 95 golos, 2 sofridos182 milhõesdias (o nosso rodou em várias máquinas)

Os números acima são de um treino de verdade com o kit, num PC comum. O seu pode variar um pouco (a sorte dos primeiros lances muda o caminho), mas a ordem de grandeza é essa.

Acompanhar pelos gráficos

bash
tensorboard --logdir checkpoints/tb

Abra o endereço que ele mostrar (normalmente http://localhost:6006):

GráficoO que esperar
bonk/golsSobe até a meta e cai quando o estágio muda (o exercício ficou mais difícil). Normal
bonk/sofridosNo estágio 3, deve cair com o tempo
bonk/estagio1 → 2 → 3
rollout/ep_rew_meanA nota média por lance. Sobe aos poucos
train/entropy_lossO quanto a IA ainda "experimenta". Vai diminuindo; se despencar cedo, ela parou de explorar

Avaliar

bash
python avaliar.py checkpoints/policy.json --lances 200

Joga contra o script mais forte, decidindo exatamente como a sala (eixo a eixo, com o atraso escolhido). Para ter uma referência, o modelo publicado dá:

text
$ python avaliar.py football-1x1.policy.json --lances 100
100 lances: 95 gols, 2 sofridos, 3 sem gol (saldo +0.93 por lance)

Levar para a sala

O treino já grava checkpoints/policy.json a cada checkpoint. É só copiar para a pasta da sala e usar no lugar do football-1x1.policy.json (ou apontar IA_MODELO para ele). Lembre de usar na sala o mesmo --visao do treino.

A exportação pega só a parte da rede que decide (a rede de valor só serve no treino) e grava os pesos em float32 em base64:

python
# politica.py
"""Exporta a rede treinada para o `policy.json` (o formato que a sala roda em JavaScript) e a roda de volta em NumPy
(para usar versões antigas como adversárias no self-play sem carregar outro PyTorch)."""
from __future__ import annotations

import base64
import time

import numpy as np

from .decisao import decide
from .features import ACTION_TABLE, N_ACTIONS, version_for_size

FORMATO = "bonktools-rl-policy/1"


def exportar(model) -> dict:
    """PPO (MlpPolicy do stable-baselines3) -> dict do policy.json. Só a parte que decide (a rede de valor fica)."""
    import torch

    p = model.policy
    lineares = [m for m in p.mlp_extractor.policy_net if isinstance(m, torch.nn.Linear)] + [p.action_net]
    ativacoes = {type(m).__name__ for m in p.mlp_extractor.policy_net if not isinstance(m, torch.nn.Linear)}
    if ativacoes != {"Tanh"}:
        raise ValueError(f"ativação inesperada: {ativacoes} (o formato só conhece Tanh)")

    def b64(t) -> str:  # float32 little-endian em base64: exato e ~4x menor que texto
        return base64.b64encode(t.detach().cpu().numpy().astype("<f4").tobytes()).decode("ascii")

    camadas = [{"in": l.in_features, "out": l.out_features, "w": b64(l.weight), "b": b64(l.bias)} for l in lineares]
    return {
        "format": FORMATO,
        "obsSize": camadas[0]["in"],
        "obsVersion": version_for_size(camadas[0]["in"]),
        "actionTable": ACTION_TABLE,
        "activation": "tanh",
        "layers": camadas,
        "timesteps": int(model.num_timesteps),
        "exportedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
    }


class PoliticaNP:
    """Roda um policy.json em NumPy: tanh nas camadas escondidas, linear na última (18 logits)."""

    def __init__(self, data: dict):
        if data.get("format") != FORMATO:
            raise ValueError(f"formato desconhecido: {data.get('format')}")
        self.obs_version = int(data["obsVersion"])
        self.timesteps = int(data.get("timesteps", 0))
        self.camadas = []
        for c in data["layers"]:
            w = np.frombuffer(base64.b64decode(c["w"]), dtype="<f4").reshape(c["out"], c["in"])
            b = np.frombuffer(base64.b64decode(c["b"]), dtype="<f4")
            self.camadas.append((w.astype(np.float64), b.astype(np.float64)))
        if self.camadas[-1][0].shape[0] != N_ACTIONS:
            raise ValueError("a rede não termina em 18 ações")

    def logits(self, obs: np.ndarray) -> np.ndarray:
        x = np.asarray(obs, dtype=np.float64)
        for i, (w, b) in enumerate(self.camadas):
            x = w @ x + b
            if i < len(self.camadas) - 1:
                x = np.tanh(x)
        return x

    def agir(self, obs: np.ndarray, anterior: int | None = None) -> int:
        """Decisão eixo a eixo (a mesma da sala), não o argmax puro."""
        return decide(self.logits(obs), anterior)

O script de treino completo

python
# treinar.py
"""Treina a IA de football 1x1 com PPO (stable-baselines3) e self-play.

    python treinar.py                     # começa do zero ou continua de checkpoints/latest.zip
    python treinar.py --passos 20000000   # quantos passos treinar nesta rodada
    python treinar.py --envs 4            # simulações em paralelo (1 processo Node cada; use 2, 4 ou 8)
    python treinar.py --novo              # ignora o checkpoint (não apaga nada)
    python treinar.py --visao atrasada    # para salas SEM os "olhos" (ver a documentação); padrão: agora
    tensorboard --logdir checkpoints/tb   # gráficos

A cada --salvar passos grava checkpoints/latest.zip, checkpoints/estado.json (estágio do currículo) e
checkpoints/policy.json (o modelo pronto para a sala).
"""
from __future__ import annotations

import argparse
import json
from collections import deque
from pathlib import Path

import numpy as np
from stable_baselines3 import PPO
from stable_baselines3.common.callbacks import BaseCallback
from stable_baselines3.common.vec_env import DummyVecEnv

from bonk_ia.ambiente import BonkFootballEnv, Liga
from bonk_ia.politica import exportar

PASTA = Path("checkpoints")
# Para avançar de estágio: taxa de gol nos últimos 400 lances.
META = {1: 0.7, 2: 0.6}

# Base do RLGym-PPO-Guide: lr 2e-4, poucas épocas, lotes grandes, entropia 0,01. Rede 256x256 com tanh.
PPO_ARGS = dict(
    learning_rate=2e-4,
    n_steps=1024,  # por ambiente
    batch_size=2048,
    n_epochs=4,
    gamma=0.99,  # a 10 decisões/s, olha ~10 s à frente
    gae_lambda=0.95,
    clip_range=0.2,
    ent_coef=0.01,
    policy_kwargs=dict(net_arch=dict(pi=[256, 256], vf=[256, 256])),
)


class VecEmParalelo(DummyVecEnv):
    """Manda o passo para TODAS as pontes antes de ler as respostas: as simulações (processos Node) andam juntas,
    com um único processo Python (e um único PyTorch na memória)."""

    def step_wait(self):
        for env, acao in zip(self.envs, self.actions):
            env.step_send(acao)
        for i, env in enumerate(self.envs):
            obs, r, terminou, cortou, info = env.step_recv()
            self.buf_rews[i] = r
            self.buf_dones[i] = terminou or cortou
            info = dict(info)
            info["TimeLimit.truncated"] = cortou and not terminou
            if self.buf_dones[i]:
                info["terminal_observation"] = obs
                obs, self.reset_infos[i] = env.reset()
            self.buf_infos[i] = info
            self._save_obs(i, obs)
        return self._obs_from_buf(), np.copy(self.buf_rews), np.copy(self.buf_dones), list(self.buf_infos)


class Curriculo(BaseCallback):
    """Avança o estágio pela taxa de gol, grava checkpoints e alimenta a liga do self-play."""

    def __init__(self, estagio: int, liga: Liga, salvar: int, rival_a_cada: int):
        super().__init__()
        self.estagio = estagio
        self.liga = liga
        self.salvar_a_cada = salvar
        self.rival_a_cada = rival_a_cada
        self.janela: deque[int] = deque(maxlen=400)
        self.prox_salvar = 0
        self.prox_rival = 0

    def _on_training_start(self) -> None:
        # ao continuar um treino, conta a partir dos passos que o modelo já tem
        self.prox_salvar = self.num_timesteps + self.salvar_a_cada
        self.prox_rival = self.num_timesteps + self.rival_a_cada

    def _on_step(self) -> bool:
        for info in self.locals["infos"]:
            if "gol" in info and info.get("estagio") == self.estagio:
                self.janela.append(info["gol"])
        if len(self.janela) == self.janela.maxlen:
            gols = sum(g == 1 for g in self.janela) / len(self.janela)
            sofridos = sum(g == -1 for g in self.janela) / len(self.janela)
            self.logger.record("bonk/gols", gols)
            self.logger.record("bonk/sofridos", sofridos)
            self.logger.record("bonk/estagio", self.estagio)
            if self.estagio in META and gols >= META[self.estagio]:
                self.estagio += 1
                self.janela.clear()
                self.training_env.env_method("set_estagio", self.estagio)
                print(f"[currículo] passou para o estágio {self.estagio} ({self.num_timesteps} passos)")
        if self.estagio == 3 and self.num_timesteps >= self.prox_rival:
            self.prox_rival = self.num_timesteps + self.rival_a_cada
            self.liga.adicionar(exportar(self.model))  # a versão de agora vira rival das próximas
        if self.num_timesteps >= self.prox_salvar:
            self.prox_salvar = self.num_timesteps + self.salvar_a_cada
            self.salvar()
        return True

    def salvar(self) -> None:
        PASTA.mkdir(exist_ok=True)
        self.model.save(PASTA / "latest.zip")
        (PASTA / "estado.json").write_text(json.dumps({"estagio": self.estagio, "passos": self.num_timesteps}))
        (PASTA / "policy.json").write_text(json.dumps(exportar(self.model), separators=(",", ":")))
        print(f"[salvo] {self.num_timesteps} passos, estágio {self.estagio}")


def main() -> None:
    ap = argparse.ArgumentParser()
    ap.add_argument("--passos", type=int, default=5_000_000)
    ap.add_argument("--envs", type=int, default=4)
    ap.add_argument("--novo", action="store_true")
    ap.add_argument("--salvar", type=int, default=100_000)
    ap.add_argument("--rival-a-cada", type=int, default=250_000)
    ap.add_argument("--visao", choices=["agora", "atrasada"], default="agora")
    a = ap.parse_args()

    continuar = (PASTA / "latest.zip").exists() and not a.novo
    estagio = json.loads((PASTA / "estado.json").read_text())["estagio"] if continuar else 1
    liga = Liga()
    venv = VecEmParalelo([lambda i=i: BonkFootballEnv(estagio=estagio, liga=liga, seed=1000 + i, visao=a.visao) for i in range(a.envs)])
    if continuar:
        model = PPO.load(PASTA / "latest.zip", env=venv, device="cpu")
        print(f"continuando de {model.num_timesteps} passos (estágio {estagio})")
    else:
        model = PPO("MlpPolicy", venv, device="cpu", tensorboard_log=str(PASTA / "tb"), verbose=0, **PPO_ARGS)
    cb = Curriculo(estagio, liga, a.salvar, a.rival_a_cada)
    try:
        model.learn(total_timesteps=a.passos, callback=cb, reset_num_timesteps=not continuar, progress_bar=False)
    finally:
        cb.salvar()
        venv.close()


if __name__ == "__main__":
    main()

Os hiperparâmetros

ParâmetroValorPor quê
learning_rate2e-4Padrão do guia de PPO para Rocket League (RLGym); mais alto fica instável
n_steps × envs1024 × 4~4 mil passos (7 minutos de jogo) por atualização
batch_size, n_epochs2048, 4Lotes grandes e poucas passadas: estável
gamma0,99A 10 decisões/s, a IA "enxerga" ~10 s à frente
ent_coef0,01Mantém a IA experimentando
Rede256 × 256, tanhPequena o bastante para rodar em JS puro, grande o bastante para o problema

Próximos desafios

Quando o básico estiver rodando, estas são as melhorias que mais deram resultado para a gente (em ordem):

  1. Cenários de lances reais. Grave partidas da sua sala contra humanos (rec) e comece lances de treino a partir das situações em que a IA sofreu golo. O reset da ponte aceita overrides com posições e velocidades.
  2. Um "explorador". Treine uma segunda IA cujo único objetivo é ganhar da principal, e coloque as versões dela como adversárias da principal. Ela acha os furos antes dos jogadores.
  3. Adversários que imitam humanos, como um atacante que chuta de primeira na saída de bola (a maioria dos golos humanos de saída vem disso).