Chiamare i modelli Vertex AI utilizzando la libreria OpenAI

L'API Chat Completions ti consente di inviare richieste ai modelli Vertex AI utilizzando le librerie OpenAI per Python e REST. Se utilizzi già le librerie OpenAI, puoi utilizzare questa API per passare dall'uso dei modelli OpenAI a quello dei modelli ospitati su Vertex AI per confrontare output, costi e scalabilità senza modificare il codice esistente. Se non utilizzi già le librerie OpenAI, ti consigliamo di chiamare direttamente l'API Gemini.

Modelli supportati

L'API Chat Completions supporta sia i modelli Gemini sia alcuni modelli di deployment autonomo di Model Garden.

Modelli Gemini

La tabella seguente mostra i modelli Gemini supportati:

Modello Versione
Gemini 2.0 Flash google/gemini-2.0-flash
Gemini 1.5 Flash google/gemini-1.5-flash
Gemini 1.5 Pro google/gemini-1.5-pro
Gemini 1.0 Pro Vision google/gemini-1.0-pro-vision
google/gemini-1.0-pro-vision-001
Gemini 1.0 Pro google/gemini-1.0-pro-002
google/gemini-1.0-pro-001
google/gemini-1.0-pro

Modelli di cui è stato eseguito il deployment autonomo da Model Garden

I container Hugging Face Text Generation Interface (HF TGI) e vLLM predefiniti di Vertex AI Model Garden supportano l'API Chat Completions. Tuttavia, non tutti i modelli di cui è stato eseguito il deployment in questi contenitori supportano l'API Chat Completions. La tabella seguente include i modelli supportati più popolari per contenitore:

HF TGI

vLLM

Autentica

Per utilizzare le librerie Python di OpenAI, installa l'SDK OpenAI:

pip install openai

Per autenticarti con l'API Chat Completions, puoi modificare la configurazione del client o la configurazione dell'ambiente per utilizzare l'autenticazione Google e un endpoint Vertex AI. Scegli il metodo più semplice e segui i passaggi per la configurazione a seconda che tu voglia chiamare i modelli Gemini o i modelli di Model Garden di cui hai eseguito il deployment autonomo.

Prima di poter gestire le richieste, alcuni modelli in Model Garden e i modelli Hugging Face supportati devono essere implementati in un endpoint Vertex AI. Quando richiama questi modelli di deployment autonomo dall'API Chat Completions, devi specificare l'ID endpoint. Per elencare gli endpoint Vertex AI esistenti, utilizza il comando gcloud ai endpoints list.

Configurazione del client

Per ottenere le credenziali Google in modo programmatico in Python, puoi utilizzare l'google-auth SDK Python:

pip install google-auth requests

Python

Prima di provare questo esempio, segui le istruzioni di configurazione Python riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python di Vertex AI.

Per autenticarti a Vertex AI, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

import openai

from google.auth import default
import google.auth.transport.requests

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# location = "us-central1"

# Programmatically get an access token
credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
credentials.refresh(google.auth.transport.requests.Request())
# Note: the credential lives for 1 hour by default (https://cloud.google.com/docs/authentication/token-types#at-lifetime); after expiration, it must be refreshed.

##############################
# Choose one of the following:
##############################

# If you are calling a Gemini model, set the ENDPOINT_ID variable to use openapi.
ENDPOINT_ID = "openapi"

# If you are calling a self-deployed model from Model Garden, set the
# ENDPOINT_ID variable and set the client's base URL to use your endpoint.
# ENDPOINT_ID = "YOUR_ENDPOINT_ID"

# OpenAI Client
client = openai.OpenAI(
    base_url=f"https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/{ENDPOINT_ID}",
    api_key=credentials.token,
)

Per impostazione predefinita, i token di accesso sono validi per 1 ora. Puoi prolungare la durata del token di accesso o aggiornare periodicamente il token e aggiornare la variabile openai.api_key.

Variabili di ambiente

Installa Google Cloud CLI. La libreria OpenAI può leggere le variabili di ambiente OPENAI_API_KEY e OPENAI_BASE_URL per modificare l'autenticazione e l'endpoint nel client predefinito. Imposta le seguenti variabili:

$ export PROJECT_ID=PROJECT_ID
$ export LOCATION=LOCATION
$ export OPENAI_API_KEY="$(gcloud auth application-default print-access-token)"

Per chiamare un modello Gemini, imposta la variabile MODEL_ID e utilizza l'endpoint openapi:

$ export MODEL_ID=MODEL_ID
$ export OPENAI_BASE_URL="https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/endpoints/openapi"

Per chiamare un modello di cui è stato eseguito il deployment autonomo da Model Garden, imposta la variabile ENDPOINT e utilizzala nell'URL:

$ export ENDPOINT=ENDPOINT_ID
$ export OPENAI_BASE_URL="https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/endpoints/${ENDPOINT}"

Poi, inizializza il client:

client = openai.OpenAI()

L'API Gemini Chat Completions utilizza OAuth per autenticarsi con un token di accesso a breve durata. Per impostazione predefinita, i token di accesso sono validi per 1 ora. Puoi prolungare la durata del token di accesso o aggiornare periodicamente il token e la variabile di ambiente OPENAI_API_KEY.

Chiamare Gemini con l'API Chat Completions

L'esempio seguente mostra come inviare richieste non in streaming:

curl

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/endpoints/openapi/chat/completions \
  -d '{
    "model": "google/${MODEL_ID}",
    "messages": [{
      "role": "user",
      "content": "Write a story about a magic backpack."
    }]
  }'

Python

Prima di provare questo esempio, segui le istruzioni di configurazione Python riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python di Vertex AI.

Per autenticarti a Vertex AI, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.auth import default
import google.auth.transport.requests

import openai

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# location = "us-central1"

# Programmatically get an access token
credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
credentials.refresh(google.auth.transport.requests.Request())

# OpenAI Client
client = openai.OpenAI(
    base_url=f"https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/openapi",
    api_key=credentials.token,
)

response = client.chat.completions.create(
    model="google/gemini-2.0-flash-001",
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
)

print(response)

L'esempio seguente mostra come inviare richieste di streaming a un modello Gemini utilizzando l'API Chat Completions:

REST

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/endpoints/openapi/chat/completions \
  -d '{
    "model": "google/${MODEL_ID}",
    "stream": true,
    "messages": [{
      "role": "user",
      "content": "Write a story about a magic backpack."
    }]
  }'

Python

Prima di provare questo esempio, segui le istruzioni di configurazione Python riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python di Vertex AI.

Per autenticarti a Vertex AI, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.auth import default
import google.auth.transport.requests

import openai

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# location = "us-central1"

# Programmatically get an access token
credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
credentials.refresh(google.auth.transport.requests.Request())

# OpenAI Client
client = openai.OpenAI(
    base_url=f"https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/openapi",
    api_key=credentials.token,
)

response = client.chat.completions.create(
    model="google/gemini-2.0-flash-001",
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
    stream=True,
)
for chunk in response:
    print(chunk)

Chiamare un modello di cui è stato eseguito il deployment autonomo con l'API Chat Completions

L'esempio seguente mostra come inviare richieste non in streaming:

REST

  curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/endpoints/${ENDPOINT}/chat/completions \
  -d '{
    "messages": [{
      "role": "user",
      "content": "Write a story about a magic backpack."
    }]
  }'

Python

Prima di provare questo esempio, segui le istruzioni di configurazione Python riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python di Vertex AI.

Per autenticarti a Vertex AI, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.auth import default
import google.auth.transport.requests

import openai

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# location = "us-central1"
# model_id = "gemma-2-9b-it"
# endpoint_id = "YOUR_ENDPOINT_ID"

# Programmatically get an access token
credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
credentials.refresh(google.auth.transport.requests.Request())

# OpenAI Client
client = openai.OpenAI(
    base_url=f"https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/{endpoint_id}",
    api_key=credentials.token,
)

response = client.chat.completions.create(
    model=model_id,
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
)
print(response)

L'esempio seguente mostra come inviare richieste in streaming a un modello di cui è stato eseguito il deployment autonomamente utilizzando l'API Chat Completions:

REST

    curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
    https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/endpoints/${ENDPOINT}/chat/completions \
    -d '{
      "stream": true,
      "messages": [{
        "role": "user",
        "content": "Write a story about a magic backpack."
      }]
    }'

Python

Prima di provare questo esempio, segui le istruzioni di configurazione Python riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python di Vertex AI.

Per autenticarti a Vertex AI, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

from google.auth import default
import google.auth.transport.requests

import openai

# TODO(developer): Update and un-comment below lines
# project_id = "PROJECT_ID"
# location = "us-central1"
# model_id = "gemma-2-9b-it"
# endpoint_id = "YOUR_ENDPOINT_ID"

# Programmatically get an access token
credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
credentials.refresh(google.auth.transport.requests.Request())

# OpenAI Client
client = openai.OpenAI(
    base_url=f"https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/{endpoint_id}",
    api_key=credentials.token,
)

response = client.chat.completions.create(
    model=model_id,
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
    stream=True,
)
for chunk in response:
    print(chunk)

Parametri supportati

Per i modelli Google, l'API Chat Completions supporta i seguenti parametri OpenAI. Per una descrizione di ciascun parametro, consulta la documentazione di OpenAI sulla creazione di completamenti di chat. Il supporto dei parametri per i modelli di terze parti varia in base al modello. Per sapere quali parametri sono supportati, consulta la documentazione del modello.

messages
  • System message
  • User message: sono supportati i tipi text e image_url. Il tipo image_url supporta le immagini memorizzate in un URI Cloud Storage o in una codifica base 64 nel formato "data:<MIME-TYPE>;base64,<BASE64-ENCODED-BYTES>". Per scoprire come creare un bucket Cloud Storage e caricarvi un file, consulta Scopri lo spazio di archiviazione degli oggetti. L'opzione detail non è supportata.
  • Assistant message
  • Tool message
  • Function message: questo campo è deprecato, ma supportato per la compatibilità con le versioni precedenti.
model
max_tokens
n
frequency_penalty
presence_penalty
response_format
  • json_object: interpretato come passaggio di "application/json" all'API Gemini.
  • text: interpretato come passaggio di "text/plain" all'API Gemini.
  • Qualsiasi altro tipo MIME viene passato così com'è al modello, ad esempio passando direttamente "application/json".
stop
stream
temperature
top_p
tools
  • type
  • function
    • name
    • description
    • parameters: specifica i parametri utilizzando la specifica OpenAPI. È diverso dal campo dei parametri OpenAI, che è descritto come oggetto JSON Schema. Per scoprire le differenze tra le parole chiave di OpenAPI e JSON Schema, consulta la guida di OpenAPI.
tool_choice
  • none
  • auto
  • required: corrisponde alla modalità ANY in FunctionCallingConfig.
function_call Questo campo è deprecato, ma supportato per la compatibilità con le versioni precedenti.
functions Questo campo è deprecato, ma supportato per la compatibilità con le versioni precedenti.

Se passi un parametro non supportato, questo viene ignorato.

Aggiorna le credenziali

L'esempio seguente mostra come aggiornare automaticamente le credenziali in base alle necessità:

Python 

from typing import Any

import google.auth
import google.auth.transport.requests
import openai


class OpenAICredentialsRefresher:
    def __init__(self, **kwargs: Any) -> None:
        # Set a placeholder key here
        self.client = openai.OpenAI(**kwargs, api_key="PLACEHOLDER")
        self.creds, self.project = google.auth.default(
            scopes=["https://www.googleapis.com/auth/cloud-platform"]
        )

    def __getattr__(self, name: str) -> Any:
        if not self.creds.valid:
            self.creds.refresh(google.auth.transport.requests.Request())

            if not self.creds.valid:
                raise RuntimeError("Unable to refresh auth")

            self.client.api_key = self.creds.token
        return getattr(self.client, name)



    # TODO(developer): Update and un-comment below lines
    # project_id = "PROJECT_ID"
    # location = "us-central1"

    client = OpenAICredentialsRefresher(
        base_url=f"https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/openapi",
    )

    response = client.chat.completions.create(
        model="google/gemini-2.0-flash-001",
        messages=[{"role": "user", "content": "Why is the sky blue?"}],
    )

    print(response)

Passaggi successivi