Usar pontos de verificação no ajuste de modelos do Gemini

Um checkpoint é um snapshot do estado de um modelo em um ponto específico do processo de ajuste. É possível usar checkpoints intermediários em ajuste de modelos do Gemini para fazer o seguinte:

  • Salvar o progresso do ajuste.
  • Comparar a performance de checkpoints intermediários.
  • Selecionar o checkpoint de melhor performance antes do overfitting para ser o checkpoint padrão.

Para jobs de ajuste com menos de 10 épocas, um checkpoint é salvo aproximadamente após cada época. Para jobs de ajuste com mais de 10 épocas, cerca de 10 checkpoints são salvos em distribuição uniforme, com exceção do checkpoint final, que é salvo imediatamente após o treinamento de todas as épocas.

Os checkpoints intermediários são implantados em novos endpoints sequencialmente à medida que o ajuste avança. O endpoint do modelo ajustado representa o endpoint do checkpoint padrão, e os checkpoints do modelo ajustado incluem todos os checkpoints e os endpoints correspondentes.

Modelos compatíveis

Os seguintes modelos do Gemini são compatíveis com checkpoints:

Para informações detalhadas sobre as versões do modelo do Gemini, consulte Modelos do Google e Versões e ciclo de vida do modelo.

Criar um job de ajuste que exporta checkpoints

É possível criar um job de ajuste que exporta checkpoints usando o SDK do Google Gen AI ou o Google Cloud console.

Console

Para criar um job de ajuste que exporta checkpoints, acesse a Vertex AI Studio página e selecione a guia Ajuste. Para mais informações, consulte Ajustar um modelo.

SDK do Google Gen AI

(Visualização) É possível configurar o serviço de avaliação de IA generativa para executar avaliações automaticamente após cada checkpoint. Essa configuração de avaliação está disponível na região us-central1.

Instale o SDK do Google Gen AI:

pip install --upgrade google-genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK do Gen AI com a Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True

Crie o job de ajuste:

import time

from google import genai
from google.genai.types import HttpOptions, CreateTuningJobConfig, TuningDataset, EvaluationConfig, OutputConfig, GcsDestination, Metric

# TODO(developer): Update and un-comment below line
# output_gcs_uri = "gs://your-bucket/your-prefix"

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))

training_dataset = TuningDataset(
    gcs_uri="gs://cloud-samples-data/ai-platform/generative_ai/gemini/text/sft_train_data.jsonl",
)
validation_dataset = TuningDataset(
    gcs_uri="gs://cloud-samples-data/ai-platform/generative_ai/gemini/text/sft_validation_data.jsonl",
)

evaluation_config = EvaluationConfig(
    metrics=[
        Metric(
            name="FLUENCY",
            prompt_template="""Evaluate this {prediction}"""
        )
    ],
    output_config=OutputConfig(
        gcs_destination=GcsDestination(
            output_uri_prefix=output_gcs_uri,
        )
    ),
)

tuning_job = client.tunings.tune(
    base_model="gemini-2.5-flash",
    training_dataset=training_dataset,
    config=CreateTuningJobConfig(
        tuned_model_display_name="Example tuning job",
        # Set to True to disable tuning intermediate checkpoints. Default is False.
        export_last_checkpoint_only=False,
        validation_dataset=validation_dataset,
        evaluation_config=evaluation_config,
    ),
)

running_states = set([
    "JOB_STATE_PENDING",
    "JOB_STATE_RUNNING",
])

while tuning_job.state in running_states:
    print(tuning_job.state)
    tuning_job = client.tunings.get(name=tuning_job.name)
    time.sleep(60)

print(tuning_job.tuned_model.model)
print(tuning_job.tuned_model.endpoint)
print(tuning_job.experiment)
# Example response:
# projects/123456789012/locations/us-central1/models/1234567890@1
# projects/123456789012/locations/us-central1/endpoints/123456789012345
# projects/123456789012/locations/us-central1/metadataStores/default/contexts/tuning-experiment-2025010112345678

if tuning_job.tuned_model.checkpoints:
    for i, checkpoint in enumerate(tuning_job.tuned_model.checkpoints):
        print(f"Checkpoint {i + 1}: ", checkpoint)
    # Example response:
    # Checkpoint 1:  checkpoint_id='1' epoch=1 step=10 endpoint='projects/123456789012/locations/us-central1/endpoints/123456789000000'
    # Checkpoint 2:  checkpoint_id='2' epoch=2 step=20 endpoint='projects/123456789012/locations/us-central1/endpoints/123456789012345'

Listar os checkpoints de um job de ajuste

