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 di modelli OpenAI a quello di 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 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 HuggingFace 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
pip install requests

Modifica l'SDK OpenAI in modo che punti all'endpoint di completamento chat di Vertex AI:

# Programmatically get an access token
creds, project = google.auth.default()
auth_req = google.auth.transport.requests.Request()
creds.refresh(auth_req)
# 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.

# Pass the Vertex endpoint and authentication to the OpenAI SDK
PROJECT_ID = 'PROJECT_ID'
LOCATION = 'LOCATION'

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

# If you are calling a Gemini model, set the MODEL_ID variable and set
# your client's base URL to use openapi.
MODEL_ID = 'MODEL_ID'
client = openai.OpenAI(
    base_url = f'https://{LOCATION}-aiplatform.googleapis.com/v1beta1/projects/{PROJECT_ID}/locations/{LOCATION}/endpoints/openapi',
    api_key = creds.token)

# If you are calling a self-deployed model from Model Garden, set the
# ENDPOINT_ID variable and set your client's base URL to use your endpoint.
MODEL_ID = 'MODEL_ID'
client = openai.OpenAI(
    base_url = f'https://{LOCATION}-aiplatform.googleapis.com/v1beta1/projects/{PROJECT_ID}/locations/{LOCATION}/endpoints/{ENDPOINT}',
    api_key = creds.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

Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 

import vertexai
import openai

from google.auth import default, transport

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
location = "us-central1"

vertexai.init(project=PROJECT_ID, location=location)

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

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

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

print(response.choices[0].message.content)
# Example response:
# The sky is blue due to a phenomenon called **Rayleigh scattering**.
# Sunlight is made up of all the colors of the rainbow.
# As sunlight enters the Earth's atmosphere ...

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

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}",
    "stream": true,
    "messages": [{
      "role": "user",
      "content": "Write a story about a magic backpack."
    }]
  }'

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 

import vertexai
import openai

from google.auth import default, transport

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
location = "us-central1"

vertexai.init(project=PROJECT_ID, location=location)

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

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

response = client.chat.completions.create(
    model="google/gemini-1.5-flash-002",
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
    stream=True,
)
for chunk in response:
    print(chunk.choices[0].delta.content)
# Example response:
# The sky is blue due to a phenomenon called **Rayleigh scattering**. Sunlight is
# made up of all the colors of the rainbow. When sunlight enters the Earth 's atmosphere,
# it collides with tiny air molecules (mostly nitrogen and oxygen). ...

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:

  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."
    }]
  }'

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

  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."
    }]
  }'

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 dummy key here
        self.client = openai.OpenAI(**kwargs, api_key="DUMMY")
        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:
            auth_req = google.auth.transport.requests.Request()
            self.creds.refresh(auth_req)

            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 line
# PROJECT_ID = "your-project-id"
location = "us-central1"

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

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

print(response.choices[0].message.content)
# Example response:
# The sky is blue due to a phenomenon called **Rayleigh scattering**.
# Sunlight is made up of all the colors of the rainbow.
# When sunlight enters the Earth's atmosphere, it collides with ...

Passaggi successivi