本頁面由 Cloud Translation API 翻譯而成。

設定 API 要求格式

本頁面將說明如何使用 OpenAI Chat Completions 端點的要求內文詳細資料，為 Google Distributed Cloud (GDC) 氣隙環境中的 Gemini 設定 API 請求格式。只要遵循這個格式，您就能在應用程式中順暢整合 Gemini 的進階功能，同時使用 OpenAI API 的結構。

Gemini 模型系列包含可處理多模態提示要求的多模態模型。「多模態」一詞表示您可以在提示中使用多種模態或輸入類型。詳情請參閱「設計提示」。

如要進一步瞭解為 gRPC 程式庫產生的型別、方法和欄位泛型說明，請參閱 Gemini gRPC 參考資料。

事前準備

格式化 API 要求前，請先確認您符合下列先決條件：

在 GDC 上瞭解 Gemini 的功能。
開始使用最低專案需求，對 Gemini 發出 API 要求。
找出要在要求中使用的 Gemini 模型端點 ID。選取特定模型後，即可使用該模型獨有的功能執行工作。請參閱 GDC 上的可用 Gemini 模型。
瞭解如何仔細編寫提示，引導 Gemini 提供預期回覆。嘗試不同的提示風格和格式，以最佳化輸出內容。詳情請參閱「提示簡介」。
探索 OpenAI Chat Completions 端點提供的各種參數，藉此控管 Gemini 的行為。調整 temperature、max_completion_tokens 和 top_p 等參數，控制生成文字的創意度、長度和多樣性。詳情請參閱「使用參數進行實驗」一文。

要求語法

下列範例包含 API 要求中必須使用的語法，可生成模型回應：

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

API 參數

本節列出您可以在 Gemini on GDC 的 API 要求要求主體中定義的最重要參數，以及模型必須傳回的回應主體。如需 OpenAI Chat Completions 端點的完整 API 參考資料，請參閱 https://platform.openai.com/docs/api-reference/chat。

要求主體

{
  "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
}

下表列出搭配 Gemini 使用 OpenAI Chat Completions 端點時，要求主體中的重要欄位和說明：

參數
欄位名稱		說明
`model`		必要條件：`string` 要使用的 Gemini 模型。詳情請參閱可用的 Gemini 模型。
`messages`		必要條件：`object` 與模型進行目前對話的訊息清單。每則訊息都會提供 `role` 和 `content`。支援不同類型的訊息 (模態)，例如文字、圖片、音訊、影片和文件。
	`role`	必要條件：`string` 訊息作者的角色，可以是下列任一項： `system`：系統提供的指令，模型必須遵守，無論使用者傳送的訊息為何。 `user`：使用者提供的訊息，模型必須回覆，且包含提示或額外背景資訊。 `assistant`：模型根據使用者訊息提供的回覆。
	`content`	必要條件：`string` 或 `array` 系統、使用者或助理傳送的訊息內容。如果是單輪查詢，這個值是單一例項。如果是多輪查詢，`content` 是重複欄位，內含對話記錄和最新要求。詳情請參閱 `content`。
`temperature`		選用：`number` 或 `null` 生成文字的隨機性。值越低 (越接近 `0`)，生成的回覆越具確定性且更精確；值越高 (越接近 `2`)，生成的回覆越多元且更具創意。預設值為 `1`。
`max_completion_tokens`		選用：`integer` 或 `null` 回覆中可生成的詞元數量上限，包括可見的輸出詞元和推理詞元。
`top_p`		選用：`number` 或 `null` 核心取樣機率。值越高 (越接近 `1`)，取樣範圍就越廣，值越低 (越接近 `0`)，取樣範圍就越窄，只會取樣最有可能的符記。預設值為 `1`。
`n`		選用：`integer` 或 `null` 每個提示要生成的完成次數。預設值為 `1`。
`stop`		選用：`string`、`array` 或 `null` 字串清單，遇到這些字串時，系統會停止生成文字。預設值為 `null`。
`user`		自由參加：`string` 使用者的專屬 ID。這項參數可讓您追蹤使用模式，並提供個人化回覆。

`content`

這個欄位是基本結構化資料類型，內含訊息的多部分內容。

如果輸入的是文字提示，這個欄位的值就是字串。不過，如果是多模態提示，這個欄位會包含陣列，每個物件都包含兩個主要屬性：type 和 INPUT。type 屬性表示多模態輸入的內容類型，而 INPUT 屬性則包含輸入元素，以 Base64 編碼資料或 GDC 儲存空間值區的網址表示。

下表列出多模態提示的主要 content 欄位及其說明：

