Usar AI Platform Vizier

En esta página, se describe cómo realizar solicitudes a la API a AI Platform Vizier mediante curl.

Antes de comenzar

  1. Consulta la descripción general de AI Platform Vizier para obtener información sobre cómo funciona AI Platform Vizier.
  2. Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
  3. En la página del selector de proyectos de Google Cloud Console, selecciona o crea un proyecto de Google Cloud.

    Ir al selector de proyecto

  4. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Descubre cómo confirmar que tienes habilitada la facturación en un proyecto.

  5. Habilita las AI Platform Training and Prediction API.

    Habilita la API

  6. Instala e inicializa el SDK de Cloud.

Accede a tu cuenta de Facturación de Cloud

Usa los siguientes comandos para acceder a tu cuenta de Google Cloud:

gcloud auth application-default login
gcloud auth login

Define constantes

Ejecuta los siguientes comandos y reemplaza USERNAME y PROJECT_ID por tu nombre de usuario y la información del ID del proyecto. Crea tu propio ID de cliente o nombre de estudio, o usa los valores sugeridos.

export USER=USERNAME
export PROJECT_ID=PROJECT_ID{"</var>"}}
export REGION=us-central1

export STUDY_NAME=${USER}_vizier_study_$(date +%Y%m%d%H%M%S)
export CLIENT_ID=${USER}_client_1
export ENDPOINT=https://$REGION-ml.googleapis.com/v1

Crea solicitudes a la API

A continuación, se describe cómo crear solicitudes a la API de la línea de comandos para AI Platform Vizier con curl.

Crea un estudio

Un estudio es una serie de experimentos o pruebas que te ayudan a optimizar los hiperparámetros o parámetros.

Para crear un estudio, debes crear una configuración de estudio en formato JSON y, luego, enviar una solicitud POST que pase la configuración a AI Platform Vizier.

Es posible que la configuración del estudio se vea de la siguiente manera. Obtén más información sobre las opciones de algoritmos, los tipos de objetivos y otras opciones en la documentación de la API de entrenamiento y predicción de AI Platform.

En el siguiente ejemplo, el objetivo es maximizar y = x^2 con x en el rango [-10. 10]. En este ejemplo, solo hay un parámetro y se usa una función fácil de calcular para demostrar cómo usar AI Platform Vizier. Si lo deseas, obtén más información a fin de usar AI Platform Vizier para problemas de optimización más complejos o intenta optimizar dos funciones a la vez.

cat > /tmp/create_study.json <<EOF
{
  "studyConfig": {
    "algorithm": 0,
    "metrics": [
      {
        "goal": "MAXIMIZE",
        "metric": "y"
      }
    ],
    "parameters": [
      {
        "doubleValueSpec": {
          "maxValue": 10.0,
          "minValue": -10.0
        },
        "parameter": "x",
        "type": "DOUBLE"
      }
    ]
  }
}
EOF

Para crear el estudio mediante la configuración del estudio, envía la siguiente solicitud POST.

curl -X POST -H "Content-Type: application/json" \
  -d @/tmp/create_study.json \
  -H "Authorization: Bearer `gcloud auth print-access-token`" \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies?study_id=${STUDY_NAME}"

Obtén un estudio

Para obtener un estudio, envía la siguiente solicitud.

curl -H "Content-Type: application/json"   \
  -H "Authorization: Bearer `gcloud auth print-access-token`"   \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies/${STUDY_NAME}"

Genera una lista de los estudios

Para generar una lista de los estudios en un proyecto y una región específicos, envía la siguiente solicitud.

curl -H "Content-Type: application/json"  \
  -H "Authorization: Bearer `gcloud auth print-access-token`"   \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies/"

Recibe sugerencias de pruebas

Para obtener una sugerencia de prueba de AI Platform Vizier, crea un archivo JSON que contenga un valor de suggestionCount y tu ID de cliente. Luego, envía una solicitud POST que pase esta información a AI Platform Vizier.

Crea el archivo JSON mediante los siguientes comandos. Cambia el valor de suggestionCount por la cantidad de sugerencias que deseas obtener de cada solicitud.

cat > /tmp/suggest_trial.json <<EOF
{
  "suggestionCount": 1,
  "clientId": "${CLIENT_ID}"
}
EOF

Para obtener la sugerencia o las sugerencias, envía la siguiente solicitud POST.

curl -X POST -H "Content-Type: application/json" \
  -d @/tmp/suggest_trial.json \
  -H "Authorization: Bearer `gcloud auth print-access-token`" \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies/${STUDY_NAME}/trials:suggest"

suggestTrial inicia una operación de larga duración que se encarga de generar la prueba. La respuesta te informa que AI Platform Vizier está trabajando en sugerencias de pruebas. Esta respuesta tendrá el siguiente formato:

{
  "name": "projects/<project>/locations/<region>/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.ml.v1.SuggestTrialsMetadata",
    "study": <study-name>,
    "createTime": <create-time>,
    "suggestionCount": <suggestion-count>
  }
}

