推理 API

使用 Inference API 生成 Gemini 提示。

Gemini 模型系列包含可处理多模态提示请求的模型。多模态一词表示您可以在一个提示中使用多种模态（或输入类型）。非多模态模型仅接受文本提示。模态可以包括文本、音频、视频等。

如需了解更多概览信息，请参阅：

支持的模型：

模型	版本
Gemini 1.5 Flash	`gemini-1.5-flash-001`
Gemini 1.5 Pro	`gemini-1.5-pro-001`
Gemini 1.0 Pro Vision	`gemini-1.0-pro-001` `gemini-1.0-pro-vision-001`
Gemini 1.0 Pro	`gemini-1.0-pro` `gemini-1.0-pro-001` `gemini-1.0-pro-002`

限制：

如果您提供的图片很多，延迟时间可能会很长。

示例语法

用于生成模型回答的语法。

非流式传输

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \

https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:generateContent \
-d '{
  "contents": [{
    ...
  }],
  "generation_config": {
    ...
  },
  "safety_settings": {
    ...
  }
  ...
}'

Python

gemini_model = GenerativeModel(MODEL_ID)
generation_config = GenerationConfig(...)

model_response = gemini_model.generate_content([...], generation_config, safety_settings={...})

流式处理

curl

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:streamGenerateContent \
  -d '{
    "contents": [{
      ...
    }],
    "generation_config": {
      ...
    },
    "safety_settings": {
      ...
    }
    ...
  }'

Python

gemini_model = GenerativeModel(MODEL_ID)
model_response = gemini_model.generate_content([...], generation_config, safety_settings={...}, stream=True)

参数列表

如需了解实现详情，请参阅示例。

请求正文

请求正文中包含具有以下参数的数据：

参数
`contents`	必需：`Content` 与模型当前对话的内容。对于单轮查询，这是单个实例。对于多轮查询，此字段是包含对话记录和最新请求的重复字段。
`system_instruction`	可选：`Content`。用户为模型提供了系统说明。注意：`parts` 中只能使用 `text`，并且每个 `part` 中的内容应位于单独的段落中。
`tools`	可选。请参阅 Function Call API。
`tool_config`	可选。请参阅 Function Call API。
`safety_settings`	可选：`SafetySetting`。用于屏蔽不安全内容的按请求设置。在 `GenerateContentResponse.candidates` 上强制执行。
`generation_config`	可选：`GenerationConfig`。生成配置设置。

内容

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

此类包含两个主要属性：role 和 parts。role 属性表示生成内容的个人，而 parts 属性包含多个元素，每个元素表示消息中的一段数据。

参数

参数
`role`	可选：`string`。创建消息的实体的身份。支持以下值： `user`：表示消息是由真人发送的，通常是用户生成的消息。 `model`：表示消息是由模型生成的。 `model` 值用于在多轮对话期间将来自模型的消息插入到对话中。对于非多轮对话，此字段可以留空或未设置。
`parts`	`Part` 构成单条消息的有序部分的列表。不同的部分可能具有不同的 IANA MIME 类型。

role

可选：string。

创建消息的实体的身份。支持以下值：

user：表示消息是由真人发送的，通常是用户生成的消息。
model：表示消息是由模型生成的。

model 值用于在多轮对话期间将来自模型的消息插入到对话中。

对于非多轮对话，此字段可以留空或未设置。

parts

Part

构成单条消息的有序部分的列表。不同的部分可能具有不同的 IANA MIME 类型。

部分

包含属于多部分 Content 消息一部分的媒体的数据类型。

参数
`text`	可选：`string`。文本提示或代码段。
`inline_data`	可选：`Blob`。原始字节中的内嵌数据。
`file_data`	可选：`FileData`。存储在文件中的数据。
`function_call`	可选：`FunctionCall`。它包含一个表示 `FunctionDeclaration.name` 字段的字符串和一个结构化 JSON 对象，其中包含模型预测的函数调用的任何参数。请参阅 Function Call API。
`function_response`	可选：`FunctionResponse`。 `FunctionCall` 的结果输出，其中包含表示 `FunctionDeclaration.name` 字段的字符串以及包含函数调用的任何输出的结构化 JSON 对象。它用作模型的上下文。请参阅 Function Call API。
`video_metadata`	可选：`VideoMetadata`。视频元数据。仅当视频数据以 `inline_data` 或 `file_data` 形式呈现时，才应指定元数据。

