Chiamare le API MaaS per i modelli aperti

Molti modelli aperti su Gemini Enterprise Agent Platform offrono modelli completamente gestiti e serverless come API utilizzando l'API Chat Completions di Gemini Enterprise Agent Platform. Per questi modelli, non è necessario eseguire il provisioning o gestire l'infrastruttura.

Puoi riprodurre in streaming le risposte per ridurre la percezione della latenza da parte dell'utente finale. Una risposta in streaming utilizza gli eventi inviati dal server (SSE) per trasmettere in modo incrementale la risposta.

Questa pagina mostra come effettuare chiamate in modalità flusso e non flusso ai modelli aperti che supportano l'API OpenAI Chat Completions. Per considerazioni specifiche su Llama, consulta Richiedi previsioni Llama.

Prima di iniziare

Per utilizzare i modelli aperti con Gemini Enterprise Agent Platform, devi eseguire i seguenti passaggi. Per utilizzare i modelli aperti su Gemini Enterprise Agent Platform, è necessario abilitare l'API Agent Platform (aiplatform.googleapis.com) e l'API Cloud Commerce Consumer Procurement (cloudcommerceconsumerprocurement.googleapis.com). Se hai già un progetto esistente con queste API abilitate, puoi utilizzarlo anziché crearne uno nuovo.

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.
  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. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

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

  5. Enable the Gemini Enterprise Agent Platform and Cloud Commerce Consumer Procurement APIs, if any are not already enabled.

    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 APIs

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

  7. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

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

  9. Enable the Gemini Enterprise Agent Platform and Cloud Commerce Consumer Procurement APIs, if any are not already enabled.

    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 APIs

  10. Vai alla scheda del modello in Model Garden per il modello che vuoi utilizzare, quindi fai clic su Abilita per abilitare il modello da utilizzare nel tuo progetto.

    Vai a Model Garden

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per abilitare e utilizzare i modelli aperti, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Per saperne di più sulla concessione delle autorizzazioni e sulla configurazione delle policy dell'organizzazione per i modelli aperti, consulta Concedi agli utenti l'accesso ai modelli aperti.

Effettua una chiamata in streaming a un modello aperto

L'esempio seguente effettua una chiamata in modalità flusso di dati a un modello aperto:

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

Prima di eseguire questo esempio, assicurati di impostare la variabile di ambiente OPENAI_BASE_URL. Per saperne di più, consulta Autenticazione e credenziali.

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: il nome del modello che vuoi utilizzare, ad esempio openai/gpt-oss-120b-maas.
  • ROLE: il ruolo associato a un messaggio. Puoi specificare un user o un assistant. Il primo messaggio deve utilizzare il ruolo user. I modelli operano con turni alternati di user e assistant. Se il messaggio finale utilizza il ruolo assistant, i contenuti della risposta continuano immediatamente dai contenuti di quel messaggio. Puoi utilizzarlo per limitare parte della risposta del modello.
  • CONTENT: i contenuti, ad esempio il testo, del messaggio user o assistant.
  • MAX_OUTPUT_TOKENS: Numero massimo di token che possono essere generati nella risposta. Un token equivale a circa quattro caratteri. 100 token corrispondono a circa 60-80 parole.

    Specifica un valore più basso per risposte più brevi e un valore più alto per risposte potenzialmente più lunghe.

REST

Dopo aver configurato l'ambiente, puoi utilizzare REST per testare un prompt testuale. L'esempio seguente invia una richiesta all'endpoint del modello del publisher.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: l'ID progetto Google Cloud.
  • MODEL: il nome del modello che vuoi utilizzare, ad esempio openai/gpt-oss-120b-maas.
  • ROLE: il ruolo associato a un messaggio. Puoi specificare un user o un assistant. Il primo messaggio deve utilizzare il ruolo user. I modelli operano con turni alternati di user e assistant. Se il messaggio finale utilizza il ruolo assistant, i contenuti della risposta continuano immediatamente dai contenuti di quel messaggio. Puoi utilizzarlo per limitare parte della risposta del modello.
  • CONTENT: i contenuti, ad esempio il testo, del messaggio user o assistant.
  • MAX_OUTPUT_TOKENS: Numero massimo di token che possono essere generati nella risposta. Un token equivale a circa quattro caratteri. 100 token corrispondono a circa 60-80 parole.

    Specifica un valore più basso per risposte più brevi e un valore più alto per risposte potenzialmente più lunghe.

  • STREAM: un valore booleano che specifica se la risposta viene trasmessa in streaming o meno. Trasmetti in streaming la risposta per ridurre la percezione della latenza da parte dell'utente finale. Imposta su true per trasmettere la risposta in streaming e su false per restituire la risposta in una sola volta.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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

