Ajustar modelos de LLM de tradução usando ajuste supervisionado

Neste documento, descrevemos como ajustar um modelo de LLM de tradução usando o ajuste supervisionado.

Antes de começar

Antes de começar, é preciso preparar um conjunto de dados de ajuste supervisionado. Dependendo do caso de uso, há requisitos diferentes.

Modelos compatíveis

  • translation-llm-002 (só oferece suporte ao ajuste de texto)

Criar um modelo de ajuste

É possível criar um job de ajuste supervisionado usando a API REST ou o SDK de IA generativa do Google.

REST

Para criar um job de ajuste de modelo, envie uma solicitação POST usando o método tuningJobs.create. Alguns dos parâmetros não são compatíveis com todos os modelos. Inclua apenas os parâmetros aplicáveis ao modelo que você está ajustando.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto. .
  • TUNING_JOB_REGION: a região onde o job de ajuste é executado. Essa também é a região padrão para onde o modelo ajustado é transferido. Região com disponibilidade: us-central1.
  • BASE_MODEL: nome do modelo de tradução a ser ajustado. Valores aceitos: translation-llm-002.
  • TRAINING_DATASET_URI: URI do Cloud Storage do conjunto de dados de treinamento. O conjunto de dados precisa estar formatado como um arquivo JSONL. Para melhores resultados, forneça pelo menos 100 a 500 exemplos. Para mais informações, consulte Sobre conjuntos de dados de ajuste supervisionados.
  • VALIDATION_DATASET_URIOpcional: o URI do Cloud Storage do arquivo do conjunto de dados de validação.
  • TUNED_MODEL_DISPLAYNAMEOpcional: um nome de exibição para o modelo ajustado. Se não for definido, um nome aleatório será gerado.

Método HTTP e URL: 

POST https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/endpoints/ENDPOINT_ID:generateContent

Corpo JSON da solicitação:

{
  "baseModel": "BASE_MODEL",
  "supervisedTuningSpec" : {
      "trainingDatasetUri": "TRAINING_DATASET_URI",
      "validationDatasetUri": "VALIDATION_DATASET_URI",
  },
  "tunedModelDisplayName": "TUNED_MODEL_DISPLAYNAME"
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/endpoints/ENDPOINT_ID:generateContent"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/endpoints/ENDPOINT_ID:generateContent" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a seguinte.

Exemplo de comando curl

PROJECT_ID=myproject
LOCATION=us-central1
curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
"https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/tuningJobs" \
-d \
$'{
   "baseModel": "translation-llm-002",
   "supervisedTuningSpec" : {
      "training_dataset_uri": "gs://cloud-samples-data/ai-platform/generative_ai/gemini-2_0/text/sft_train_data.jsonl",
      "validation_dataset_uri": "gs://cloud-samples-data/ai-platform/generative_ai/gemini-2_0/text/sft_validation_data.jsonl"
   },
   "tunedModelDisplayName": "tuned_translation_llm"
}'

Python 

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",
        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'

Confira uma lista de jobs de ajuste

É possível visualizar uma lista de jobs de ajuste no projeto atual usando o console do Cloud de Confiance , o SDK de IA Generativa do Google ou enviando uma solicitação GET usando o método tuningJobs.

REST

Para consultar uma lista de jobs de ajuste de modelos, envie uma solicitação GET usando o método tuningJobs.list.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • TUNING_JOB_REGION: a região onde o job de ajuste é executado. Essa também é a região padrão para onde o modelo ajustado é transferido.

Método HTTP e URL: 

GET https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/endpoints/ENDPOINT_ID:generateContent

Para enviar a solicitação, escolha uma destas opções:

curl

Execute o seguinte comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/endpoints/ENDPOINT_ID:generateContent"

PowerShell

execute o seguinte comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/endpoints/ENDPOINT_ID:generateContent" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a seguinte.

Python 

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

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

responses = client.tunings.list()
for response in responses:
    print(response.name)
    # Example response:
    # projects/123456789012/locations/us-central1/tuningJobs/123456789012345

Console

Para conferir os jobs de ajuste no console do Cloud de Confiance , acesse a página Agent Studio.

Acesse o Agent Studio

Os jobs de ajuste do LLM de tradução estão listados na tabela na seção Modelos ajustados do LLM de tradução.

Detalhes de um job de ajuste

É possível receber os detalhes de um job de ajuste no projeto atual usando o console do Cloud de Confiance , o SDK de IA Generativa do Google ou enviando uma solicitação GET com o método tuningJobs.

REST

Para visualizar uma lista de jobs de ajuste de modelos, envie uma solicitação GET usando o método tuningJobs.get e especifique o TuningJob_ID.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • TUNING_JOB_REGION: a região onde o job de ajuste é executado. Essa também é a região padrão para onde o modelo ajustado é transferido.
  • TUNING_JOB_ID: o ID do job de ajuste.

Método HTTP e URL: 

GET https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/endpoints/ENDPOINT_ID:generateContent

Para enviar a solicitação, escolha uma destas opções:

curl

Execute o seguinte comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/endpoints/ENDPOINT_ID:generateContent"

PowerShell

