搭配使用 OpenAI 程式庫與 Vertex AI

Chat Completions API 是與 Open AI 相容的端點，可讓您使用 Python 和 REST 適用的 OpenAI 程式庫，更輕鬆地與 Vertex AI 上的 Gemini 互動。如果您已使用 OpenAI 程式庫，可以透過這個 API 在呼叫 OpenAI 模型和 Vertex AI 代管模型之間切換，比較輸出內容、費用和擴充性，不必變更現有程式碼，是經濟實惠的替代方案。如果您尚未採用 OpenAI 程式庫，建議使用 Google Gen AI SDK。如要遷移現有的 OpenAI SDK 程式碼，改用 Google Gen AI SDK，請參閱「從 OpenAI SDK 遷移至 Google Gen AI SDK」。

支援的模型

Chat Completions API 支援 Gemini 模型，以及 Model Garden 中選取的自行部署模型。

Gemini 模型

下列模型支援 Chat Completions API：

從 Model Garden 自行部署的模型

Hugging Face 文字生成介面 (HF TGI) 和 Vertex AI Model Garden 預先建構的 vLLM 容器支援 Chat Completions API。不過，並非部署至這些容器的所有模型都支援 Chat Completions API。下表列出各容器最常支援的型號：

HF TGI

vLLM

支援的參數

對於 Google 模型，Chat Completions API 支援下列 OpenAI 參數。如要查看各項參數的說明，請參閱 OpenAI 的「建立對話完成項目」說明文件。第三方模型支援的參數因模型而異。如要查看支援的參數，請參閱模型說明文件。

messages
  • System message
  • User message：支援 text 和 image_url 類型。image_url 類型支援以 Cloud Storage URI 形式儲存的圖片，或以 "data:<MIME-TYPE>;base64,<BASE64-ENCODED-BYTES>" 形式進行 base64 編碼的圖片。如要瞭解如何建立 Cloud Storage bucket 並將檔案上傳至 bucket，請參閱「探索物件儲存空間」。系統不支援 detail 選項。
  • Assistant message
  • Tool message
  • Function message：這個欄位已淘汰，但為了回溯相容性，系統仍支援這個欄位。
model
max_completion_tokens max_tokens 的別名。
max_tokens
n
frequency_penalty
presence_penalty
reasoning_effort 設定回覆所用的時間和詞元數量。
  • low：1024
  • medium：8192
  • high: 24576
由於回應中未包含想法，因此只能指定 reasoning_effort 或 extra_body.google.thinking_config。
response_format
  • json_object：解讀為將「application/json」傳遞至 Gemini API。
  • json_schema。 系統不支援完全遞迴結構定義。additional_properties 支援。
  • text：解讀為將「text/plain」傳遞至 Gemini API。
  • 其他 MIME 類型會直接傳遞至模型，例如直接傳遞「application/json」。
seed 對應至 GenerationConfig.seed。
stop
stream
temperature
top_p
tools
  • type
  • function
    • name
    • description
    • parameters：使用 OpenAPI 規格指定參數。這與 OpenAI 參數欄位不同，後者描述為 JSON 結構定義物件。如要瞭解 OpenAPI 和 JSON 結構定義之間的關鍵字差異，請參閱 OpenAPI 指南。
tool_choice
  • none
  • auto
  • required：對應於 FunctionCallingConfig 中的模式 ANY。
  • validated：對應於 FunctionCallingConfig 中的模式 VALIDATED。這是 Google 專屬功能。
web_search_options 對應至 GoogleSearch 工具。不支援任何子選項。
function_call 這個欄位已淘汰，但仍支援回溯相容性。
functions 這個欄位已淘汰，但仍支援回溯相容性。

如果傳遞任何不支援的參數，系統會忽略該參數。

多模態輸入參數

Chat Completions API 支援特定多模態輸入內容。

input_audio
  • data: 任何 URI 或有效 Blob 格式。我們支援所有 Blob 類型，包括圖片、音訊和影片。支援 GenerateContent 支援的所有項目 (HTTP、Cloud Storage 等)。
  • format:OpenAI 支援 wav (audio/wav) 和 mp3 (audio/mp3)。使用 Gemini 時，系統支援所有有效的 MIME 類型。
image_url
  • data: 與 input_audio 類似，支援任何 URI 或有效 Blob 格式。
    請注意，如果 image_url 是網址，預設會是 image/* MIME 類型，而 image_url 是 Blob 資料時，則可做為任何多模態輸入內容。
  • detail: 類似於媒體解析度，這項設定會決定要求中每張圖片的權杖上限。請注意，雖然 OpenAI 的欄位是針對每張圖片，但 Gemini 會在要求中強制執行相同的詳細資料，且在單一要求中傳遞多個詳細資料類型會擲回錯誤。

一般來說，data 參數可以是 URI，也可以是 MIME 類型和 Base64 編碼位元組的組合，格式為 "data:<MIME-TYPE>;base64,<BASE64-ENCODED-BYTES>"。如需完整的 MIME 類型清單，請參閱 GenerateContent。 如要進一步瞭解 OpenAI 的 base64 編碼，請參閱他們的說明文件。

如需使用方式，請參閱多模態輸入範例。

Gemini 專屬參數

Gemini 支援多項 OpenAI 模型不支援的功能。 這些功能仍可做為參數傳遞，但必須包含在 extra_content 或 extra_body 中，否則系統會忽略這些功能。

extra_body 項功能

加入 google 欄位，內含任何 Gemini 專屬功能。extra_body

{
  ...,
  "extra_body": {
     "google": {
       ...,
       // Add extra_body features here.
     }
   }
}
safety_settings 這對應於 Gemini SafetySetting。
cached_content 這會對應至 Gemini generateContent.cached_content 欄位。
thinking_config 這對應於 Gemini GenerationConfig.ThinkingConfig。
thought_tag_marker 如果模型支援「思考」功能，這項設定可用於將模型的想法與回覆分開。
如未指定，系統不會傳回模型想法的相關標記。如果存在，後續查詢會移除想法標記，並適當標記想法以供參考。這有助於保留後續查詢的適當情境。

extra_part 項功能

extra_part 可讓您在每個 Part 層級指定其他設定。

加入 google 欄位，內含任何 Gemini 專屬功能。extra_part

{
  ...,
  "extra_part": {
     "google": {
       ...,
       // Add extra_part features here.
     }
   }
}
extra_content 用於新增不應忽略的 Gemini 專屬內容的欄位。
thought 這個欄位會明確標示欄位是否為想法，且優先順序高於 thought_tag_marker。這有助於區分思考過程中的不同步驟，尤其是在工具使用情境中，中間步驟可能會被誤認為最終答案。將輸入內容的特定部分標示為想法，即可引導模型將這些內容視為內部推理，而非面向使用者的回覆。
thought_signature 位元組欄位，提供用於驗證模型傳回想法的思考簽章。這個欄位與布林欄位 thought 不同。詳情請參閱「想法簽章」。

後續步驟