Skip to content

TensorFlow Folha de referência

Plataforma open-source de aprendizado de máquina ponta a ponta, da Google.

01

Primeiros Passos

Instalação e Básico

TensorFlow 2.x roda eagerly por padrão (operações executam imediatamente, como Python normal). Use tf.config.list_physical_devices('GPU') para verificar se as GPUs CUDA estão visíveis. Para suporte a GPU, instale o extra [and-cuda] no Linux/Windows, ou use tensorflow-metal no Apple Silicon. TF 2.x fundiu o Keras como tf.keras — a API de alto nível usada na maioria dos fluxos de trabalho.

tensorflow
# install TensorFlow (CPU)
pip install tensorflow

# with GPU support on Linux/Windows (CUDA-enabled)
pip install tensorflow[and-cuda]

import tensorflow as tf

# check version and devices
print(tf.__version__)
print("GPU:", tf.config.list_physical_devices('GPU'))

# eager execution is on by default in TF2
print(tf.executing_eagerly())   # True

Primeiros Tensores

tf.constant cria um tensor imutável; tf.zeros / tf.ones / tf.random.* criam padrões comuns. Cada tensor tem shape, dtype e rank. .numpy() faz a ponte de volta ao NumPy — na GPU isso pode disparar uma cópia sincronizada. Prefira dtypes explícitos (float32 é o padrão para ML) para evitar upcasts silenciosos que quebram o desempenho.

tensorflow
import tensorflow as tf

# constants are immutable
x = tf.constant([[1, 2], [3, 4]])
y = tf.zeros((3, 3))
z = tf.random.normal((2, 3), mean=0.0, stddev=1.0)

print(x.shape, x.dtype)   # (2, 2) int32
print(tf.reduce_sum(x))   # tf.Tensor(10, shape=(), dtype=int32)

# numpy interop is zero-copy when possible
print(x.numpy())          # array([[1, 2], [3, 4]])

Execução Eager e Gradientes

A execução eager torna o TF depurável como Python normal — print, pdb e tracebacks funcionam. GradientTape registra ops de forward em tensores observados (tf.Variable é observado automaticamente) para que tape.gradient compute derivadas. Esta é a fundação dos loops de treino personalizados. Tapes são de uso único por padrão; use persistent=True para chamar gradient múltiplas vezes.

tensorflow
import tensorflow as tf

a = tf.constant(3.0)
b = tf.constant(4.0)
print(a * b + 1)   # tf.Tensor(13.0, ...)

# GradientTape records ops for automatic differentiation
with tf.GradientTape() as tape:
    tape.watch(a)
    y = a ** 2 + b    # y = a^2 + b, dy/da = 2a
grad = tape.gradient(y, a)
print(grad)   # tf.Tensor(6.0, ...)  (= 2*3)

tf.function e Grafos

@tf.function converte uma função Python num grafo TensorFlow portátil e otimizável — muito mais rápido na GPU e exigido para distribuição. A função é rastreada uma vez por assinatura de entrada, então evite efeitos colaterais Python ou fluxo de controle Python dependente de dados dentro dela (use tf.cond / tf.while_loop, ou a função re-rastreia). Variáveis devem ser criadas uma vez, fora da função, ou reutilize tf.Variable com o mesmo nome.

tensorflow
import tensorflow as tf

@tf.function  # traces a graph; runs in graph mode after first call
def train_step(x, y):
    with tf.GradientTape() as tape:
        preds = x * w + b
        loss = tf.reduce_mean((preds - y) ** 2)
    grads = tape.gradient(loss, [w, b])
    optimizer.apply_gradients(zip(grads, [w, b]))
    return loss

w = tf.Variable(0.1)
b = tf.Variable(0.0)
optimizer = tf.keras.optimizers.SGD(0.01)

# first call builds the graph (slower); subsequent calls are fast
loss = train_step(tf.constant([1., 2.]), tf.constant([2., 4.]))

Precisão Mista

Precisão mista computa em float16, mas mantém cópias mestras float32, dando 2-3x de rendimento e metade da memória em GPUs Tensor Core (Volta+). A política 'mixed_float16' cuida do escalonamento da perda automaticamente para prevenir underflow. Force a camada de saída a float32 pela estabilidade numérica. Precisa de capacidade de computo >= 7.0; em GPUs antigas pode ficar mais lento.

tensorflow
import tensorflow as tf

# enable mixed precision: compute in float16, store in float32
tf.keras.mixed_precision.set_global_policy('mixed_float16')

model = tf.keras.Sequential([
    tf.keras.layers.Dense(64, activation='relu', dtype='float32'),
    tf.keras.layers.Dense(10, activation='softmax', dtype='float32')
])

# loss scaling is automatic with mixed_float16 policy
print(tf.keras.mixed_precision.global_policy())
02

Tensores

tf.constant

tf.constant cria um tensor imutável — não se pode atribuir a elementos. Para tensores treináveis, use tf.Variable. tf.random.normal/uniform aceitam um argumento seed por reprodutibilidade; tf.random.set_seed(42) torna o programa inteiro reproduzível. Use tuplas de shape (não ints) para criação multidimensional, evitando surpresas.

tensorflow
import tensorflow as tf

a = tf.constant([1, 2, 3])
b = tf.constant([[1.0, 2.0], [3.0, 4.0]], dtype=tf.float32)

zeros = tf.zeros((2, 3))
ones = tf.ones((3, 3))
eye = tf.eye(3)
full = tf.fill((2, 3), 7.0)

arange = tf.range(0, 10, 2)       # [0, 2, 4, 6, 8]
linspace = tf.linspace(0.0, 1.0, 5)

rand = tf.random.uniform((2, 3))
randn = tf.random.normal((2, 3))

# constants are immutable: a[0] = 5  -> TypeError

tf.Variable

tf.Variable é um wrapper de tensor mutável usado para parâmetros de modelo e estado de otimizador. assign / assign_add / assign_sub atualizam-no no próprio local — atribuição Python comum (w = w + 1) cria um tensor novo e não muta. Variáveis são observadas pelo GradientTape automaticamente, diferentemente de tf.constant, que você precisa observar explicitamente com tape.watch(). Mantenha as Variáveis no mesmo device das ops que as usam.

tensorflow
import tensorflow as tf

w = tf.Variable(0.1, dtype=tf.float32)
W = tf.Variable(tf.random.normal((3, 4)))
b = tf.Variable(tf.zeros((4,)))

# read value
print(w.numpy())        # 0.1

# update value
w.assign(0.5)
w.assign_add(0.1)       # w += 0.1
w.assign_sub(0.05)

# assign in place on a slice
W[0, 0].assign(99.0)

# watched by GradientTape automatically
with tf.GradientTape() as tape:
    y = w ** 2
grad = tape.gradient(y, w)   # 2w

Operações de Tensor

A maioria da matemática espelha NumPy: tf.reduce_sum / reduce_mean / reduce_max correspondem a np.sum/mean/max. Use axis= para reduzir uma dimensão específica e keepdims=True para preservar o rank, para broadcasting. tf.matmul e o operador @ fazem multiplicação de matrizes (em lote quando as entradas são 3D+). reshape retorna uma view quando possível; transpose sempre retorna uma cópia no TF.

tensorflow
import tensorflow as tf

a = tf.constant([[1.0, 2.0], [3.0, 4.0]])
b = tf.constant([[5.0, 6.0], [7.0, 8.0]])

a + b; a - b; a * b; a / b      # element-wise
c = tf.matmul(a, b)              # matrix multiply
c = a @ b                        # equivalent

tf.reduce_sum(a)                 # sum of all
tf.reduce_sum(a, axis=0)         # sum along axis 0
tf.reduce_mean(a, axis=1)        # mean along axis 1
tf.reduce_max(a, axis=1)
tf.reduce_sum(a, axis=1, keepdims=True)

x = tf.range(12)
y = tf.reshape(x, (3, 4))
t = tf.transpose(y)              # shape (4, 3)

Indexação e Slicing

TF suporta slicing estilo NumPy no modo eager e dentro de tf.function. tf.boolean_mask extrai elementos onde a máscara é True (achatado). tf.gather seleciona ao longo do eixo 0 por padrão (como indexação fancy). tf.where(cond, x, y) é o ternário vetorizado — quando cond é True, pegue de x, senão de y. Para atribuição, use tf.tensor_scatter_nd_update ou um tf.Variable.

tensorflow
import tensorflow as tf

x = tf.constant([[1, 2, 3], [4, 5, 6], [7, 8, 9]])

x[0]              # first row
x[1, 2]           # element (1,2) -> 6
x[:, 1]           # second column
x[0:2]            # first two rows
x[:, ::2]         # every other column

# boolean mask
mask = x > 4
sel = tf.boolean_mask(x, mask)   # tensor([5, 6, 7, 8, 9])

# gather by indices
idx = tf.constant([0, 2])
rows = tf.gather(x, idx)         # rows 0 and 2

# where: select from two tensors
tf.where(x > 4, x, tf.zeros_like(x))

Tensores Ragged e Esparsos

Tensores ragged guardam sequências de comprimento variável sem preenchimento — perfeitos para lotes de NLP de comprimentos diferentes. Tensores esparsos guardam só índices e valores não zero, economizando memória para dados altamente esparsos (recomendações, grafos). A maioria das ops tem variantes cientes de esparsidade; converta para denso só quando uma op exigir. tf.RaggedTensor.to_tensor() preenche até um retângulo para lookups de embedding.

tensorflow
import tensorflow as tf

# ragged: variable-length sequences
ragged = tf.ragged.constant([[1, 2, 3], [4], [5, 6]])
print(ragged.shape)           # (3, None)
ragged.to_tensor()            # pad to (3, 3)

# sparse: mostly-zero tensors
indices = [[0, 0], [1, 2], [2, 1]]
values = [1.0, 2.0, 3.0]
sparse = tf.sparse.SparseTensor(
    indices=indices, values=values, dense_shape=[3, 3])
dense = tf.sparse.to_dense(sparse)

sp_sum = tf.sparse.reduce_sum(sparse)
sp_matmul = tf.sparse.sparse_dense_matmul(sparse, tf.eye(3))

Broadcasting e Matemática

Broadcasting estica tensores de dimensões menores para casar com os maiores, elemento a elemento. clip_by_value é o clamp do TF. tf.maximum/minimum são elemento a elemento (diferentes de tf.reduce_max/min, que reduzem uma dimensão). cumsum/cumprod produzem somas/produtos acumulados ao longo de um eixo — úteis para métricas cumulativas e algoritmos de soma de prefixo em camadas personalizadas.

tensorflow
import tensorflow as tf

# broadcasting follows NumPy rules
a = tf.constant([[1.0, 2.0, 3.0]])    # shape (1, 3)
b = tf.constant([[10.0], [20.0]])      # shape (2, 1)
c = a + b                              # shape (2, 3)

tf.abs(x); tf.sqrt(x); tf.exp(x); tf.log(x)
tf.square(x); tf.pow(x, 3)
tf.maximum(a, b); tf.minimum(a, b)
tf.clip_by_value(x, 0.0, 1.0)

tf.norm(x)                  # L2 norm
tf.norm(x, ord=1)           # L1 norm

tf.cumsum(tf.range(5))      # [0, 1, 3, 6, 10]
tf.cumprod(tf.range(1, 5))  # [1, 2, 6, 24]
03

Modelos Keras

API Sequential

Sequential é o modelo Keras mais simples — um pipeline linear em que a saída de cada camada alimenta a próxima. input_shape exclui a dimensão de lote (use None para lote variável). model.summary() imprime shapes de camadas e contagens de parâmetros. Se não passar input_shape, o modelo se constrói preguiçosamente na primeira chamada fit/forward — chame build() explicitamente para inspecioná-lo antes.

tensorflow
import tensorflow as tf

model = tf.keras.Sequential([
    tf.keras.layers.Dense(128, activation='relu', input_shape=(784,)),
    tf.keras.layers.Dropout(0.5),
    tf.keras.layers.Dense(64, activation='relu'),
    tf.keras.layers.Dense(10, activation='softmax'),
])

model.summary()

# build later with input_shape (or first call)
model = tf.keras.Sequential()
model.add(tf.keras.layers.Dense(128, activation='relu'))
model.add(tf.keras.layers.Dense(10))
model.build((None, 784))   # None = variable batch

API Funcional

A API Funcional permite que camadas se ramifiquem, se mesclem e saltem — exigido para qualquer coisa não linear (ResNets, multi-entrada/saída, redes siamesas). Defina tensores Input, encadeie camadas chamando-as e depois passe inputs/outputs ao Model. O modelo resultante se comporta identicamente a um Sequential para fit/predict. Nomeie inputs/outputs para salvamento limpo e assinaturas de serviço.

tensorflow
import tensorflow as tf

inputs = tf.keras.Input(shape=(784,), name='img')
x = tf.keras.layers.Dense(128, activation='relu')(inputs)
x = tf.keras.layers.Dropout(0.5)(x)
x = tf.keras.layers.Dense(64, activation='relu')(x)
outputs = tf.keras.layers.Dense(10, activation='softmax')(x)

model = tf.keras.Model(inputs=inputs, outputs=outputs, name='mlp')

# multi-input / multi-output
img_in = tf.keras.Input(shape=(224, 224, 3))
meta_in = tf.keras.Input(shape=(10,))
x = tf.keras.layers.Conv2D(32, 3, activation='relu')(img_in)
x = tf.keras.layers.GlobalAveragePooling2D()(x)
x = tf.keras.layers.concatenate([x, meta_in])
out = tf.keras.layers.Dense(1, activation='sigmoid')(x)
model = tf.keras.Model([img_in, meta_in], out)

Subclasseamento de Modelo

Subclassear tf.keras.Model dá controle total do forward (como PyTorch). Defina camadas em __init__, implemente call(inputs, training=). A flag training alterna o comportamento de dropout e BatchNorm. Subclassear é mais flexível, mas perde alguns benefícios da API Funcional: mais difícil de inspecionar/plotar, sem inferência automática de forma de entrada e serialização mais delicada. Prefira Funcional para a maioria das arquiteturas; subclasseie para modelos de pesquisa.

tensorflow
import tensorflow as tf

class MLP(tf.keras.Model):
    def __init__(self, hidden=128, num_classes=10):
        super().__init__()
        self.dense1 = tf.keras.layers.Dense(hidden, activation='relu')
        self.drop = tf.keras.layers.Dropout(0.5)
        self.dense2 = tf.keras.layers.Dense(hidden, activation='relu')
        self.out = tf.keras.layers.Dense(num_classes, activation='softmax')

    def call(self, inputs, training=False):
        x = self.dense1(inputs)
        x = self.drop(x, training=training)
        x = self.dense2(x)
        return self.out(x)

model = MLP(hidden=64)
model.build((None, 784))
model.summary()

Compilação do Modelo

compile conecta o otimizador, a perda e as métricas antes do fit. Strings ('adam', 'mse') são atalhos para as classes correspondentes; passe objetos para hiperparâmetros personalizados. Para modelos multi-saída, passe dicionários mapeando nomes de saída a perdas. run_eagerly=True desativa o rastreamento do tf.function, para que você possa usar pdb e print — inestimável para depuração, mas lento.

tensorflow
model.compile(
    optimizer='adam',
    loss='sparse_categorical_crossentropy',
    metrics=['accuracy'],
    loss_weights={'cls': 1.0, 'box': 0.5},
)

# explicit objects (more control)
model.compile(
    optimizer=tf.keras.optimizers.Adam(learning_rate=1e-3),
    loss=tf.keras.losses.SparseCategoricalCrossentropy(),
    metrics=[tf.keras.metrics.SparseCategoricalAccuracy(name='acc')],
    run_eagerly=False,   # debug mode: run without graph
)

Resumo e Plot do Modelo

summary() imprime uma tabela por camada com shapes de saída e contagens de parâmetros — a forma mais rápida de notar bugs de shape. plot_model salva um grafo visual (requer pydot e Graphviz). get_config retorna um dict serializável, para que a arquitetura possa ser reconstruída sem os pesos — usado por model.to_json() e o formato de salvamento do Keras. Para modelos Funcionais, a config captura totalmente a arquitetura; para modelos subclassados, você precisa implementar get_config você mesmo.

tensorflow
model.summary()
print(model.layers)
print(model.inputs, model.outputs)

# plot architecture (needs pydot + graphviz)
tf.keras.utils.plot_model(
    model, to_file='model.png', show_shapes=True,
    show_layer_names=True, rankdir='TB',
)

print(f"{model.count_params():,} params")

config = model.get_config()
new_model = tf.keras.Model.from_config(config)

Pré-processamento no Modelo

Pôr o pré-processamento dentro do modelo (Rescaling, camadas de augmentation do Keras) torna-o implantável: o mesmo SavedModel aceita imagens cruas na inferência, sem passo separado de pré-processamento. Camadas de pré-processamento Keras rodam na GPU e dentro de tf.function, então são rápidas. Para augmentation só de treino, defina training=True no fit, para que as camadas fiquem inativas na inferência. Rescaling(1./255) converte imagens uint8 [0,255] para float [0,1].

tensorflow
import tensorflow as tf

# preprocessing as part of the model (deployable)
model = tf.keras.Sequential([
    tf.keras.layers.Input(shape=(224, 224, 3)),
    tf.keras.layers.Rescaling(1./255),
    tf.keras.layers.RandomFlip('horizontal'),
    tf.keras.layers.RandomRotation(0.1),
    tf.keras.layers.Conv2D(32, 3, activation='relu'),
    # ...
])
# the model now includes preprocessing, so inference needs raw images
04

Camadas

Camada Dense

Dense é a camada totalmente conectada: y = ativação(xW + b). A forma do peso é (in_features, out_features) — a transposta do PyTorch. kernel_initializer assume Glorot/Xavier uniform, bom para tanh/sigmoid; use 'he_normal' para a família ReLU. Adicione regularização L2 via kernel_regularizer. GELU é a ativação padrão em transformers.

tensorflow
import tensorflow as tf

dense = tf.keras.layers.Dense(
    units=64, activation='relu', use_bias=True,
    kernel_initializer='glorot_uniform',
    bias_initializer='zeros',
    kernel_regularizer=tf.keras.regularizers.l2(1e-4),
)

x = tf.random.normal((4, 128))
y = dense(x)                     # shape (4, 64)

print(dense.kernel.shape)        # (128, 64)
print(dense.bias.shape)          # (64,)

dense = tf.keras.layers.Dense(64, activation=tf.nn.gelu)

Camada Conv2D

TF/Keras usa NHWC (channels-last) por padrão, oposto ao NCHW do PyTorch. padding='same' preenche para que o tamanho espacial da saída = tamanho da entrada / stride; 'valid' significa sem preenchimento. DepthwiseConv2D aplica um filtro por canal de entrada (usado no MobileNet). Conv2DTranspose amplia (usada em decodificadores de segmentação). A forma do kernel é (kA, kL, canais_de_entrada, filtros).

tensorflow
import tensorflow as tf

conv = tf.keras.layers.Conv2D(
    filters=32, kernel_size=3, strides=(1, 1),
    padding='same', activation='relu', use_bias=True,
)

x = tf.random.normal((4, 28, 28, 3))   # NHWC
out = conv(x)
print(out.shape)                        # (4, 28, 28, 32) with padding='same'

dw = tf.keras.layers.DepthwiseConv2D(3, padding='same', activation='relu')
up = tf.keras.layers.Conv2DTranspose(32, 3, strides=2, padding='same')

Camadas Recorrentes (LSTM/GRU)

A forma de entrada para RNNs é (lote, timesteps, features). return_sequences=True é necessário ao empilhar RNNs ou para modelos sequência-para-sequência; False para sequência-para-vetor. Bidirectional dobra o tamanho da saída concatenando para frente e para trás. recurrent_dropout é conveniente, mas lento (sem aceleração cuDNN) — prefira dropout simples nas entradas.

tensorflow
import tensorflow as tf

lstm = tf.keras.layers.LSTM(units=128, return_sequences=False)
x = tf.random.normal((4, 10, 64))   # (batch, time, features)
out = lstm(x)                       # (4, 128)

# stacked LSTM needs return_sequences=True
model = tf.keras.Sequential([
    tf.keras.layers.LSTM(128, return_sequences=True, input_shape=(10, 64)),
    tf.keras.layers.LSTM(64),
    tf.keras.layers.Dense(10),
])

gru = tf.keras.layers.GRU(128)
bi = tf.keras.layers.Bidirectional(tf.keras.layers.LSTM(64))
out = bi(x)   # shape (4, 128) — 64 * 2

Dropout e Regularização

Dropout zera unidades aleatoriamente durante o treino para prevenir co-adaptação — é automaticamente desativado na inferência (training=False). SpatialDropout2D descarta mapas de features inteiros, melhor para redes conv. L2 (weight decay) é o regularizador mais comum. LayerNormalization normaliza sobre o eixo de features (por amostra), diferentemente do BatchNorm, que normaliza sobre o eixo de lote — preferido para transformers e RNNs.

tensorflow
import tensorflow as tf

drop = tf.keras.layers.Dropout(0.5)
x = tf.random.normal((4, 10))
y = drop(x, training=True)   # training=True activates dropout

tf.keras.layers.SpatialDropout2D(0.5)   # drop entire feature maps
tf.keras.layers.GaussianDropout(0.5)
tf.keras.layers.AlphaDropout(0.5)

# weight regularization
tf.keras.layers.Dense(64,
    kernel_regularizer=tf.keras.regularizers.l2(1e-4),
    activity_regularizer=tf.keras.regularizers.l1(1e-5))

norm = tf.keras.layers.LayerNormalization()

Batch Normalization

BatchNormalization normaliza ativações por canal, mantendo estatísticas móveis EMA para inferência. axis=-1 normaliza o último eixo (canal) para NHWC. Ponha o BN depois do conv e antes da ativação, e desative o bias do conv (use_bias=False), já que o beta do BN cuida do deslocamento. momentum controla quão rápido as estatísticas móveis acompanham os dados — valores altos (0.99) são mais estáveis. BN comporta-se diferente em treino vs inferência (flag training).

tensorflow
import tensorflow as tf

bn = tf.keras.layers.BatchNormalization(
    axis=-1, momentum=0.99, epsilon=1e-3,
)

model = tf.keras.Sequential([
    tf.keras.layers.Conv2D(32, 3, padding='same', use_bias=False),
    tf.keras.layers.BatchNormalization(),
    tf.keras.layers.ReLU(),
])

print(len(bn.weights))         # 4
print(len(bn.trainable_weights))    # 2

Camada Personalizada

Subclasseie Layer para construir ops personalizadas. Defina pesos em build() (chamada uma vez com a forma de entrada) em vez de __init__, para que a camada se adapte ao tamanho da entrada. Implemente get_config() para que a camada possa ser serializada e recarregada. add_weight registra o tensor com o rastreamento do Keras (então aparece em weights, é salvo e movido ao device). Para transformações sem estado, você pode pular build() e só sobrescrever call().

tensorflow
import tensorflow as tf

class Linear(tf.keras.layers.Layer):
    def __init__(self, units=32, **kwargs):
        super().__init__(**kwargs)
        self.units = units

    def build(self, input_shape):
        self.w = self.add_weight(
            shape=(input_shape[-1], self.units),
            initializer='glorot_uniform', trainable=True, name='w')
        self.b = self.add_weight(
            shape=(self.units,), initializer='zeros', trainable=True, name='b')

    def call(self, inputs):
        return tf.matmul(inputs, self.w) + self.b

    def get_config(self):
        config = super().get_config()
        config.update({'units': self.units})
        return config

layer = Linear(64)
out = layer(tf.random.normal((4, 10)))
05

Perdas

BinaryCrossentropy

BinaryCrossentropy serve a tarefas binárias ou multi-rótulo (cada classe independente). Passe from_logits=True se seu modelo produz logits crus — numericamente mais seguro que aplicar sigmoid + BCE separadamente. pos_weight pondera mais os exemplos positivos para tratar desequilíbrio. Para problemas multi-rótulo com C classes, o alvo tem forma (N, C) de 0/1 e as previsões são (N, C) de probabilidades ou logits.

tensorflow
import tensorflow as tf

bce = tf.keras.losses.BinaryCrossentropy(from_logits=False)
y_true = tf.constant([[1.0], [0.0], [1.0], [0.0]])
y_pred = tf.constant([[0.9], [0.1], [0.8], [0.2]])
loss = bce(y_true, y_pred)

# from_logits=True is more numerically stable
bce_logits = tf.keras.losses.BinaryCrossentropy(from_logits=True)
logits = tf.constant([[2.0], [-2.0], [1.5], [-1.5]])
loss = bce_logits(y_true, logits)

bce = tf.keras.losses.BinaryCrossentropy(
    from_logits=True, pos_weight=tf.constant([5.0]))

CategoricalCrossentropy

CategoricalCrossentropy espera alvos one-hot; SparseCategoricalCrossentropy espera índices de classe inteiros (mais eficiente em memória para muitas classes). Sempre passe from_logits=True quando o modelo não termina em softmax — usa o truque log-sum-exp pela estabilidade numérica. Para label smoothing, use CategoricalCrossentropy(label_smoothing=0.1), um regularizador forte para classificação e NLP.

tensorflow
import tensorflow as tf

# one-hot labels
cce = tf.keras.losses.CategoricalCrossentropy(from_logits=False)
y_true = tf.constant([[0, 1, 0], [1, 0, 0]], dtype=tf.float32)
y_pred = tf.constant([[0.1, 0.8, 0.1], [0.7, 0.2, 0.1]])
loss = cce(y_true, y_pred)

# integer labels -> use sparse version
scce = tf.keras.losses.SparseCategoricalCrossentropy(from_logits=True)
y_true_int = tf.constant([1, 0])
logits = tf.constant([[1.0, 3.0, 0.5], [2.5, 0.2, 0.1]])
loss = scce(y_true_int, logits)

MSE e Perdas de Regressão

MSE penaliza erros grandes quadraticamente (sensível a outliers); MAE é linear. Huber comporta-se como MSE perto de zero e MAE longe — o padrão para regressão de detecção de objetos. LogCosh é similar, mas duas vezes diferenciável em qualquer lugar, útil quando você precisa de gradientes de segunda ordem. Toda redução assume média sobre o lote; sobrescreva com reduction=tf.keras.losses.Reduction.NONE para perdas por amostra.

tensorflow
import tensorflow as tf

mse = tf.keras.losses.MeanSquaredError()
y_true = tf.constant([3.0, -0.5, 2.0, 7.0])
y_pred = tf.constant([2.5, 0.0, 2.0, 8.0])
loss = mse(y_true, y_pred)

mae = tf.keras.losses.MeanAbsoluteError()
loss = mae(y_true, y_pred)

huber = tf.keras.losses.Huber(delta=1.0)
loss = huber(y_true, y_pred)

logcosh = tf.keras.losses.LogCosh()
loss = logcosh(y_true, y_pred)

Perda Personalizada

Uma perda personalizada é qualquer chamável que recebe (y_true, y_pred) e retorna um tensor escalar. Para serialização ou hiperparâmetros, subclasseie tf.keras.losses.Loss e implemente call() + get_config(). Mantenha toda op diferenciável. FocalLoss reduz o peso de exemplos fáceis para focar nos difíceis — popular em detecção de objetos. Use Reduction.NONE em call() e deixe o Keras reduzir no fim, se quiser que o mascaramento funcione.

tensorflow
import tensorflow as tf

def weighted_mse(y_true, y_pred):
    weights = tf.cast(y_true != 0, tf.float32)
    return tf.reduce_sum(weights * tf.square(y_true - y_pred)) / tf.reduce_sum(weights)

class FocalLoss(tf.keras.losses.Loss):
    def __init__(self, alpha=0.25, gamma=2.0, **kwargs):
        super().__init__(**kwargs)
        self.alpha = alpha
        self.gamma = gamma

    def call(self, y_true, y_pred):
        bce = tf.keras.losses.binary_crossentropy(y_true, y_pred)
        p = y_pred
        pt = p * y_true + (1 - p) * (1 - y_true)
        return self.alpha * tf.pow(1 - pt, self.gamma) * bce

    def get_config(self):
        config = super().get_config()
        config.update({'alpha': self.alpha, 'gamma': self.gamma})
        return config

loss = FocalLoss(alpha=0.25, gamma=2.0)

Perda a partir de Logits

Computar softmax e depois cross-entropy separadamente pode transbordar para logits grandes (e^100). Passar from_logits=True deixa o TF fundi-los com o truque log-sum-exp, numericamente estável. As APIs funcionais tf.nn.*_cross_entropy_with_logits fazem o mesmo. Garanta que seu modelo NÃO termine em softmax/sigmoid ao usar from_logits=True, senão você aplica a ativação duas vezes.

tensorflow
import tensorflow as tf

# why logits? numerical stability
logits = tf.constant([[100.0, 0.0, 0.0]])

# BAD: softmax first then CCE (can overflow)
probs = tf.nn.softmax(logits)
loss_bad = tf.keras.losses.CategoricalCrossentropy()(
    tf.constant([[1.0, 0.0, 0.0]]), probs)

# GOOD: from_logits=True uses log-sum-exp internally
loss_good = tf.keras.losses.CategoricalCrossentropy(from_logits=True)(
    tf.constant([[1.0, 0.0, 0.0]]), logits)

loss = tf.nn.sigmoid_cross_entropy_with_logits(labels=y, logits=z)
loss = tf.nn.softmax_cross_entropy_with_logits(labels=y, logits=z)

Perdas Multi-saída

Para modelos multi-saída, passe um dict mapeando nomes de saída a funções de perda e um dict loss_weights para equilibrá-las. A perda total é a soma ponderada. Este é o padrão padrão de aprendizado multitarefa — cada cabeça recebe sua própria perda e métrica. Passe os alvos de treino como um dict com as mesmas chaves na hora do fit. Ajuste loss_weights para que nenhuma tarefa domine o gradiente.

tensorflow
import tensorflow as tf

model.compile(
    optimizer='adam',
    loss={
        'priority': tf.keras.losses.BinaryCrossentropy(from_logits=True),
        'department': tf.keras.losses.SparseCategoricalCrossentropy(from_logits=True),
    },
    loss_weights={'priority': 1.0, 'department': 0.5},
    metrics={'priority': ['accuracy'], 'department': ['accuracy']},
)

inputs = tf.keras.Input(shape=(64,))
x = tf.keras.layers.Dense(64, activation='relu')(inputs)
out_a = tf.keras.layers.Dense(1, name='priority')(x)
out_b = tf.keras.layers.Dense(10, name='department')(x)
model = tf.keras.Model(inputs, [out_a, out_b])

model.fit(x_train, {'priority': y_pri, 'department': y_dep}, epochs=5)
06

Otimizadores

Adam

Adam é o otimizador padrão para a maioria das tarefas — taxas de aprendizado adaptativas por parâmetro, robusto à escolha de hiperparâmetros. beta_1/beta_2 controlam o decaimento EMA do primeiro e segundo momentos. Passe um objeto LearningRateSchedule em vez de um float para decair o LR ao longo do treino. global_clipnorm reescala cada um dos gradientes se sua norma combinada exceder o limiar — importante para RNNs e transformers.

tensorflow
import tensorflow as tf

opt = tf.keras.optimizers.Adam(learning_rate=1e-3)

opt = tf.keras.optimizers.Adam(
    learning_rate=1e-3, beta_1=0.9, beta_2=0.999,
    epsilon=1e-7, amsgrad=False,
)

# schedule as learning_rate
lr_schedule = tf.keras.optimizers.schedules.CosineDecay(
    initial_learning_rate=1e-3, decay_steps=10000)
opt = tf.keras.optimizers.Adam(learning_rate=lr_schedule)

# gradient clipping
opt = tf.keras.optimizers.Adam(learning_rate=1e-3, global_clipnorm=1.0)

SGD

SGD + momentum frequentemente generaliza melhor que Adam no treino de CNNs com lotes grandes, ao custo de mais ajuste de LR. momentum=0.9 é padrão; Nesterov dá uma pequena vantagem extra. weight_decay adiciona regularização L2 desacoplada (Keras 3) — versões antigas usam kernel_regularizer nas camadas em vez disso. SGD precisa de warmup e agendamento de LR para competir com Adam de fábrica.

tensorflow
import tensorflow as tf

opt = tf.keras.optimizers.SGD(learning_rate=0.01)
opt = tf.keras.optimizers.SGD(learning_rate=0.01, momentum=0.9)
opt = tf.keras.optimizers.SGD(
    learning_rate=0.01, momentum=0.9, nesterov=True)

