Esta página se ha traducido con Cloud Translation API.

Llamar a las APIs de MaaS para modelos abiertos

Muchos modelos abiertos de Vertex AI ofrecen modelos totalmente gestionados y sin servidor como APIs mediante la API Chat Completions de Vertex AI. En el caso de estos modelos, no es necesario aprovisionar ni gestionar la infraestructura.

Puedes transmitir tus respuestas para reducir la latencia que perciben los usuarios finales. Una respuesta en streaming usa eventos enviados por el servidor (SSE) para enviar la respuesta de forma incremental.

En esta página se explica cómo hacer llamadas de streaming y no de streaming a modelos abiertos que admitan la API Chat Completions de OpenAI. Para ver consideraciones específicas de Llama, consulta Solicitar predicciones de Llama.

Antes de empezar

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

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.

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

Verify that billing is enabled for your Google Cloud project.

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

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

Verify that billing is enabled for your Google Cloud project.

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

Ve a la tarjeta del modelo de Model Garden que quieras usar y haz clic en Habilitar para habilitarlo en tu proyecto.
Ir a Model Garden

Hacer una llamada de streaming a un modelo abierto

En el siguiente ejemplo se hace una llamada de streaming a un modelo abierto:

Python

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

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.

Antes de ejecutar este ejemplo, asegúrate de definir 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 quieras 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 funcionan con turnos alternos de user y assistant. Si el mensaje final usa el rol assistant, el contenido de la respuesta continúa inmediatamente a partir del contenido de ese mensaje. Puedes usarlo para restringir parte de la respuesta del modelo.
CONTENT: el contenido, como el texto, del mensaje user o assistant.
MAX_OUTPUT_TOKENS: Número máximo de tokens que se pueden generar en la respuesta. Un token tiene aproximadamente cuatro caracteres. 100 tokens corresponden aproximadamente a entre 60 y 80 palabras.
Especifica un valor inferior para las respuestas más cortas y un valor superior para las respuestas que puedan ser más largas.

REST

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

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

LOCATION: una región que admite modelos abiertos.
MODEL: el nombre del modelo que quieras 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 funcionan con turnos alternos de user y assistant. Si el mensaje final usa el rol assistant, el contenido de la respuesta continúa inmediatamente a partir del contenido de ese mensaje. Puedes usarlo para restringir parte de la respuesta del modelo.
CONTENT: el contenido, como el texto, del mensaje user o assistant.
MAX_OUTPUT_TOKENS: Número máximo de tokens que se pueden generar en la respuesta. Un token tiene aproximadamente cuatro caracteres. 100 tokens corresponden aproximadamente a entre 60 y 80 palabras.
Especifica un valor inferior para las respuestas más cortas y un valor superior para las respuestas que puedan ser más largas.
STREAM: valor booleano que especifica si la respuesta se transmite o no. Transmite tu respuesta para reducir la percepción de latencia del usuario final. Defínelo como true para transmitir la respuesta y false para devolver la respuesta de una 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

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar la cuenta activa, ejecuta el comando gcloud auth list.

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

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar la cuenta activa, ejecuta el comando gcloud auth list.

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 siguiente.

Respuesta

data: {
  "choices": [
    {
      "delta": {
        "content": "CONTENT",
        "role": "assistant"
      },
      "index": 0,
      "logprobs": null
    }
  ],
  "created": 1234567890,
  "id": "2025-06-11|10:00:00.292195-07|9.7.144.202|-123456789",
  "model": "MODEL",
  "object": "chat.completion.chunk",
  "system_fingerprint": ""
}

data: {
  "choices": [
    {
      "delta": {
        "content": "CONTENT",
        "role": "assistant"
      },
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null
    }
  ],
  "created": 1234567890,
  "id": "2025-06-11|10:00:00.292195-07|9.7.144.202|-123456789",
  "model": "MODEL",
  "object": "chat.completion.chunk",
  "system_fingerprint": "",
  "usage": {
    "completion_tokens": 131,
    "prompt_tokens": 14,
    "total_tokens": 145
  }
}

data: [DONE]

Hacer una llamada que no sea de streaming a un modelo abierto

En el siguiente ejemplo se hace una llamada sin streaming a un modelo abierto:

Python

Antes de ejecutar este ejemplo, asegúrate de definir 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 quieras 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 funcionan con turnos alternos de user y assistant. Si el mensaje final usa el rol assistant, el contenido de la respuesta continúa inmediatamente a partir del contenido de ese mensaje. Puedes usarlo para restringir parte de la respuesta del modelo.
CONTENT: el contenido, como el texto, del mensaje user o assistant.
MAX_OUTPUT_TOKENS: Número máximo de tokens que se pueden generar en la respuesta. Un token tiene aproximadamente cuatro caracteres. 100 tokens corresponden aproximadamente a entre 60 y 80 palabras.
Especifica un valor inferior para las respuestas más cortas y un valor superior para las respuestas que puedan ser más largas.

REST

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

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

LOCATION: una región que admite modelos abiertos.
MODEL: el nombre del modelo que quieras 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 funcionan con turnos alternos de user y assistant. Si el mensaje final usa el rol assistant, el contenido de la respuesta continúa inmediatamente a partir del contenido de ese mensaje. Puedes usarlo para restringir parte de la respuesta del modelo.
CONTENT: el contenido, como el texto, del mensaje user o assistant.
MAX_OUTPUT_TOKENS: Número máximo de tokens que se pueden generar en la respuesta. Un token tiene aproximadamente cuatro caracteres. 100 tokens corresponden aproximadamente a entre 60 y 80 palabras.
Especifica un valor inferior para las respuestas más cortas y un valor superior para las respuestas que puedan ser más largas.
STREAM: valor booleano que especifica si la respuesta se transmite o no. Transmite tu respuesta para reducir la percepción de latencia del usuario final. Defínelo como true para transmitir la respuesta y false para devolver la respuesta de una 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 siguiente.

Respuesta

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "CONTENT",
        "role": "assistant"
      }
    }
  ],
  "created": 1234567890,
  "id": "2025-06-11|10:00:00.292195-07|9.7.144.202|-123456789",
  "model": "MODEL",
  "object": "chat.completion",
  "system_fingerprint": "",
  "usage": {
    "completion_tokens": 367,
    "prompt_tokens": 14,
    "total_tokens": 381
  }
}

Puntos finales regionales y globales

En el caso de los endpoints regionales, las solicitudes se atienden desde la región especificada. En los casos en los que tengas requisitos de residencia de datos o si un modelo no admite el endpoint global, usa los endpoints regionales.

Cuando usas el endpoint global, Google puede procesar y responder a tus solicitudes desde cualquier región admitida por el modelo que estés usando. Esto puede provocar una latencia mayor en algunos casos. El endpoint global ayuda a mejorar la disponibilidad general y a reducir los errores.

No hay ninguna diferencia de precio con los endpoints regionales cuando se usa el endpoint global. Sin embargo, las cuotas de los endpoints globales y las funciones de los modelos admitidos pueden ser diferentes a las de los endpoints regionales. Para obtener más información, consulta la página del modelo de terceros correspondiente.

Especificar el endpoint global

Para usar el endpoint global, define la región como global.

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

En el SDK de Vertex AI, el endpoint regional es el predeterminado. Asigna el valor GLOBAL a la región para usar el endpoint global.

Restringir el uso de endpoints de API globales

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

Siguientes pasos

Consulta cómo usar llamadas a funciones.
Consulta información sobre la salida estructurada.
Consulta información sobre las predicciones por lotes.