此页面由 Cloud Translation API 翻译。

设置 API 请求的格式

本页将指导您使用 OpenAI Chat Completions 端点的请求正文详细信息，在 Google Distributed Cloud (GDC) 空气隔离环境中为 Gemini 设置 API 请求格式。通过遵循此格式，您可以在使用 OpenAI API 的结构的同时，将 Gemini 的高级功能无缝集成到您的应用中。

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 参数

本部分列出了您可以在 GDC 上针对 Gemini 的 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
}

下表概述了将 OpenAI Chat Completions 端点与 Gemini 搭配使用时，请求正文中的关键字段及其说明：

参数
字段名称		说明
`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`），采样范围越广，涵盖的潜在 token 越多；值越低（越接近 `0`），采样范围越窄，越侧重于最有可能的 token。默认值为 `1`。
`n`		可选：`integer` 或 `null` 针对每个提示生成的补全数量。默认值为 `1`。
`stop`		可选：`string`、`array` 或 `null` 一个字符串列表，当遇到列表中的字符串时，文本生成过程会停止。默认值为 `null`。
`user`		可选：`string`。最终用户的唯一标识符。借助此参数，您可以跟踪使用情况模式并提供个性化回答。

`content`

此字段是包含消息的多部分内容的基本结构化数据类型。

如果输入是文本提示，则此字段的值为字符串。不过，对于多模态提示，此字段包含一个数组，该数组中的每个对象都包含两个主要属性：type 和 INPUT。type 属性表示多模态输入的相应内容类型，而 INPUT 属性包含输入元素，以 base64 编码的数据或来自 GDC 存储桶的网址表示。

下表概述了多模态提示的关键 content 字段及其说明：

字段名称		说明
`type`		必需：`string` 注意：OpenAI 和 Gemini 均仅支持 `image_url` 和 `input_audio` 类型。其他类型仅受 Gemini 支持，不受 OpenAI 支持。因此，使用 OpenAI Python SDK 发送内容数据类型不同于 `image_url` 和 `input_audio` 的请求将无法正常运行。多模态提示的内容类型。可接受的值包括： `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` 生成文本的唯一标识符。
`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` 模型停止生成 token 的原因。该值可以是以下值之一： `stop`：模型达到自然停止点或提供的停止序列。 `length`：已达到请求中指定的 token 数量上限。 `content_filter`：由于内容过滤器的标志，内容被省略。 `tool_calls`：调用工具的模型。
`usage`		`object` 相应请求的使用情况统计信息。
	`completion_tokens`	`integer` 生成的文本中的 token 数。
	`prompt_tokens`	`integer` 提示中的 token 数量。
	`total_tokens`	`integer` 提示和生成的文本中的词元总数。
`system_fingerprint`		`string` 模型用于运行的后端配置。

示例

本部分包含一个请求正文示例以及模型必须返回的文本生成响应。

示例请求

以下示例展示了向 Gemini 发送提示以生成文本的请求正文的详细信息。此示例包含温度和 token 数上限控制。如需了解实现详情，请参阅发送文本提示或发送多模态提示。

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