Llama a las APIs de MaaS para modelos abiertos

Muchos modelos abiertos en Vertex AI ofrecen modelos completamente administrados y sin servidores como APIs con la API de Chat Completions de Vertex AI. Para estos modelos, no es necesario aprovisionar ni administrar la infraestructura.

Puedes transmitir tus respuestas para reducir la percepción de latencia del usuario final. Una respuesta transmitida usa eventos enviados por el servidor (SSE) para transmitir la respuesta de forma incremental.

En esta página, se muestra cómo realizar llamadas de transmisión y no transmisión a modelos abiertos que admiten la API de chat completions de OpenAI. Para conocer las consideraciones específicas de Llama, consulta Cómo solicitar predicciones de Llama.

Antes de comenzar

Para usar modelos abiertos con Vertex AI, debes realizar los siguientes pasos. La API de Vertex AI (aiplatform.googleapis.com) debe estar habilitada para usar Vertex AI. Si ya tienes un proyecto existente con la API de Vertex AI habilitada, puedes usar ese proyecto en lugar de crear uno nuevo.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.
  8. Ve a la tarjeta de modelo de Model Garden del modelo que deseas usar y, luego, haz clic en Habilitar para habilitar el modelo y usarlo en tu proyecto.

    Ir a Model Garden

    9. Haz una llamada de transmisión a un modelo abierto

    En el siguiente ejemplo, se realiza una llamada de transmisión a un modelo abierto:

    Python

    Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de Vertex AI sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Vertex AI Python.

    Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

    Antes de ejecutar esta muestra, asegúrate de configurar la variable de entorno OPENAI_BASE_URL. Para obtener más información, consulta Autenticación y credenciales.

    from openai import OpenAI
client = OpenAI()