Puedes usar el ID de la operación incluido en la respuesta anterior para sondear la operación de sugerencia y obtener las sugerencias de pruebas. Usa el siguiente comando:

SUGGEST_OPERATION_ID=OPERATION_ID

curl -H "Content-Type: application/json"   \
  -H "Authorization: Bearer `gcloud auth print-access-token`"   \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/operations/${SUGGEST_OPERATION_ID}"

Si no recibes una respuesta, es posible que la solicitud suggestTrial no se haya completado. Repite el comando anterior si es necesario.

La respuesta proporciona sugerencias de pruebas, en este formato:

{
  "name": "projects/<project>/locations/<region>/operations/<operation-id>",
  "metadata": {...},
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.ml.v1.SuggestTrialsResponse",
    "trials": [
      {
        "name": "projects/<project>/locations/<region>/studies/<study-id>/trials/TRIAL_ID",
        "state": "ACTIVE",
        "parameters": [
          {
            "parameter": "x",
            "floatValue": 0.1
          }
        ],
        ...
      }
    ],
    ...
  }
}

En el ejemplo anterior, esta prueba sugiere usar el valor 0.1 para el parámetro x.

Si usas el ID de la prueba incluido en la respuesta anterior, puedes obtener la prueba mediante el siguiente comando:

TRIAL_ID=TRIAL_ID

curl -H "Content-Type: application/json"   \
  -H "Authorization: Bearer `gcloud auth print-access-token`"   \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies/${STUDY_NAME}/trials/${TRIAL_ID}"

Evalúa los resultados

Después de recibir las sugerencias de pruebas, evalúa cada prueba y registra cada resultado como una medida.

Por ejemplo, si la función que intentas optimizar es y = x^2, evalúa la función con el valor x que sugirió la prueba. Con el valor sugerido 0.1, la función se evalúa como y = 0.1 * 0.1, lo que da como resultado 0.01.

Agrega una medida

Después de evaluar la prueba sugerida para obtener una medida, agrega esta medida a la prueba. Para ello, debes crear un archivo JSON que contenga la métrica que mediste y el resultado. Luego, envía una solicitud POST que pase esta información a AI Platform Vizier.

Almacena la medida y crea el archivo JSON mediante los siguientes comandos. En este ejemplo, reemplazas RESULT por la medida. Si la función que optimizas es y = x^2, y el valor sugerido de x es 0.1, el resultado es 0.01.

METRIC_VALUE=RESULT

cat > /tmp/add_measurement.json <<EOF
{
  "measurement": {
    "stepCount": 1,
    "metrics": [
      {
        "metric": "y",
        "value": ${METRIC_VALUE}
      }
    ]
  }
}
EOF

Si deseas agregar esta medida a tu prueba, envía la siguiente solicitud POST.

curl -X POST -H "Content-Type: application/json" \
  -d @/tmp/add_measurement.json \
  -H "Authorization: Bearer `gcloud auth print-access-token`" \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies/${STUDY_NAME}/trials/${TRIAL_ID}:addMeasurement"

Completa una prueba

Una vez que hayas agregado todas las medidas de una prueba, completa la prueba mediante el siguiente comando. De manera opcional, puedes agregar una medida final cuando llames a completeTrial.

Sin una medida final

Para completar la prueba sin agregar una medida final, envía la siguiente solicitud POST.

curl -X POST -H "Content-Type: application/json" \
  -d "" \
  -H "Authorization: Bearer `gcloud auth print-access-token`" \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies/${STUDY_NAME}/trials/${TRIAL_ID}:complete"

Con una medida final

Para incluir una medida final cuando completes la prueba, primero debes almacenarla y crear un archivo JSON mediante los siguientes comandos y luego debes reemplazar RESULT por la medida final.

FINAL_METRIC_VALUE=RESULT

cat > /tmp/complete_trial.json <<EOF
{
  "finalMeasurement": {
    "stepCount": 1,
    "metrics": [
      {
        "metric": "y",
        "value": ${FINAL_METRIC_VALUE}
      }
    ]
  }
}
EOF

Envía la siguiente solicitud POST.

curl -X POST -H "Content-Type: application/json" \
  -d @/tmp/complete_trial.json \
  -H "Authorization: Bearer `gcloud auth print-access-token`" \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies/${STUDY_NAME}/trials/${TRIAL_ID}:complete"

Listado de pruebas

Para generar una lista de las pruebas en un estudio específico, envía la siguiente solicitud.

curl -H "Content-Type: application/json"   \
  -H "Authorization: Bearer `gcloud auth print-access-token`"   \
  "${ENDPOINT}/projects/${PROJECT_ID}/locations/${REGION}/studies/${STUDY_NAME}/trials/"

Una vez que hayas completado todas las pruebas pendientes, puede llamar a suggestTrial para obtener más sugerencias y repetir el proceso de evaluación de pruebas.

Próximos pasos

Si deseas ver ejemplos del uso de la API, consulta estos vínculos: