Memformat permintaan API

Halaman ini memandu Anda memformat permintaan API untuk Gemini di Google Distributed Cloud (GDC) yang terisolasi menggunakan detail isi permintaan dari endpoint Chat Completions OpenAI. Dengan mematuhi format ini, Anda dapat mengintegrasikan kemampuan canggih Gemini ke dalam aplikasi Anda dengan lancar sambil menggunakan struktur OpenAI API.

Serangkaian model Gemini mencakup model yang berfungsi dengan permintaan perintah multimodal. Istilah multimodal menunjukkan bahwa Anda dapat menggunakan lebih dari satu modalitas atau jenis input dalam perintah. Untuk mengetahui informasi selengkapnya, lihat Mendesain perintah.

Untuk mengetahui informasi selengkapnya tentang deskripsi generik jenis, metode, dan kolom yang dihasilkan untuk library gRPC, lihat referensi gRPC Gemini.

Sebelum memulai

Sebelum memformat permintaan API, pastikan Anda memenuhi prasyarat berikut:

  • Pelajari kemampuan Gemini di GDC.
  • Mulai dengan persyaratan project minimum untuk membuat permintaan API untuk Gemini.
  • Identifikasi ID endpoint model Gemini yang ingin Anda gunakan dalam permintaan Anda. Dengan memilih model tertentu, Anda dapat menggunakan kemampuan uniknya untuk tugas Anda. Lihat model Gemini yang tersedia di GDC.
  • Pahami cara menyusun perintah dengan cermat untuk mendapatkan respons yang diharapkan dari Gemini. Bereksperimen dengan berbagai gaya dan format perintah untuk mengoptimalkan output. Untuk mengetahui informasi selengkapnya, lihat Pengantar perintah.
  • Jelajahi berbagai parameter yang tersedia di endpoint Penyelesaian Chat OpenAI untuk mengontrol perilaku Gemini. Sesuaikan parameter seperti temperature, max_completion_tokens, dan top_p untuk mengontrol kreativitas, panjang, dan keragaman teks yang dihasilkan. Untuk informasi selengkapnya, lihat Bereksperimen dengan parameter.

Sintaksis permintaan

Contoh berikut berisi sintaksis yang harus Anda gunakan dalam permintaan API untuk membuat respons model:

Python 

import openai

client = openai.OpenAI()
model_response = client.chat.completions.create(
  model = "MODEL_ID",
  messages = [
    {
      ...
    }
  ]
  ...
)

print(model_response)

curl 

curl \
  -X POST "https://ENDPOINT:443/v1/projects/PROJECT/locations/PROJECT/chat/completions" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer $(gdcloud auth print-identity-token)" \
  -d '{
      "model_id": "MODEL_ID",
      "messages" = [
        {
          ...
        }
      ]
      ...
  }'

Parameter API

Bagian ini berisi daftar parameter terpenting yang dapat Anda tentukan di isi permintaan API untuk Gemini di GDC dan isi respons yang harus ditampilkan model. Untuk referensi API lengkap endpoint Chat Completions OpenAI, lihat https://platform.openai.com/docs/api-reference/chat.

Isi permintaan

{
  "messages" = [
    {
      "role": string,
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": string
          }
        },
        {
          "type": "input_audio",
          "input_audio": {
            "data": string,
            "format": string
          }
        },
        {
          "type": "audio_url",
          "audio_url": {
            "url": string
          }
        },
        {
          "type": "input_video",
          "input_video": {
            "data": string,
            "format": string
          }
        },
        {
          "type": "video_url",
          "video_url": {
            "url": string
          }
        },
        {
          "type": "input_document",
          "input_document": {
            "data": string,
            "format": string
          }
        },
        {
          "type": "document_url",
          "document_url": {
            "url": string
          }
        }
      ]
    }
  ],
  "temperature": number,
  "max_completion_tokens": integer,
  "top_p": number,
  "n": integer,
  "stop": string,
  "user": string
}

Tabel berikut menguraikan kolom utama dan deskripsinya di isi permintaan untuk endpoint Penyelesaian Chat OpenAI saat digunakan dengan Gemini:

Parameter
Nama kolom Deskripsi

model

Wajib: string

Model Gemini yang akan digunakan.

Untuk mengetahui informasi selengkapnya, lihat model Gemini yang tersedia.

messages

Wajib: object

Daftar pesan yang membentuk percakapan saat ini dengan model. Setiap pesan memiliki role dan content.

Berbagai jenis pesan (modalitas) didukung, seperti teks, gambar, audio, video, dan dokumen.

role

Wajib: string

Peran penulis pesan, yang dapat berupa salah satu dari berikut:

  • system: Petunjuk yang disediakan sistem yang harus diikuti model, terlepas dari pesan yang dikirim oleh pengguna.
  • user: Pesan yang diberikan pengguna yang harus direspons oleh model dan yang berisi perintah atau informasi konteks tambahan.
  • assistant: Pesan yang disediakan model sebagai respons terhadap pesan pengguna.

content

Wajib: string atau array

Isi pesan dari sistem, pengguna, atau asisten.

Nilainya adalah satu instance untuk kueri sekali putaran. Untuk kueri multi-turn, content adalah kolom berulang yang berisi histori percakapan dan permintaan terbaru. Untuk mengetahui detailnya, lihat content.

temperature

Opsional: number atau null

Keacakan teks yang dihasilkan.

Nilai yang lebih rendah (lebih dekat ke 0) menghasilkan respons yang lebih deterministik dan terfokus, sedangkan nilai yang lebih tinggi (lebih dekat ke 2) menghasilkan output yang lebih beragam dan kreatif.

Nilai defaultnya adalah 1.

max_completion_tokens

Opsional: integer atau null

Jumlah maksimum token yang akan dibuat dalam respons, termasuk token output yang terlihat dan token penalaran.

top_p

Opsional: number atau null

Probabilitas pengambilan sampel inti.

Nilai yang lebih tinggi (lebih dekat ke 1) mengambil sampel dari rentang token potensial yang lebih luas, sedangkan nilai yang lebih rendah (lebih dekat ke 0) berfokus pada token yang paling mungkin.

Nilai defaultnya adalah 1.

n

Opsional: integer atau null

Jumlah penyelesaian yang akan dihasilkan untuk setiap perintah.

Nilai defaultnya adalah 1.

stop

Opsional: string, array, atau null

Daftar string yang, saat ditemukan, akan menghentikan proses pembuatan teks.

Nilai defaultnya adalah null.

user

Opsional: string

ID unik untuk pengguna akhir.

Parameter ini memungkinkan Anda melacak pola penggunaan dan mempersonalisasi respons.

content

Kolom ini adalah jenis data terstruktur dasar yang berisi konten multi-bagian dari pesan.

Jika input berupa perintah teks, nilai kolom ini adalah string. Namun, untuk perintah multimodal, kolom ini terdiri dari array yang berisi dua properti utama di setiap objek: type dan INPUT. Properti type menunjukkan jenis konten dari input multimodal, sedangkan properti INPUT berisi elemen input, yang ditampilkan sebagai data berenkode base64 atau URL dari bucket penyimpanan GDC.

Tabel berikut menguraikan kolom content utama dan deskripsinya untuk perintah multimodal:

Nama kolom Deskripsi

type

Wajib: string

Jenis konten untuk perintah multimodal. Nilai yang dapat diterima mencakup hal berikut:

  • image_url: Konten input adalah gambar yang disediakan sebagai data berenkode base64 atau sebagai URL dari bucket penyimpanan GDC.
  • input_audio: Konten input adalah audio yang disediakan sebagai data berenkode base64.
  • audio_url: Konten input adalah audio yang disediakan sebagai URL dari bucket penyimpanan GDC.
  • input_video: Konten input adalah video yang disediakan sebagai data berenkode base64.
  • video_url: Konten input adalah video yang disediakan sebagai URL dari bucket penyimpanan GDC.
  • input_document: Konten input adalah dokumen yang disediakan sebagai data berenkode base64.
  • document_url: Konten input adalah dokumen yang disediakan sebagai URL dari bucket penyimpanan GDC.

INPUT

Wajib: object

Input konten untuk perintah multimodal. Nama kolom ini harus sama dengan nilai yang ditentukan di kolom type.