stream = client.chat.completions.create(
    model="MODEL",
    messages=[{"role": "ROLE", "content": "CONTENT"}],
    max_tokens=MAX_OUTPUT_TOKENS,
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")
    • MODEL: El nombre del modelo que deseas usar, por ejemplo, deepseek-ai/deepseek-v3.1-maas.
    • ROLE: El rol asociado a un mensaje. Puedes especificar un user o un assistant. El primer mensaje debe usar el rol user. Los modelos operan con turnos alternativos de user y assistant. Si el mensaje final usa el rol assistant, el contenido de la respuesta continúa inmediatamente desde el contenido de ese mensaje. Puedes usar esto para restringir parte de la respuesta del modelo.
    • CONTENT: el contenido, como texto, del mensaje user o assistant.
    • MAX_OUTPUT_TOKENS: Cantidad máxima de tokens que se pueden generar en la respuesta. Un token tiene casi cuatro caracteres. 100 tokens corresponden a casi 60 u 80 palabras.

      Especifica un valor más bajo para las respuestas más cortas y un valor más alto para las respuestas potencialmente más largas.

    REST

    Después de configurar tu entorno, puedes usar REST para probar una instrucción de texto. En el siguiente ejemplo, se envía una solicitud al extremo del modelo de publicador.

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

    • LOCATION: Una región que admite modelos abiertos.
    • MODEL: El nombre del modelo que deseas usar, por ejemplo, deepseek-ai/deepseek-v2.
    • ROLE: El rol asociado a un mensaje. Puedes especificar un user o un assistant. El primer mensaje debe usar el rol user. Los modelos operan con turnos alternativos de user y assistant. Si el mensaje final usa el rol assistant, el contenido de la respuesta continúa inmediatamente desde el contenido de ese mensaje. Puedes usar esto para restringir parte de la respuesta del modelo.
    • CONTENT: el contenido, como texto, del mensaje user o assistant.
    • MAX_OUTPUT_TOKENS: Cantidad máxima de tokens que se pueden generar en la respuesta. Un token tiene casi cuatro caracteres. 100 tokens corresponden a casi 60 u 80 palabras.

      Especifica un valor más bajo para las respuestas más cortas y un valor más alto para las respuestas potencialmente más largas.

    • STREAM: Un valor booleano que especifica si la respuesta se transmite o no. Transmite tu respuesta para reducir la percepción de latencia del uso final. Configúralo como true para transmitir la respuesta y false para mostrar la respuesta de una sola vez.

    Método HTTP y URL: 

    POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions

    Cuerpo JSON de la solicitud:

    {
  "model": "MODEL",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_OUTPUT_TOKENS,
  "stream": true
}

    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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions"

    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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions" | Select-Object -Expand Content

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

    Realiza una llamada sin transmisión a un modelo abierto

    En el siguiente ejemplo, se realiza una llamada sin transmisión a un modelo abierto:

    Python

    Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de Vertex AI sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Vertex AI Python.

    Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

    Antes de ejecutar esta muestra, asegúrate de configurar la variable de entorno OPENAI_BASE_URL. Para obtener más información, consulta Autenticación y credenciales.

    from openai import OpenAI
client = OpenAI()

completion = client.chat.completions.create(
    model="MODEL",
    messages=[{"role": "ROLE", "content": "CONTENT"}],
    max_tokens=MAX_OUTPUT_TOKENS,
    stream=False,
)
print(completion.choices[0].message)
    • MODEL: El nombre del modelo que deseas usar, por ejemplo, deepseek-ai/deepseek-v3.1-maas.
    • ROLE: El rol asociado a un mensaje. Puedes especificar un user o un assistant. El primer mensaje debe usar el rol user. Los modelos operan con turnos alternativos de user y assistant. Si el mensaje final usa el rol assistant, el contenido de la respuesta continúa inmediatamente desde el contenido de ese mensaje. Puedes usar esto para restringir parte de la respuesta del modelo.
    • CONTENT: el contenido, como texto, del mensaje user o assistant.
    • MAX_OUTPUT_TOKENS: Cantidad máxima de tokens que se pueden generar en la respuesta. Un token tiene casi cuatro caracteres. 100 tokens corresponden a casi 60 u 80 palabras.

      Especifica un valor más bajo para las respuestas más cortas y un valor más alto para las respuestas potencialmente más largas.

    REST

    Después de configurar tu entorno, puedes usar REST para probar una instrucción de texto. En el siguiente ejemplo, se envía una solicitud al extremo del modelo de publicador.

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

    • LOCATION: Una región que admite modelos abiertos.
    • MODEL: El nombre del modelo que deseas usar, por ejemplo, deepseek-ai/deepseek-v2.
    • ROLE: El rol asociado a un mensaje. Puedes especificar un user o un assistant. El primer mensaje debe usar el rol user. Los modelos operan con turnos alternativos de user y assistant. Si el mensaje final usa el rol assistant, el contenido de la respuesta continúa inmediatamente desde el contenido de ese mensaje. Puedes usar esto para restringir parte de la respuesta del modelo.
    • CONTENT: el contenido, como texto, del mensaje user o assistant.
    • MAX_OUTPUT_TOKENS: Cantidad máxima de tokens que se pueden generar en la respuesta. Un token tiene casi cuatro caracteres. 100 tokens corresponden a casi 60 u 80 palabras.

      Especifica un valor más bajo para las respuestas más cortas y un valor más alto para las respuestas potencialmente más largas.

    • STREAM: Un valor booleano que especifica si la respuesta se transmite o no. Transmite tu respuesta para reducir la percepción de latencia del uso final. Configúralo como true para transmitir la respuesta y false para mostrar la respuesta de una sola vez.

    Método HTTP y URL: 

    POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions

    Cuerpo JSON de la solicitud:

    {
  "model": "MODEL",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_OUTPUT_TOKENS,
  "stream": false
}

    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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions"

    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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions" | Select-Object -Expand Content

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

    Extremos regionales y globales

    En el caso de los extremos regionales, las solicitudes se entregan desde la región que especificaste. En los casos en los que tengas requisitos de residencia de datos o si un modelo no admite el extremo global, usa los extremos regionales.

    Cuando usas el extremo global, Google puede procesar y entregar tus solicitudes desde cualquier región compatible con el modelo que usas. En algunos casos, esto puede generar una latencia más alta. El extremo global ayuda a mejorar la disponibilidad general y a reducir los errores.

    No hay diferencia de precios con los extremos regionales cuando usas el extremo global. Sin embargo, las cuotas del extremo global y las capacidades del modelo admitido pueden diferir de las de los extremos regionales. Para obtener más información, consulta la página del modelo de terceros relacionado.

    Especifica el extremo global

    Para usar el extremo global, configura la región como global.

    Por ejemplo, la URL de solicitud para un comando curl usa el siguiente formato: https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi

    En el SDK de Vertex AI, un extremo regional es el valor predeterminado. Configura la región como GLOBAL para usar el extremo global.

    Restringe el uso del extremo de API global

    Para ayudar a aplicar el uso de extremos regionales, usa la restricción de política de la organización constraints/gcp.restrictEndpointUsage para bloquear las solicitudes al extremo de API global. Para obtener más información, consulta Cómo restringir el uso de extremos.

    ¿Qué sigue?