Blob

内容 blob。如果可能，这会以文本而非原始字节的形式发送。

参数

参数
`mime_type`	`string` 数据的 IANA MIME 类型。
`data`	`bytes` 原始字节。

mime_type

string

数据的 IANA MIME 类型。

data

bytes

原始字节。

FileData

基于 URI 的数据。

参数

参数
mime_type	`string` 数据的 IANA MIME 类型。
file_uri	字符串存储数据的文件的 Cloud Storage URI

mime_type

string

数据的 IANA MIME 类型。

file_uri

字符串

存储数据的文件的 Cloud Storage URI

FunctionCall

从模型返回的预测 FunctionCall，其中包含表示 FunctionDeclaration.name 的字符串和包含参数及其值的结构化 JSON 对象。

参数

参数
`name`	`string` 要调用的函数名称。
`args`	`Struct` 以 JSON 对象格式表示的函数参数和值。如需了解参数详情，请参阅 Function Calling API。

name

string

要调用的函数名称。

args

Struct

以 JSON 对象格式表示的函数参数和值。

如需了解参数详情，请参阅 Function Calling API。

FunctionResponse

FunctionCall 的生成输出，其中包含表示 FunctionDeclaration.name 的字符串。还包含带有函数输出的结构化 JSON 对象（并将其用作模型的上下文）。其中应包含根据模型预测进行的 FunctionCall 结果。

参数

参数
`name`	`string` 要调用的函数名称。
`response`	`Struct` 函数响应，采用 JSON 对象格式。

name

string

要调用的函数名称。

response

Struct

函数响应，采用 JSON 对象格式。

VideoMetadata

描述输入视频内容的元数据。

参数

参数
`start_offset`	可选：`google.protobuf.Duration`。视频的起始偏移量。
`end_offset`	可选：`google.protobuf.Duration`。视频的结束偏移量。

start_offset

可选：google.protobuf.Duration。

视频的起始偏移量。

end_offset

可选：google.protobuf.Duration。

视频的结束偏移量。

SafetySetting

安全设置。

参数
`category`	可选：`HarmCategory`。有害类别。
`threshold`	可选：`HarmBlockThreshold`。有害屏蔽阈值。
`max_influential_terms`	可选：`int`。对安全得分贡献最大的影响字词的最大数量，可能导致潜在屏蔽。
`method`	可选：`HarmBlockMethod`。指定是将阈值用于概率得分还是严重程度得分。如果未指定，则阈值用于概率得分。

HarmCategory

屏蔽内容的有害类别。

参数
`HARM_CATEGORY_UNSPECIFIED`	未指定有害类别。
`HARM_CATEGORY_HATE_SPEECH`	有害类别为仇恨言论。
`HARM_CATEGORY_DANGEROUS_CONTENT`	有害类别为危险内容。
`HARM_CATEGORY_HARASSMENT`	有害类别为骚扰。
`HARM_CATEGORY_SEXUALLY_EXPLICIT`	有害类别为露骨色情内容。

HarmBlockThreshold

用于屏蔽回答的概率阈值级别。

参数
`HARM_BLOCK_THRESHOLD_UNSPECIFIED`	未指定的有害屏蔽阈值。
`BLOCK_LOW_AND_ABOVE`	屏蔽最低阈值及较高值（即屏蔽更多）。
`BLOCK_MEDIUM_AND_ABOVE`	屏蔽中等阈值及更高级别。
`BLOCK_ONLY_HIGH`	仅屏蔽高阈值（即屏蔽较少）。
`BLOCK_NONE`	全部不屏蔽。

HarmBlockMethod

根据概率和严重级别组合屏蔽回答的概率阈值。

参数
`HARM_BLOCK_METHOD_UNSPECIFIED`	未指定有害内容屏蔽方法。
`SEVERITY`	有害内容屏蔽方法同时使用可能性得分和严重程度得分。
`PROBABILITY`	有害内容屏蔽方法使用概率得分。

GenerationConfig

生成提示时使用的配置设置。

参数
`temperature`	可选：`float`。控制预测的随机性。
`top_p`	可选：`float`。如果指定，则使用核采样。
`top_k`	可选：如果指定，则使用 top-k 采样。
`candidate_count`	可选：`int`。要生成的候选项数量。
`max_output_tokens`	可选：int 每条消息生成的输出词元数上限。
`stop_sequences`	可选：`List[string]`。停止序列。
`presence_penalty`	可选：`float`。正惩罚。
`frequency_penalty`	可选：`float`。频次处罚。
`response_mime_type`	可选：`string (enum)`。生成的候选文本的输出回答 mimetype。支持的 mimetype： `text/plain`：（默认）文本输出。 `application/json`：候选项中的 JSON 响应。需要提示模型输出适当的回答类型，否则行为未定义。这是预览版功能。

示例

非流式文本回答

根据文本输入生成非流式传输模型回答。

REST

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
TEXT：要包含在提示中的文本说明。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

请求 JSON 正文：

{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "TEXT"
    }]
  }]
}'

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content

Python

import vertexai

from vertexai.generative_models import GenerativeModel

vertexai.init(project=PROJECT_ID, location="us-central1")

model = GenerativeModel(MODEL_ID)
response = model.generate_content("Write a story about a magic backpack.")

print(response)

NodeJS

const {VertexAI} = require('@google-cloud/vertexai');

/**
 * TODO(developer): Update these variables before running the sample.
 */
async function generateContent(
  projectId = 'PROJECT_ID',
  location = 'us-central1',
  model = 'gemini-1.5-flash-001'
) {
  // Initialize Vertex with your Cloud project and location
  const vertexAI = new VertexAI({project: projectId, location: location});

  // Instantiate the model
  const generativeModel = vertexAI.getGenerativeModel({
    model: model,
  });

  const request = {
    contents: [
      {
        role: 'user',
        parts: [
          {
            text: 'Write a story about a magic backpack.',
          },
        ],
      },
    ],
  };

  console.log(JSON.stringify(request));

  const result = await generativeModel.generateContent(request);

  console.log(result.response.candidates[0].content.parts[0].text);
}

非流式多模态回答

根据多模态输入（例如文本和图片）生成非流式模型回答。

REST

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
TEXT：要包含在提示中的文本说明。
FILE_URI：存储数据的文件的 Cloud Storage URI。
MIME_TYPE：数据的 TIANA MIME 类型。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

请求 JSON 正文：

{
"contents": [{
  "role": "user",
  "parts": [
    {
      "text": "TEXT"
    },
    {
      "file_data": {"file_uri": "FILE_URI", "MIME_TYPE"}
    },
    {
      "file_data": {"file_uri": "FILE_URI", "MIME_TYPE"}
    }
  ]
}]
}

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content

Python

import vertexai

from vertexai.generative_models import GenerativeModel, Part

vertexai.init(project=PROJECT_ID, location="us-central1")

model = GenerativeModel(MODEL_ID)
response = model.generate_content(
    [
        Part.from_uri(
            "gs://cloud-samples-data/generative-ai/video/animals.mp4", "video/mp4"
        ),
        Part.from_uri(
            "gs://cloud-samples-data/generative-ai/image/character.jpg",
            "image/jpeg",
        ),
        "Are these video and image correlated?",
    ]
)

print(response)

NodeJS

const {VertexAI} = require('@google-cloud/vertexai');

/**
 * TODO(developer): Update these variables before running the sample.
 */
async function generateContent(
  projectId = 'PROJECT_ID',
  location = 'us-central1',
  model = 'gemini-1.5-flash-001'
) {
  // Initialize Vertex AI
  const vertexAI = new VertexAI({project: projectId, location: location});
  const generativeModel = vertexAI.getGenerativeModel({model: model});

  const request = {
    contents: [
      {
        role: 'user',
        parts: [
          {
            file_data: {
              file_uri: 'gs://cloud-samples-data/video/animals.mp4',
              mime_type: 'video/mp4',
            },
          },
          {
            file_data: {
              file_uri:
                'gs://cloud-samples-data/generative-ai/image/character.jpg',
              mime_type: 'image/jpeg',
            },
          },
          {text: 'Are this video and image correlated?'},
        ],
      },
    ],
  };

  const result = await generativeModel.generateContent(request);

  console.log(result.response.candidates[0].content.parts[0].text);
}

流式传输文本回答

根据文本输入生成流式模型回答。

REST

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
TEXT：要包含在提示中的文本说明。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:streamGenerateContent

请求 JSON 正文：

{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "TEXT"
    }]
  }]
}'

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:streamGenerateContent"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:streamGenerateContent" | Select-Object -Expand Content

Python

import vertexai

from vertexai.generative_models import GenerativeModel

vertexai.init(project=PROJECT_ID, location="us-central1")

model = GenerativeModel(MODEL_ID)
responses = model.generate_content(
    "Write a story about a magic backpack.", stream=True
)

for response in responses:
    print(response)

NodeJS

const {VertexAI} = require('@google-cloud/vertexai');

/**
 * TODO(developer): Update these variables before running the sample.
 */
async function generateContent(
  projectId = 'PROJECT_ID',
  location = 'us-central1',
  model = 'gemini-1.5-flash-001'
) {
  // Initialize Vertex with your Cloud project and location
  const vertexAI = new VertexAI({project: projectId, location: location});

  // Instantiate the model
  const generativeModel = vertexAI.getGenerativeModel({
    model: model,
  });

  const request = {
    contents: [
      {
        role: 'user',
        parts: [
          {
            text: 'Write a story about a magic backpack.',
          },
        ],
      },
    ],
  };

  console.log(JSON.stringify(request));

  const result = await generativeModel.generateContentStream(request);
  for await (const item of result.stream) {
    console.log(item.candidates[0].content.parts[0].text);
  }
}

流式多模态回答

根据多模态输入（如文本和图片）生成流式模型回答。

REST

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
TEXT：要包含在提示中的文本说明。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:streamGenerateContent

请求 JSON 正文：

{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "TEXT"
    }]
  }]
}'

如需发送请求，请选择以下方式之一：

curl

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:streamGenerateContent"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:streamGenerateContent" | Select-Object -Expand Content

Python

import vertexai

from vertexai.generative_models import GenerativeModel, Part

vertexai.init(project=PROJECT_ID, location="us-central1")

model = GenerativeModel(MODEL_ID)
responses = model.generate_content(
    [
        Part.from_uri(
            "gs://cloud-samples-data/generative-ai/video/animals.mp4", "video/mp4"
        ),
        Part.from_uri(
            "gs://cloud-samples-data/generative-ai/image/character.jpg",
            "image/jpeg",
        ),
        "Are these video and image correlated?",
    ],
    stream=True,
)

for response in responses:
    print(response)

NodeJS

const {VertexAI} = require('@google-cloud/vertexai');

/**
 * TODO(developer): Update these variables before running the sample.
 */
async function generateContent(
  projectId = 'PROJECT_ID',
  location = 'us-central1',
  model = 'gemini-1.5-flash-001'
) {
  // Initialize Vertex AI
  const vertexAI = new VertexAI({project: projectId, location: location});
  const generativeModel = vertexAI.getGenerativeModel({model: model});

  const request = {
    contents: [
      {
        role: 'user',
        parts: [
          {
            file_data: {
              file_uri: 'gs://cloud-samples-data/video/animals.mp4',
              mime_type: 'video/mp4',
            },
          },
          {
            file_data: {
              file_uri:
                'gs://cloud-samples-data/generative-ai/image/character.jpg',
              mime_type: 'image/jpeg',
            },
          },
          {text: 'Are this video and image correlated?'},
        ],
      },
    ],
  };

  const result = await generativeModel.generateContentStream(request);

  for await (const item of result.stream) {
    console.log(item.candidates[0].content.parts[0].text);
  }
}

后续步骤

详细了解 Gemini API。
详细了解函数调用。
详细了解 Gemini 模型的标准回答。