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.
- 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.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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.
-
Verify that billing is enabled for your Google Cloud project.
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.enablepermission. 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.-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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.
-
Verify that billing is enabled for your Google Cloud project.
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.enablepermission. 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.- 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.
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:
- Utente della piattaforma agente (
roles/aiplatform.user) - Consumer Procurement Entitlement Manager (
roles/consumerprocurement.entitlementManager)
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
usero unassistant. Il primo messaggio deve utilizzare il ruolouser. I modelli operano con turni alternati diusereassistant. Se il messaggio finale utilizza il ruoloassistant, 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
useroassistant. - 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
usero unassistant. Il primo messaggio deve utilizzare il ruolouser. I modelli operano con turni alternati diusereassistant. Se il messaggio finale utilizza il ruoloassistant, 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
useroassistant. - 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
trueper trasmettere la risposta in streaming e sufalseper 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
usero unassistant. Il primo messaggio deve utilizzare il ruolouser. I modelli operano con turni alternati diusereassistant. Se il messaggio finale utilizza il ruoloassistant, 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
useroassistant. - 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
usero unassistant. Il primo messaggio deve utilizzare il ruolouser. I modelli operano con turni alternati diusereassistant. Se il messaggio finale utilizza il ruoloassistant, 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
useroassistant. - 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
trueper trasmettere la risposta in streaming e sufalseper 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
- Scopri come utilizzare la chiamata di funzione.
- Scopri di più sull'output strutturato.
- Scopri di più sulle previsioni in batch.