execute o seguinte comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/endpoints/ENDPOINT_ID:generateContent" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a seguinte.

Python 

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)

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

Console

  1. Para conferir os detalhes de um modelo ajustado no console do Cloud de Confiance , acesse a página do Agent Studio.

    Acesse o Agent Studio

  2. Na tabela Modelos ajustados do LLM de tradução, encontre seu modelo e clique em Detalhes.

    Os detalhes do seu modelo serão mostrados.

Cancelar um job de ajuste

É possível cancelar um job de ajuste no projeto atual usando o console do Cloud de Confiance , o SDK de IA Generativa do Google ou enviando uma solicitação POST com o método tuningJobs.

REST

Para visualizar uma lista de jobs de ajuste de modelos, envie uma solicitação GET usando o método tuningJobs.cancel e especifique o TuningJob_ID.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • TUNING_JOB_REGION: a região onde o job de ajuste é executado. Essa também é a região padrão para onde o modelo ajustado é transferido.
  • TUNING_JOB_ID: o ID do job de ajuste.

Método HTTP e URL: 

POST https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/endpoints/ENDPOINT_ID:generateContent

Para enviar a solicitação, escolha uma destas opções:

curl

Execute o seguinte comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/endpoints/ENDPOINT_ID:generateContent"

PowerShell

execute o seguinte comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/endpoints/ENDPOINT_ID:generateContent" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a seguinte.

Python 


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


def cancel_tuning_job(tuning_job_name: str) -> None:
    client = genai.Client(http_options=HttpOptions(api_version="v1"))

    # Cancel the tuning job.
    # Eg. tuning_job_name = "projects/123456789012/locations/us-central1/tuningJobs/123456789012345"
    client.tunings.cancel(name=tuning_job_name)

Console

  1. Para cancelar um job de ajuste no console do Cloud de Confiance , acesse a página do Agent Studio.

    Acesse o Agent Studio

  2. Na tabela Modelos ajustados de tradução, clique em Gerenciar execução.

  3. Clique em Cancelar.

Testar o modelo ajustado com um comando

É possível testar um job de ajuste no projeto atual usando o SDK de IA Generativa do Google ou enviando uma solicitação POST com o método tuningJobs.

O exemplo a seguir solicita um modelo com a pergunta "Por que o céu é azul?".

REST

Para testar um modelo ajustado com um comando, envie uma solicitação POST e especifique o TUNED_ENDPOINT_ID.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: .
  • TUNING_JOB_REGION: a região onde o job de ajuste é executado. Essa também é a região padrão para onde o modelo ajustado é transferido.
  • ENDPOINT_ID: o ID do endpoint do modelo ajustado da API GET.

Método HTTP e URL: 

POST https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/endpoints/ENDPOINT_ID:generateContent

Corpo JSON da solicitação:

{
    "contents": [
        {
            "role": "USER",
            "parts": {
                "text" : "English: Hello. Spanish:"
            }
        }
    ],
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/endpoints/ENDPOINT_ID:generateContent"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/endpoints/ENDPOINT_ID:generateContent" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a seguinte.

Python 

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 tuned endpoint.
response = client.models.generate_content(
    model=tuning_job.tuned_model.endpoint,
    contents=contents,
)
print(response.text)
# Example response:
# The sky is blue because ...

Métricas de ajuste e validação

É possível configurar um job de ajuste de modelo para coletar e relatar o ajuste e métricas de avaliação do modelo, que podem ser visualizadas no Agent Studio.

  1. Para conferir os detalhes de um modelo ajustado no console do Cloud de Confiance , acesse a página do Agent Studio.

    Acesse o Agent Studio

  2. Na tabela Ajustar e destilar, clique no nome do modelo ajustado. que você quer conferir.

    As métricas de ajuste aparecem na guia Monitor.

Métricas de ajuste de modelos

O job de ajuste de modelo coleta automaticamente as seguintes métricas de ajuste para translation-llm-002.

  • /train_total_loss: perda do conjunto de dados de ajuste em uma etapa de treinamento.
  • /train_fraction_of_correct_next_step_preds: a precisão do token em uma etapa de treinamento. Uma única inferência consiste em uma sequência de tokens previstos. Mede a precisão dos tokens previstos quando comparados às informações empíricas no conjunto de dados de ajuste.
  • /train_num_predictions: Número de tokens previstos em uma etapa de treinamento.

Métricas de validação do modelo:

É possível configurar um job de ajuste de modelos para coletar as seguintes métricas de validação para translation-llm-002.

  • /eval_total_loss: perda do conjunto de dados em uma etapa de validação.
  • /eval_fraction_of_correct_next_step_preds: a acurácia do token em uma etapa de validação. Uma única inferência consiste em uma sequência de tokens previstos. Mede a acurácia dos tokens previstos quando comparados às informações empíricas no conjunto de dados de avaliação.
  • /eval_num_predictions Número de tokens previstos em uma etapa de validação.

As visualizações de métricas ficam disponíveis após o início da execução do job de ajuste. Ele será atualizado em tempo real conforme o ajuste avança. Se você não especificar um conjunto de dados de validação ao criar o job de ajuste, apenas as visualizações das métricas de ajuste estarão disponíveis.

A seguir