API Tuning

O ajuste de modelos é um processo crucial na adaptação do Gemini para realizar tarefas específicas com maior precisão e exatidão. A otimização de modelos funciona fornecendo a um modelo um conjunto de dados de preparação que contém um conjunto de exemplos de tarefas específicas a jusante.

Use a API de ajuste do Gemini para os seguintes exemplos de utilização:

Modelos suportados:

Pode usar o ajuste fino supervisionado nos seguintes modelos Gemini:

O MDI/CE de tradução V2 (translation-llm-002) também é suportado.

Sintaxe de exemplo

Sintaxe para ajustar um modelo.

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \

https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs \
-d '{
  "baseModel": "...",
  "supervisedTuningSpec" : {
    ...
      "hyper_parameters": {
        ...
      },
  },
  "tunedModelDisplayName": "",
}'

Lista de parâmetros

Consulte exemplos para ver detalhes de implementação.

Corpo do pedido

O corpo do pedido contém dados com os seguintes parâmetros:

Parâmetros

source_model

Opcional: string

Nome do modelo base que está a ser otimizado.

tunedModelDisplayName

string

O nome a apresentar do TunedModel. O nome pode ter até 128 carateres e pode consistir em quaisquer carateres UTF-8.

supervisedTuningSpec

Parâmetros

training_dataset

string

URI do Cloud Storage do conjunto de dados de preparação. O conjunto de dados tem de estar formatado como um ficheiro JSONL. Para ter os melhores resultados, forneça, pelo menos, 100 a 500 exemplos. Para mais informações, consulte o artigo Acerca dos conjuntos de dados de ajuste supervisionados.

validation_dataset

Opcional: string

URI do Cloud Storage do conjunto de dados de validação. O conjunto de dados tem de estar formatado como um ficheiro JSONL. Um conjunto de dados pode conter até 256 exemplos. Se facultar este ficheiro, os dados são usados para gerar métricas de validação periodicamente durante o ajuste preciso. Para mais informações, consulte o artigo Acerca dos conjuntos de dados de ajuste supervisionados .

epoch_count

Opcional: int

O número de passes completos que o modelo faz em todo o conjunto de dados de preparação durante a preparação. O Vertex AI ajusta automaticamente o valor predefinido ao tamanho do conjunto de dados de preparação. Este valor baseia-se nos resultados dos testes de referência para otimizar a qualidade do resultado do modelo.

learning_rate_multiplier

Opcional: float

Multiplicador para ajustar a taxa de aprendizagem predefinida.

adapter_size

Opcional: AdapterSize

Tamanho do adaptador para a otimização.

tuned_model_display_name

Opcional: string

Nome a apresentar de TunedModel. O nome pode ter até 128 carateres e pode consistir em quaisquer carateres UTF-8.

AdapterSize

Tamanho do adaptador para a tarefa de ajuste.

Parâmetros

ADAPTER_SIZE_UNSPECIFIED

Tamanho do adaptador não especificado.

ADAPTER_SIZE_ONE

Tamanho do adaptador 1.

ADAPTER_SIZE_FOUR

Tamanho do adaptador 4.

ADAPTER_SIZE_EIGHT

Adaptador de tamanho 8.

ADAPTER_SIZE_SIXTEEN

Adaptador de tamanho 16.

Exemplos

Crie uma tarefa de ajuste supervisionada

Pode criar uma tarefa de ajuste fino de modelo de texto supervisionado através do SDK do Vertex AI para Python ou enviando um pedido POST.

Exemplo de utilização básico

O exemplo de utilização básico apenas define valores para baseModel e training_dataset_uri. Todos os outros parâmetros usam os valores predefinidos.

REST

Para criar uma tarefa de ajuste de modelos, envie um pedido POST através do método tuningJobs.create. Tenha em atenção que alguns dos parâmetros não são suportados por todos os modelos. Certifique-se de que inclui apenas os parâmetros aplicáveis para o modelo que está a ajustar.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o seu ID do projeto.
  • TUNING_JOB_REGION: a região onde a tarefa de otimização é executada. Esta é também a região predefinida para onde o modelo otimizado é carregado.
  • BASE_MODEL: nome do modelo base a otimizar.
  • TRAINING_DATASET_URI: URI do Cloud Storage do seu conjunto de dados de preparação. O conjunto de dados tem de estar formatado como um ficheiro JSONL. Para ter os melhores resultados, forneça, pelo menos, 100 a 500 exemplos. Para mais informações, consulte o artigo Acerca dos conjuntos de dados de ajuste supervisionados .

