Chamar modelos da Vertex AI usando a biblioteca OpenAI

Com a API Chat Autocomplete, é possível enviar solicitações para modelos da Vertex AI usando as bibliotecas da OpenAI para Python e REST. Se você já estiver usando as bibliotecas OpenAI, poderá usar esta API para alternar entre chamar modelos OpenAI e modelos hospedados do Vertex AI para comparar resultados, custos e escalabilidade, sem mudar o código atual. Se você ainda não usa as bibliotecas OpenAI, recomendamos chamar a API Gemini diretamente.

Modelos compatíveis

A API Chat Completions oferece suporte a modelos do Gemini e a alguns modelos autoimplantados do Model Garden.

Modelos do Gemini

A tabela a seguir mostra os modelos do Gemini compatíveis:

Modelo Versão
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

Modelos autoimplantados do Model Garden

O Interface de geração de texto Hugging Face (HF TGI) (link em inglês) e os contêineres de vLLM pré-criados do Model Garden da Vertex AI têm suporte à API Chat Completions. No entanto, nem todos os modelos implantados nesses contêineres são compatíveis com a API Chat Completions. A tabela a seguir inclui os modelos com suporte mais conhecidos por contêiner:

HF TGI

vLLM

Autenticar

Para usar as bibliotecas OpenAI Python, instale o OpenAI SDK:

pip install openai

Para autenticar com a API Chat Completions, você pode modificar a configuração do cliente ou alterar a configuração do ambiente para usar a autenticação do Google e um endpoint da Vertex AI. Escolha o método mais fácil e siga as etapas de configuração, dependendo se você quer chamar modelos do Gemini ou do Model Garden autoimplantado.

Certos modelos no Grupo de modelos e modelos Hugging Face com suporte precisam ser implantadas em um endpoint da Vertex AI antes de veicular solicitações. Ao chamar esses modelos autoimplantados da API Chat Completions, é necessário especificar o ID do endpoint. Para listar seus endpoints atuais da Vertex AI, use o comando gcloud ai endpoints list.

Configuração do cliente

Para obter credenciais do Google de maneira programática em Python, use o SDK Python google-auth:

pip install google-auth requests

Python

Antes de testar esse exemplo, siga as instruções de configuração para Python no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Python.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

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

Por padrão, os tokens de acesso duram 1 hora. Você pode prolongar a vida útil do seu token de acesso ou atualizá-lo periodicamente e atualizar a variável openai.api_key.

Variáveis de ambiente

Instale a CLI do Google Cloud. A biblioteca OpenAI pode ler as variáveis de ambiente OPENAI_API_KEY e OPENAI_BASE_URL para alterar a autenticação e o endpoint no cliente padrão. Configure as variáveis a seguir:

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

Para chamar um modelo do Gemini, defina o MODEL_ID e use o endpoint openapi:

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

Para chamar um modelo autoimplantado do Model Garden, defina a variável ENDPOINT e use-a no URL:

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

Em seguida, inicialize o cliente:

client = openai.OpenAI()

A API Gemini Chat Completions usa OAuth para autenticação com um token de acesso de curta duração. Por padrão, os tokens de acesso duram 1 hora. Você pode prolongar a vida útil do seu token de acesso ou atualizá-lo periodicamente e atualizar a variável de ambiente OPENAI_API_KEY.

Chamar o Gemini com a API Chat Completions

O exemplo a seguir mostra como enviar solicitações sem 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

Antes de testar esse exemplo, siga as instruções de configuração para Python no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Python.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

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)

O exemplo a seguir mostra como enviar solicitações de streaming para um Modelo do Gemini usando a 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

Antes de testar esse exemplo, siga as instruções de configuração para Python no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Python.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

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)

Chamar um modelo autoimplantado com a API Chat Completions

O exemplo a seguir mostra como enviar solicitações sem 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

Antes de testar esse exemplo, siga as instruções de configuração para Python no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Python.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

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)

O exemplo a seguir mostra como enviar solicitações de streaming para um modelo autoimplantado usando a 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

Antes de testar esse exemplo, siga as instruções de configuração para Python no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Python.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

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)

Parâmetros aceitos

Para modelos do Google, a API Chat Completions é compatível com as seguintes APIs parâmetros. Para ver uma descrição de cada parâmetro, consulte a documentação da OpenAI sobre Como criar conclusões de chat. A compatibilidade com parâmetros para modelos de terceiros varia de acordo com o modelo. Para saber quais parâmetros são aceitos, consulte a documentação do modelo.

messages
  • System message
  • User message: os tipos text e image_url são aceitos. O tipo image_url oferece suporte a imagens armazenadas em um URI do Cloud Storage ou uma codificação Base64 no formato "data:<MIME-TYPE>;base64,<BASE64-ENCODED-BYTES>". Para saber como criar um bucket do Cloud Storage e fazer upload de um arquivo nele, consulte Descubra o armazenamento de objetos. A opção detail não é compatível.
  • Assistant message
  • Tool message
  • Function message: o uso deste campo foi descontinuado, mas tem suporte para compatibilidade com versões anteriores.
model
max_tokens
n
frequency_penalty
presence_penalty
response_format
  • json_object: interpretado como transmissão de "application/json" para a API Gemini.
  • text: interpretado como transmissão de "texto/simples" para a API Gemini.
  • Qualquer outro tipo MIME é passado no estado em que se encontra para o modelo, como passar "application/json" diretamente.
stop
stream
temperature
top_p
tools
  • type
  • function
    • name
    • description
    • parameters: especifique parâmetros usando a Especificação OpenAPI. Ela é diferente do campo de parâmetros da OpenAI, que é descrito como um objeto de esquema JSON. Para saber mais sobre as diferenças de palavras-chave entre os esquemas OpenAPI e JSON, consulte o Guia da OpenAPI.
tool_choice
  • none
  • auto
  • required: corresponde ao modo ANY no FunctionCallingConfig.
function_call Este campo está obsoleto, mas tem suporte para compatibilidade com versões anteriores.
functions Este campo está obsoleto, mas tem suporte para compatibilidade com versões anteriores.

Se você passar algum parâmetro não suportado, ele será ignorado.

Atualizar suas credenciais

O exemplo a seguir mostra como atualizar suas credenciais automaticamente como necessário:

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)

A seguir