Dovresti ricevere una risposta JSON simile alla seguente.

Effettua una chiamata non in streaming a un modello aperto

L'esempio seguente effettua una chiamata non in streaming a un modello aperto:

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

Prima di eseguire questo esempio, assicurati di impostare la variabile di ambiente OPENAI_BASE_URL. Per saperne di più, consulta Autenticazione e credenziali.

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: il nome del modello che vuoi utilizzare, ad esempio openai/gpt-oss-120b-maas.
  • ROLE: il ruolo associato a un messaggio. Puoi specificare un user o un assistant. Il primo messaggio deve utilizzare il ruolo user. I modelli operano con turni alternati di user e assistant. Se il messaggio finale utilizza il ruolo assistant, i contenuti della risposta continuano immediatamente dai contenuti di quel messaggio. Puoi utilizzarlo per limitare parte della risposta del modello.
  • CONTENT: i contenuti, ad esempio il testo, del messaggio user o assistant.
  • MAX_OUTPUT_TOKENS: Numero massimo di token che possono essere generati nella risposta. Un token equivale a circa quattro caratteri. 100 token corrispondono a circa 60-80 parole.

    Specifica un valore più basso per risposte più brevi e un valore più alto per risposte potenzialmente più lunghe.

REST

Dopo aver configurato l'ambiente, puoi utilizzare REST per testare un prompt testuale. L'esempio seguente invia una richiesta all'endpoint del modello del publisher.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: l'ID progetto Google Cloud.
  • MODEL: il nome del modello che vuoi utilizzare, ad esempio openai/gpt-oss-120b-maas.
  • ROLE: il ruolo associato a un messaggio. Puoi specificare un user o un assistant. Il primo messaggio deve utilizzare il ruolo user. I modelli operano con turni alternati di user e assistant. Se il messaggio finale utilizza il ruolo assistant, i contenuti della risposta continuano immediatamente dai contenuti di quel messaggio. Puoi utilizzarlo per limitare parte della risposta del modello.
  • CONTENT: i contenuti, ad esempio il testo, del messaggio user o assistant.
  • MAX_OUTPUT_TOKENS: Numero massimo di token che possono essere generati nella risposta. Un token equivale a circa quattro caratteri. 100 token corrispondono a circa 60-80 parole.

    Specifica un valore più basso per risposte più brevi e un valore più alto per risposte potenzialmente più lunghe.

  • STREAM: un valore booleano che specifica se la risposta viene trasmessa in streaming o meno. Trasmetti in streaming la risposta per ridurre la percezione della latenza da parte dell'utente finale. Imposta su true per trasmettere la risposta in streaming e su false per restituire la risposta in una sola volta.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/chat/completions"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

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

Dovresti ricevere una risposta JSON simile alla seguente.

Endpoint globali e regionali

Per gli endpoint regionali, le richieste vengono gestite dalla regione specificata. Se hai requisiti di residenza dei dati o se un modello non supporta l'endpoint globale, utilizza gli endpoint regionali.

Quando utilizzi l'endpoint globale, Google può elaborare e gestire le tue richieste da qualsiasi regione supportata dal modello che stai utilizzando. In alcuni casi, ciò potrebbe comportare una latenza più elevata. L'endpoint globale contribuisce a migliorare la disponibilità complessiva e a ridurre gli errori.

Non esiste alcuna differenza di prezzo con gli endpoint regionali quando utilizzi l'endpoint globale. Tuttavia, le quote degli endpoint globali e le funzionalità dei modelli supportati possono differire da quelle degli endpoint regionali. Per saperne di più, consulta la pagina del modello di terze parti correlato.

Specifica l'endpoint globale

Per utilizzare l'endpoint globale, imposta la regione su global.

Ad esempio, l'URL della richiesta per un comando curl utilizza il seguente formato: https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi

Per l'SDK Agent Platform, l'endpoint predefinito è a livello di regione. Imposta la regione su GLOBAL per utilizzare l'endpoint globale.

Limita l'utilizzo degli endpoint API globali

Per contribuire a imporre l'utilizzo di endpoint regionali, utilizza il vincolo delle policy dell'organizzazione constraints/gcp.restrictEndpointUsage per bloccare le richieste all'endpoint API globale. Per saperne di più, consulta Limita l'utilizzo degli endpoint.

Passaggi successivi