Llama a las APIs de MaaS para modelos abiertos

Muchos modelos abiertos en Gemini Enterprise Agent Platform ofrecen modelos completamente administrados y sin servidores como APIs con la API de Chat Completions de Gemini Enterprise Agent Platform. 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 Gemini Enterprise Agent Platform, debes seguir estos pasos. La API de Agent Platform (aiplatform.googleapis.com) debe estar habilitada para usar Gemini Enterprise Agent Platform. Si ya tienes un proyecto existente con la API de Agent Platform habilitada, puedes usar ese proyecto en lugar de crear uno nuevo.

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

  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 role (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 Gemini Enterprise Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). 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 role (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 Gemini Enterprise Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). 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

Realiza 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 que encontrarás en la guía de inicio rápido de Agent Platform sobre cómo usar bibliotecas cliente.

Para autenticarte en Agent Platform, configura las credenciales predeterminadas de la aplicación. Para 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: Es 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: Es 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 que encontrarás en la guía de inicio rápido de Agent Platform sobre cómo usar bibliotecas cliente.

Para autenticarte en Agent Platform, configura las credenciales predeterminadas de la aplicación. Para 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: Es 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: Es 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 atienden 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 endpoint 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 admitidas 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 caso del SDK de Agent Platform, se usa un extremo regional de forma predeterminada. Configura la región en GLOBAL para usar el extremo global.

Restringe el uso del extremo de API global

Para ayudar a aplicar de manera forzosa el uso de extremos regionales, usa la restricción de políticas 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?