Oleh karena itu, nama kolom ini adalah salah satu dari berikut ini:

  • Untuk gambar: image_url
  • Untuk audio: input_audio atau audio_url
  • Untuk video: input_video atau video_url
  • Untuk dokumen: input_document atau document_url.

Setiap kolom input memiliki url atau data dan format.

url

Opsional: string

Jika konten input diberikan sebagai URL, jalur ke file di bucket penyimpanan GDC.

Dalam kasus gambar, kolom ini dapat berisi data berenkode base64, bukan URL.

data

Opsional: string

Jika konten input diberikan sebagai data berenkode base64, data biner akan dikonversi menjadi string karakter.

Untuk gambar, data berenkode base64 diberikan di kolom url.

format

Opsional: string

Jika konten input diberikan di kolom data, spesifikasi format data yang diberikan.

Bergantung pada data input, format yang berbeda didukung. Untuk mengetahui informasi selengkapnya, lihat jenis MIME untuk gambar, audio, video, dan dokumen.

Isi respons

{
  "id": string,
  "object": string,
  "created": integer,
  "model": string,
  "choices": [
    {
      "index": integer,
      "message": {
        "role": string,
        "content": string,
        "refusal": null
      },
      "logprobs": null,
      "finish_reason": string
    }
  ],
  "usage": {
    "completion_tokens": integer,
    "prompt_tokens": integer,
    "total_tokens": integer
  },
  "system_fingerprint": string
}

Tabel berikut menguraikan kolom utama dan deskripsinya dalam isi respons yang ditampilkan oleh model berdasarkan input yang diberikan:

Nama kolom Deskripsi

id

string

ID unik untuk teks yang dihasilkan.

object

string

Jenis objek, yang selalu chat.completion.

created

integer

Stempel waktu dalam detik saat teks dibuat.

model

string

Model yang digunakan untuk membuat teks.

choices

array

Daftar pilihan pembuatan teks. Kolom ini dapat berisi beberapa pilihan jika n lebih besar dari 1.

index

integer

Indeks pilihan dalam daftar pilihan.

message

object

Pesan pembuatan teks yang dihasilkan oleh model. Kolom ini berisi properti berikut:

  • role: (string) Peran penulis pesan.
  • content: (string atau null) Isi pesan.
  • refusal: (string atau null) Pesan penolakan yang dihasilkan oleh model.

logprobs

object atau null

Informasi probabilitas log untuk pilihan.

finish_reason

string

Alasan model berhenti menghasilkan token. Nilainya adalah salah satu dari berikut:

  • stop: Model mencapai titik berhenti alami atau urutan berhenti yang diberikan.
  • length: Jumlah maksimum token yang ditentukan dalam permintaan telah tercapai.
  • content_filter: Konten dihilangkan karena adanya laporan dari filter konten.
  • tool_calls: Model yang memanggil alat.

usage

object

Statistik penggunaan untuk permintaan.

completion_tokens

integer

Jumlah token dalam teks yang dihasilkan.

prompt_tokens

integer

Jumlah token dalam perintah.

total_tokens

integer

Jumlah total token dalam perintah dan teks yang dihasilkan.

system_fingerprint

string

Konfigurasi backend yang digunakan model untuk berjalan.

Contoh

Bagian ini berisi contoh isi permintaan dan respons pembuatan teks yang harus ditampilkan model.

Contoh permintaan

Contoh berikut menunjukkan detail isi permintaan yang mengirimkan perintah ke Gemini untuk membuat teks. Contoh ini berisi kontrol token suhu dan maksimum. Untuk mengetahui detail penerapan, lihat Mengirim perintah teks atau Mengirim perintah multimodal.

{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful and informative assistant."
    },
    {
      "role": "user",
      "content": "What is the capital of France?"
    }
  ],
  "temperature": 0.7,
  "max_completion_tokens": 100
}

Contoh respons

Contoh berikut menunjukkan detail respons pembuatan teks yang ditampilkan oleh model:

{
  "id": "",
  "object": "",
  "created": 0,
  "model": "",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris.\n",
        "refusal": null
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "completion_tokens": 7,
    "prompt_tokens": 8,
    "total_tokens": 15
  },
  "system_fingerprint": ""
}

Langkah berikutnya