API Tuning

El ajuste de modelos es un proceso crucial para adaptar Gemini a tareas específicas con mayor precisión. El ajuste de modelos funciona proporcionando a un modelo un conjunto de datos de entrenamiento que contiene un conjunto de ejemplos de tareas específicas posteriores.

Usa la API de ajuste de Gemini en los siguientes casos prácticos:

Modelos admitidos:

Puedes usar el ajuste fino supervisado en los siguientes modelos de Gemini:

También se admite Translation LLM V2 (translation-llm-002).

Sintaxis de ejemplo

Sintaxis para ajustar un 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

Consulta los ejemplos para obtener más información sobre la implementación.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene datos con los siguientes parámetros:

Parámetros

source_model

Opcional: string

Nombre del modelo fundacional que se está ajustando.

tunedModelDisplayName

string

El nombre visible de TunedModel. El nombre puede tener hasta 128 caracteres y puede estar formado por cualquier carácter UTF-8.

supervisedTuningSpec

Parámetros

training_dataset

string

URI de Cloud Storage de tu conjunto de datos de entrenamiento. El conjunto de datos debe tener el formato de un archivo JSONL. Para obtener los mejores resultados, proporcione entre 100 y 500 ejemplos. Para obtener más información, consulta el artículo Acerca de los conjuntos de datos de ajuste supervisado.

validation_dataset

Opcional: string

URI de Cloud Storage de tu conjunto de datos de validación. El conjunto de datos debe tener el formato de un archivo JSONL. Un conjunto de datos puede contener hasta 256 ejemplos. Si proporciona este archivo, los datos se usarán para generar métricas de validación periódicamente durante el ajuste. Para obtener más información, consulta Acerca de los conjuntos de datos de ajuste supervisado .

epoch_count

Opcional: int

Número de pases completos que realiza el modelo en todo el conjunto de datos de entrenamiento durante el entrenamiento. Vertex AI ajusta automáticamente el valor predeterminado al tamaño de tu conjunto de datos de entrenamiento. Este valor se basa en los resultados de las comparativas para optimizar la calidad de los resultados del modelo.

learning_rate_multiplier

Opcional: float

Multiplicador para ajustar la tasa de aprendizaje predeterminada.

adapter_size

Opcional: AdapterSize

Tamaño del adaptador para la optimización.

tuned_model_display_name

Opcional: string

Nombre visible de TunedModel. El nombre puede tener hasta 128 caracteres y puede estar formado por cualquier carácter UTF-8.

AdapterSize

Tamaño del adaptador para la tarea de ajuste.

Parámetros

ADAPTER_SIZE_UNSPECIFIED

Tamaño del adaptador no especificado.

ADAPTER_SIZE_ONE

Tamaño del adaptador 1.

ADAPTER_SIZE_FOUR

Tamaño del adaptador 4.

ADAPTER_SIZE_EIGHT

Tamaño del adaptador 8.

ADAPTER_SIZE_SIXTEEN

Tamaño del adaptador 16.

Ejemplos

Crear una tarea de ajuste supervisada

Puedes crear un trabajo de ajuste de un modelo de texto supervisado mediante el SDK de Vertex AI para Python o enviando una solicitud POST.

Caso práctico básico

En el caso práctico básico, solo se definen los valores de baseModel y training_dataset_uri. El resto de los parámetros usan los valores predeterminados.

REST

Para crear un trabajo de ajuste de un modelo, envía una solicitud POST mediante el método tuningJobs.create. Tenga en cuenta que no todos los modelos admiten algunos de los parámetros. Asegúrate de incluir solo los parámetros aplicables al modelo que estés ajustando.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: tu ID de proyecto.
  • TUNING_JOB_REGION: la región en la que se ejecuta el trabajo de ajuste. También es la región predeterminada en la que se sube el modelo ajustado.
  • BASE_MODEL: nombre del modelo base que se va a ajustar.
  • TRAINING_DATASET_URI: URI de Cloud Storage de tu conjunto de datos de entrenamiento. El conjunto de datos debe tener el formato de un archivo JSONL. Para obtener los mejores resultados, proporcione entre 100 y 500 ejemplos. Para obtener más información, consulta el artículo Acerca de los conjuntos de datos de ajuste supervisado .

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud: 

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Deberías recibir una respuesta JSON similar a la siguiente.

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>

Caso práctico avanzado

El caso práctico avanzado se basa en el básico, pero también define valores para hyper_parametersopcionalesepoch_count, como epoch_count, learning_rate_multiplier y adapter_size.

REST

