glassllmDocumentação
Abrir laboratório
DocumentaçãoReferência da biblioteca

Referência da biblioteca

Mapa da API e convenções

Importações, tipos, dimensões e contratos do motor glassllm em NumPy.

glassllm 0.1.03 min de leitura · estimativa

Escolher o nível de entrada

O pacote glassllm exporta 12 nomes: Config, GenStep, GlassLM, LANGUAGES, STEPS, StepRecord, Tensor, Tokenizer, Tracer, load_pretrained, no_grad e __version__. Esses nomes cobrem a configuração, a geração, o carregamento e a observação do modelo. As funções matemáticas, camadas, otimizadores e ferramentas de treinamento são importadas de seus submódulos.

import numpy as np
from glassllm import Config, GlassLM, Tensor, Tracer, no_grad

cfg = Config(vocab_size=8, d_model=8, n_layers=1,
             n_heads=2, n_kv_heads=1, max_len=4)
model = GlassLM(cfg, seed=0)
trace = Tracer()
with no_grad():
    logits = model([1, 2, 3], trace=trace)
assert logits.shape == (1, 3, 8)
assert not logits.requires_grad
np.testing.assert_allclose(
    trace.get("attn.softmax", layer=0, head=0).value.sum(-1), 1.0,
    rtol=1e-5,
)

O exemplo usa pesos aleatórios para verificar contratos. Para gerar com os pesos treinados, use model, tokenizer = load_pretrained("pt"); a publicação da biblioteca ainda está adiada, portanto a instalação documentada usa o checkout ou o wheel local.

Caminhos de importação

Módulo Símbolos e finalidade
glassllm.config Config: dimensões, limites e validações
glassllm.model GlassLM, GenStep, next_token_probs: logits, perda e geração
glassllm.tokenizer Tokenizer, pre_tokenize, SPACE, SPECIALS, UNK_TEXT: BPE próprio
glassllm.trace Tracer, StepRecord, record: snapshots copiados
glassllm.steps StepInfo, STEPS, LAYER_STEPS, HEAD_STEPS, scan_markers, load_step_index: equações e origem
glassllm.autograd Tensor, no_grad e operações diferenciáveis: grafo reverso
glassllm.nn Module, RMSNorm, Attention, SwiGLU, Block, KVCache, funções de inicialização, máscara e ângulos
glassllm.optim AdamW, clip_grad_norm, lr_schedule: atualização dos parâmetros
glassllm.train get_batch, evaluate, train: janelas, avaliação e treinamento
glassllm.cli main, build_parser, format_matrix, comandos cmd_*: terminal

Os nomes com prefixo _ são auxiliares internos. Não há compatibilidade com a interface de módulos do PyTorch: Module não oferece .train(), .eval(), .to() ou .state_dict(). O motor executa no NumPy; o navegador usa esse mesmo Python em Pyodide.

Convenções de forma e índice

Símbolo Significado Padrão dos modelos incluídos
B batch 1 na interface e no trace
n posições recebidas na chamada atual até 128
m posições das chaves, incluindo cache até 128
V tamanho do vocabulário 1024
d dimensão do modelo 128
Hq, Hkv cabeças de consulta e de chave/valor 4 e 2
dk = d / Hq dimensão de cada cabeça 32

IDs e targets são índices inteiros; posições, camadas e cabeças começam em zero. forward aceita IDs (n,) ou (B,n) e devolve Tensor (B,n,V). Ele mantém o eixo de batch mesmo quando recebeu uma lista. O tracer remove o batch unitário dos valores gravados: atenção completa (Hq,n,m), ou (n,m) após selecionar uma cabeça. O tokenizer não acrescenta BOS/EOS automaticamente.

Tipos, estado e erros

Tensor.data é um numpy.ndarray; Tensor.grad começa como None. Parâmetros normalmente são float32; exemplos de derivadas podem usar float64. Não há dispositivo GPU, tipos simbólicos ou suporte a derivadas de segunda ordem. Chamadas NumPy diretas em .data ficam fora do grafo.

forward, loss e generate não atualizam pesos. train e AdamW.step os modificam no mesmo objeto; forward também preenche o cache quando ele é fornecido. generate cria seu próprio cache e um novo tracer por token quando trace=True.

As validações explícitas usam principalmente ValueError, TypeError, KeyError e FileNotFoundError. Formas incompatíveis, IDs fora de faixa e arquivos malformados também podem produzir erros do NumPy ou JSON. A biblioteca não converte todo erro interno para uma classe única. Como generate é um generator, suas validações só são executadas quando o iterador avança.

Continue em Configuração e carregamento, GlassLM ou Tensor e autograd.

Assinaturas no código

12 exports pela raiz; 64 declarações de classes/funções em 11 módulos. Abra um módulo para consultar métodos, operadores e propriedades.

glassllm1

src/glassllm/__init__.py

  • load_pretrained(lang: str, model_dir: str | Path | None=None) -> tuple[GlassLM, Tokenizer]
glassllm.autograd28

src/glassllm/autograd.py

  • no_grad()
  • Tensor
    • __init__(self, data, parents=(), backward=None, requires_grad=False)
    • shape(self)
    • ndim(self)
    • backward(self, grad=None)
    • __add__(self, other)
    • __radd__ = __add__
    • __sub__(self, other)
    • __rsub__(self, other)
    • __mul__(self, other)
    • __rmul__ = __mul__
    • __truediv__(self, other)
    • __rtruediv__(self, other)
    • __neg__(self)
    • __pow__(self, exponent)
    • __matmul__(self, other)
    • __getitem__(self, index)
    • sum(self, axis=None, keepdims=False)
    • mean(self, axis=None, keepdims=False)
    • max(self, axis=None, keepdims=False)
    • reshape(self, *shape)
    • transpose(self, *axes)
  • add(a, b)
  • neg(a)
  • mul(a, b)
  • div(a, b)
  • power(a, exponent)
  • matmul(a, b)
  • exp(a)
  • log(a)
  • tsum(a, axis=None, keepdims=False)
  • mean(a, axis=None, keepdims=False)
  • max(a, axis=None, keepdims=False)
  • reshape(a, shape)
  • transpose(a, axes)
  • concat(tensors, axis=0)
  • where(condition, a, b)
  • embedding(weight, ids)
  • masked_fill(a, mask, value)
  • softmax_np(x, axis=-1)
  • softmax(a, axis=-1)
  • log_softmax(a, axis=-1)
  • sigmoid(a)
  • silu(a)
  • cross_entropy_grad(logits, targets)
  • cross_entropy(logits, targets)
  • rope(x, cos, sin)
  • repeat_kv(x, repeats)
glassllm.cli8

src/glassllm/cli.py

  • format_matrix(values: np.ndarray, row_labels: list[str], col_labels: list[str] | None=None) -> str
  • cmd_tokenize(args, model: GlassLM | None, tok: Tokenizer) -> None
  • cmd_generate(args, model: GlassLM, tok: Tokenizer) -> None
  • cmd_trace(args, model: GlassLM, tok: Tokenizer) -> None
  • cmd_steps(args, model, tok) -> None
  • cmd_train(args, model: GlassLM, tok: Tokenizer) -> None
  • build_parser() -> argparse.ArgumentParser
  • main(argv: list[str] | None=None) -> None
glassllm.config1

src/glassllm/config.py

  • Config
    • vocab_size: int
    • d_model: int
    • n_layers: int
    • n_heads: int
    • n_kv_heads: int
    • max_len: int
    • rope_base: float
    • eps: float
    • init_std: float
glassllm.model3

src/glassllm/model.py

  • GenStep
    • token: int
    • probs: np.ndarray
    • trace: Tracer | None
  • next_token_probs(logits: np.ndarray, temperature: float) -> np.ndarray
  • GlassLM
    • __init__(self, cfg: Config, seed: int=0, dtype=np.float32)
    • new_cache(self) -> list[KVCache]
    • forward(self, ids, trace: Tracer | None=None, cache: list[KVCache] | None=None, start: int=0) -> Tensor
    • __call__ = forward
    • loss(self, ids, targets, trace: Tracer | None=None) -> Tensor
    • generate(self, ids, n_new: int, temperature: float=1.0, greedy: bool=False, seed: int | None=None, trace: bool=False) -> Iterator[GenStep]
    • save(self, path: str | Path, fp16: bool=True) -> None
    • load(cls, path: str | Path, dtype=np.float32) -> GlassLM