É possível conferir os checkpoints do job de ajuste concluído no Google Cloud console ou listá-los usando o SDK do Google Gen AI.

Se os checkpoints intermediários estiverem desativados, apenas o checkpoint final será mostrado ou retornado.

Console

  1. Para localizar o modelo ajustado no Google Cloud console, acesse a página Vertex AI Studio.

    Acessar o Vertex AI Studio

  2. Na guia Ajuste, encontre seu modelo e clique em Monitorar.

    As métricas de ajuste e os checkpoints do modelo são mostrados. Em cada gráfico de métricas, os números de checkpoint são mostrados como anotações da seguinte maneira:

    • Para cada época, você verá um número de etapa e um número de época.
    • O número da etapa é a etapa exata em que um checkpoint é salvo.
    • O número da época é um número estimado da época a que o checkpoint pertence, exceto para o checkpoint final de um job de ajuste concluído, que tem o número exato da época.

SDK do Google Gen AI 

from google import genai
from google.genai.types import HttpOptions

client = genai.Client(http_options=HttpOptions(api_version="v1"))

# Get the tuning job and the tuned model.
# Eg. tuning_job_name = "projects/123456789012/locations/us-central1/tuningJobs/123456789012345"
tuning_job = client.tunings.get(name=tuning_job_name)

if tuning_job.tuned_model.checkpoints:
    for i, checkpoint in enumerate(tuning_job.tuned_model.checkpoints):
        print(f"Checkpoint {i + 1}: ", checkpoint)
# Example response:
# Checkpoint 1:  checkpoint_id='1' epoch=1 step=10 endpoint='projects/123456789012/locations/us-central1/endpoints/123456789000000'
# Checkpoint 2:  checkpoint_id='2' epoch=2 step=20 endpoint='projects/123456789012/locations/us-central1/endpoints/123456789012345'

Conferir detalhes e checkpoints do modelo

É possível conferir o modelo ajustado no Google Cloud console ou usar o SDK do Google Gen AI para receber detalhes do modelo, incluindo endpoints e checkpoints.

O campo Endpoint do modelo é atualizado da seguinte maneira:

  • Ele é atualizado com base no checkpoint padrão e representa o endpoint que o job de ajuste criou para o checkpoint padrão atualizado durante o ajuste.
  • Se um modelo não estiver presente ou se o job de ajuste não conseguir um modelo, o Endpoint valor estará vazio.

  • Se o checkpoint padrão não for implantado (porque o ajuste ainda está em andamento ou porque a implantação falhou), o valor Endpoint estará vazio.

Console

É possível conferir o modelo ajustado no Registro de modelos da Vertex AI na página Endpoints de previsão on-line.

  1. Acesse a página Registro do modelo na seção "Vertex AI" do Google Cloud console.

    Acessar a página "Modelo de registro"

  2. Clique no nome do modelo.

    A versão padrão do modelo aparece.

  3. Clique na guia Detalhes da versão para conferir informações sobre a versão do modelo.

    O objetivo é Large model, o tipo de modelo é Foundation e a origem é Vertex AI Studio tuning.

  4. Clique na guia Implantar e testar para conferir o endpoint em que o modelo está implantado.

  5. Clique no nome do endpoint para acessar a página Endpoint e conferir a lista de checkpoints implantados no endpoint. Para cada checkpoint, o ID da versão do modelo e o ID do checkpoint são mostrados. O checkpoint padrão é indicado pela palavra default ao lado do ID do checkpoint.

Como alternativa, os checkpoints também podem ser conferidos na página Detalhes do job de ajuste. Para acessar essa página, acesse a página Ajuste e clique em um dos jobs de ajuste.

Acessar a página "Ajuste"

SDK do Google Gen AI 

from google import genai
from google.genai.types import HttpOptions

client = genai.Client(http_options=HttpOptions(api_version="v1"))

# Get the tuning job and the tuned model.
# Eg. tuning_job_name = "projects/123456789012/locations/us-central1/tuningJobs/123456789012345"
tuning_job = client.tunings.get(name=tuning_job_name)
tuned_model = client.models.get(model=tuning_job.tuned_model.model)
print(tuned_model)
# Example response:
# Model(name='projects/123456789012/locations/us-central1/models/1234567890@1', ...)

print(f"Default checkpoint: {tuned_model.default_checkpoint_id}")
# Example response:
# Default checkpoint: 2

if tuned_model.checkpoints:
    for _, checkpoint in enumerate(tuned_model.checkpoints):
        print(f"Checkpoint {checkpoint.checkpoint_id}: ", checkpoint)
# Example response:
# Checkpoint 1:  checkpoint_id='1' epoch=1 step=10
# Checkpoint 2:  checkpoint_id='2' epoch=2 step=20

Se você configurou o serviço de avaliação de IA generativa para executar avaliações após cada checkpoint, confira o bucket do Cloud Storage configurado para resultados de avaliação.

Testar os checkpoints

É possível conferir uma lista de checkpoints no Registro de modelos da Vertex AI e testar cada um deles. Ou você pode usar o SDK do Google Gen AI para listar e testar seus checkpoints.

Console

  1. Para localizar o modelo ajustado no Google Cloud console, acesse a página Vertex AI Studio.

    Acessar o Vertex AI Studio

  2. Na guia Ajuste, encontre seu modelo e clique em Monitorar.

  3. Na tabela de checkpoints no painel Monitorar, ao lado do checkpoint desejado, clique no link Testar.

SDK do Google Gen AI 

from google import genai
from google.genai.types import HttpOptions

client = genai.Client(http_options=HttpOptions(api_version="v1"))

# Get the tuning job and the tuned model.
# Eg. tuning_job_name = "projects/123456789012/locations/us-central1/tuningJobs/123456789012345"
tuning_job = client.tunings.get(name=tuning_job_name)

contents = "Why is the sky blue?"

# Predicts with the default checkpoint.
response = client.models.generate_content(
    model=tuning_job.tuned_model.endpoint,
    contents=contents,
)
print(response.text)
# Example response:
# The sky is blue because ...

# Predicts with Checkpoint 1.
checkpoint1_response = client.models.generate_content(
    model=tuning_job.tuned_model.checkpoints[0].endpoint,
    contents=contents,
)
print(checkpoint1_response.text)
# Example response:
# The sky is blue because ...

# Predicts with Checkpoint 2.
checkpoint2_response = client.models.generate_content(
    model=tuning_job.tuned_model.checkpoints[1].endpoint,
    contents=contents,
)
print(checkpoint2_response.text)
# Example response:
# The sky is blue because ...

Selecionar um novo checkpoint padrão

É possível usar o checkpoint padrão para representar o checkpoint de melhor performance. Por padrão, o checkpoint padrão é o checkpoint final de um job de ajuste.

Ao implantar um modelo com checkpoints, o checkpoint padrão é implantado.

Ao copiar um modelo com checkpoints, o modelo de destino terá o mesmo ID de checkpoint padrão que o modelo de origem. Todos os checkpoints são copiados, então você pode selecionar um novo checkpoint padrão para o modelo de destino.

O endpoint do job de ajuste será atualizado se você atualizar um checkpoint padrão, e será possível usar o novo endpoint para inferência.

Console

  1. Para localizar o modelo ajustado no Google Cloud console, acesse a página Vertex AI Studio.

    Acessar o Vertex AI Studio

  2. Na guia Ajuste, encontre seu modelo e clique em Monitorar.

  3. Na tabela de checkpoints no painel Monitorar, ao lado do checkpoint desejado, clique em Ações e selecione Definir como padrão.

  4. Clique em Confirmar.

    Os gráficos de métricas e a tabela de checkpoints são atualizados para mostrar o novo checkpoint padrão. O endpoint na página de detalhes do TuningJob é atualizado para mostrar o endpoint do novo checkpoint padrão.

SDK do Google Gen AI 

from google import genai
from google.genai.types import HttpOptions, UpdateModelConfig

client = genai.Client(http_options=HttpOptions(api_version="v1"))

# Get the tuning job and the tuned model.
# Eg. tuning_job_name = "projects/123456789012/locations/us-central1/tuningJobs/123456789012345"
tuning_job = client.tunings.get(name=tuning_job_name)
tuned_model = client.models.get(model=tuning_job.tuned_model.model)

print(f"Default checkpoint: {tuned_model.default_checkpoint_id}")
print(f"Tuned model endpoint: {tuning_job.tuned_model.endpoint}")
# Example response:
# Default checkpoint: 2
# projects/123456789012/locations/us-central1/endpoints/123456789012345

# Set a new default checkpoint.
# Eg. checkpoint_id = "1"
tuned_model = client.models.update(
    model=tuned_model.name,
    config=UpdateModelConfig(default_checkpoint_id=checkpoint_id),
)

print(f"Default checkpoint: {tuned_model.default_checkpoint_id}")
print(f"Tuned model endpoint: {tuning_job.tuned_model.endpoint}")
# Example response:
# Default checkpoint: 1
# projects/123456789012/locations/us-central1/endpoints/123456789000000

A seguir