Entrena la IA

Entrenar y exportar

Ejecuta el entrenamiento con PPO y self-play, síguelo con gráficos, evalúa y lleva el modelo a tu sala.

Ejecutar el entrenamiento

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

Lo que aparece en la terminal (salvo = guardado, passos = pasos, estágio = etapa, currículo = currículo):

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)
...
OpciónPor defectoQué hace
--passos5 millonesCuántos pasos entrenar en esta ronda
--envs4Simulaciones en paralelo (usa 2, 4 u 8)
--visaoagoraCómo ve la IA el juego; tiene que coincidir con la sala (por qué)
--novo—Empieza de cero (el checkpoint antiguo se ignora, no se borra)
--salvar100 milCada cuántos pasos guarda el checkpoint
--rival-a-cada250 milCada cuántos pasos la IA actual entra en la "liga" de rivales

Puedes detenerlo con Ctrl+C cuando quieras: guarda antes de salir. Ejecutando python treinar.py de nuevo, continúa donde se quedó (la etapa del currículo queda en checkpoints/estado.json).

Cuánto tarda

Medido en un PC común con --envs 4 (~750 pasos/s):

HitoPasosTiempo
Sale de la etapa 1 (encuentra la pelota y marca sin portero)~820 mil~18 min
Sale de la etapa 2 (rival quieto en el camino)~870 mil~1 min después
Contra el script más fuerte: 78 goles, 21 recibidos en 100 jugadas2 millones~45 min
Modelo publicado: 95 goles, 2 recibidos182 millonesdías (el nuestro corrió en varias máquinas)

Los números de arriba son de un entrenamiento real con el kit, en un PC común. El tuyo puede variar un poco (la suerte de las primeras jugadas cambia el camino), pero el orden de magnitud es ese.

Seguir con gráficos

bash
tensorboard --logdir checkpoints/tb

Abre la dirección que muestre (normalmente http://localhost:6006):

GráficoQué esperar
bonk/gols (goles)Sube hasta la meta y cae cuando cambia la etapa (el ejercicio se volvió más difícil). Normal
bonk/sofridos (recibidos)En la etapa 3, debe bajar con el tiempo
bonk/estagio (etapa)1 → 2 → 3
rollout/ep_rew_meanLa nota media por jugada. Sube de a poco
train/entropy_lossCuánto "experimenta" todavía la IA. Va bajando; si se desploma pronto, dejó de explorar

Evaluar

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

Juega contra el script más fuerte, decidiendo exactamente como la sala (eje por eje, con el retraso elegido). Como referencia, el modelo publicado da (gols = goles, sofridos = recibidos, saldo = saldo):

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

Llevarlo a la sala

El entrenamiento ya guarda checkpoints/policy.json en cada checkpoint. Solo cópialo a la carpeta de la sala y úsalo en lugar de football-1x1.policy.json (o apunta IA_MODELO a él). Recuerda usar en la sala el mismo --visao del entrenamiento.

La exportación toma solo la parte de la red que decide (la red de valor solo sirve para entrenar) y guarda los pesos en float32 en base64:

python
# politica.py
"""Exporta la red entrenada a `policy.json` (el formato que la sala ejecuta en JavaScript) y la vuelve a ejecutar en NumPy
(para usar versiones antiguas como rivales en el self-play sin cargar otro 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 de stable-baselines3) -> dict del policy.json. Solo la parte que decide (la red de valor se queda)."""
    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 en base64: exacto y ~4x más pequeño 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:
    """Ejecuta un policy.json en NumPy: tanh en las capas ocultas, lineal en la ú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:
        """Decisión eje por eje (la misma de la sala), no el argmax puro."""
        return decide(self.logits(obs), anterior)

El script de entrenamiento completo

python
# treinar.py
"""Entrena la IA de fútbol 1x1 con PPO (stable-baselines3) y self-play.

    python treinar.py                     # empieza de cero o continúa desde checkpoints/latest.zip
    python treinar.py --passos 20000000   # cuántos pasos entrenar en esta ronda
    python treinar.py --envs 4            # simulaciones en paralelo (1 proceso Node cada una; usa 2, 4 u 8)
    python treinar.py --novo              # ignora el checkpoint (no borra nada)
    python treinar.py --visao atrasada    # para salas SIN los "ojos" (ver la documentación); por defecto: agora
    tensorboard --logdir checkpoints/tb   # gráficos

Cada --salvar pasos guarda checkpoints/latest.zip, checkpoints/estado.json (etapa del currículo) y
checkpoints/policy.json (el modelo listo para la 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 avanzar de etapa: tasa de gol en las últimas 400 jugadas.
META = {1: 0.7, 2: 0.6}

# Base del RLGym-PPO-Guide: lr 2e-4, pocas épocas, lotes grandes, entropía 0,01. Red 256x256 con tanh.
PPO_ARGS = dict(
    learning_rate=2e-4,
    n_steps=1024,  # por entorno
    batch_size=2048,
    n_epochs=4,
    gamma=0.99,  # a 10 decisiones/s, mira ~10 s adelante
    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):
    """Envía el paso a TODOS los puentes antes de leer las respuestas: las simulaciones (procesos Node) avanzan juntas,
    con un único proceso Python (y un único PyTorch en memoria)."""

    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):
    """Avanza la etapa según la tasa de gol, guarda checkpoints y alimenta la liga del 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:
        # al continuar un entrenamiento, cuenta desde los pasos que ya tiene el modelo
        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))  # la versión actual se vuelve rival de las siguientes
        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()

Los hiperparámetros

ParámetroValorPor qué
learning_rate2e-4Valor estándar de la guía de PPO para Rocket League (RLGym); más alto se vuelve inestable
n_steps × envs1024 × 4~4 mil pasos (7 minutos de juego) por actualización
batch_size, n_epochs2048, 4Lotes grandes y pocas pasadas: estable
gamma0,99A 10 decisiones/s, la IA "ve" ~10 s adelante
ent_coef0,01Mantiene a la IA experimentando
Red256 × 256, tanhLo bastante pequeña para correr en JS puro, lo bastante grande para el problema

Próximos desafíos

Cuando lo básico funcione, estas son las mejoras que más resultado nos dieron (en orden):

  1. Escenarios de jugadas reales. Graba partidas de tu sala contra humanos (rec) y empieza jugadas de entrenamiento desde las situaciones en que la IA recibió gol. El reset del puente acepta overrides con posiciones y velocidades.
  2. Un "explorador". Entrena una segunda IA cuyo único objetivo es ganarle a la principal, y usa sus versiones como rivales de la principal. Encuentra los huecos antes que los jugadores.
  3. Rivales que imitan a humanos, como un delantero que tira de primera en el saque (la mayoría de los goles humanos de saque viene de eso).