glassllm.nn9

src/glassllm/nn.py

  • Module
    • named_parameters(self, prefix: str='') -> dict[str, Tensor]
    • parameters(self) -> list[Tensor]
  • init_param(rng: np.random.Generator, shape: tuple[int, ...], std: float, dtype) -> Tensor
  • RMSNorm
    • __init__(self, d: int, eps: float, dtype)
    • __call__(self, x: Tensor) -> Tensor
  • rope_angles(d_k: int, max_len: int, base: float) -> tuple[np.ndarray, np.ndarray]
  • causal_mask(n_queries: int, n_keys: int, start: int) -> np.ndarray
  • KVCache
    • __init__(self)
  • Attention
    • __init__(self, d: int, n_heads: int, n_kv_heads: int, max_len: int, rope_base: float, rng: np.random.Generator, std: float, dtype)
    • __call__(self, x: Tensor, layer: int, trace: Tracer | None=None, cache: KVCache | None=None, start: int=0) -> Tensor
  • SwiGLU
    • __init__(self, d: int, rng: np.random.Generator, std: float, dtype)
    • __call__(self, x: Tensor, layer: int, trace: Tracer | None=None) -> Tensor
  • Block
    • __init__(self, cfg, rng: np.random.Generator, dtype)
    • __call__(self, x: Tensor, layer: int, trace: Tracer | None=None, cache: KVCache | None=None, start: int=0) -> Tensor
glassllm.optim3

src/glassllm/optim.py

  • AdamW
    • __init__(self, params: list[Tensor], lr: float=0.003, betas=(0.9, 0.95), eps: float=1e-08, weight_decay: float=0.1)
    • zero_grad(self) -> None
    • step(self, lr: float | None=None) -> None
  • clip_grad_norm(params: list[Tensor], max_norm: float) -> float
  • lr_schedule(step: int, total_steps: int, base_lr: float, warmup: int, min_ratio: float=0.1) -> float
glassllm.steps3

src/glassllm/steps.py

  • StepInfo
    • latex: str
    • plain: str
  • scan_markers(package_dir: Path=PACKAGE_DIR) -> dict[str, dict]
  • load_step_index() -> dict[str, dict]
glassllm.tokenizer2

src/glassllm/tokenizer.py

  • pre_tokenize(text: str) -> list[str]
  • Tokenizer
    • __init__(self, alphabet: list[str], merges: list[tuple[str, str]])
    • vocab_size(self) -> int
    • train(cls, text: str, vocab_size: int) -> Tokenizer
    • encode(self, text: str) -> list[int]
    • encode_verbose(self, text: str) -> list[dict]
    • tokens(self, ids: list[int]) -> list[str]
    • decode(self, ids: list[int]) -> str
    • save(self, path: str | Path) -> None
    • load(cls, path: str | Path) -> Tokenizer
glassllm.trace3

src/glassllm/trace.py

  • StepRecord
    • id: str
    • layer: int | None
    • value: np.ndarray
    • order: int
    • head: int | None
    • shape(self) -> tuple[int, ...]
    • equation(self) -> str
    • latex(self) -> str
  • Tracer
    • __init__(self)
    • record(self, step_id: str, value, layer: int | None=None, batched: bool=True, *, head: int | None=None) -> None
    • get(self, step_id: str, layer: int | None=None, head: int | None=None) -> StepRecord
    • step_ids(self) -> list[str]
  • record(trace: Tracer | None, step_id: str, value, layer: int | None=None, batched: bool=True, *, head: int | None=None) -> None
glassllm.train3

src/glassllm/train.py

  • get_batch(data: np.ndarray, batch_size: int, seq_len: int, rng: np.random.Generator) -> tuple[np.ndarray, np.ndarray]
  • evaluate(model: GlassLM, data: np.ndarray, batch_size: int, seq_len: int, n_batches: int=10, seed: int=1234) -> float
  • train(model: GlassLM, data: np.ndarray, steps: int, batch_size: int=16, seq_len: int=128, lr: float=0.003, warmup: int=100, seed: int=0, val_data: np.ndarray | None=None, eval_every: int=100, keep_best: bool=False, log: Callable[[str], None] | None=print) -> list[dict]

Fontes no projeto

src/glassllm/__init__.pysrc/glassllm/