Chiamare le API MaaS per i modelli aperti

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

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

Questa pagina mostra come effettuare chiamate in streaming e non in streaming a modelli aperti che supportano l'API OpenAI Chat Completions. Per considerazioni specifiche per Llama, vedi Richiedere previsioni Llama.

Prima di iniziare

Per utilizzare i modelli aperti con Vertex AI, devi eseguire i seguenti passaggi. L'API Vertex AI (aiplatform.googleapis.com) deve essere abilitata per utilizzare Vertex AI. Se hai già un progetto esistente con l'API Vertex AI abilitata, puoi utilizzare questo progetto anziché crearne uno nuovo.

  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. Vai alla scheda del modello Model Garden per il modello che vuoi utilizzare, poi fai clic su Abilita per abilitare il modello per l'utilizzo nel tuo progetto.

    Vai a Model Garden

    9. Fai una chiamata di streaming a un modello aperto

    L'esempio seguente esegue una chiamata di streaming a un modello aperto:

    Python

    Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Vertex AI per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Vertex AI Python.

    Per eseguire l'autenticazione in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, 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 ulteriori informazioni, vedi 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 deepseek-ai/deepseek-v3.1-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 funzionano con turni alternati user e assistant. Se il messaggio finale utilizza il ruolo assistant, il contenuto della risposta continua immediatamente dal contenuto di quel messaggio. Puoi utilizzare questo parametro per vincolare una 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 di testo. Il seguente esempio invia una richiesta all'endpoint del modello del publisher.

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

    • LOCATION: una regione che supporta modelli aperti.
    • MODEL: il nome del modello che vuoi utilizzare, ad esempio deepseek-ai/deepseek-v2.
    • ROLE: Il ruolo associato a un messaggio. Puoi specificare un user o un assistant. Il primo messaggio deve utilizzare il ruolo user. I modelli funzionano con turni alternati user e assistant. Se il messaggio finale utilizza il ruolo assistant, il contenuto della risposta continua immediatamente dal contenuto di quel messaggio. Puoi utilizzare questo parametro per vincolare una 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 di utilizzo finale. Imposta su true per trasmettere in streaming la risposta e su false per restituire la risposta tutta in una volta.

    Metodo HTTP e URL: 

    POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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, ed esegui questo 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

    Salva il corpo della richiesta in un file denominato request.json, ed esegui questo 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

    Dovresti ricevere una risposta JSON simile alla seguente.

    Fai una chiamata non in streaming a un modello aperto

    Il seguente esempio esegue 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 Vertex AI per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Vertex AI Python.

    Per eseguire l'autenticazione in Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, 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 ulteriori informazioni, vedi 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 deepseek-ai/deepseek-v3.1-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 funzionano con turni alternati user e assistant. Se il messaggio finale utilizza il ruolo assistant, il contenuto della risposta continua immediatamente dal contenuto di quel messaggio. Puoi utilizzare questo parametro per vincolare una 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 di testo. Il seguente esempio invia una richiesta all'endpoint del modello del publisher.

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

    • LOCATION: una regione che supporta modelli aperti.
    • MODEL: il nome del modello che vuoi utilizzare, ad esempio deepseek-ai/deepseek-v2.
    • ROLE: Il ruolo associato a un messaggio. Puoi specificare un user o un assistant. Il primo messaggio deve utilizzare il ruolo user. I modelli funzionano con turni alternati user e assistant. Se il messaggio finale utilizza il ruolo assistant, il contenuto della risposta continua immediatamente dal contenuto di quel messaggio. Puoi utilizzare questo parametro per vincolare una 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 di utilizzo finale. Imposta su true per trasmettere in streaming la risposta e su false per restituire la risposta tutta in una volta.

    Metodo HTTP e URL: 

    POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/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, ed esegui questo 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

    Salva il corpo della richiesta in un file denominato request.json, ed esegui questo 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

    Dovresti ricevere una risposta JSON simile alla seguente.

    Endpoint regionali e globali

    Per gli endpoint regionali, le richieste vengono gestite dalla regione specificata. Nei casi in cui 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 maggiore. L'endpoint globale contribuisce a migliorare la disponibilità complessiva e a ridurre gli errori.

    Non c'è 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 Vertex AI, un endpoint regionale è il valore predefinito. 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 Limitare l'utilizzo degli endpoint.

    Passaggi successivi