Etiquetas de metadatos personalizados

Puedes agregar metadatos personalizados a las llamadas a la API de generateContent y streamGenerateContent con etiquetas. En esta página, se explica qué son las etiquetas y se muestra cómo usarlas para desglosar los cargos facturados.

¿Qué son las etiquetas?

Una etiqueta es un par clave-valor que puedes asignar a las llamadas a la API de generateContent y streamGenerateContent. Te ayudan a organizar estas llamadas y administrar los costos a gran escala, con el nivel de detalle que necesitas. Puedes adjuntar una etiqueta a cada llamada y, luego, filtrar las llamadas según sus etiquetas. La información sobre las etiquetas se envía al sistema de facturación que te permite desglosar los cargos facturados por etiqueta. Con los informes de facturación integrados, puedes filtrar y agrupar costos por etiquetas. También puedes usar etiquetas para consultar las exportaciones de datos de facturación.

Requisitos para las etiquetas

Las etiquetas que se aplican a una llamada a la API deben cumplir con los siguientes requisitos:

• Cada llamada a la API puede tener hasta 64 etiquetas.
• Cada etiqueta debe ser un par clave-valor.
• La longitud de las claves debe ser de entre 1 y 63 caracteres, y no pueden estar vacías. Los valores pueden estar vacíos y su longitud máxima es de 63 caracteres.
• Las claves y los valores pueden contener solo letras en minúscula, caracteres numéricos, guiones bajos y guiones. Todos los caracteres deben usar la codificación UTF-8, además, se permiten los caracteres internacionales. Las claves deben comenzar con una letra en minúscula o un carácter internacional.
• La porción de clave de una etiqueta debe ser única para una sola llamada a la API. Sin embargo, puedes usar la misma clave con varias llamadas.

Estos límites se aplican a la clave y al valor de cada etiqueta, y a las llamadas a la API individuales que tienen etiquetas. No hay límite para la cantidad de etiquetas que puedes aplicar en todas las llamadas a la API de un proyecto.

Usos comunes de las etiquetas

Estos son algunos casos prácticos comunes de las etiquetas:

• Etiquetas por equipo o centro de costos: Agrega etiquetas por equipo o centro de costos para distinguir las llamadas a la API que pertenecen a diferentes equipos (por ejemplo, team:research y team:analytics). Puedes usar este tipo de etiqueta para la contabilidad de costos o la creación de presupuestos.

• Etiquetas de componentes: por ejemplo, component:redis, component:frontend, component:ingest y component:dashboard.

• Etiquetas de entorno o etapa: por ejemplo, environment:production y environment:test.

• Etiquetas de propiedad: Se usan para identificar a los equipos responsables de las operaciones, por ejemplo: team:shopping-cart.

Nota: No incluyas información sensible en las etiquetas, incluida la información de identificación personal, como el nombre o el título de una persona. Las etiquetas no están diseñadas para contener información sensible.

No recomendamos crear grandes cantidades de etiquetas únicas, como marcas de tiempo o valores individuales para cada llamada a la API. El problema con este enfoque es que, cuando los valores cambian con frecuencia o con claves que sobrecargan el catálogo, esto dificulta el filtrado y la generación de informes eficaces para las llamadas a la API.

Agrega una etiqueta a una llamada a la API

Para agregar una etiqueta a una llamada a la API de generateContent o streamGenerateContent, haz lo siguiente:

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• GENERATE_RESPONSE_METHOD: El tipo de respuesta que quieres que genere el modelo. Elige un método que genere cómo quieres que se muestre la respuesta del modelo:
  • streamGenerateContent: La respuesta se transmite a medida que se genera para reducir la percepción de latencia para un público humano.
  • generateContent: La respuesta se muestra después de que se genera por completo.
• LOCATION: La región para procesar la solicitud. Las opciones disponibles incluyen las siguientes:

  Haz clic para expandir una lista parcial de regiones disponibles

  • us-central1
  • us-west4
  • northamerica-northeast1
  • us-east4
  • us-west1
  • asia-northeast3
  • asia-southeast1
  • asia-northeast1
• PROJECT_ID: El ID del proyecto.
• MODEL_ID: el ID del modelo multimodal que deseas usar. Estas son algunas opciones:
  • gemini-1.0-pro-002
  • gemini-1.0-pro-vision-001
  • gemini-1.5-pro-002
  • gemini-1.5-flash
• ROLE: El rol en una conversación asociada con el contenido. Especificar un rol es obligatorio incluso en casos de uso de un solo turno. Los valores aceptables son los siguientes:
  • USER: especifica el contenido que envías.
  • MODEL: especifica la respuesta del modelo.
• PROMPT_TEXT

  Las instrucciones de texto que se incluirán en el mensaje. JSON
• LABEL_KEY: Son los metadatos de la etiqueta que deseas asociar con esta llamada a la API.
• LABEL_VALUE: Es el valor de la etiqueta.

Para enviar tu solicitud, elige una de estas opciones:

curl

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:

cat > request.json << 'EOF'
{
  "contents": {
    "role": "ROLE",
    "parts": { "text": "PROMPT_TEXT" }
  },
  "labels": {
    "LABEL_KEY": "LABEL_VALUE"
  },
}
EOF

Luego, ejecuta el siguiente comando para enviar tu solicitud de REST:

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

PowerShell

Nota: En el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:

@'
{
  "contents": {
    "role": "ROLE",
    "parts": { "text": "PROMPT_TEXT" }
  },
  "labels": {
    "LABEL_KEY": "LABEL_VALUE"
  },
}
'@  | Out-File -FilePath request.json -Encoding utf8

Luego, ejecuta el siguiente comando para enviar tu solicitud de REST:

$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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

Respuesta

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": Generative AI is a type of artificial intelligence (AI) that can **create new
            content**, like text, images, audio, video, and even code.
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.037841797,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.06347656
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.053466797,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.08496094
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.08154297,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.033203125
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.071777344,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.083984375
        }
      ],
      "avgLogprobs": -0.40486351219383448
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 555,
    "totalTokenCount": 560
  }
}

Los productos de Google Cloud informan los datos de costos y de uso a los procesos de la Facturación de Cloud en intervalos variables. Como resultado, es posible que veas una demora entre el uso de los servicios de Google Cloud y el uso y los costos disponibles para ver en la Facturación de Cloud. Por lo general, tus costos están disponibles dentro de un día, aunque, a veces, pueden tardar más de 24 horas.