Chiamare i modelli Vertex AI utilizzando la libreria OpenAI

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

L'API Chat Completions funziona come endpoint compatibile con Open AI, progettata per semplificare l'interfaccia con Gemini su Vertex AI utilizzando le librerie OpenAI per Python e REST. Se utilizzi già le librerie OpenAI, puoi utilizzare questa API come un modo economico per passare dall'uso dei modelli OpenAI a quello dei modelli ospitati su Vertex AI per confrontare l'output, i costi e la scalabilità, senza modificare il codice esistente. Ciò contribuisce a garantire la compatibilità tra i fornitori e la coerenza con gli standard della community. Se non utilizzi già le librerie OpenAI, ti consigliamo di utilizzare l'SDK Google Gen AI.

Modelli supportati

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

Modelli Gemini

I seguenti modelli forniscono supporto per l'API Chat Completions:

• Gemini 2.5 Pro
• Gemini 2.5 Flash
• Gemini 2.0 Flash
• Gemini 2.0 Flash-Lite

Modelli con 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:

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.

pip install google-auth requests

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,
)

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

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

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

client = openai.OpenAI()

Chiamare Gemini con l'API Chat Completions

Il seguente esempio mostra come inviare richieste non in streaming:

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

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:

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

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

Il seguente esempio mostra come inviare richieste non in streaming:

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

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:

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

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.

Se passi un parametro non supportato, questo viene ignorato.

Configurare i parametri specifici di Gemini

Gemini supporta diverse funzionalità non disponibili nei modelli OpenAI. Queste funzionalità possono comunque essere passate come parametri, ma devono essere contenute in un extra_content o extra_body, altrimenti verranno ignorate.

extra_body funzionalità

extra_body esempi

Puoi utilizzare l'SDK o l'API REST per passare extra_body.

Aggiungi thought_tag_marker

{
  ...,
  "extra_body": {
     "google": {
       ...,
       "thought_tag_marker": "..."
     }
   }
}

Aggiungere extra_body utilizzando l'SDK

client.chat.completions.create(
  ...,
  extra_body = {
    'extra_body': { 'google': { ... } }
  },
)

extra_content funzionalità

extra_content ti consente di specificare impostazioni aggiuntive a livello di Part.

extra_content esempi

Puoi compilare questo campo utilizzando direttamente l'API REST.

extra_content con stringa content

{
  "messages": [
    { "role": "...", "content": "...", "extra_content": { "google": { ... } } }
  ]
}

Per messaggio extra_content

{
  "messages": [
    {
      "role": "...",
      "content": [
        { "type": "...", ..., "extra_content": { "google": { ... } } }
      ]
    }
}

Chiamata per strumento extra_content

{
  "messages": [
    {
      "role": "...",
      "tool_calls": [
        {
          ...,
          "extra_content": { "google": { ... } }
        }
      ]
    }
  ]
}

Richieste curl di esempio

Puoi utilizzare queste richieste curl direttamente, anziché tramite l'SDK.

Richieste multimodali

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/endpoints/openapi/chat/completions \
  -d '{ \
    "model": "google/gemini-2.0-flash-001", \
    "messages": [ \
      { "role": "user", \
        "content": [ \
          { "type": "text", "text": "Summarize the main points of this audio file: " }, \
          { "type": "input_audio", "input_audio": { \
            "format": "audio/mp3", \
            "data": "gs://cloud-samples-data/generative-ai/audio/pixel.mp3" } }] }] }'

Output strutturato

Puoi utilizzare il parametro response_format per ottenere un output strutturato.

Esempio di utilizzo dell'SDK

from pydantic import BaseModel
from openai import OpenAI

client = OpenAI()

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

completion = client.beta.chat.completions.parse(
    model="google/gemini-2.5-flash-preview-04-17",
    messages=[
        {"role": "system", "content": "Extract the event information."},
        {"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
    ],
    response_format=CalendarEvent,
)

print(completion.choices[0].message.parsed)

Aggiorna le credenziali

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

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

• Consulta gli esempi di chiamata dell'API Inference con la sintassi compatibile con OpenAI.
• Consulta gli esempi di chiamata dell'API di chiamata delle funzioni con sintassi compatibile con OpenAI.
• Scopri di più sull'API Gemini.
• Scopri di più sulla migrazione da Azure OpenAI all'API Gemini.