# with weight decay (Keras 2.13+ / 3.x)
opt = tf.keras.optimizers.SGD(
    learning_rate=0.01, momentum=0.9, weight_decay=1e-4)

# clip gradients by value
opt = tf.keras.optimizers.SGD(
    learning_rate=0.01, momentum=0.9, clipvalue=0.5)

AdamW e Outros Otimizadores

AdamW desacopla o weight decay da atualização de gradiente, o que importa em escala (transformers, CNNs grandes). RMSprop é o otimizador clássico de RNN. Adagrad se adapta por parâmetro, mas pode estagnar cedo — serve a features esparsas. FTRL é projetado para aprendizado online em larga escala com features esparsas (previsão de cliques). Para projetos novos, comece com AdamW.

tensorflow
import tensorflow as tf

opt = tf.keras.optimizers.AdamW(
    learning_rate=3e-4, weight_decay=0.01,
    beta_1=0.9, beta_2=0.999)

opt = tf.keras.optimizers.RMSprop(learning_rate=1e-3, rho=0.9)
opt = tf.keras.optimizers.Adagrad(learning_rate=1e-2)
opt = tf.keras.optimizers.Adadelta(learning_rate=1.0)
opt = tf.keras.optimizers.Nadam(learning_rate=1e-3)
opt = tf.keras.optimizers.Ftrl(learning_rate=0.1)

Aplicando Gradientes

Num loop de treino personalizado, você computa gradientes com GradientTape e depois chama opt.apply_gradients(zip(grads, vars)). Este é o bloco de construção dos loops de treino personalizados (veja a seção custom-training-loop). clip_by_global_norm reescala os gradientes para que sua norma L2 combinada fique sob o limiar. Gradientes None significam que a variável não afetou a perda — comum para parâmetros não usados e vale registrar.

tensorflow
import tensorflow as tf

opt = tf.keras.optimizers.Adam(1e-3)
vars = [w, b]

with tf.GradientTape() as tape:
    preds = model(x)
    loss = loss_fn(y, preds)
grads = tape.gradient(loss, vars)

grads, _ = tf.clip_by_global_norm(grads, 1.0)
opt.apply_gradients(zip(grads, vars))

for v, g in zip(vars, grads):
    print(v.name, g is not None, g.numpy().norm() if g is not None else None)

Agendamentos de Taxa de Aprendizado

Objetos LearningRateSchedule computam o LR como função do contador de passos do otimizador. CosineDecay decresce suavemente até alpha*lr_inicial — um padrão forte. CosineDecayRestarts implementa reinícios quentes estilo SGDR. Passe o agendamento como learning_rate ao construir o otimizador; o Keras o chama automaticamente a cada passo. Para warmup, envolva com um agendamento personalizado ou use o callback WarmUp do tensorflow/addons.

tensorflow
import tensorflow as tf

sched = tf.keras.optimizers.schedules.PiecewiseConstantDecay(
    boundaries=[500, 1500], values=[1e-3, 1e-4, 1e-5])

sched = tf.keras.optimizers.schedules.ExponentialDecay(
    initial_learning_rate=1e-3, decay_steps=1000, decay_rate=0.96,
    staircase=True)

sched = tf.keras.optimizers.schedules.CosineDecay(
    initial_learning_rate=1e-3, decay_steps=10000, alpha=0.0)

opt = tf.keras.optimizers.Adam(learning_rate=sched)
print(opt.learning_rate(opt.iterations))

Clipping de Gradiente e EMA

global_clipnorm (reescala cada um dos gradientes juntos) é a escolha mais comum e é o que os transformers usam. clipvalue recorta rigidamente cada elemento. Para clipping personalizado, modifique os grads entre tape.gradient e apply_gradients. A Média Móvel Exponencial (EMA) dos pesos frequentemente dá um pequeno ganho de acurácia na inferência — aplique-a a cada passo e use os pesos médios para avaliação. TF Addons tem um wrapper de otimizador MovingAverage.

tensorflow
import tensorflow as tf

opt = tf.keras.optimizers.Adam(1e-3, global_clipnorm=1.0)
opt = tf.keras.optimizers.Adam(1e-3, clipvalue=0.5)
opt = tf.keras.optimizers.Adam(1e-3, clipnorm=1.0)

# manual clipping (more control)
grads = tape.gradient(loss, vars)
grads = [tf.clip_by_norm(g, 1.0) if g is not None else g for g in grads]
grads, _ = tf.clip_by_global_norm(grads, 1.0)
opt.apply_gradients(zip(grads, vars))

# exponential moving average of weights (improves generalization)
ema = tf.train.ExponentialMovingAverage(decay=0.999)
07

Treino

compile e fit

fit é a API de treino de alto nível: cuida de agrupamento, embaralhamento, validação, callbacks e progresso. Passe validation_data=(x, y) ou validation_split=0.2 (separado do treino). verbose=2 imprime uma linha por época (bom para logs); 1 mostra uma barra de progresso. O objeto history retornado guarda perda e métricas por época — plote-o para notar overfitting.

tensorflow
import tensorflow as tf

model.compile(
    optimizer='adam',
    loss='sparse_categorical_crossentropy',
    metrics=['accuracy'],
)

history = model.fit(
    x_train, y_train, batch_size=32, epochs=10,
    validation_data=(x_val, y_val),
    validation_split=0.2, shuffle=True, verbose=2,
)

print(history.history['loss'])

Validação e Métricas

Métricas são objetos com estado que acumulam entre lotes e computam o valor final no fim da época — diferentemente das perdas, não afetam o treino. Passe strings ('accuracy') ou objetos Metric para métricas personalizadas. Subclasseie tf.keras.metrics.Metric e implemente update_state/result/reset_state. reset_state (renomeado de reset_states no TF 2.11+) é chamado no início de cada época.

tensorflow
model.compile(
    optimizer='adam', loss='sparse_categorical_crossentropy',
    metrics=[
        'accuracy',
        tf.keras.metrics.SparseTopKCategoricalAccuracy(k=5, name='top5_acc'),
        tf.keras.metrics.Precision(name='precision'),
        tf.keras.metrics.Recall(name='recall'),
    ],
)

class F1Score(tf.keras.metrics.Metric):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.precision = tf.keras.metrics.Precision()
        self.recall = tf.keras.metrics.Recall()
    def update_state(self, y_true, y_pred, sample_weight=None):
        self.precision.update_state(y_true, y_pred, sample_weight)
        self.recall.update_state(y_true, y_pred, sample_weight)
    def result(self):
        p, r = self.precision.result(), self.recall.result()
        return 2 * p * r / (p + r + 1e-8)
    def reset_state(self):
        self.precision.reset_state(); self.recall.reset_state()

Épocas, Tamanho de Lote e Passos

Ao usar tf.data.Dataset, não passe batch_size — o dataset já está agrupado. steps_per_epoch diz ao fit quantos lotes constituem uma época quando o dataset repete indefinidamente. validation_steps faz o mesmo para a validação. Use initial_epoch para retomar o treino de um checkpoint — o fit pulará as primeiras N épocas, mas o estado do otimizador (agendamento de LR, momentum) continua corretamente.

tensorflow
model.fit(x_train, y_train, batch_size=32, epochs=10)

# with tf.data.Dataset
model.fit(train_dataset, epochs=10, validation_data=val_dataset)

# Dataset of unknown size: use steps_per_epoch
model.fit(
    train_dataset, epochs=10, steps_per_epoch=500,
    validation_data=val_dataset, validation_steps=50,
)

# initial epoch (resume training)
model.fit(train_dataset, initial_epoch=5, epochs=10)

Pesos de Classe e Amostra

class_weight escala a perda de cada classe para contrabalançar desequilíbrio — equivalente a sobreamostragem sem o cálculo extra. sample_weight dá controle por exemplo, útil para mineração de exemplos difíceis ou mascarar posições preenchidas. Ao usar um tf.data.Dataset, inclua sample_weight como terceiro elemento da tupla, para que o dataset produza (x, y, w). Use sklearn.utils.class_weight para computar pesos balanceados automaticamente.

tensorflow
class_weight = {0: 1.0, 1: 5.0, 2: 1.0}   # class 1 is rare
model.fit(x_train, y_train, class_weight=class_weight, epochs=10)

sample_weight = np.where(y_train == 1, 5.0, 1.0)
model.fit(x_train, y_train, sample_weight=sample_weight, epochs=10)

# with Dataset: yield (x, y, sample_weight) tuples
ds = tf.data.Dataset.from_tensor_slices((x, y, w))
model.fit(ds, epochs=10)

from sklearn.utils import class_weight
cw = class_weight.compute_class_weight('balanced', classes=np.unique(y), y=y)
class_weight = dict(enumerate(cw))

Predict e Evaluate

predict retorna um array NumPy de previsões para toda a entrada — use batch_size para controlar a memória. evaluate retorna a perda mais quaisquer métricas do compile. Para entradas muito grandes, itere lotes manualmente com predict_on_batch. Chamar o modelo diretamente (model(x)) retorna um tensor e respeita training=, enquanto predict sempre roda em modo de inferência e retorna NumPy. Use model(x, training=True) para augmentation no tempo de teste.

tensorflow
preds = model.predict(x_test, batch_size=64)
print(preds.shape)   # (N, num_classes)

pred = model.predict(x_test[:1])

loss, acc = model.evaluate(x_test, y_test, batch_size=64, verbose=2)
test_loss, test_acc, test_prec = model.evaluate(test_dataset)

for batch in test_dataset:
    preds = model.predict_on_batch(batch[0])

preds = model(x_test, training=True)   # callable form, test-time aug

Sobrescrever train_step

Sobrescrever train_step permite personalizar o que acontece em cada lote do fit, mantendo o loop de épocas, callbacks e distribuição do fit. Esta é a ponte entre o fit de alto nível e um loop totalmente personalizado — ótimo para GANs, aprendizado contrastivo ou qualquer objetivo não padrão. Use self.compiled_loss e self.compiled_metrics para que a perda/métricas do compile() continuem funcionando. test_step sobrescreve o comportamento de validação da mesma forma.

tensorflow
import tensorflow as tf

class CustomModel(tf.keras.Model):
    def train_step(self, data):
        x, y = data
        with tf.GradientTape() as tape:
            y_pred = self(x, training=True)
            loss = self.compiled_loss(y, y_pred, regularization_losses=self.losses)
        grads = tape.gradient(loss, self.trainable_variables)
        self.optimizer.apply_gradients(zip(grads, self.trainable_variables))
        self.compiled_metrics.update_state(y, y_pred)
        return {m.name: m.result() for m in self.metrics}

    def test_step(self, data):
        x, y = data
        y_pred = self(x, training=False)
        self.compiled_loss(y, y_pred)
        self.compiled_metrics.update_state(y, y_pred)
        return {m.name: m.result() for m in self.metrics}

model = CustomModel(inputs, outputs)
model.compile(optimizer='adam', loss='...', metrics=['accuracy'])
model.fit(dataset, epochs=10)
08

Callbacks

EarlyStopping

EarlyStopping interrompe o treino quando a métrica monitorada para de melhorar, economizando tempo e prevenindo overfitting. patience=N espera N épocas sem melhoria antes de parar. restore_best_weights=True volta ao melhor epoch no fim — sem isso você fica com os pesos finais (possivelmente piores). mode='min' para perdas, 'max' para acurácia. Sempre defina um máximo de épocas generoso e deixe o callback decidir.

tensorflow
import tensorflow as tf

early = tf.keras.callbacks.EarlyStopping(
    monitor='val_loss', min_delta=0.001, patience=5,
    mode='auto', restore_best_weights=True, verbose=1,
)

model.fit(train_ds, validation_data=val_ds, epochs=100, callbacks=[early])

ModelCheckpoint

ModelCheckpoint salva o modelo durante o treino, para que você possa se recuperar de quedas ou escolher a melhor época. save_best_only=True guarda só o melhor checkpoint (pela métrica monitor) — defina monitor como sua métrica de validação. save_weights_only=True é menor e agnóstico de arquitetura, mas você precisa da classe do modelo para recarregar. placeholders de formato como {epoch:02d} embutem o número da época no nome do arquivo. save_freq='epoch' é o padrão; um inteiro N salva a cada N lotes.

tensorflow
import tensorflow as tf

ckpt = tf.keras.callbacks.ModelCheckpoint(
    filepath='checkpoints/epoch-{epoch:02d}-val-{val_loss:.3f}.keras',
    monitor='val_loss', save_best_only=True, save_weights_only=False,
    mode='min', save_freq='epoch', verbose=1,
)

ckpt = tf.keras.callbacks.ModelCheckpoint(
    'weights.{epoch:02d}.h5', save_weights_only=True, save_freq='epoch',
)

model.fit(train_ds, validation_data=val_ds, epochs=50, callbacks=[ckpt])

ReduceLROnPlateau

ReduceLROnPlateau reduz o LR quando a métrica monitorada estabiliza — útil quando você não conhece o agendamento certo de antemão. factor é o multiplicador (0.5 = metade), patience é quantas épocas esperar, min_lr é o piso. cooldown pausa o monitoramento logo após uma redução, para deixar o novo LR assentar. Combine com EarlyStopping: reduza o LR primeiro, depois pare se não houver mais melhoria. verbose=1 imprime cada redução.

tensorflow
import tensorflow as tf

reduce = tf.keras.callbacks.ReduceLROnPlateau(
    monitor='val_loss', factor=0.5, patience=3, min_lr=1e-7,
    mode='min', min_delta=1e-4, cooldown=0, verbose=1,
)

model.fit(train_ds, validation_data=val_ds, epochs=100, callbacks=[reduce])

Callback TensorBoard

O callback TensorBoard transmite métricas de treino, histogramas de pesos, o grafo do modelo e dados de profiling para log_dir durante o fit. histogram_freq=1 registra distribuições de pesos por época — defina 0 para economizar espaço. profile_batch=2 roda o TF Profiler no lote 2 para identificar gargalos de desempenho (pipeline de entrada, latência de op). Inicie o TensorBoard apontando para log_dir para ver os gráficos. Use subdiretórios distintos por experimento para comparar execuções.

tensorflow
import tensorflow as tf

tb = tf.keras.callbacks.TensorBoard(
    log_dir='./logs/fit', histogram_freq=1, write_graph=True,
    write_images=False, update_freq='epoch',
    profile_batch=2, embeddings_freq=0,
)

model.fit(train_ds, validation_data=val_ds, epochs=10, callbacks=[tb])
# launch: tensorboard --logdir=./logs

LearningRateScheduler

LearningRateScheduler recebe uma função de (época, lr) e aplica o novo LR no início de cada época — simples, mas só por época. Para agendamentos por passo, prefira um objeto LearningRateSchedule passado ao otimizador (veja a seção de otimizadores) — é chamado a cada lote e funciona dentro de tf.function. A forma de Callback serve para agendamentos grosseiros. Para warmup+decaimento, um objeto de agendamento é mais limpo.

tensorflow
import tensorflow as tf

def schedule(epoch, lr):
    if epoch < 10:
        return lr
    return lr * tf.math.exp(-0.1).numpy()

scheduler = tf.keras.callbacks.LearningRateScheduler(schedule, verbose=1)