Método HTTP e URL:

POST https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs

Corpo JSON do pedido:

{
  "baseModel": "BASE_MODEL",
  "supervisedTuningSpec" : {
      "training_dataset_uri": "TRAINING_DATASET_URI"
  },
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

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/tuningJobs"

PowerShell

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

$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/tuningJobs" | Select-Object -Expand Content

Deve receber uma resposta JSON semelhante à seguinte.

Python


import time

import vertexai
from vertexai.tuning import sft

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

sft_tuning_job = sft.train(
    source_model="gemini-2.0-flash-001",
    # 1.5 and 2.0 models use the same JSONL format
    train_dataset="gs://cloud-samples-data/ai-platform/generative_ai/gemini-1_5/text/sft_train_data.jsonl",
)

# Polling for job completion
while not sft_tuning_job.has_ended:
    time.sleep(60)
    sft_tuning_job.refresh()

print(sft_tuning_job.tuned_model_name)
print(sft_tuning_job.tuned_model_endpoint_name)
print(sft_tuning_job.experiment)
# Example response:
# projects/123456789012/locations/us-central1/models/1234567890@1
# projects/123456789012/locations/us-central1/endpoints/123456789012345
# <google.cloud.aiplatform.metadata.experiment_resources.Experiment object at 0x7b5b4ae07af0>

Exemplo de utilização avançado

O exemplo de utilização avançado baseia-se no exemplo de utilização básico, mas também define valores para parâmetros opcionaishyper_parameters, como epoch_count, learning_rate_multiplier e adapter_size.

REST

Para criar uma tarefa de ajuste de modelos, envie um pedido POST através do método tuningJobs.create. Tenha em atenção que alguns dos parâmetros não são suportados por todos os modelos. Certifique-se de que inclui apenas os parâmetros aplicáveis para o modelo que está a ajustar.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu projeto.
  • TUNING_JOB_REGION: a região onde a tarefa de otimização é executada. Esta é também a região predefinida para onde o modelo otimizado é carregado.
  • BASE_MODEL: nome do modelo base a otimizar.
  • TRAINING_DATASET_URI: URI do Cloud Storage do seu conjunto de dados de preparação. O conjunto de dados tem de estar formatado como um ficheiro JSONL. Para ter os melhores resultados, forneça, pelo menos, 100 a 500 exemplos. Para mais informações, consulte o artigo Acerca dos conjuntos de dados de ajuste supervisionados .
  • VALIDATION_DATASET_URIOpcional: o URI do Cloud Storage do ficheiro do conjunto de dados de validação.
  • EPOCH_COUNTOpcional: o número de passes completos que o modelo faz em todo o conjunto de dados de preparação durante a preparação. Deixe-o não definido para usar o valor recomendado pré-preenchido.
  • ADAPTER_SIZEOpcional: o tamanho do adaptador a usar para a tarefa de otimização. O tamanho do adaptador influencia o número de parâmetros treináveis para a tarefa de ajuste. Um tamanho do adaptador maior implica que o modelo pode aprender tarefas mais complexas, mas requer um conjunto de dados de preparação maior e tempos de preparação mais longos.
  • LEARNING_RATE_MULTIPLIER: opcional: um multiplicador a aplicar à taxa de aprendizagem recomendada. Deixe-o não definido para usar o valor recomendado.
  • EXPORT_LAST_CHECKPOINT_ONLYOpcional: defina como true para usar apenas o ponto de verificação mais recente.
  • METRIC_SPECOpcional: uma ou mais especificações de métricas que está a usar para executar uma avaliação com o serviço de avaliação de IA gen. Pode usar as seguintes especificações de métricas: "pointwise_metric_spec", "pairwise_metric_spec", "exact_match_spec", "bleu_spec" e "rouge_spec".
  • METRIC_SPEC_FIELD_NAMEOpcional: os campos obrigatórios para a especificação da métrica escolhida. Por exemplo, "metric_prompt_template"
  • METRIC_SPEC_FIELD_NAME_CONTENTOpcional: o conteúdo do campo para a especificação da métrica escolhida. Por exemplo, pode usar o seguinte conteúdo do campo para uma avaliação ponto a ponto: "Evaluate the fluency of this sentence: {response}. Give score from 0 to 1. 0 - not fluent at all. 1 - very fluent."
  • CLOUD_STORAGE_BUCKETOpcional: o contentor do Cloud Storage para armazenar os resultados de uma execução de avaliação do serviço de avaliação de IA gen.
  • TUNED_MODEL_DISPLAYNAMEOpcional: um nome a apresentar para o modelo otimizado. Se não for definido, é gerado um nome aleatório.
  • KMS_KEY_NAMEOpcional: o identificador do recurso do Cloud KMS da chave de encriptação gerida pelo cliente usada para proteger um recurso. A chave tem o formato: projects/my-project/locations/my-region/keyRings/my-kr/cryptoKeys/my-key. A chave tem de estar na mesma região onde o recurso de computação é criado. Para mais informações, consulte o artigo Chaves de encriptação geridas pelo cliente (CMEK).
  • SERVICE_ACCOUNTOpcional: a conta de serviço na qual a carga de trabalho tuningJob é executada. Se não for especificado, é usado o agente do serviço de ajuste preciso seguro do Vertex AI no projeto. Consulte o artigo Agente do serviço de otimização. Se planeia usar uma conta de serviço gerida pelo cliente, tem de conceder a função roles/aiplatform.tuningServiceAgent à conta de serviço. Conceda também a função Agente do serviço de ajuste roles/iam.serviceAccountTokenCreator à conta de serviço gerida pelo cliente.

Método HTTP e URL:

POST https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs

Corpo JSON do pedido:

{
  "baseModel": "BASE_MODEL",
  "supervisedTuningSpec" : {
      "trainingDatasetUri": "TRAINING_DATASET_URI",
      "validationDatasetUri": "VALIDATION_DATASET_URI",
      "hyperParameters": {
          "epochCount": "EPOCH_COUNT",
          "adapterSize": "ADAPTER_SIZE",
          "learningRateMultiplier": "LEARNING_RATE_MULTIPLIER"
      },
      "exportLastCheckpointOnly": EXPORT_LAST_CHECKPOINT_ONLY,
      "evaluationConfig": {
          "metrics": [
              {
                  "aggregation_metrics": ["AVERAGE", "STANDARD_DEVIATION"],
                  "METRIC_SPEC": {
                      "METRIC_SPEC_FIELD_NAME":
                          METRIC_SPEC_FIELD_CONTENT
                  }
              },
          ],
          "outputConfig": {
              "gcs_destination": {
                  "output_uri_prefix": "CLOUD_STORAGE_BUCKET"
              }
          },
      },
  },
  "tunedModelDisplayName": "TUNED_MODEL_DISPLAYNAME",
  "encryptionSpec": {
    "kmsKeyName": "KMS_KEY_NAME"
  },
  "serviceAccount": "SERVICE_ACCOUNT"
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

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/tuningJobs"

PowerShell

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

$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/tuningJobs" | Select-Object -Expand Content

Deve receber uma resposta JSON semelhante à seguinte.

Python


import time

import vertexai
from vertexai.tuning import sft

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Initialize Vertex AI with your service account for BYOSA (Bring Your Own Service Account).
# Uncomment the following and replace "your-service-account"
# vertexai.init(service_account="your-service-account")

# Initialize Vertex AI with your CMEK (Customer-Managed Encryption Key).
# Un-comment the following line and replace "your-kms-key"
# vertexai.init(encryption_spec_key_name="your-kms-key")

sft_tuning_job = sft.train(
    source_model="gemini-2.0-flash-001",
    # 1.5 and 2.0 models use the same JSONL format
    train_dataset="gs://cloud-samples-data/ai-platform/generative_ai/gemini-1_5/text/sft_train_data.jsonl",
    # The following parameters are optional
    validation_dataset="gs://cloud-samples-data/ai-platform/generative_ai/gemini-1_5/text/sft_validation_data.jsonl",
    tuned_model_display_name="tuned_gemini_2_0_flash",
    # Advanced use only below. It is recommended to use auto-selection and leave them unset
    # epochs=4,
    # adapter_size=4,
    # learning_rate_multiplier=1.0,
)

# Polling for job completion
while not sft_tuning_job.has_ended:
    time.sleep(60)
    sft_tuning_job.refresh()

print(sft_tuning_job.tuned_model_name)
print(sft_tuning_job.tuned_model_endpoint_name)
print(sft_tuning_job.experiment)
# Example response:
# projects/123456789012/locations/us-central1/models/1234567890@1
# projects/123456789012/locations/us-central1/endpoints/123456789012345
# <google.cloud.aiplatform.metadata.experiment_resources.Experiment object at 0x7b5b4ae07af0>

Apresentar tarefas de otimização

Pode ver uma lista de tarefas de otimização no seu projeto atual através do SDK Vertex AI para Python ou enviando um pedido GET.

REST

Para criar uma tarefa de ajuste de modelos, envie um pedido POST através do método tuningJobs.create. Tenha em atenção que alguns dos parâmetros não são suportados por todos os modelos. Certifique-se de que inclui apenas os parâmetros aplicáveis para o modelo que está a ajustar.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: .
  • TUNING_JOB_REGION: a região onde a tarefa de otimização é executada. Esta é também a região predefinida para onde o modelo otimizado é carregado.

Método HTTP e URL:

GET https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs

Para enviar o seu pedido, 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/tuningJobs"

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/tuningJobs" | Select-Object -Expand Content

Deve receber uma resposta JSON semelhante à seguinte.

Python

import vertexai
from vertexai.tuning import sft

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

responses = sft.SupervisedTuningJob.list()

for response in responses:
    print(response)
# Example response:
# <vertexai.tuning._supervised_tuning.SupervisedTuningJob object at 0x7c85287b2680>
# resource name: projects/12345678/locations/us-central1/tuningJobs/123456789012345

Veja detalhes de uma tarefa de ajuste

Pode obter os detalhes de uma tarefa de ajuste através do SDK Vertex AI para Python ou do envio de um pedido GET.

REST

Para ver uma lista de tarefas de ajuste de modelos, envie um pedido GET através do método tuningJobs.get e especifique o TuningJob_ID.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: .
  • TUNING_JOB_REGION: a região onde a tarefa de otimização é executada. Esta é também a região predefinida para onde o modelo otimizado é carregado.
  • TUNING_JOB_ID: o ID da tarefa de otimização.

Método HTTP e URL:

GET https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs/TUNING_JOB_ID

Para enviar o seu pedido, 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/tuningJobs/TUNING_JOB_ID"

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/tuningJobs/TUNING_JOB_ID" | Select-Object -Expand Content

Deve receber uma resposta JSON semelhante à seguinte.

Python

import vertexai
from vertexai.tuning import sft

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# LOCATION = "us-central1"
vertexai.init(project=PROJECT_ID, location=LOCATION)

tuning_job_id = "4982013113894174720"
response = sft.SupervisedTuningJob(
    f"projects/{PROJECT_ID}/locations/{LOCATION}/tuningJobs/{tuning_job_id}"
)

print(response)
# Example response:
# <vertexai.tuning._supervised_tuning.SupervisedTuningJob object at 0x7cc4bb20baf0>
# resource name: projects/1234567890/locations/us-central1/tuningJobs/4982013113894174720

Cancele uma tarefa de otimização

Pode cancelar uma tarefa de otimização usando o SDK Vertex AI para Python ou enviando um pedido POST.

REST

Para ver uma lista de tarefas de ajuste de modelos, envie um pedido GET através do método tuningJobs.cancel e especifique o TuningJob_ID.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: .
  • TUNING_JOB_REGION: a região onde a tarefa de otimização é executada. Esta é também a região predefinida para onde o modelo otimizado é carregado.
  • TUNING_JOB_ID: o ID da tarefa de otimização.

Método HTTP e URL:

POST https://TUNING_JOB_REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/TUNING_JOB_REGION/tuningJobs/TUNING_JOB_ID:cancel

Para enviar o seu pedido, 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/tuningJobs/TUNING_JOB_ID:cancel"

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/tuningJobs/TUNING_JOB_ID:cancel" | Select-Object -Expand Content

Deve receber uma resposta JSON semelhante à seguinte.

Python

import vertexai
from vertexai.tuning import sft

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# LOCATION = "us-central1"
vertexai.init(project=PROJECT_ID, location=LOCATION)

tuning_job_id = "4982013113894174720"
job = sft.SupervisedTuningJob(
    f"projects/{PROJECT_ID}/locations/{LOCATION}/tuningJobs/{tuning_job_id}"
)
job.cancel()

O que se segue?

Para ver documentação detalhada, consulte o seguinte: