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 no 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:

Clique para expandir os modelos compatíveis

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 exporte checkpoints

É possível criar um job de ajuste que exporte checkpoints usando o SDK de IA generativa do Google ou o Google Cloud console.

Console

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

SDK de IA generativa do Google

(Prévia) É 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 de IA generativa do Google:

pip install --upgrade google-genai

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

Defina variáveis de ambiente para usar o SDK de IA generativa do Google com a Gemini Enterprise Agent Platform:

# 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_ENTERPRISE=True

Crie o job de ajuste:

import time

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

# 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-3.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 de IA generativa do Google.

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 Agent Platform Studio página.

    Acessar o Agent Platform 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 de IA generativa do Google 

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 de IA generativa do Google 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 valor Endpoint 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 Model Registry da Gemini Enterprise Agent Platform na página Endpoints de previsão on-line.

  1. Acesse a página Model Registry na seção "Agent Platform" no Google Cloud console.

    Acessar a página Model Registry

  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 de ajuste

SDK de IA generativa do Google 

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 os resultados da avaliação.

Testar os checkpoints

É possível conferir uma lista de checkpoints no Model Registry da Gemini Enterprise Agent Platform e testar cada um deles. Ou você pode usar o SDK de IA generativa do Google para listar e testar seus checkpoints.

Console

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

    Acessar o Agent Platform 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 de IA generativa do Google 

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 do modelo de origem. Todos os checkpoints são copiados, então é possível 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 Agent Platform Studio página.

    Acessar o Agent Platform 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 de IA generativa do Google 

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