欄位名稱		說明
`type`		必要條件：`string` 注意：OpenAI 和 Gemini 僅支援 `image_url` 和 `input_audio` 類型。其他類型僅支援 Gemini，不支援 OpenAI。因此，如果使用與 `image_url` 和 `input_audio` 不同的內容資料類型傳送要求，OpenAI Python SDK 就無法運作。多模態提示的內容類型。可接受的值包括： `image_url`：輸入內容為圖片，可採用 Base64 編碼資料或 GDC 儲存空間值區的網址。 `input_audio`：輸入內容為以 Base64 編碼資料形式提供的音訊。 `audio_url`：輸入內容為音訊，以 GDC 儲存空間值區的網址形式提供。 `input_video`：輸入內容為以 Base64 編碼資料形式提供的影片。 `video_url`：輸入內容為影片，以 GDC 儲存空間值區的網址形式提供。 `input_document`：輸入內容是採用 Base64 編碼資料格式的文件。 `document_url`：輸入內容是從 GDC 儲存空間值區以網址形式提供的文件。
`INPUT`		必要條件：`object` 多模態提示的內容輸入。這個欄位名稱必須與 `type` 欄位中指定的值相同。因此，這個欄位名稱是下列其中一項：圖片：`image_url` 音訊：`input_audio` 或 `audio_url` 影片：`input_video` 或 `video_url` 文件：`input_document` 或 `document_url`。每個輸入欄位都有 `url` 或 `data` 和 `format`。
	`url`	自由參加：`string` 如果輸入內容是以網址形式提供，則為 GDC 儲存空間值區中的檔案路徑。如果是圖片，這個欄位可以包含 Base64 編碼資料，而非網址。注意：Base64 編碼資料必須加上資料 URI 結構定義 (RFC 2397) 前置字元。因此，Base64 編碼資料的格式為 `data:image/jpeg;base64,{base64_image}` 等。
	`data`	自由參加：`string` 如果輸入內容是以 base64 編碼資料的形式提供，則二進位資料會轉換為字元字串。如果是圖片，則會改為在 `url` 欄位中提供 Base64 編碼資料。注意：Base64 編碼資料必須加上資料 URI 結構定義 (RFC 2397) 前置字元。因此，Base64 編碼資料的格式為 `data:video/wmv;base64,{base64_video}` 等。
	`format`	自由參加：`string` 如果輸入內容是在 `data` 欄位中提供，則為所提供資料的格式規格。系統支援的格式會因輸入資料而異。詳情請參閱圖片、音訊、影片和文件的 MIME 類型。

回應主體

{
  "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
}

下表列出模型根據提供的輸入內容傳回的回應主體中，主要欄位及其說明：

欄位名稱		說明
`id`		`string` 生成文字的專屬 ID。
`object`		`string` 物件類型，一律為 `chat.completion`。
`created`		`integer` 生成文字的時間戳記 (以秒為單位)。
`model`		`string` 用來生成文字的模型。
`choices`		`array` 文字生成選項清單。如果 `n` 大於 `1`，這個欄位可以包含多個選項。
	`index`	`integer` 選項清單中選項的索引。
	`message`	`object` 模型生成的文字生成訊息。這個欄位包含下列屬性： `role`：(`string`) 訊息作者的角色。 `content`：(`string` 或 `null`) 訊息內容。 `refusal`：(`string` 或 `null`) 模型產生的拒絕訊息。
	`logprobs`	`object`或`null` 選項的記錄機率資訊。
	`finish_reason`	`string` 模型停止生成權杖的原因。值為下列其中之一： `stop`：模型達到自然停止點或提供的停止序列。 `length`：已達到要求中指定的權杖數量上限。 `content_filter`：內容因內容篩選器標記而遭省略。 `tool_calls`：呼叫工具的模型。
`usage`		`object` 要求的用量統計資料。
	`completion_tokens`	`integer` 生成文字中的權杖數量。
	`prompt_tokens`	`integer` 提示中的權杖數量。
	`total_tokens`	`integer` 提示和生成文字中的權杖總數。
`system_fingerprint`		`string` 模型用於執行的後端設定。

範例

本節包含要求主體的範例，以及模型必須傳回的文字生成回應。

要求範例

以下範例顯示要求主體的詳細資料，該主體會將提示傳送至 Gemini，要求生成文字。這個範例包含溫度和輸出詞元數量上限控制項。如要瞭解實作方式，請參閱「傳送文字提示」或「傳送多模態提示」。

{
  "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
}

回覆範例

以下範例顯示模型傳回的文字生成回應詳細資料：

{
  "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": ""
}