class StepScheduler(tf.keras.callbacks.Callback):
    def on_train_batch_begin(self, batch, logs=None):
        step = self.model.optimizer.iterations.numpy()
        new_lr = 1e-3 * (0.5 ** (step // 1000))
        self.model.optimizer.learning_rate.assign(new_lr)

scheduler = tf.keras.callbacks.LearningRateScheduler(
    lambda epoch: 1e-3 * 0.9 ** epoch)

Callback Personalizado

Callbacks se enganchar no ciclo de vida do treino: on_epoch_begin/end, on_train_batch_begin/end, on_test_*, on_predict_*. Acesse o modelo via self.model e o otimizador via self.model.optimizer. logs é um dict das métricas atuais. Callbacks personalizados são ótimos para logging, manipulação de LR, terminação antecipada (self.model.stop_training = True) ou sincronização com sistemas externos (W&B, MLflow). Mantenha-os baratos — rodam a cada lote.

tensorflow
import tensorflow as tf

class DebugCallback(tf.keras.callbacks.Callback):
    def on_epoch_end(self, epoch, logs=None):
        lr = self.model.optimizer.learning_rate
        if hasattr(lr, 'numpy'):
            lr = lr.numpy()
        print(f"Epoch {epoch}: lr={lr}, logs={logs}")

    def on_train_batch_end(self, batch, logs=None):
        if batch % 100 == 0:
            print(f"  batch {batch}: loss={logs.get('loss'):.4f}")

    def on_train_end(self, logs=None):
        print("Training finished!")

model.fit(train_ds, epochs=5, callbacks=[DebugCallback()])
09

Pipeline tf.data

tf.data.Dataset

tf.data.Dataset é a API de dados em streaming do TF — canaliza dados do disco/CPU para a GPU com eficiência. from_tensor_slices une tensores ao longo do eixo 0. A cadeia canônica é shuffle -> batch -> prefetch: shuffle randomiza, batch agrupa, prefetch sobrepõe a preparação do próximo lote com o treino atual. Use AUTOTUNE para deixar o TF escolher os tamanhos dos buffers de prefetch automaticamente.

tensorflow
import tensorflow as tf

ds = tf.data.Dataset.from_tensor_slices((x_train, y_train))

def gen():
    for i in range(len(x_train)):
        yield x_train[i], y_train[i]
ds = tf.data.Dataset.from_generator(gen, output_signature=(
    tf.TensorSpec(shape=(28, 28), dtype=tf.float32),
    tf.TensorSpec(shape=(), dtype=tf.int32),
))

ds = ds.shuffle(10000).batch(32).prefetch(tf.data.AUTOTUNE)

for x, y in ds:
    print(x.shape, y.shape)
    break

Map, Filter e Cache

map aplica uma função a cada elemento — augmentation, normalização, tokenização. num_parallel_calls=AUTOTUNE paraleliza pelos núcleos de CPU. cache() guarda o dataset em memória (ou arquivo), para que épocas seguintes pulem a fonte — enorme aceleração para dados pequenos/médios, mas cacheie ANTES das ops aleatórias, senão você repetirá as mesmas augmentations a cada época. A ordem canônica é cache -> map(aumentar) -> shuffle -> batch -> prefetch.

tensorflow
import tensorflow as tf

def augment(image, label):
    image = tf.image.random_flip_left_right(image)
    image = tf.image.random_brightness(image, 0.2)
    return image, label

ds = tf.data.Dataset.from_tensor_slices((images, labels))
ds = ds.map(augment, num_parallel_calls=tf.data.AUTOTUNE)
ds = ds.map(lambda x, y: (tf.cast(x, tf.float32) / 255.0, y))
ds = ds.filter(lambda x, y: y < 10)

ds = ds.cache()                    # in memory
ds = ds.cache('/tmp/data.cache')   # to file

ds = ds.cache().shuffle(1000).batch(32).prefetch(tf.data.AUTOTUNE)

Batch, Shuffle e Repeat

shuffle usa um buffer de tamanho N: preenche o buffer, amostra um, reabastece — então um buffer >= tamanho do dataset dá ordem verdadeiramente aleatória. shuffle -> repeat -> batch reembaralha a cada época. Para treinar com steps_per_epoch, use repeat() para que o dataset nunca acabe. drop_remainder=True descarta o último lote curto — importante para BatchNorm e modelos de forma fixa. Seed torna o embaralhamento reproduzível entre iterações só se reshuffle_each_iteration=True com a mesma seed.

tensorflow
import tensorflow as tf

ds = tf.data.Dataset.from_tensor_slices((x, y))
ds = ds.batch(32, drop_remainder=False)
ds = ds.shuffle(buffer_size=10000, seed=42, reshuffle_each_iteration=True)
ds = ds.repeat()         # infinite
ds = ds.repeat(5)        # 5 epochs

# recommended order: shuffle -> repeat -> batch
ds = ds.shuffle(10000).repeat().batch(32)

Prefetch e Desempenho

prefetch(AUTOTUNE) é o maior ganho isolado — deixa a CPU preparar o lote N+1 enquanto a GPU treina no lote N, para que nenhum espere. num_parallel_calls=AUTOTUNE no map paraleliza o pré-processamento ligado à CPU. A ordem ótima do pipeline é: fonte -> cache -> shuffle -> map(aumentar) -> batch -> prefetch. Use tf.data.experimental.AUTOTUNE (igual a tf.data.AUTOTUNE) e deixe o TF ajustar os tamanhos de buffer. Sempre faça profiling antes de otimizar — o gargalo costuma estar em outro lugar.

tensorflow
import tensorflow as tf

ds = ds.prefetch(tf.data.AUTOTUNE)
ds = ds.map(parse_fn, num_parallel_calls=tf.data.AUTOTUNE)

# full recommended pipeline
ds = (tf.data.Dataset.from_tensor_slices((x, y))
      .cache()
      .shuffle(10000)
      .map(augment, num_parallel_calls=tf.data.AUTOTUNE)
      .batch(32)
      .prefetch(tf.data.AUTOTUNE))

Lendo Arquivos

TextLineDataset transmite linhas de arquivos de texto (logs, linhas CSV). make_csv_dataset analisa CSVs com inferência automática de tipo de coluna. image_dataset_from_directory é o equivalente Keras do ImageFolder do PyTorch — infere rótulos dos nomes de subdiretórios e retorna (lote_de_imagens, lote_de_rótulos). Para mais controle sobre o carregamento de imagens, use tf.io.read_file + tf.io.decode_image dentro de uma função map. Sempre agrupe o dataset em lotes antes de passar ao fit.

tensorflow
import tensorflow as tf

ds = tf.data.TextLineDataset(['file1.txt', 'file2.txt'])

ds = tf.data.experimental.make_csv_dataset(
    'data.csv', batch_size=32, label_name='label',
    num_epochs=1, shuffle_buffer_size=1000,
)

ds = tf.keras.utils.image_dataset_from_directory(
    'data/train', image_size=(224, 224), batch_size=32,
    shuffle=True, seed=42, validation_split=0.2, subset='training',
)

TFRecord

TFRecord é o formato de registro binário do TF — a forma mais rápida de alimentar datasets grandes do disco. Cada registro é um tf.train.Example serializado (um dict de features). A leitura é I/O sequencial, muito mais rápida que leituras aleatórias em armazenamento na nuvem (GCS/S3). Para imagens, guarde bytes crus e decodifique em map(). Use tf.data.TFRecordDataset com compression='GZIP' para arquivos menores. Sharding (múltiplos arquivos .tfrecord-0000N-de-0000M) habilita leitura paralela.

tensorflow
import tensorflow as tf

def serialize(x, y):
    feature = {
        'x': tf.train.Feature(float_list=tf.train.FloatList(value=x.flatten())),
        'y': tf.train.Feature(int64_list=tf.train.Int64List(value=[y])),
    }
    return tf.train.Example(features=tf.train.Features(feature=feature)).SerializeToString()

with tf.io.TFRecordWriter('data.tfrecord') as w:
    for x, y in dataset:
        w.write(serialize(x, y))

def parse(serialized):
    feature = {'x': tf.io.FixedLenFeature([784], tf.float32),
               'y': tf.io.FixedLenFeature([], tf.int64)}
    parsed = tf.io.parse_single_example(serialized, feature)
    return parsed['x'], parsed['y']

ds = tf.data.TFRecordDataset('data.tfrecord').map(parse).batch(32)
10

Salvar e Carregar

Formato SavedModel

SavedModel é o formato de grau de produção: reúne a arquitetura, os pesos e um grafo rastreado, para que o modelo possa ser carregado em TF Serving, TFLite, TF.js ou C++ sem o código Python original. Use tf.keras.models.load_model para recarregar no Python. Passe um input_signature para definir a assinatura de serviço explicitamente — exigido para TF Serving. SavedModel é um diretório, não um arquivo único.

tensorflow
import tensorflow as tf

model.save('saved_model')   # SavedModel directory
loaded = tf.keras.models.load_model('saved_model')
loaded.evaluate(x_test, y_test)

# export for serving (explicit signature)
@tf.function(input_signature=[tf.TensorSpec([None, 784], tf.float32)])
def serve(x):
    return {'outputs': model(x)}

tf.saved_model.save(model, 'serving_model', signatures=serve)

Formato Keras (.keras)

O formato .keras (padrão do Keras 3) é um único arquivo zipado contendo a config da arquitetura, os pesos e o estado do otimizador — fácil de compartilhar e versionar. .h5 é o formato HDF5 legado, ainda suportado, mas não recomendado para projetos novos. SavedModel (um diretório) é exigido para implantação (TFLite, TF Serving). Para camadas personalizadas, .keras salva a config, para que a camada possa ser reconstruída — garanta que get_config() esteja correto.

tensorflow
import tensorflow as tf

model.save('model.keras')   # Keras 3 default
loaded = tf.keras.models.load_model('model.keras')

# legacy HDF5 format
model.save('model.h5')
loaded = tf.keras.models.load_model('model.h5')

# .keras  — Keras 3 default, supports custom layers via config
# .h5     — legacy, weights + architecture but limited custom layer support
# SavedModel — directory, best for deployment/serving

Salvar e Carregar Só Pesos

save_weights guarda só os tensores de parâmetros — muito menor que um modelo completo e desacoplado da arquitetura. Você precisa reconstruir o modelo com a mesma estrutura antes de carregar. skip_mismatch=True (Keras 3) carrega só as camadas que casam, útil para transfer learning. O formato de checkpoint (prefixo 'ckpt') cria arquivos checkpoint/weights-of-ckpt-1.index — o formato nativo de checkpoint do TF, usado internamente pelos callbacks do fit.

tensorflow
import tensorflow as tf

model.save_weights('weights.keras')

model = build_model()   # must match the saved architecture
model.load_weights('weights.keras')

model.save_weights('weights.h5')
model.load_weights('weights.h5')

# load weights from one model into another (partial)
model.load_weights('weights.keras', skip_mismatch=True, by_name=True)

model.save_weights('ckpt')
model.load_weights('ckpt')

Checkpoint Manager

Checkpoint + CheckpointManager dão controle total sobre o salvamento em loops de treino personalizados — mantenha os últimos N checkpoints, restaure o mais recente automaticamente e versione por passo. expect_partial() silencia avisos sobre slots não restaurados (ex.: momentum do otimizador para variáveis novas). Checkpoints guardam o grafo de objetos, não definições de classe — você ainda precisa do código do modelo para restaurar. CheckpointManager.max_to_keep=3 auto-deleta checkpoints antigos.

tensorflow
import tensorflow as tf

ckpt = tf.train.Checkpoint(model=model, optimizer=optimizer, step=optimizer.iterations)
manager = tf.train.CheckpointManager(
    ckpt, directory='./ckpts', max_to_keep=3,
    checkpoint_name='step-{step}',
)

manager.save()
ckpt.restore(manager.latest_checkpoint).expect_partial()

# in a custom loop: save every N steps
if step % 1000 == 0:
    manager.save()

Carregar com Objetos Personalizados

Ao carregar um modelo que usa camadas, perdas ou métricas personalizadas, o Keras precisa saber como reconstruí-las. Passe o dict custom_objects mapeando nomes a classes/funções. Para código mais limpo, decore as classes com @register_keras_serializable, para que sejam registradas globalmente e não precisem de custom_objects. Garanta que get_config retorne cada um dos argumentos do construtor, para que o objeto possa ser reconstruído exatamente — o Keras chama from_config(config) por baixo.

tensorflow
import tensorflow as tf

class MyLayer(tf.keras.layers.Layer):
    ...

custom_objects = {'MyLayer': MyLayer, 'focal_loss': FocalLoss}

loaded = tf.keras.models.load_model(
    'model.keras', custom_objects=custom_objects,
)

# or register globally
@tf.keras.utils.register_keras_serializable(package='my_pkg')
class MyLayer(tf.keras.layers.Layer):
    ...

Exportar para Serviço

TF Serving espera diretórios versionados (serving/1/, serving/2/), para que possa trocar modelos a quente. A assinatura de serviço define os nomes e shapes dos tensores de entrada/saída que os clientes usam. model.export() (Keras 3) embrulha isso automaticamente. Para pré-processamento personalizado, envolva o modelo num tf.Module e defina __call__ com um input_signature que inclua a entrada crua (ex.: imagem uint8) e retorne a saída final. Nomeie os tensores, para que clientes possam endereçá-los.

tensorflow
import tensorflow as tf

# Keras 3 export API (recommended)
model.export('serving/1')

class ServingModule(tf.Module):
    def __init__(self, model):
        self.model = model
    @tf.function(input_signature=[tf.TensorSpec([None, 784], tf.float32, name='inputs')])
    def __call__(self, x):
        return {'outputs': self.model(x)}

module = ServingModule(model)
tf.saved_model.save(module, 'serving/1',
                    signatures={'serving_default': module.__call__})

loaded = tf.saved_model.load('serving/1')
print(list(loaded.signatures.keys()))   # ['serving_default']
11

CNN

Conv2D e Pooling

O bloco CNN canônico no Keras: Conv2D -> BatchNormalization -> ReLU -> MaxPooling. padding='same' mantém o tamanho espacial para stride 1. GlobalAveragePooling2D colapsa as dimensões espaciais num vetor — mais eficiente em parâmetros que Flatten + Dense e menos propenso a overfitting. Keras usa NHWC (channels-last) por padrão, então a forma do Input é (A, L, C) sem dimensão de lote. Convs com stride podem substituir pooling para redução de amostragem aprendível.

tensorflow
import tensorflow as tf

model = tf.keras.Sequential([
    tf.keras.layers.Input(shape=(28, 28, 1)),
    tf.keras.layers.Conv2D(32, 3, padding='same', activation='relu'),
    tf.keras.layers.BatchNormalization(),
    tf.keras.layers.MaxPooling2D(),                # 28 -> 14
    tf.keras.layers.Conv2D(64, 3, padding='same', activation='relu'),
    tf.keras.layers.BatchNormalization(),
    tf.keras.layers.MaxPooling2D(),                # 14 -> 7
    tf.keras.layers.Conv2D(128, 3, padding='same', activation='relu'),
    tf.keras.layers.GlobalAveragePooling2D(),      # (7,7,128) -> (128,)
    tf.keras.layers.Dense(10, activation='softmax'),
])
model.summary()

Construindo uma CNN

Uma CNN estilo VGG com filtros dobrados a cada estágio (32 -> 64 -> 128) e tamanho espacial reduzido pela metade via MaxPooling. Dois convs por estágio (bloco VGG) extrai features mais ricas que um. Rescaling dentro do modelo o torna implantável — imagens uint8 cruas entram direto. GlobalAveragePooling + Dropout regulariza a cabeça. Compile com sparse_categorical_crossentropy, porque os rótulos são índices de classe inteiros.

tensorflow
import tensorflow as tf

inputs = tf.keras.Input(shape=(32, 32, 3))
x = tf.keras.layers.Rescaling(1./255)(inputs)

for filters in [32, 64, 128]:
    x = tf.keras.layers.Conv2D(filters, 3, padding='same', activation='relu')(x)
    x = tf.keras.layers.BatchNormalization()(x)
    x = tf.keras.layers.Conv2D(filters, 3, padding='same', activation='relu')(x)
    x = tf.keras.layers.MaxPooling2D()(x)
    x = tf.keras.layers.Dropout(0.25)(x)

x = tf.keras.layers.GlobalAveragePooling2D()(x)
x = tf.keras.layers.Dense(256, activation='relu')(x)
x = tf.keras.layers.Dropout(0.5)(x)
outputs = tf.keras.layers.Dense(10, activation='softmax')(x)
model = tf.keras.Model(inputs, outputs)

Mapas de Features e Visualização

Crie um Model com a mesma entrada, mas múltiplas saídas (as ativações das camadas conv) para inspecionar o que cada camada aprende. Camadas iniciais detectam bordas/cores, mais profundas detectam texturas/partes. Inestimável para depuração — mapas de features mortos (só zeros) indicam ReLUs quebradas ou problemas de taxa de aprendizado. Para Grad-CAM (mapas de ativação de classe), use tf-keras-vis ou implemente ativações de classe ponderadas por gradiente, para ver que regiões impulsionaram uma previsão.

tensorflow
import tensorflow as tf
import matplotlib.pyplot as plt

feature_model = tf.keras.Model(
    inputs=model.inputs,
    outputs=[layer.output for layer in model.layers if 'conv2d' in layer.name],
)

img = x_test[0:1]
features = feature_model.predict(img)
print([f.shape for f in features])

fig, axes = plt.subplots(4, 8, figsize=(12, 6))
for i, ax in enumerate(axes.flat):
    if i < features[0].shape[-1]:
        ax.imshow(features[0][0, :, :, i], cmap='viridis')
    ax.axis('off')

Backbones CNN Pré-treinados

keras.applications expõe ResNet, EfficientNet, MobileNet, ViT e mais, com pesos do ImageNet. include_top=False descarta a cabeça de 1000 classes, para que você possa anexar a sua. preprocess_input aplica a normalização exata com que o backbone foi treinado — chame-a dentro do modelo para implantação. Congele o backbone (trainable=False) e defina training=False na chamada, para que BatchNorm use estatísticas de inferência — crítico para transfer learning com datasets pequenos.

tensorflow
import tensorflow as tf

backbone = tf.keras.applications.ResNet50(
    include_top=False, weights='imagenet',
    input_shape=(224, 224, 3), pooling='avg',
)
backbone.trainable = False

inputs = tf.keras.Input(shape=(224, 224, 3))
x = tf.keras.applications.resnet50.preprocess_input(inputs)
x = backbone(x, training=False)
x = tf.keras.layers.Dense(256, activation='relu')(x)
x = tf.keras.layers.Dropout(0.5)(x)
outputs = tf.keras.layers.Dense(10, activation='softmax')(x)
model = tf.keras.Model(inputs, outputs)

Conexões Residuais

Conexões residuais (skip) somam a entrada à saída de um bloco, deixando os gradientes fluir diretamente às camadas anteriores — isto é o que habilita treinar redes muito profundas (ResNet). O atalho precisa casar os canais e o tamanho espacial da saída; use um conv 1x1 com stride para ajustar quando diferirem. Add() mescla os dois caminhos. Use a API funcional (não Sequential) para qualquer arquitetura com skip connections. ResNet-50 empilha muitos desses blocos.

tensorflow
import tensorflow as tf

def residual_block(x, filters, stride=1):
    shortcut = x
    x = tf.keras.layers.Conv2D(filters, 3, strides=stride, padding='same', use_bias=False)(x)
    x = tf.keras.layers.BatchNormalization()(x)
    x = tf.keras.layers.ReLU()(x)
    x = tf.keras.layers.Conv2D(filters, 3, padding='same', use_bias=False)(x)
    x = tf.keras.layers.BatchNormalization()(x)
    if stride != 1 or shortcut.shape[-1] != filters:
        shortcut = tf.keras.layers.Conv2D(filters, 1, strides=stride, use_bias=False)(shortcut)
        shortcut = tf.keras.layers.BatchNormalization()(shortcut)
    x = tf.keras.layers.Add()([x, shortcut])
    return tf.keras.layers.ReLU()(x)

inputs = tf.keras.Input(shape=(32, 32, 3))
x = residual_block(inputs, 64)
x = residual_block(x, 128, stride=2)
model = tf.keras.Model(inputs, x)

Cabeça de Detecção

Cabeças de detecção preveem caixas por âncora ou por pixel mais probabilidades de classe. A API funcional torna modelos multi-saída fáceis: retorne um dict de tensores nomeados. Para projetos reais, use a TensorFlow Object Detection API ou KerasCV (detecção, segmentação) — cuidam do casamento de âncoras, NMS e avaliação. Escrever um detector completo do zero é um exercício avançado: trate codificação de caixas, perda de IoU e focal loss com cuidado.

tensorflow
import tensorflow as tf

# YOLO-style detection head: conv to (grid * grid * (5 + num_classes))
def detection_head(x, num_classes, num_anchors=3):
    out = tf.keras.layers.Conv2D(
        num_anchors * (5 + num_classes), 1, activation='linear')(x)
    return out

# anchor-free alternative: predict (cx, cy, w, h, obj, class_logits)
def center_net_head(features, num_classes):
    cls = tf.keras.layers.Conv2D(num_classes, 1, activation='sigmoid', name='cls')(features)
    wh = tf.keras.layers.Conv2D(2, 1, name='wh')(features)
    offset = tf.keras.layers.Conv2D(2, 1, name='offset')(features)
    return {'cls': cls, 'wh': wh, 'offset': offset}
12

RNN e LSTM

Camadas LSTM e GRU

A forma de entrada de LSTM/GRU é (lote, timesteps, features). return_sequences=False retorna a última saída (para classificação); True retorna a sequência completa (para empilhar ou seq2seq). Bidirectional concatena saídas para frente e para trás, dobrando o tamanho das features. stateful=True carrega o estado oculto entre lotes — útil para sequências muito longas divididas em pedaços, mas exige batch_size fixo e resets manuais de estado entre épocas.

tensorflow
import tensorflow as tf

lstm = tf.keras.layers.LSTM(128, return_sequences=False)
x = tf.random.normal((4, 10, 64))
out = lstm(x)                       # (4, 128)

gru = tf.keras.layers.GRU(128)
out = gru(x)                        # (4, 128)

lstm = tf.keras.layers.LSTM(128, return_sequences=True)
out = lstm(x)                       # (4, 10, 128)

bi = tf.keras.layers.Bidirectional(tf.keras.layers.LSTM(64))
out = bi(x)                         # (4, 128) — 64*2

lstm = tf.keras.layers.LSTM(64, stateful=True)

RNNs Empilhadas

Empilhe RNNs definindo return_sequences=True em todas, exceto a última LSTM/GRU. mask_zero=True na camada Embedding gera uma máscara que as RNNs respeitam — pulam posições preenchidas, então você pode agrupar sequências de comprimento variável sem afetar o estado oculto. Dropout entre camadas de RNN regulariza; recurrent_dropout dentro de uma RNN é mais lento (sem cuDNN) — prefira dropout na entrada. Para classificação de texto, este biLSTM é uma baseline forte.

tensorflow
import tensorflow as tf

model = tf.keras.Sequential([
    tf.keras.layers.Embedding(10000, 128, input_length=100, mask_zero=True),
    tf.keras.layers.LSTM(128, return_sequences=True),
    tf.keras.layers.Dropout(0.3),
    tf.keras.layers.LSTM(64),
    tf.keras.layers.Dense(64, activation='relu'),
    tf.keras.layers.Dense(10, activation='softmax'),
])

model.compile(optimizer='adam', loss='sparse_categorical_crossentropy')

Classificação de Texto com RNN

Um classificador de texto padrão: Embedding -> biLSTM -> biLSTM -> Dense -> sigmoid. mask_zero=True é crítico — sem ele, a LSTM processa tokens de preenchimento, enviesando o estado oculto. Bidirectional dobra o poder representacional lendo a sequência nos dois sentidos. Para classificação binária, use sigmoid + binary_crossentropy. Para sequências longas (>500 tokens), transformers superam LSTMs, mas precisam de mais dados e computação.

tensorflow
import tensorflow as tf

model = tf.keras.Sequential([
    tf.keras.layers.Input(shape=(200,)),
    tf.keras.layers.Embedding(10000, 128, mask_zero=True),
    tf.keras.layers.Bidirectional(tf.keras.layers.LSTM(64, return_sequences=True)),
    tf.keras.layers.Bidirectional(tf.keras.layers.LSTM(32)),
    tf.keras.layers.Dense(64, activation='relu'),
    tf.keras.layers.Dropout(0.5),
    tf.keras.layers.Dense(1, activation='sigmoid'),
])

model.compile(optimizer=tf.keras.optimizers.Adam(1e-3),
              loss='binary_crossentropy', metrics=['accuracy'])
model.fit(train_ds, validation_data=val_ds, epochs=5)

Encoder-Decoder Seq2Seq

LSTM encoder-decoder para seq2seq (tradução, resumização). O estado oculto final do encoder inicializa o decoder, que gera a sequência alvo token a token. Treine com teacher forcing: alimente a sequência alvo deslocada como entrada do decoder. Para inferência, escreva um loop separado que alimente cada token previsto de volta como próxima entrada. Atenção (Bahdanau/Luong) melhora drasticamente seq2seq e é o ancestral conceitual dos transformers.

tensorflow
import tensorflow as tf

encoder_input = tf.keras.Input(shape=(None,), name='enc_in')
enc_emb = tf.keras.layers.Embedding(vocab_src, 128)(encoder_input)
encoder = tf.keras.layers.LSTM(256, return_state=True)
enc_out, state_h, state_c = encoder(enc_emb)

decoder_input = tf.keras.Input(shape=(None,), name='dec_in')
dec_emb = tf.keras.layers.Embedding(vocab_tgt, 128)(decoder_input)
decoder_lstm = tf.keras.layers.LSTM(256, return_sequences=True, return_state=True)
dec_out, _, _ = decoder_lstm(dec_emb, initial_state=[state_h, state_c])
decoder_dense = tf.keras.layers.Dense(vocab_tgt, activation='softmax')
outputs = decoder_dense(dec_out)

model = tf.keras.Model([encoder_input, decoder_input], outputs)
model.compile(optimizer='adam', loss='sparse_categorical_crossentropy')

Previsão de Séries Temporais

Para séries temporais, construa pares (entrada, alvo) em janelas: o último valor de cada janela é o alvo, o resto são entradas. window(shift=1) cria janelas sobrepostas; drop_remainder as mantém do mesmo tamanho. LSTM aprende padrões temporais; um Dense(1) final prevê o próximo valor. Para previsão de múltiplos passos, preveja um vetor de horizonte ou use uma arquitetura seq2seq. Sempre padronize a série usando só estatísticas de treino.

tensorflow
import tensorflow as tf

def make_dataset(series, window=20, batch=32):
    ds = tf.data.Dataset.from_tensor_slices(series)
    ds = ds.window(window + 1, shift=1, drop_remainder=True)
    ds = ds.flat_map(lambda w: w.batch(window + 1))
    ds = ds.map(lambda w: (w[:-1][..., tf.newaxis], w[-1:]))
    return ds.shuffle(1000).batch(batch).prefetch(tf.data.AUTOTUNE)

model = tf.keras.Sequential([
    tf.keras.layers.Input(shape=(20, 1)),
    tf.keras.layers.LSTM(32, return_sequences=False),
    tf.keras.layers.Dense(1),
])
model.compile(optimizer='adam', loss='mse')
model.fit(make_dataset(train_series), epochs=10)

Mecanismo de Atenção

A atenção permite que o decoder se foque em estados relevantes do encoder, em vez de depender de um único vetor fixo — uma melhoria importante para sequências longas. Bahdanau (aditiva) e Luong (multiplicativa) são as duas variantes clássicas. Keras fornece tf.keras.layers.AdditiveAttention e Attention como camadas prontas. A atenção é a ponte conceitual para os transformers: multi-head self-attention é só atenção aplicada à mesma sequência.

tensorflow
import tensorflow as tf

class BahdanauAttention(tf.keras.layers.Layer):
    def __init__(self, units):
        super().__init__()
        self.W1 = tf.keras.layers.Dense(units)
        self.W2 = tf.keras.layers.Dense(units)
        self.V = tf.keras.layers.Dense(1)
    def call(self, query, values):
        q = tf.expand_dims(query, 1)
        scores = self.V(tf.nn.tanh(self.W1(values) + self.W2(q)))
        attn = tf.nn.softmax(scores, axis=1)
        context = tf.reduce_sum(attn * values, axis=1)
        return context, attn

attn = tf.keras.layers.AdditiveAttention()
context = attn([query, value])
13

Transformer

MultiHeadAttention

MultiHeadAttention é a camada central do transformer — projeta q/k/v em múltiplas cabeças, atende em paralelo e recombina. Para self-attention, passe o mesmo tensor como query, key e value. attention_mask pode ser uma máscara causal (triangular inferior) para decodificação ou uma máscara de preenchimento (True = ignorar). return_attention_scores=True retorna a matriz de atenção para visualização. A dim de saída iguala a de entrada, para que blocos possam empilhar.

tensorflow
import tensorflow as tf

mha = tf.keras.layers.MultiHeadAttention(
    num_heads=8, key_dim=64, dropout=0.1, use_bias=True)

x = tf.random.normal((4, 10, 512))
out, attn_weights = mha(query=x, value=x, key=x,
                        return_attention_scores=True)
print(out.shape)          # (4, 10, 512)
print(attn_weights.shape) # (4, 8, 10, 10)

# causal mask (decoder self-attention)
mask = tf.linalg.band_part(tf.ones((10, 10)), -1, 0)
out = mha(query=x, value=x, key=x, attention_mask=mask)

# key padding mask (ignore pad positions)
padding = tf.cast(tokens == 0, tf.bool)[:, tf.newaxis, tf.newaxis, :]
out = mha(query=x, value=x, key=x, attention_mask=padding)

Bloco de Encoder Transformer

Um bloco de encoder transformer é: multi-head self-attention + add e norm + feed-forward (MLP) + add e norm. Pre-LN (norma antes da subcamada) é mais estável para treinar do zero; post-LN precisa de warmup. O FFN é um MLP de 2 camadas com GELU, expandindo para 'ff' unidades ocultas e voltando a 'dim'. Empilhe N destes para um encoder completo. epsilon=1e-6 no LayerNorm evita divisão por zero para variâncias pequenas.

tensorflow
import tensorflow as tf

class TransformerBlock(tf.keras.layers.Layer):
    def __init__(self, dim=512, heads=8, ff=2048, dropout=0.1, **kwargs):
        super().__init__(**kwargs)
        self.att = tf.keras.layers.MultiHeadAttention(num_heads=heads, key_dim=dim // heads)
        self.ffn = tf.keras.Sequential([
            tf.keras.layers.Dense(ff, activation='gelu'),
            tf.keras.layers.Dense(dim),
        ])
        self.norm1 = tf.keras.layers.LayerNormalization(epsilon=1e-6)
        self.norm2 = tf.keras.layers.LayerNormalization(epsilon=1e-6)
        self.drop1 = tf.keras.layers.Dropout(dropout)
        self.drop2 = tf.keras.layers.Dropout(dropout)

    def call(self, x, training=False, mask=None):
        attn = self.att(x, x, x, attention_mask=mask)
        x = self.norm1(x + self.drop1(attn, training=training))
        ffn = self.ffn(x)
        return self.norm2(x + self.drop2(ffn, training=training))

Positional Encoding

Transformers são invariantes à permutação — precisam de informação posicional para conhecer a ordem dos tokens. Codificações senoidais adicionam um padrão fixo com base em posição e dimensão; generalizam para sequências mais longas que as vistas no treino. Some o encoding posicional à saída do embedding. Alternativamente, use embeddings de posição aprendidos (uma camada Embedding indexada por posição) ou codificações de posição relativa (usadas em transformers modernos como T5). Para imagens (ViT), adicione um embedding de posição aprendível por patch.

tensorflow
import tensorflow as tf
import numpy as np

class PositionalEncoding(tf.keras.layers.Layer):
    def __init__(self, max_len=5000, dim=512, **kwargs):
        super().__init__(**kwargs)
        pos = np.arange(max_len)[:, np.newaxis]
        i = np.arange(dim)[np.newaxis, :]
        angle = pos / np.power(10000, (2 * (i // 2)) / np.float32(dim))
        angle[:, 0::2] = np.sin(angle[:, 0::2])
        angle[:, 1::2] = np.cos(angle[:, 1::2])
        self.pos = tf.constant(angle[np.newaxis, ...], dtype=tf.float32)

    def call(self, x):
        return x + self.pos[:, :tf.shape(x)[1], :]

model = tf.keras.Sequential([
    tf.keras.layers.Embedding(10000, 512),
    PositionalEncoding(max_len=200, dim=512),
    tf.keras.layers.Dropout(0.1),
])

Transformer de Classificação de Texto

Um classificador de texto transformer do zero: embedding + encoding posicional + N blocos de encoder + global average pool + cabeça Dense. GlobalAveragePooling1D colapsa a dimensão de sequência (use um token CLS para uma agregação aprendível). mask_zero=True propaga uma máscara que MultiHeadAttention respeita — passe-a manualmente se necessário. Para NLP real, use um transformer pré-treinado (BERT, T5) do HuggingFace — treinar do zero exige dados enormes.

tensorflow
import tensorflow as tf

class TransformerEncoder(tf.keras.layers.Layer):
    def __init__(self, dim, heads, ff, num_layers, dropout=0.1, **kwargs):
        super().__init__(**kwargs)
        self.blocks = [TransformerBlock(dim, heads, ff, dropout)
                       for _ in range(num_layers)]
    def call(self, x, training=False, mask=None):
        for block in self.blocks:
            x = block(x, training=training, mask=mask)
        return x

inputs = tf.keras.Input(shape=(200,))
x = tf.keras.layers.Embedding(10000, 128, mask_zero=True)(inputs)
x = PositionalEncoding(200, 128)(x)
x = TransformerEncoder(128, 4, 512, 4)(x)
x = tf.keras.layers.GlobalAveragePooling1D()(x)
x = tf.keras.layers.Dropout(0.3)(x)
outputs = tf.keras.layers.Dense(1, activation='sigmoid')(x)
model = tf.keras.Model(inputs, outputs)

Vision Transformer (ViT)

Um Vision Transformer fatia a imagem com um Conv2d com stride (kernel=stride=patch_size), trata os patches como tokens, precede um token CLS, adiciona embeddings posicionais e roda blocos de encoder transformer. O estado oculto final do token CLS é a representação global da imagem para classificação. Para uso real, carregue um ViT pré-treinado de keras.applications ou HuggingFace — precisam de pré-treino no ImageNet-21k para funcionar bem. Patch de 16 e dim 768 são os padrões do ViT-Base.

tensorflow
import tensorflow as tf

class ViTPatchEmbed(tf.keras.layers.Layer):
    def __init__(self, patch_size=16, dim=768, **kwargs):
        super().__init__(**kwargs)
        self.proj = tf.keras.layers.Conv2D(dim, patch_size, strides=patch_size)
    def call(self, x):
        x = self.proj(x)
        shape = tf.shape(x)
        x = tf.reshape(x, [shape[0], -1, x.shape[-1]])
        return x

inputs = tf.keras.Input(shape=(224, 224, 3))
x = ViTPatchEmbed(16, 768)(inputs)
x = x + tf.Variable(tf.random.normal((1, 196, 768)))
cls = tf.Variable(tf.random.normal((1, 1, 768)))
x = tf.keras.layers.Concatenate(axis=1)([cls, x])
for _ in range(6):
    x = TransformerBlock(768, 12, 3072, 0.1)(x)
x = tf.keras.layers.Lambda(lambda t: t[:, 0])(x)
outputs = tf.keras.layers.Dense(10, activation='softmax')(x)
model = tf.keras.Model(inputs, outputs)

Decoder Transformer

Um bloco de decoder tem três subcamadas: self-attention mascarada (máscara causal, para que a posição t não veja o futuro), cross-attention (query do decoder, key/value da saída do encoder) e um FFN. Cada subcamada tem residual + LayerNorm. A cross-attention é o que deixa o decoder 'olhar para trás' na sequência fonte. Para modelos só de decoder (GPT), descarte a subcamada de cross-attention. Empilhe N blocos para um decoder completo. A inferência precisa de um loop autorregressivo alimentando os tokens previstos de volta.

tensorflow
import tensorflow as tf

class DecoderBlock(tf.keras.layers.Layer):
    def __init__(self, dim, heads, ff, dropout=0.1, **kwargs):
        super().__init__(**kwargs)
        self.self_att = tf.keras.layers.MultiHeadAttention(heads, dim // heads)
        self.cross_att = tf.keras.layers.MultiHeadAttention(heads, dim // heads)
        self.ffn = tf.keras.Sequential([
            tf.keras.layers.Dense(ff, activation='gelu'),
            tf.keras.layers.Dense(dim),
        ])
        self.norm1 = self.norm2 = self.norm3 = tf.keras.layers.LayerNormalization(epsilon=1e-6)
        self.drop = tf.keras.layers.Dropout(dropout)

    def call(self, x, enc_out, training=False, causal_mask=None, padding_mask=None):
        attn = self.self_att(x, x, x, attention_mask=causal_mask)
        x = self.norm1(x + self.drop(attn, training=training))
        cross = self.cross_att(query=x, value=enc_out, key=enc_out, attention_mask=padding_mask)
        x = self.norm2(x + self.drop(cross, training=training))
        x = self.norm3(x + self.drop(self.ffn(x), training=training))
        return x
14

TensorBoard

Setup e Callback

O callback TensorBoard transmite métricas, grafos e dados de profiling para log_dir durante o fit. histogram_freq=1 registra distribuições de pesos por época — defina 0 para economizar espaço. profile_batch=2 roda o TF Profiler naquele lote para identificar gargalos (pipeline de entrada, latência de op, memória). Use subdiretórios distintos por experimento (logs/exp1, logs/exp2), para que o TensorBoard os sobreponha — perfeito para varreduras de hiperparâmetros. Inicie com `tensorboard --logdir=logs`.

tensorflow
import tensorflow as tf

tb = tf.keras.callbacks.TensorBoard(
    log_dir='logs/experiment_1', histogram_freq=1,
    write_graph=True, profile_batch=2,
)

model.fit(train_ds, validation_data=val_ds, epochs=10, callbacks=[tb])

# launch tensorboard
# tensorboard --logdir=logs

import datetime
log_dir = 'logs/fit/' + datetime.datetime.now().strftime('%Y%m%d-%H%M%S')

Escalares Personalizados (Summary Writer)

tf.summary.create_file_writer dá um handle de baixo nível para registrar escalares personalizados em loops de treino personalizados. Use writer.as_default() e tf.summary.scalar(nome, valor, step=step) para escrever. Step precisa ser um inteiro (geralmente o contador de iterações do otimizador). Faça flush periodicamente, para que os eventos cheguem ao disco. Use namespaces (train/loss, val/loss) para organizar gráficos na UI do TensorBoard. Registre LR, normas de gradiente e qualquer métrica personalizada que você se importe.

tensorflow
import tensorflow as tf

writer = tf.summary.create_file_writer('logs/custom')

with writer.as_default():
    tf.summary.scalar('train/loss', loss, step=step)
    tf.summary.scalar('train/lr', lr, step=step)
    tf.summary.scalar('val/accuracy', acc, step=step)
    tf.summary.text('config', 'lr=1e-3, batch=32', step=0)
    writer.flush()

# in a custom training loop
for step, (x, y) in enumerate(train_ds):
    # ... train step ...
    if step % 100 == 0:
        with writer.as_default():
            tf.summary.scalar('loss', loss, step=step)

Imagens e Histogramas

tf.summary.image registra imagens para QA visual — passe forma (B, A, L, C) com B até max_outputs. Histogramas mostram distribuições de pesos e gradientes ao longo do tempo; picos súbitos sugerem instabilidade. Registre algumas amostras de validação por época para ver progresso qualitativo, não só métricas escalares. Áudio é útil para modelos de fala. Cada um dos summaries recebe um argumento step que vira o eixo x no TensorBoard. Mantenha o logging barato amostrando a cada N passos.

tensorflow
import tensorflow as tf

writer = tf.summary.create_file_writer('logs/viz')

with writer.as_default():
    tf.summary.image('sample', img[None, ...], step=step)
    tf.summary.image('batch', images[:8], step=step, max_outputs=8)
    for var in model.trainable_variables:
        tf.summary.histogram('weights/' + var.name, var, step=step)
    tf.summary.audio('waveform', audio[None, ...], sample_rate=16000, step=step)
    writer.flush()

Ajuste de Hiperparâmetros

O plugin HParams organiza varreduras de hiperparâmetros no TensorBoard — uma visão de tabela permite filtrar execuções e achar a melhor config. Defina objetos HParam com faixas/valores discretos, registre uma config uma vez com hp.hparams_config, e depois para cada execução registre hp.hparams(hparams) mais a métrica final. Para varreduras sérias, use KerasTuner (RandomSearch, Hyperband, BayesianOptimization), que automatiza a busca e integra-se ao TensorBoard.

tensorflow
import tensorflow as tf
# from tensorboard.plugins.hparams import api as hp
# (run: pip install tensorboard-plugin-hparams)

HP_LR = hp.HParam('lr', hp.RealInterval(1e-4, 1e-2))
HP_DROPOUT = hp.HParam('dropout', hp.Discrete([0.1, 0.3, 0.5]))
METRIC_ACC = 'accuracy'

with tf.summary.create_file_writer('logs/hparam_tuning').as_default():
    hp.hparams_config(hparams=[HP_LR, HP_DROPOUT], metrics=[hp.Metric(METRIC_ACC)])

for lr in [1e-3, 5e-3]:
    for dropout in [0.1, 0.3]:
        hparams = {HP_LR: lr, HP_DROPOUT: dropout}
        run_name = f"lr-{lr}-drop-{dropout}"
        with tf.summary.create_file_writer('logs/hparam_tuning/' + run_name).as_default():
            hp.hparams(hparams)
            acc = train(hparams)
            tf.summary.scalar(METRIC_ACC, acc, step=1)

Profiling de Desempenho

O TF Profiler mostra onde o tempo é gasto: por op, por device e no pipeline de entrada. profile_batch='10,20' profileia os lotes 10-20 (pule os primeiros, para que o warmup já tenha acontecido). A página Overview dá recomendações acionáveis (ex.: 'o pipeline de entrada é o gargalo'). O Memory Viewer mostra a memória de pico e que tensores dominam. O Trace Viewer é uma linha do tempo estilo Chrome para imersão. Sempre profileie no hardware alvo — gargalos de CPU vs GPU diferem.

tensorflow
import tensorflow as tf

# profile via callback
tb = tf.keras.callbacks.TensorBoard(
    log_dir='logs/profile', profile_batch='10,20',
)

# or use the Profiler API directly
tf.profiler.experimental.start('logs/profile')
# ... run a few batches ...
tf.profiler.experimental.stop()

# in TensorBoard, open the Profile tab to see:
# - op-level time breakdown
# - input pipeline analysis (tf.data bottleneck)
# - memory viewer
# - overview page with recommendations
15

Treino em GPU / TPU

Detecção e Memória de GPU

Por padrão, TF agarra toda a memória da GPU na inicialização, bloqueando outros processos. set_memory_growth(True) aloca só o necessário — essencial para compartilhar uma GPU. set_logical_device_configuration limita a memória ou divide uma GPU em múltiplos devices lógicos (útil para testar código multi-GPU numa única GPU). tf.device('/GPU:1') posiciona ops num device específico. Ops de CPU rodam em '/CPU:0'. Posicionamento de device incompatível causa cópias implícitas que prejudicam o desempenho.

tensorflow
import tensorflow as tf

gpus = tf.config.list_physical_devices('GPU')
print('GPUs:', gpus)

# set memory growth (don't grab all GPU memory at start)
for gpu in gpus:
    tf.config.experimental.set_memory_growth(gpu, True)

# or limit GPU memory explicitly
tf.config.set_logical_device_configuration(
    gpus[0],
    [tf.config.LogicalDeviceConfiguration(memory_limit=4096)],
)

with tf.device('/GPU:1'):
    x = tf.random.normal((1000, 1000))
    y = tf.matmul(x, x)

Estratégia de Distribuição

Estratégias de distribuição abstraem a topologia de devices. MirroredStrategy serve para multi-GPU numa máquina (espelha variáveis entre GPUs, all-reduce de gradientes) — o caminho multi-GPU mais fácil. MultiWorkerMirroredStrategy estende a múltiplas máquinas. TPUStrategy roda em TPUs da Google (Colab/Nuvem). Sempre crie o modelo dentro de strategy.scope(), para que as variáveis se espelhem corretamente. O mesmo código fit/predict funciona entre estratégias.

tensorflow
import tensorflow as tf

strategy = tf.distribute.OneDeviceStrategy(device='/gpu:0')
strategy = tf.distribute.MirroredStrategy()
print('num replicas:', strategy.num_replicas_in_sync)

# TPU
resolver = tf.distribute.cluster_resolver.TPUClusterResolver()
tf.config.experimental_connect_to_cluster(resolver)
tf.tpu.experimental.initialize_tpu_system(resolver)
strategy = tf.distribute.TPUStrategy(resolver)

with strategy.scope():
    model = build_model()
    model.compile(optimizer='adam', loss='...', metrics=['accuracy'])

model.fit(train_ds, epochs=10)

Treino Multi-GPU

MirroredStrategy espelha as variáveis do modelo em cada GPU e divide cada lote entre réplicas — o tamanho de lote efetivo é o global (ex.: 64 por GPU * 4 GPUs = 256). Passe o lote global ao dataset; o TF distribui os shards automaticamente. fit() cuida do all-reduce de gradientes por baixo. Para loops de treino personalizados, use strategy.experimental_distribute_dataset e strategy.run(train_step).

tensorflow
import tensorflow as tf

strategy = tf.distribute.MirroredStrategy()
print(f'using {strategy.num_replicas_in_sync} GPUs')

global_batch = 64 * strategy.num_replicas_in_sync
train_ds = make_dataset().batch(global_batch)

with strategy.scope():
    model = build_model()
    model.compile(optimizer='adam', loss='sparse_categorical_crossentropy',
                  metrics=['accuracy'])

model.fit(train_ds, epochs=10, validation_data=val_ds)

Treino em TPU (Colab)

TPUs estão disponíveis no Google Colab (Mudar tipo de runtime -> TPU) e na Google Cloud. Inicialize o sistema TPU uma vez, depois envolva a criação do modelo em strategy.scope(). TPUs são mais rápidas com tamanhos de lote grandes (1024+) e formas fixas — use drop_remainder=True no agrupamento. TPUs não leem arquivos locais diretamente; carregue os dados na memória ou transmita do GCS via tf.data. Precisão mista (bfloat16) dá grande aceleração na TPU e não precisa de escalonamento de perda.

tensorflow
import tensorflow as tf

try:
    resolver = tf.distribute.cluster_resolver.TPUClusterResolver()
    tf.config.experimental_connect_to_cluster(resolver)
    tf.tpu.experimental.initialize_tpu_system(resolver)
    strategy = tf.distribute.TPUStrategy(resolver)
    print('TPUs:', strategy.num_replicas_in_sync)
except ValueError:
    print('No TPU found')
    strategy = tf.distribute.get_strategy()

with strategy.scope():
    model = tf.keras.Sequential([
        tf.keras.layers.Dense(128, activation='relu', input_shape=(784,)),
        tf.keras.layers.Dense(10, activation='softmax'),
    ])
    model.compile(optimizer='adam', loss='sparse_categorical_crossentropy')

model.fit(x_train, y_train, batch_size=1024, epochs=5)

Precisão Mista

Precisão mista computa em float16, mas mantém cópias mestras float32, dando 2-3x de rendimento em GPUs Tensor Core (Volta+) e metade da memória. 'mixed_float16' precisa de escalonamento de perda (Keras cuida automaticamente via LossScaleOptimizer). 'mixed_bfloat16' tem o mesmo intervalo do float32, então não precisa de escalonamento, mas só GPUs Ampere+ e TPUs o suportam. Force a camada final a float32 pela estabilidade numérica (softmax/logits). Precisão mista é a vitória isolada de desempenho mais fácil.

tensorflow
import tensorflow as tf

tf.keras.mixed_precision.set_global_policy('mixed_float16')
# or bfloat16 on Ampere+ / TPU (no loss scaling needed)
tf.keras.mixed_precision.set_global_policy('mixed_bfloat16')

model = tf.keras.Sequential([
    tf.keras.layers.Dense(512, activation='relu', input_shape=(784,)),
    tf.keras.layers.Dense(10, dtype='float32'),
])

model.compile(optimizer='adam', loss='sparse_categorical_crossentropy')
print(model.layers[0].dtype_policy)   # <Policy "mixed_float16">
16

Aumento de Dados

Camadas de Pré-processamento Keras

Camadas de pré-processamento Keras (RandomFlip, RandomRotation etc.) rodam na GPU e dentro de tf.function — muito mais rápidas que augmentation PIL/numpy. Pô-las dentro do modelo significa que ficam desativadas na inferência automaticamente (training=False). Alternativamente, aplique-as num map do tf.data para mais controle. Essas camadas são sem estado e compilam por JIT, então não retardam a inferência. Para pré-processamento com estado (ex.: scalers ajustados), use a API Adapt.

tensorflow
import tensorflow as tf

augment = tf.keras.Sequential([
    tf.keras.layers.RandomFlip('horizontal'),
    tf.keras.layers.RandomRotation(0.1),
    tf.keras.layers.RandomZoom(0.1),
    tf.keras.layers.RandomContrast(0.2),
    tf.keras.layers.RandomTranslation(0.1, 0.1),
])

# put augmentation INSIDE the model (training-only, inactive at inference)
model = tf.keras.Sequential([
    tf.keras.layers.Input(shape=(224, 224, 3)),
    tf.keras.layers.Rescaling(1./255),
    augment,
    tf.keras.layers.Conv2D(32, 3, activation='relu'),
])

# or apply via dataset.map
ds = ds.map(lambda x, y: (augment(x, training=True), y))

ImageDataGenerator (Legado)

ImageDataGenerator é a API legada de augmentation — funciona, mas roda na CPU e é mais lenta que as camadas de pré-processamento do Keras. Use só quando precisar da conveniência de iteração de diretórios ou de código legado. Para projetos novos, prefira keras.utils.image_dataset_from_directory + camadas de pré-processamento Keras (RandomFlip etc.) — aceleradas por GPU e integradas ao tf.data. flow_from_directory infere rótulos de classe dos nomes de subdiretórios, como ImageFolder.

tensorflow
from tensorflow.keras.preprocessing.image import ImageDataGenerator

train_datagen = ImageDataGenerator(
    rescale=1./255, rotation_range=20,
    width_shift_range=0.2, height_shift_range=0.2,
    shear_range=0.2, zoom_range=0.2,
    horizontal_flip=True, fill_mode='nearest',
    validation_split=0.2,
)

train_gen = train_datagen.flow_from_directory(
    'data/train', target_size=(224, 224), batch_size=32,
    class_mode='binary', subset='training',
)

model.fit(train_gen, epochs=10)

Ops de Augmentation de Imagens

Ops tf.image.* dão controle fino para augmentation personalizada. random_brightness/contrast/saturation/hue mudam a cor sem mudar a geometria. Cutout e Mixup são augmentations avançadas que melhoram a regularização; implemente-as com ops tf.image + tf.tensor_scatter_nd_update. Aplique augmentation num map do tf.data com num_parallel_calls=AUTOTUNE, para que rode nos workers de CPU e nunca bloqueie a GPU. Sempre recorte de volta às faixas válidas de pixel após o jitter de cor.

tensorflow
import tensorflow as tf

def augment(image, label):
    image = tf.image.random_flip_left_right(image)
    image = tf.image.random_brightness(image, max_delta=0.2)
    image = tf.image.random_contrast(image, lower=0.8, upper=1.2)
    image = tf.image.random_saturation(image, lower=0.8, upper=1.2)
    image = tf.image.random_hue(image, max_delta=0.1)
    image = tf.clip_by_value(image, 0.0, 1.0)
    return image, label

ds = ds.map(augment, num_parallel_calls=tf.data.AUTOTUNE)

Mixup e CutMix

Mixup mistura linearmente duas imagens e seus rótulos, criando exemplos virtuais entre classes — regularização forte que reduz overfitting e melhora a calibração. CutMix cola um patch retangular de uma imagem em outra, preservando a estrutura local melhor que Mixup. Ambas exigem que a perda aceite rótulos suaves (misturados) — use categorical_crossentropy, não sparse. Aplique por lote depois do batching. Combine com augmentation geométrica padrão pelos melhores resultados.

tensorflow
import tensorflow as tf

def mixup(images, labels, alpha=0.2):
    lam = tf.random.beta([], alpha, alpha)
    batch_size = tf.shape(images)[0]
    idx = tf.random.shuffle(tf.range(batch_size))
    mixed_images = lam * images + (1 - lam) * tf.gather(images, idx)
    mixed_labels = lam * labels + (1 - lam) * tf.gather(labels, idx)
    return mixed_images, mixed_labels

ds = ds.batch(32).map(mixup, num_parallel_calls=tf.data.AUTOTUNE)

Augmentation de Texto e Tabular

Para texto, augmentations simples no nível de palavra (troca de sinônimos, deleção/troca aleatória) são baratas e eficazes; para NLP sério, use back-translation ou modelos como EDA/AugBERT. Para dados tabulares, mixup mistura linhas; ruído gaussiano em features numéricas regulariza. Sempre aplique augmentation só aos dados de treino, nunca validação/teste. Mantenha as augmentations preservando rótulos (ou misturando rótulos como mixup) — corromper rótulos prejudica mais do que ajuda.

tensorflow
import tensorflow as tf
import random

def text_augment(text):
    words = text.split()
    if random.random() < 0.2:
        words = [w for w in words if random.random() > 0.2]
    if len(words) > 1 and random.random() < 0.2:
        i, j = random.sample(range(len(words)), 2)
        words[i], words[j] = words[j], words[i]
    return ' '.join(words)

def tabular_mixup(x, y, alpha=0.2):
    lam = tf.random.beta([], alpha, alpha)
    idx = tf.random.shuffle(tf.range(tf.shape(x)[0]))
    return lam * x + (1 - lam) * tf.gather(x, idx), lam * y + (1 - lam) * tf.gather(y, idx)

def add_noise(x, std=0.01):
    return x + tf.random.normal(tf.shape(x), stddev=std)
17

Transfer Learning

Modelos Pré-treinados

keras.applications expõe ResNet, EfficientNet, MobileNet, ViT e mais, com pesos do ImageNet. include_top=False descarta a cabeça de 1000 classes, para que você possa anexar a sua. preprocess_input aplica a normalização exata que o backbone espera — chame-a dentro do modelo para implantação. Congele o backbone (trainable=False) e chame base(x, training=False), para que BatchNorm use estatísticas de inferência — crítico para datasets pequenos, onde as estatísticas de BN seriam ruidosas.

tensorflow
import tensorflow as tf

base = tf.keras.applications.ResNet50(
    include_top=False, weights='imagenet',
    input_shape=(224, 224, 3), pooling='avg',
)
base.trainable = False

inputs = tf.keras.Input(shape=(224, 224, 3))
x = tf.keras.applications.resnet50.preprocess_input(inputs)
x = base(x, training=False)
x = tf.keras.layers.Dense(256, activation='relu')(x)
x = tf.keras.layers.Dropout(0.5)(x)
outputs = tf.keras.layers.Dense(num_classes, activation='softmax')(x)
model = tf.keras.Model(inputs, outputs)

Extração de Features

A extração de features congela o backbone inteiro e treina só uma nova cabeça — a baseline de transfer learning mais rápida. Como o backbone está fixo, você pode pré-computar features uma vez (base.predict(train_ds)) e treinar um classificador minúsculo sobre elas, economizando muito computo. Defina training=False ao chamar o backbone, para que BatchNorm use estatísticas móveis — senão lotes pequenos as corrompem. Bom para datasets pequenos (centenas de imagens), onde fine-tuning sofreria overfitting.

tensorflow
import tensorflow as tf

base = tf.keras.applications.MobileNetV2(
    include_top=False, weights='imagenet', pooling='avg')
base.trainable = False

model = tf.keras.Sequential([
    tf.keras.layers.Input(shape=(224, 224, 3)),
    tf.keras.applications.mobilenet_v2.preprocess_input,
    base,
    tf.keras.layers.Dropout(0.3),
    tf.keras.layers.Dense(num_classes, activation='softmax'),
])

model.compile(optimizer=tf.keras.optimizers.Adam(1e-3),
              loss='sparse_categorical_crossentropy', metrics=['accuracy'])
model.fit(train_ds, validation_data=val_ds, epochs=5)

Fine-tuning

Fine-tuning descongela algumas camadas do backbone e as treina com um LR pequeno, para que as features pré-treinadas se adaptem à sua tarefa. Sempre faça extração de features primeiro (só cabeça) por algumas épocas, DEPOIS descongele — senão os gradientes grandes da cabeça aleatória destroem as features pré-treinadas. Use um LR muito menor (1e-5 vs 1e-3 para a cabeça). Descongele de cima para baixo (camadas posteriores são mais específicas da tarefa; iniciais são gerais). Mantenha as camadas BatchNorm congeladas, para preservar suas estatísticas móveis.

tensorflow
import tensorflow as tf

base = tf.keras.applications.ResNet50(include_top=False, weights='imagenet', pooling='avg')
base.trainable = True

# freeze everything except the last few blocks
for layer in base.layers[:-20]:
    layer.trainable = False

model.compile(
    optimizer=tf.keras.optimizers.Adam(1e-5),   # 10x smaller than head
    loss='sparse_categorical_crossentropy', metrics=['accuracy'],
)
model.fit(train_ds, validation_data=val_ds, epochs=5)

Congelando e Descongelando

Defina layer.trainable=False para congelá-la. Após mudar trainable, você PRECISA recompilar o modelo, para que o otimizador pegue o novo conjunto treinável. Mantenha as camadas BatchNorm congeladas durante o fine-tuning — suas estatísticas móveis são preciosas e lotes finos de fine-tuning as corromperiam. Inspecione trainable_weights vs weights para confirmar o que vai atualizar. Registre a contagem de parâmetros treináveis, para não congelar ou descongelar tudo acidentalmente (um bug silencioso comum).

tensorflow
import tensorflow as tf

base = tf.keras.applications.EfficientNetB0(
    include_top=False, weights='imagenet', pooling='avg')

base.trainable = False
for layer in base.layers:
    layer.trainable = 'block7' in layer.name

# freeze BatchNorm specifically (recommended during fine-tuning)
for layer in base.layers:
    if isinstance(layer, tf.keras.layers.BatchNormalization):
        layer.trainable = False

n_train = sum(tf.keras.backend.count_params(w) for w in model.trainable_weights)
n_total = sum(tf.keras.backend.count_params(w) for w in model.weights)
print(f"trainable: {n_train:,} / {n_total:,}")

Transferência Multitarefa

Aprendizado multitarefa compartilha um backbone entre tarefas relacionadas, regularizando a representação e economizando computo. Cada cabeça é um pequeno ramo das features compartilhadas. Passe perdas por saída e loss_weights no compile para equilibrar os gradientes das tarefas (ajuste os pesos para que nenhuma tarefa domine). Na hora do fit, passe os alvos como um dict casando com os nomes das saídas. Transferência multitarefa é poderosa quando você tem uma tarefa com muitos dados e outra com poucos — o backbone compartilhado beneficia ambas.

tensorflow
import tensorflow as tf

base = tf.keras.applications.ResNet50(include_top=False, weights='imagenet')
base.trainable = False

inputs = tf.keras.Input(shape=(224, 224, 3))
x = tf.keras.applications.resnet50.preprocess_input(inputs)
features = base(x, training=False)
features = tf.keras.layers.GlobalAveragePooling2D()(features)

cls_out = tf.keras.layers.Dense(num_classes, activation='softmax', name='cls')(features)
box_out = tf.keras.layers.Dense(4, name='box')(features)
attr_out = tf.keras.layers.Dense(num_attr, activation='sigmoid', name='attr')(features)

model = tf.keras.Model(inputs, [cls_out, box_out, attr_out])
model.compile(
    optimizer='adam',
    loss={'cls': 'sparse_categorical_crossentropy', 'box': 'mse',
          'attr': 'binary_crossentropy'},
    loss_weights={'cls': 1.0, 'box': 5.0, 'attr': 0.5},
)
18

Implantação de Modelo

Conversor TFLite

TFLite converte modelos TF num formato flatbuffer para dispositivos móveis, embarcados e de borda. Optimize.DEFAULT aplica quantização pós-treino automaticamente; quantização int8 completa precisa de um dataset representativo para calibrar as faixas de ativação e produz um modelo que roda em Edge TPU / microcontroladores. float16 mantém compatibilidade com GPU e é mais seguro se int8 prejudicar a acurácia. O conversor infere formas de entrada do modelo; para formas dinâmicas, fixe-as com funções concretas.

tensorflow
import tensorflow as tf

converter = tf.lite.TFLiteConverter.from_keras_model(model)
tflite_model = converter.convert()

with open('model.tflite', 'wb') as f:
    f.write(tflite_model)

# with quantization (8-bit, ~4x smaller, faster on CPU)
converter.optimizations = [tf.lite.Optimize.DEFAULT]
# float16 quantization (GPU-friendly, 2x smaller)
converter.target_spec.supported_types = [tf.float16]
# full integer quantization (needs representative dataset)
converter.representative_dataset = rep_data
converter.target_spec.supported_ops = [tf.lite.OpsSet.TFLITE_BUILTINS_INT8]
converter.inference_input_type = tf.int8
tflite_quant = converter.convert()

Interpretador TFLite

O Interpretador TFLite roda modelos .tflite em CPU, GPU, Edge TPU ou microcontroladores. allocate_tensors prepara a memória com base na forma de entrada fixa — redimensione com resize_tensor_input para formas dinâmicas. set_tensor / invoke / get_tensor é o loop de inferência. Para inferência em lote, o modelo precisa ser convertido com tamanho de lote fixo ou usar resize_tensor_input. TFLite tem bindings Python, C++, Java, Swift e JavaScript — o mesmo arquivo .tflite roda em qualquer lugar.

tensorflow
import tensorflow as tf
import numpy as np

interpreter = tf.lite.Interpreter(model_path='model.tflite')
interpreter.allocate_tensors()

input_details = interpreter.get_input_details()
output_details = interpreter.get_output_details()
print(input_details)
# [{'name': 'input', 'shape': (1, 224, 224, 3), 'dtype': tf.float32, ...}]

input_data = np.expand_dims(img, axis=0).astype(np.float32)
interpreter.set_tensor(input_details[0]['index'], input_data)
interpreter.invoke()
output = interpreter.get_tensor(output_details[0]['index'])
print(output.shape, output.argmax())

TF Serving

TF Serving hospeda SavedModels atrás de uma API gRPC/REST com versionamento, agrupamento e suporte a GPU. A estrutura de diretórios serving/1/, serving/2/ habilita trocas de modelo a quente. A imagem Docker é a implantação local mais fácil; para produção, use Vertex AI, SageMaker ou KServe. TF Serving agrupa requisições automaticamente, para maximizar a utilização da GPU. A API REST usa {instances: [...]} para entradas e retorna {predictions: [...]}; para entradas/saídas nomeadas, use o parâmetro signature_name.

tensorflow
# save model in SavedModel format with versioning
# model.export('serving/1')  # Keras 3
tf.saved_model.save(model, 'serving/1')

# run TF Serving via Docker
# docker run -p 8501:8501 --name tfserving \
#   -v $(pwd)/serving:/models/my_model \
#   -e MODEL_NAME=my_model \
#   tensorflow/serving

# query via REST
import json, requests
data = json.dumps({'instances': x_test[:3].tolist()})
resp = requests.post(
    'http://localhost:8501/v1/models/my_model:predict',
    data=data, headers={'content-type': 'application/json'})
print(resp.json()['predictions'])

Treino Ciente de Quantização

Quantization-Aware Training (QAT) insere ops de fake-quantização durante o treino, para que o modelo se adapte ao ruído de arredondamento que verá na inferência int8 — geralmente recuperando a maior parte da acurácia perdida pela quantização pós-treino. Use tfmot (tensorflow-model-optimization) para envolver um modelo treinado, fazer fine-tune por algumas épocas e depois converter para TFLite. QAT é essencial quando a quantização pós-treino int8 derruba a acurácia abaixo do seu limiar (ex.: EfficientNet, detectores de objetos). O modelo TFLite resultante roda em Edge TPU.

tensorflow
import tensorflow as tf
# (requires: pip install tensorflow-model-optimization)
import tensorflow_model_optimization as tfmot

model = tf.keras.applications.MobileNetV2(weights='imagenet')
annot_model = tfmot.quantization.keras.quantize_model(model)
annot_model.compile(optimizer='adam', loss='sparse_categorical_crossentropy')
annot_model.fit(train_ds, epochs=3)

converter = tf.lite.TFLiteConverter.from_keras_model(annot_model)
converter.optimizations = [tf.lite.Optimize.DEFAULT]
tflite_qat = converter.convert()

TF.js e Implantação de Borda

TF.js roda modelos no navegador ou Node.js. O conversor transforma SavedModel/.keras/.h5 num model.json + diretório de pesos binários. Modelos de camadas suportam a API Keras (fit, predict, até treino em tempo real); modelos de grafo são mais compatíveis, porém menos flexíveis. Inferência no navegador usa WebGL/WASM; Node.js pode usar CUDA. TF.js é ótimo para ML no cliente (sem ida e volta ao servidor, privacidade, offline). Para mobile, prefira TFLite (menor, mais rápido, aceleração de hardware).

tensorflow
# convert to TF.js format
# pip install tensorflowjs
# tensorflowjs_converter --input_format=keras model.keras tfjs_model/

# in JavaScript:
# import * as tf from '@tensorflow/tfjs';
# const model = await tf.loadLayersModel('tfjs_model/model.json');
# const out = model.predict(tf.tensor4d(img, [1, 224, 224, 3]));

# OR convert SavedModel -> TF.js
# tensorflowjs_converter \
#   --input_format=tf_saved_model \
#   --output_format=tfjs_graph_model \
#   saved_model/ tfjs_model/

# TF.js layers model: full Keras-like API in the browser
# TF.js graph model: lower-level, supports more ops

Otimização de Inferência

Para implantação de baixa latência, empilhe otimizações: pruning (zera pesos pequenos, comprime), destilação de conhecimento (treina um estudante pequeno para casar com os logits de um professor grande), quantização (int8/float16) e compilação XLA (funde ops). Cada passo tem trocas — sempre faça benchmark no hardware alvo. Destilação geralmente preserva melhor a acurácia; pruning+quantização dão as maiores reduções de tamanho. XLA (jit_compile=True) funde ops para uma aceleração gratuita de 1.2-2x em GPU/TPU.

tensorflow
import tensorflow as tf

# knowledge distillation: train a small student to mimic a large teacher
def distill_loss(teacher_logits, student_logits, temperature=3.0):
    soft_targets = tf.nn.softmax(teacher_logits / temperature)
    soft_probs = tf.nn.log_softmax(student_logits / temperature)
    return tf.reduce_mean(
        tf.keras.losses.categorical_crossentropy(soft_targets, soft_probs, from_logits=True))

# XLA compilation (faster inference)
@tf.function(jit_compile=True)
def predict(x):
    return model(x)

# stack optimizations: prune + quantize + distill + XLA
# always benchmark latency and accuracy before/after each step
19

Loop de Treino Personalizado

Loop Personalizado Básico

Um loop personalizado dá controle total: manipulação de gradiente, múltiplos modelos, objetivos personalizados. O padrão é GradientTape -> perda -> grads -> apply_gradients, envolto em @tf.function pela velocidade. Não esqueça model.losses — são as perdas de regularização adicionadas por kernel_regularizer e devem ser somadas à perda principal. Acompanhe métricas com objetos Metric com estado e reset_state() a cada época. É mais verboso que fit, mas desbloqueia qualquer coisa.

tensorflow
import tensorflow as tf

optimizer = tf.keras.optimizers.Adam(1e-3)
loss_fn = tf.keras.losses.SparseCategoricalCrossentropy(from_logits=True)

train_loss = tf.keras.metrics.Mean(name='train_loss')
train_acc = tf.keras.metrics.SparseCategoricalAccuracy(name='train_acc')

@tf.function
def train_step(x, y):
    with tf.GradientTape() as tape:
        logits = model(x, training=True)
        loss = loss_fn(y, logits)
        loss += sum(model.losses)
    grads = tape.gradient(loss, model.trainable_variables)
    optimizer.apply_gradients(zip(grads, model.trainable_variables))
    train_loss.update_state(loss)
    train_acc.update_state(y, logits)
    return loss

for epoch in range(epochs):
    for x, y in train_ds:
        train_step(x, y)
    print(f"epoch {epoch}: loss={train_loss.result():.4f} acc={train_acc.result():.4f}")
    train_loss.reset_state(); train_acc.reset_state()

Validação em Loop Personalizado

A validação espelha o treino, mas com training=False (então dropout fica desligado e BatchNorm usa estatísticas móveis) e sem tape de gradiente nem otimizador. Use objetos Metric separados para validação, para que treino e validação não se misturem. Envolva test_step em @tf.function pela velocidade. Resete todas as métricas depois de registrar cada época. Para salvar o melhor modelo, compare val_acc.result() com um recorde corrente e chame model.save() quando melhorar.

tensorflow
import tensorflow as tf

val_loss = tf.keras.metrics.Mean(name='val_loss')
val_acc = tf.keras.metrics.SparseCategoricalAccuracy(name='val_acc')

@tf.function
def test_step(x, y):
    logits = model(x, training=False)
    loss = loss_fn(y, logits)
    val_loss.update_state(loss)
    val_acc.update_state(y, logits)

for epoch in range(epochs):
    for x, y in train_ds:
        train_step(x, y)
    for x, y in val_ds:
        test_step(x, y)
    print(f"epoch {epoch}: val_loss={val_loss.result():.4f} val_acc={val_acc.result():.4f}")
    train_loss.reset_state(); train_acc.reset_state()
    val_loss.reset_state(); val_acc.reset_state()

Loop Personalizado Distribuído

Um loop personalizado distribuído usa strategy.run para rodar o passo por réplica em cada GPU e strategy.reduce para agregar a perda. Divida a perda por réplica por num_replicas_in_sync, para que o gradiente somado case com o gradiente de lote global (senão o LR efetivo é escalado pelo número de GPUs). Aplique os gradientes normalmente — a estratégia cuida do all-reduce por baixo. O mesmo padrão funciona para MultiWorkerMirroredStrategy e TPUStrategy.

tensorflow
import tensorflow as tf

strategy = tf.distribute.MirroredStrategy()

with strategy.scope():
    model = build_model()
    optimizer = tf.keras.optimizers.Adam(1e-3)
    loss_fn = tf.keras.losses.SparseCategoricalCrossentropy(from_logits=True)

train_ds_dist = strategy.experimental_distribute_dataset(train_ds)

@tf.function
def distributed_train_step(x, y):
    def step_fn(x, y):
        with tf.GradientTape() as tape:
            logits = model(x, training=True)
            loss = loss_fn(y, logits)
            loss += sum(model.losses)
            loss /= strategy.num_replicas_in_sync
        grads = tape.gradient(loss, model.trainable_variables)
        optimizer.apply_gradients(zip(grads, model.trainable_variables))
        return loss
    per_replica_loss = strategy.run(step_fn, args=(x, y))
    return strategy.reduce(tf.distribute.ReduceOp.SUM, per_replica_loss, axis=None)

for epoch in range(epochs):
    for x, y in train_ds_dist:
        distributed_train_step(x, y)

Loop de Treino GAN

GANs treinam dois modelos adversarialmente: o gerador tenta enganar o discriminador, o discriminador tenta detectar falsos. Use dois GradientTapes (um por modelo) e dois otimizadores. beta_1=0.5 (abaixo do padrão) estabiliza o treino de GANs. Treine o discriminador e o gerador a cada passo (ou alterne razões). GANs são notoriamente instáveis — monitore d_loss e g_loss, use normalização espectral e considere Wasserstein GAN com penalidade de gradiente se ocorrer colapso de modo.

tensorflow
import tensorflow as tf

generator = build_generator()
discriminator = build_discriminator()
g_opt = tf.keras.optimizers.Adam(1e-4, beta_1=0.5)
d_opt = tf.keras.optimizers.Adam(1e-4, beta_1=0.5)
bce = tf.keras.losses.BinaryCrossentropy(from_logits=True)

@tf.function
def train_gan_step(real_images):
    batch = tf.shape(real_images)[0]
    noise = tf.random.normal((batch, 100))
    with tf.GradientTape() as g_tape, tf.GradientTape() as d_tape:
        fake = generator(noise, training=True)
        real_logits = discriminator(real_images, training=True)
        fake_logits = discriminator(fake, training=True)
        d_loss = bce(tf.ones_like(real_logits), real_logits) + \
                 bce(tf.zeros_like(fake_logits), fake_logits)
        g_loss = bce(tf.ones_like(fake_logits), fake_logits)
    g_grads = g_tape.gradient(g_loss, generator.trainable_variables)
    d_grads = d_tape.gradient(d_loss, discriminator.trainable_variables)
    g_opt.apply_gradients(zip(g_grads, generator.trainable_variables))
    d_opt.apply_gradients(zip(d_grads, discriminator.trainable_variables))
    return g_loss, d_loss

Acumulação de Gradiente

Acumulação verdadeira de gradiente no TF é delicada, porque GradientTape não suporta somar grads entre chamadas facilmente — você acumularia grads em tf.Variables manualmente. A aproximação simples acima escala a perda e aplica gradientes a cada passo, o que dá efeito similar para SGD, mas não é idêntico para Adam (o otimizador vê gradientes menores e mais ruidosos). Para acumulação exata, acumule gradientes em Variáveis persistentes e aplique a cada N passos. Útil principalmente quando a memória da GPU limita o tamanho do lote.

tensorflow
import tensorflow as tf

accum_steps = 4
optimizer = tf.keras.optimizers.Adam(1e-3)

@tf.function
def accumulated_train_step(x, y):
    with tf.GradientTape() as tape:
        logits = model(x, training=True)
        loss = loss_fn(y, logits) / accum_steps
    grads = tape.gradient(loss, model.trainable_variables)
    optimizer.apply_gradients(zip(grads, model.trainable_variables))
    return loss

# simple accumulation via averaging
for batch_idx, (x, y) in enumerate(train_ds):
    accumulated_train_step(x, y)
    # equivalent effective batch = accum_steps * batch_size
    # (Adam moments are updated every step, so this is an approximation)
20

Otimização de Desempenho

tf.function

@tf.function rastreia uma função Python num grafo estático — mais rápido na GPU e exigido para distribuição. A primeira chamada por assinatura de entrada rastreia (lento); chamadas seguintes reutilizam o grafo. Evite fluxo de controle Python que dependa de VALORES de tensor (if tensor > 0: ...) dentro de tf.function — força re-rastreamento. Use tf.cond / tf.while_loop ou fluxo de controle Python que dependa só de shapes/literais Python. input_signature fixa shapes para prevenir re-rastreamento por completo. reduce_retracing=True alarga o cache.

tensorflow
import tensorflow as tf

@tf.function
def train_step(x, y):
    with tf.GradientTape() as tape:
        preds = model(x, training=True)
        loss = loss_fn(y, preds)
    grads = tape.gradient(loss, model.trainable_variables)
    optimizer.apply_gradients(zip(grads, model.trainable_variables))
    return loss

# first call traces the graph (slow), subsequent calls reuse it (fast)
train_step(x_batch, y_batch)

# experimental_relax_shapes allows retracing only when needed
@tf.function(reduce_retracing=True)
def fn(x): return model(x)

# input_signature pins the signature so no retracing
@tf.function(input_signature=[tf.TensorSpec([None, 784], tf.float32)])
def predict(x): return model(x)

Compilação XLA

XLA (Accelerated Linear Algebra) compila subgrafos em kernels fundidos, reduzindo o custo de lançamento e habilitando otimizações entre ops. jit_compile=True num tf.function aciona o XLA para aquela função. É mais eficaz para modelos pesados de computo (transformers, atenção) e menos útil para os ligados a I/O. XLA exige formas estáticas dentro de uma região compilada — formas variáveis causam recompilação. Se tiver problemas de shape, preencha até formas fixas. Sempre faça benchmark: XLA pode ocasionalmente ser mais lento para modelos pequenos.

tensorflow
import tensorflow as tf

# JIT-compile a function with XLA (fuses ops for speed)
@tf.function(jit_compile=True)
def train_step(x, y):
    with tf.GradientTape() as tape:
        loss = loss_fn(y, model(x, training=True))
    grads = tape.gradient(loss, model.trainable_variables)
    optimizer.apply_gradients(zip(grads, model.trainable_variables))
    return loss

# enable XLA globally
tf.config.optimizer.set_jit(True)

# XLA fuses element-wise ops, reduces kernel launches,
# and can give 1.5-3x speedup on GPU/TPU
# especially effective for transformer / attention heavy models

Otimização do Pipeline de Entrada

O gargalo do treino em GPU costuma ser o pipeline de entrada, não o modelo. O pipeline canônico cacheia depois de carregar, embaralha, mapeia augmentation em paralelo, agrupa e pré-carrega. interleave lê múltiplos arquivos TFRecord em paralelo, para cargas ligadas ao disco. drop_remainder=True evita um último lote de forma variável que força re-rastreamento do grafo. Use o Input Pipeline Analyzer do TF Profiler para achar seu gargalo específico. AUTOTUNE deixa o TF escolher paralelismo e tamanhos de prefetch automaticamente.

tensorflow
import tensorflow as tf

# the canonical high-performance pipeline
ds = (tf.data.Dataset.from_tensor_slices((x, y))
      .cache()                                      # cache after loading
      .shuffle(10000)
      .map(augment, num_parallel_calls=tf.data.AUTOTUNE)
      .batch(32, drop_remainder=True)
      .prefetch(tf.data.AUTOTUNE))

# parallel file reading for TFRecord
files = tf.data.Dataset.list_files('data-*.tfrecord')
ds = files.interleave(
    tf.data.TFRecordDataset,
    cycle_length=4, num_parallel_calls=tf.data.AUTOTUNE)

# options for autotuning
options = tf.data.Options()
options.autotune.enabled = True
ds = ds.with_options(options)

Precisão Mista e TF32

Precisão mista (float16/bfloat16) dá 2-3x de rendimento em GPUs Tensor Core. TF32 é ainda mais fácil — é um formato de mantissa de 19 bits usado de forma transparente para matmul em Ampere+ (A100, H100), dando ~3x de aceleração com perda mínima de precisão e SEM mudanças de código nem escalonamento de perda. Habilite ambos para velocidade máxima. TF32 está ligado por padrão no CUDA 11+, mas o TF expõe a flag para controle explícito. Para reprodutibilidade fp32 estrita (computação científica), desative o TF32.

tensorflow
import tensorflow as tf

# mixed precision (float16 compute, float32 master)
tf.keras.mixed_precision.set_global_policy('mixed_float16')

# enable TF32 on Ampere+ (big matmul speedup, slight precision loss)
tf.config.experimental.enable_tensor_float_32_execution(True)

# TF32 uses 19-bit mantissa for matmul on A100/H100
# it's transparent — no code changes, no loss scaling
# gives ~3x matmul speedup with minimal accuracy impact

# check policy
print(tf.keras.mixed_precision.global_policy())
print('TF32:', tf.config.experimental.tensor_float_32_execution_enabled())

Otimização de Grafo

Grappler é o otimizador de grafo do TF que roda automaticamente antes da execução: dobra de constantes, otimização de layout (NCHW vs NHWC para cuDNN), fusão de ops (remapeamento), eliminação de código morto e mais. Estão todas ativas por padrão — só precisa tocá-los para desativar otimizações específicas na depuração. debug_stripper remove Assert/CheckNumerics pela velocidade de produção. O otimizador de layout escolhe automaticamente NCHW para convs cuDNN na GPU, mesmo que seu modelo especifique NHWC.

tensorflow
import tensorflow as tf

# enable grappler (default graph optimizer)
tf.config.optimizer.set_jit(True)       # XLA
tf.config.optimizer.set_experimental_options({
    'disable_model_pruning': False,
    'disable_meta_optimizer': False,
    'layout_optimizer': True,           # optimize data layout (NCHW vs NHWC)
    'constant_folding': True,           # fold constants at build time
    'shape_optimization': True,
    'remapping': True,                  # fuse compatible ops
    'arithmetic_optimization': True,
    'loop_optimization': True,
    'dependency_optimization': True,
    'function_optimization': True,
    'debug_stripper': True,             # remove Assert/CheckNumerics
})

# all on by default — only set explicitly to disable specific ones

AutoGraph e Fluxo de Controle

AutoGraph converte if/for/while de Python dentro de tf.function em ops de grafo TF (tf.cond / tf.while_loop), para que rodem com eficiência na GPU. Loops sobre um tf.data.Dataset com 'for' de Python estão ok — iteram na hora do rastreamento. Evite if/for que dependa de VALORES de tensor (não shapes) — força re-rastreamento a cada mudança de valor. Para fluxo de controle em runtime sobre valores de tensor, use tf.cond e tf.while_loop explicitamente ou deixe o AutoGraph tratar (vai tratar, mas a conversão pode ser sutil).

tensorflow
import tensorflow as tf

# AutoGraph converts Python if/for/while into tf.cond / tf.while_loop
@tf.function
def fn(x):
    if x > 0:          # AutoGraph converts this
        return x * 2
    else:
        return x

@tf.function
def sum_loop(n):
    total = tf.constant(0)
    for i in tf.range(n):    # AutoGraph converts to tf.while_loop
        total += i
    return total

# Python-side (compile-time) loop vs TF-side (runtime) loop
@tf.function
def train_epoch(dataset):
    for x, y in dataset:   # Python iteration over dataset (fine)
        train_step(x, y)

# avoid data-dependent Python control flow
# if x.shape[0] > 10: ...  # OK (static shape)
# if tf.reduce_sum(x) > 0: ...  # forces retracing

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.