Memanggil model Vertex AI menggunakan library OpenAI

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Untuk melihat contoh penggunaan API penyelesaian chat, jalankan notebook Jupyter "Call Gemini with the OpenAI Library" di salah satu lingkungan berikut:

Buka di Colab | Buka di Colab Enterprise | Buka di notebook Vertex AI Workbench yang dikelola pengguna | Lihat di GitHub

Chat Completions API memungkinkan Anda mengirim permintaan ke model Vertex AI dengan menggunakan library OpenAI untuk Python dan REST. Jika sudah menggunakan library OpenAI, Anda dapat menggunakan API ini untuk beralih antara memanggil model OpenAI dan model yang dihosting Vertex AI untuk membandingkan output, biaya, dan skalabilitas, tanpa mengubah kode yang ada. Jika Anda belum menggunakan library OpenAI, sebaiknya Anda memanggil Gemini API secara langsung.

Model yang didukung

Chat Completions API mendukung model Gemini dan beberapa model yang di-deploy sendiri dari Model Garden.

Model Gemini

Tabel berikut menunjukkan model Gemini yang didukung:

Model	Versi
Gemini 2.0 Flash	google/gemini-2.0-flash-001
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

Model yang di-deploy sendiri dari Model Garden

Penampung Hugging Face Text Generation Interface (HF TGI) dan vLLM bawaan Vertex AI Model Garden mendukung Chat Completions API. Namun, tidak semua model yang di-deploy ke penampung ini mendukung Chat Completions API. Tabel berikut menyertakan model yang didukung paling populer menurut penampung:

HF TGI	vLLM
gemma-2-9b-it gemma-2-27b-it Meta-Llama-3.1-8B-Instruct Meta-Llama-3-8B-Instruct Mistral-7B-Instruct-v0.3 Mistral-Nemo-Instruct-2407	Gemma Llama 2 Llama 3 Mistral-7B Mistral Nemo

Autentikasikan

Untuk menggunakan library OpenAI Python, instal OpenAI SDK:

pip install openai

Untuk mengautentikasi dengan Chat Completions API, Anda dapat mengubah penyiapan klien atau mengubah konfigurasi lingkungan untuk menggunakan autentikasi Google dan endpoint Vertex AI. Pilih metode mana pun yang lebih mudah, dan ikuti langkah-langkah untuk menyiapkan, bergantung pada apakah Anda ingin memanggil model Gemini atau model Model Garden yang di-deploy sendiri.

Model tertentu di Model Garden dan model Hugging Face yang didukung harus di-deploy ke endpoint Vertex AI terlebih dahulu sebelum dapat menyalurkan permintaan. Saat memanggil model yang di-deploy sendiri ini dari Chat Completions API, Anda harus menentukan ID endpoint. Untuk mencantumkan endpoint Vertex AI yang ada, gunakan perintah gcloud ai endpoints list.

Penyiapan klien

Untuk mendapatkan kredensial Google secara terprogram di Python, Anda dapat menggunakan google-auth Python SDK:

pip install google-auth requests

Python

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Python Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

Secara default, token akses berlaku selama 1 jam. Anda dapat memperpanjang masa berlaku token akses atau memuat ulang token secara berkala dan memperbarui variabel openai.api_key.

Variabel lingkungan

Menginstal Google Cloud CLI. Library OpenAI dapat membaca variabel lingkungan OPENAI_API_KEY dan OPENAI_BASE_URL untuk mengubah autentikasi dan endpoint di klien defaultnya. Tetapkan variabel berikut:

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

Untuk memanggil model Gemini, tetapkan variabel MODEL_ID dan gunakan endpoint openapi:

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

Untuk memanggil model yang di-deploy sendiri dari Model Garden, tetapkan variabel ENDPOINT dan gunakan variabel tersebut di URL Anda:

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

Selanjutnya, lakukan inisialisasi klien:

client = openai.OpenAI()

Gemini Chat Completions API menggunakan OAuth untuk mengautentikasi dengan token akses berumur pendek. Secara default, token akses berlaku selama 1 jam. Anda dapat memperpanjang masa berlaku token akses atau memuat ulang token secara berkala dan memperbarui variabel lingkungan OPENAI_API_KEY.

Memanggil Gemini dengan Chat Completions API

Contoh berikut menunjukkan cara mengirim permintaan non-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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Python Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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)

Contoh berikut menunjukkan cara mengirim permintaan streaming ke model Gemini menggunakan Chat Completions API:

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Python Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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)

Memanggil model yang di-deploy sendiri dengan Chat Completions API

Contoh berikut menunjukkan cara mengirim permintaan non-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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Python Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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)

Contoh berikut menunjukkan cara mengirim permintaan streaming ke model yang di-deploy sendiri menggunakan Chat Completions API:

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Python Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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)

Parameter yang didukung

Untuk model Google, Chat Completions API mendukung parameter OpenAI berikut. Untuk deskripsi setiap parameter, lihat dokumentasi OpenAI tentang Membuat penyelesaian chat. Dukungan parameter untuk model pihak ketiga bervariasi menurut model. Untuk melihat parameter yang didukung, lihat dokumentasi model.

messages	System message User message: Jenis text dan image_url didukung. Jenis image_url mendukung gambar yang disimpan dalam URI Cloud Storage atau encoding base 64 dalam bentuk "data:<MIME-TYPE>;base64,<BASE64-ENCODED-BYTES>". Untuk mempelajari cara membuat bucket Cloud Storage dan mengupload file ke dalamnya, lihat Menemukan penyimpanan objek. Opsi detail tidak didukung. Assistant message Tool message Function message: Kolom ini tidak digunakan lagi, tetapi didukung untuk kompatibilitas mundur.
model
max_tokens
n
frequency_penalty
presence_penalty
response_format	json_object: Ditafsirkan sebagai meneruskan "application/json" ke Gemini API. text: Ditafsirkan sebagai meneruskan "text/plain" ke Gemini API. Jenis MIME lainnya diteruskan apa adanya ke model, seperti meneruskan "application/json" secara langsung.
stop
stream
temperature
top_p
tools	type function name description parameters: Tentukan parameter menggunakan spesifikasi OpenAPI. Hal ini berbeda dengan kolom parameter OpenAI, yang dideskripsikan sebagai objek Skema JSON. Untuk mempelajari perbedaan kata kunci antara OpenAPI dan JSON Schema, lihat panduan OpenAPI.
tool_choice	none auto required: Sesuai dengan mode ANY di FunctionCallingConfig.
function_call	Kolom ini tidak digunakan lagi, tetapi didukung untuk kompatibilitas mundur.
functions	Kolom ini tidak digunakan lagi, tetapi didukung untuk kompatibilitas mundur.

Jika Anda meneruskan parameter yang tidak didukung, parameter tersebut akan diabaikan.

Memuat ulang kredensial

Contoh berikut menunjukkan cara memuat ulang kredensial secara otomatis sesuai kebutuhan:

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)

Langkah berikutnya

• Lihat contoh pemanggilan Inference API dengan sintaksis yang kompatibel dengan OpenAI.
• Lihat contoh pemanggilan Function Calling API dengan sintaksis yang kompatibel dengan OpenAI.
• Pelajari Gemini API lebih lanjut.
• Pelajari lebih lanjut cara bermigrasi dari Azure OpenAI ke Gemini API.