Para crear un trabajo de ajuste de un modelo, envía una solicitud POST mediante el método tuningJobs.create. Tenga en cuenta que no todos los modelos admiten algunos de los parámetros. Asegúrate de incluir solo los parámetros aplicables al modelo que estés ajustando.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: tu ID de proyecto.
  • TUNING_JOB_REGION: la región en la que se ejecuta el trabajo de ajuste. También es la región predeterminada en la que se sube el modelo ajustado.
  • BASE_MODEL: nombre del modelo base que se va a ajustar.
  • TRAINING_DATASET_URI: URI de Cloud Storage de tu conjunto de datos de entrenamiento. El conjunto de datos debe tener el formato de un archivo JSONL. Para obtener los mejores resultados, proporcione entre 100 y 500 ejemplos. Para obtener más información, consulta el artículo Acerca de los conjuntos de datos de ajuste supervisado .
  • VALIDATION_DATASET_URIOpcional: URI de Cloud Storage del archivo del conjunto de datos de validación.
  • EPOCH_COUNTOpcional: número de pases completos que realiza el modelo en todo el conjunto de datos de entrenamiento durante el entrenamiento. No lo defina para usar el valor recomendado rellenado previamente.
  • ADAPTER_SIZEOpcional: el tamaño del adaptador que se debe usar en la tarea de ajuste. El tamaño del adaptador influye en el número de parámetros entrenables de la tarea de ajuste. Un tamaño de adaptador mayor implica que el modelo puede aprender tareas más complejas, pero requiere un conjunto de datos de entrenamiento más grande y tiempos de entrenamiento más largos.
  • LEARNING_RATE_MULTIPLIER: opcional. Es un multiplicador que se aplica a la tasa de aprendizaje recomendada. Si no lo define, se usará el valor recomendado.
  • EXPORT_LAST_CHECKPOINT_ONLYOpcional: Asigna el valor true para usar solo el último punto de control.
  • METRIC_SPECOpcional: una o varias especificaciones de métricas que estés usando para llevar a cabo una evaluación con el servicio de evaluación de IA generativa. Puede usar las siguientes especificaciones de métricas: "pointwise_metric_spec", "pairwise_metric_spec", "exact_match_spec", "bleu_spec" y "rouge_spec".
  • METRIC_SPEC_FIELD_NAMEOpcional: los campos obligatorios de la especificación de métrica que elijas. Por ejemplo, "metric_prompt_template"
  • METRIC_SPEC_FIELD_NAME_CONTENTOpcional: el contenido del campo de la especificación de métrica que hayas elegido. Por ejemplo, puedes usar el siguiente contenido de campo para una evaluación punto a punto: "Evaluate the fluency of this sentence: {response}. Give score from 0 to 1. 0 - not fluent at all. 1 - very fluent."
  • CLOUD_STORAGE_BUCKETOpcional: el segmento de Cloud Storage en el que se almacenarán los resultados de una evaluación realizada por el servicio de evaluación de la IA generativa.
  • TUNED_MODEL_DISPLAYNAMEOpcional: nombre visible del modelo ajustado. Si no se define, se genera un nombre aleatorio.
  • KMS_KEY_NAMEOpcional: identificador de recurso de Cloud KMS de la clave de cifrado gestionada por el cliente que se usa para proteger un recurso. La clave tiene el formato projects/my-project/locations/my-region/keyRings/my-kr/cryptoKeys/my-key. La clave debe estar en la misma región en la que se cree el recurso de computación. Para obtener más información, consulta Claves de cifrado gestionadas por el cliente (CMEK).
  • SERVICE_ACCOUNTOpcional: la cuenta de servicio con la que se ejecuta la carga de trabajo tuningJob. Si no se especifica, se usa el agente del servicio de ajuste fino seguro de Vertex AI del proyecto. Consulta Ajustar el agente de servicio. Si tienes previsto usar una cuenta de servicio gestionada por el cliente, debes asignar el rol roles/aiplatform.tuningServiceAgent a la cuenta de servicio. También debes asignar el rol Agente de servicio de ajuste roles/iam.serviceAccountTokenCreator a la cuenta de servicio gestionada por el cliente.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud: 

{
  "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 tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Deberías recibir una respuesta JSON similar a la siguiente.

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>

Mostrar tareas de ajuste

Para ver una lista de las tareas de ajuste de tu proyecto actual, puedes usar el SDK de Vertex AI para Python o enviar una solicitud GET.

REST

Para crear un trabajo de ajuste de un modelo, envía una solicitud POST mediante el método tuningJobs.create. Tenga en cuenta que no todos los modelos admiten algunos de los parámetros. Asegúrate de incluir solo los parámetros aplicables al modelo que estés ajustando.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: .
  • TUNING_JOB_REGION: la región en la que se ejecuta el trabajo de ajuste. También es la región predeterminada en la que se sube el modelo ajustado.

Método HTTP y URL: 

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el comando siguiente: 

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

Ejecuta el comando siguiente: 

$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

Deberías recibir una respuesta JSON similar a la siguiente.

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

Obtener los detalles de una tarea de ajuste

Puedes obtener los detalles de una tarea de ajuste mediante el SDK de Vertex AI para Python o enviando una solicitud GET.

REST

Para ver una lista de tareas de ajuste de modelos, envía una solicitud GET mediante el método tuningJobs.get y especifica el TuningJob_ID.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: .
  • TUNING_JOB_REGION: la región en la que se ejecuta el trabajo de ajuste. También es la región predeterminada en la que se sube el modelo ajustado.
  • TUNING_JOB_ID: ID del trabajo de ajuste.

Método HTTP y URL: 

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el comando siguiente: 

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

Ejecuta el comando siguiente: 

$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

Deberías recibir una respuesta JSON similar a la siguiente.

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

Cancelar una tarea de ajuste

Puedes cancelar una tarea de ajuste mediante el SDK de Vertex AI para Python o enviando una solicitud POST.

REST

Para ver una lista de tareas de ajuste de modelos, envía una solicitud GET mediante el método tuningJobs.cancel y especifica el TuningJob_ID.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: .
  • TUNING_JOB_REGION: la región en la que se ejecuta el trabajo de ajuste. También es la región predeterminada en la que se sube el modelo ajustado.
  • TUNING_JOB_ID: ID del trabajo de ajuste.

Método HTTP y URL: 

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

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el comando siguiente: 

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

Ejecuta el comando siguiente: 

$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

Deberías recibir una respuesta JSON similar a la siguiente.

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()

Siguientes pasos

Para obtener documentación detallada, consulta lo siguiente: