方法:models.generateContent
- 端点
- 路径参数
- 请求正文
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- 响应正文
- 授权范围
- 示例请求 <ph type="x-smartling-placeholder">
在给定输入 GenerateContentRequest
的情况下,根据模型生成回答。
端点
<ph type="x-smartling-placeholder"></ph> 帖子
https://generativelanguage.googleapis.com/v1beta/{model=models/*}:generateContent
路径参数
model
string
必需。用于生成补全的 Model
的名称。
格式:name=models/{model}
。其格式为 models/{model}
。
请求正文
请求正文中包含结构如下的数据:
<ph type="x-smartling-placeholder">contents[]
object (Content
)
必需。当前与模型对话的内容。
对于单轮查询,这是指单个实例。对于多轮查询,此字段是重复字段,包含对话记录和最新请求。
tools[]
object (Tool
)
可选。模型可用于生成下一个回答的 Tools
列表。
Tool
是一段代码,使系统能够与外部系统交互,以便在模型的知识和范围之外执行操作或一组操作。目前唯一受支持的工具是 Function
。
toolConfig
object (ToolConfig
)
可选。请求中指定的任何 Tool
的工具配置。
safetySettings[]
object (SafetySetting
)
可选。用于屏蔽不安全内容的唯一 SafetySetting
实例的列表。
这将在 GenerateContentRequest.contents
和 GenerateContentResponse.candidates
上强制执行。每种 SafetyCategory
类型只能有一项设置。此 API 将屏蔽任何未达到这些设置所设阈值的内容和响应。此列表会替换 safetySettings 中指定的每个 SafetyCategory
的默认设置。如果列表中提供的给定 SafetyCategory
没有 SafetySetting
,该 API 将使用该类别的默认安全设置。支持危害类别 HARM_CATEGORY_HATE_SPEECH、HARM_CATEGORY_SEXUALLY_EXPLICIT、HARM_CATEGORY_DANGEROUS_CONTENT、HARM_CATEGORY_HARASSMENT。
systemInstruction
object (Content
)
可选。开发者设置的系统指令。目前仅支持文字广告。
generationConfig
object (GenerationConfig
)
可选。用于模型生成和输出的配置选项。
cachedContent
string
可选。用作上下文以提供预测的缓存内容的名称。注意:仅用于显式缓存。在显式缓存中,用户可以控制缓存(例如,要缓存哪些内容),并享受有保证的成本节约。格式:cachedContents/{cachedContent}
示例请求
文字
Python
Node.js
Kotlin
Swift
Dart
Java
映像
Python
Node.js
Kotlin
Swift
Dart
Java
音频
Python
Node.js
视频
Python
Node.js
聊天
Python
Node.js
Shell
Kotlin
Swift
Dart
Java
缓存
Python
Node.js
经调参的模型
Python
JSON 模式
Python
Node.js
Kotlin
Swift
Dart
Java
代码执行
Python
Kotlin
Java
函数调用
Python
Node.js
Kotlin
Swift
Dart
Java
生成配置
Python
Node.js
Shell
Kotlin
Swift
Dart
Java
安全设置
Python
Node.js
Shell
Kotlin
Swift
Dart
Java
系统指令
Python
Node.js
Kotlin
Swift
Dart
Java
响应正文
如果成功,则响应正文包含一个 GenerateContentResponse
实例。
方法:models.streamGenerateContent
- 端点
- 路径参数
- 请求正文
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- 响应正文
- 授权范围
- 示例请求 <ph type="x-smartling-placeholder">
在给定输入 GenerateContentRequest
的情况下,根据模型生成流式响应。
端点
<ph type="x-smartling-placeholder"></ph> 帖子
https://generativelanguage.googleapis.com/v1beta/{model=models/*}:streamGenerateContent
路径参数
model
string
必需。用于生成补全的 Model
的名称。
格式:name=models/{model}
。其格式为 models/{model}
。
请求正文
请求正文中包含结构如下的数据:
<ph type="x-smartling-placeholder">contents[]
object (Content
)
必需。当前与模型对话的内容。
对于单轮查询,这是指单个实例。对于多轮查询,此字段是重复字段,包含对话记录和最新请求。
tools[]
object (Tool
)
可选。模型可用于生成下一个回答的 Tools
列表。
Tool
是一段代码,使系统能够与外部系统交互,以便在模型的知识和范围之外执行操作或一组操作。目前唯一受支持的工具是 Function
。
toolConfig
object (ToolConfig
)
可选。请求中指定的任何 Tool
的工具配置。
safetySettings[]
object (SafetySetting
)
可选。用于屏蔽不安全内容的唯一 SafetySetting
实例的列表。
这将在 GenerateContentRequest.contents
和 GenerateContentResponse.candidates
上强制执行。每种 SafetyCategory
类型只能有一项设置。此 API 将屏蔽任何未达到这些设置所设阈值的内容和响应。此列表会替换 safetySettings 中指定的每个 SafetyCategory
的默认设置。如果列表中提供的给定 SafetyCategory
没有 SafetySetting
,该 API 将使用该类别的默认安全设置。支持危害类别 HARM_CATEGORY_HATE_SPEECH、HARM_CATEGORY_SEXUALLY_EXPLICIT、HARM_CATEGORY_DANGEROUS_CONTENT、HARM_CATEGORY_HARASSMENT。
systemInstruction
object (Content
)
可选。开发者设置的系统指令。目前仅支持文字广告。
generationConfig
object (GenerationConfig
)
可选。用于模型生成和输出的配置选项。
cachedContent
string
可选。用作上下文以提供预测的缓存内容的名称。注意:仅用于显式缓存。在显式缓存中,用户可以控制缓存(例如,要缓存哪些内容),并享受有保证的成本节约。格式:cachedContents/{cachedContent}
示例请求
文字
Python
Node.js
Kotlin
Swift
Dart
Java
映像
Python
Node.js
Kotlin
Swift
Dart
Java
视频
Python
Node.js
Kotlin
Java
聊天
Python
Node.js
Shell
Kotlin
Swift
Dart
Java
响应正文
如果成功,响应正文将包含一个 GenerateContentResponse
实例流。
GenerateContentResponse
- JSON 表示法
- PromptFeedback
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- BlockReason
- UsageMetadata
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
来自支持多个候选对象的模型的响应。
关于安全评级和内容过滤的注意事项。系统会在 GenerateContentResponse.prompt_feedback
中的提示以及 finishReason
和 safetyRatings
中针对每个候选字词报告它们。API 合同规定:- 要么返回所有请求的候选对象,要么完全不返回任何候选对象;仅当提示存在问题时,才会返回任何候选对象(请参阅 promptFeedback
)- 系统会在 finishReason
和 safetyRatings
上报告针对每个候选对象的反馈。
JSON 表示法 |
---|
{ "candidates": [ { object ( |
candidates[]
object (Candidate
)
来自模型的候选响应。
promptFeedback
object (PromptFeedback
)
返回与内容过滤器相关的提示反馈。
usageMetadata
object (UsageMetadata
)
仅限输出。关于生成请求的元数据令牌用量。
PromptFeedback
在 GenerateContentRequest.content
中指定的提示的一组反馈元数据。
JSON 表示法 |
---|
{ "blockReason": enum ( |
blockReason
enum (BlockReason
)
可选。如果已设置,系统会屏蔽提示,且不会返回任何候选字词。改述提示。
safetyRatings[]
object (SafetyRating
)
提示安全性的评分。每个类别最多有一个评分。
BlockReason
说明提示被屏蔽的原因。
枚举 | |
---|---|
BLOCK_REASON_UNSPECIFIED |
默认值。此值未使用。 |
SAFETY |
出于安全原因,提示已被屏蔽。您可以检查 safetyRatings ,了解哪个安全类别屏蔽了它。 |
OTHER |
由于未知原因,提示已被屏蔽。 |
UsageMetadata
关于生成请求的令牌使用情况的元数据。
JSON 表示法 |
---|
{ "promptTokenCount": integer, "cachedContentTokenCount": integer, "candidatesTokenCount": integer, "totalTokenCount": integer } |
promptTokenCount
integer
提示中的词元数量。设置 cacheContent 后,这仍是总有效提示大小。例如,这包括缓存内容中的词元数量。
cachedContentTokenCount
integer
提示的缓存部分(即缓存内容)中的令牌数量。
candidatesTokenCount
integer
生成的候选字词中的词元总数。
totalTokenCount
integer
生成请求的词元总数(提示 + 候选词)。
候选人
- JSON 表示法
- FinishReason
- GroundingAttribution
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- AttributionSourceId
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- GroundingPassageId
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
- SemanticRetrieverChunk
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
从模型生成的候选回复。
JSON 表示法 |
---|
{ "content": { object ( |
content
object (Content
)
仅限输出。从模型返回的生成内容。
finishReason
enum (FinishReason
)
可选。仅限输出。模型停止生成令牌的原因。
如果为空,则表示模型尚未停止生成词元。
safetyRatings[]
object (SafetyRating
)
回答候选内容的安全性评分列表。
每个类别最多有一个评分。
citationMetadata
object (CitationMetadata
)
仅限输出。模型生成的候选字词的引用信息。
此字段中可能会填充 content
中包含的任何文字的引述信息。这些是“朗诵”的段落基础 LLM 训练数据中受版权保护的材料。
tokenCount
integer
仅限输出。此候选者的词元数量。
groundingAttributions[]
object (GroundingAttribution
)
仅限输出。提供有依据的答案的来源的归因信息。
对于 GenerateAnswer
调用,系统会填充此字段。
index
integer
仅限输出。候选人在候选人列表中的索引。
FinishReason
定义模型停止生成令牌的原因。
枚举 | |
---|---|
FINISH_REASON_UNSPECIFIED |
默认值。此值未使用。 |
STOP |
模型的自然停靠点或提供的停靠序列。 |
MAX_TOKENS |
已达到请求中指定的令牌数量上限。 |
SAFETY |
候选人内容因安全原因而遭到举报。 |
RECITATION |
候选内容因复制内容而被标记。 |
LANGUAGE |
候选内容因使用不受支持的语言而被举报。 |
OTHER |
原因不明。 |
GroundingAttribution
对回答做出贡献的来源的提供方说明。
JSON 表示法 |
---|
{ "sourceId": { object ( |
sourceId
object (AttributionSourceId
)
仅限输出。对此归因做出贡献的来源的标识符。
content
object (Content
)
构成此提供方说明的依据来源内容。
AttributionSourceId
对此归因做出贡献的来源的标识符。
JSON 表示法 |
---|
{ // Union field |
联合字段 source
。
source
只能是下列其中一项:
groundingPassage
object (GroundingPassageId
)
内嵌段落的标识符。
semanticRetrieverChunk
object (SemanticRetrieverChunk
)
通过语义检索器提取的 Chunk
的标识符。
GroundingPassageId
GroundingPassage
中某个部分的标识符。
JSON 表示法 |
---|
{ "passageId": string, "partIndex": integer } |
passageId
string
仅限输出。与 GenerateAnswerRequest
的 GroundingPassage.id
匹配的段落的 ID。
partIndex
integer
仅限输出。GenerateAnswerRequest
的 GroundingPassage.content
中部分的索引。
SemanticRetrieverChunk
使用 SemanticRetrieverConfig
通过 GenerateAnswerRequest
中指定的语义检索器检索的 Chunk
的标识符。
JSON 表示法 |
---|
{ "source": string, "chunk": string } |
source
string
仅限输出。与请求的 SemanticRetrieverConfig.source
匹配的来源的名称。示例:corpora/123
或 corpora/123/documents/abc
chunk
string
仅限输出。包含归因文本的 Chunk
的名称。示例:corpora/123/documents/abc/chunks/xyz
CitationMetadata
- JSON 表示法
- CitationSource
<ph type="x-smartling-placeholder">
- </ph>
- JSON 表示法
一段内容的来源提供方说明集合。
JSON 表示法 |
---|
{
"citationSources": [
{
object ( |
citationSources[]
object (CitationSource
)
特定回答的来源引用。
CitationSource
对特定回答的一部分的引用。
JSON 表示法 |
---|
{ "startIndex": integer, "endIndex": integer, "uri": string, "license": string } |
startIndex
integer
可选。归因于此来源的响应的开头部分。
索引表示片段的起始值(以字节为单位)。
endIndex
integer
可选。归因细分受众群的结尾(不含)。
uri
string
可选。归因于部分文本来源的 URI。
license
string
可选。归因于细分来源的 GitHub 项目的许可。
必须提供许可信息才能引用代码。
GenerationConfig
用于模型生成和输出的配置选项。并非每个模型的所有参数都可以配置。
JSON 表示法 |
---|
{
"stopSequences": [
string
],
"responseMimeType": string,
"responseSchema": {
object ( |
stopSequences[]
string
可选。将停止生成输出的字符序列集(最多 5 个)。如果已指定,API 将在停止序列第一次出现时停止。停止序列将不会包含在响应中。
responseMimeType
string
可选。生成的候选文本的输出响应 MIME 类型。支持的 mimetype:text/plain
:(默认)文本输出。application/json
:候选项中的 JSON 响应。
responseSchema
object (Schema
)
可选。当回复 MIME 类型可以具有架构时,输出生成的候选文本的响应架构。架构可以是对象、基元或数组,是 OpenAPI 架构的子集。
设置后,还必须设置兼容的 responseMimeType。兼容的 mimetype:application/json
:JSON 响应的架构。
candidateCount
integer
可选。要返回的已生成响应的数量。
目前,此值只能设置为 1。如果未设置,则默认为 1。
maxOutputTokens
integer
可选。候选字词可包含的词元数量上限。
注意:默认值因型号而异,请参阅 getModel
函数返回的 Model
的 Model.output_token_limit
属性。
temperature
number
可选。控制输出的随机性。
注意:默认值因型号而异,请参阅 getModel
函数返回的 Model
的 Model.temperature
属性。
值的范围为 [0.0, 2.0]。
topP
number
可选。采样时要考虑的词元累计概率上限。
该模型结合使用 Top-k 和核采样。
词元根据为其分配的概率进行排序,因此只会考虑最有可能的词元。Top-k 采样会直接限制可考虑的词元数量上限,而 Nucleus 采样则根据累积概率限制词元数量。
注意:默认值因型号而异,请参阅 getModel
函数返回的 Model
的 Model.top_p
属性。
topK
integer
可选。采样时要考虑的词元数量上限。
模型使用核采样或结合使用 Top-k 和核采样。Top-k 采样会考虑概率最高的 topK
个词元。通过 Nucleus 采样运行的模型不支持 TopK 设置。
注意:默认值因型号而异,请参阅 getModel
函数返回的 Model
的 Model.top_k
属性。Model
中的 topK
字段为空表示模型未应用 Top-k 采样,且不允许对请求设置 topK
。
HarmCategory
评分的类别。
这些类别涵盖开发者可能希望调整的各种危害。
枚举 | |
---|---|
HARM_CATEGORY_UNSPECIFIED |
未指定类别。 |
HARM_CATEGORY_DEROGATORY |
针对身份和/或受保护属性的负面或有害评论。 |
HARM_CATEGORY_TOXICITY |
粗鲁、无礼或亵渎性的内容。 |
HARM_CATEGORY_VIOLENCE |
描述描绘针对个人或团体的暴力行为的场景,或一般性血腥描述。 |
HARM_CATEGORY_SEXUAL |
包含对性行为或其他淫秽内容的引用。 |
HARM_CATEGORY_MEDICAL |
宣传未经审查的医疗建议。 |
HARM_CATEGORY_DANGEROUS |
宣扬、助长或鼓励有害行为的危险内容。 |
HARM_CATEGORY_HARASSMENT |
骚扰内容。 |
HARM_CATEGORY_HATE_SPEECH |
仇恨言论和内容。 |
HARM_CATEGORY_SEXUALLY_EXPLICIT |
露骨色情内容。 |
HARM_CATEGORY_DANGEROUS_CONTENT |
危险内容。 |
SafetyRating
一段内容的安全评级。
安全评级包含一段内容对应的伤害类别以及该类别的伤害概率级别。我们将内容划分为多个危害类别的安全性,并在此处列出了损害分类的概率。
JSON 表示法 |
---|
{ "category": enum ( |
category
enum (HarmCategory
)
必需。相应评分的类别。
probability
enum (HarmProbability
)
必需。此类内容的损害概率。
blocked
boolean
此内容是因为此分级而被屏蔽吗?
HarmProbability
某项内容有害的概率。
分类系统会给出内容不安全概率。这并不表示某段内容造成的损害的严重程度。
枚举 | |
---|---|
HARM_PROBABILITY_UNSPECIFIED |
未指定概率。 |
NEGLIGIBLE |
内容不安全的可能性微乎其微。 |
LOW |
内容不安全的可能性较低。 |
MEDIUM |
内容不安全的可能性为中等。 |
HIGH |
内容很有可能不安全。 |
SafetySetting
安全设置,影响安全拦截行为。
为某个类别传递安全设置会改变允许的内容被屏蔽的概率。
JSON 表示法 |
---|
{ "category": enum ( |
category
enum (HarmCategory
)
必需。此设置的类别。
threshold
enum (HarmBlockThreshold
)
必需。控制阻止伤害的概率阈值。
HarmBlockThreshold
在达到或超过指定伤害概率的情况下禁播。
枚举 | |
---|---|
HARM_BLOCK_THRESHOLD_UNSPECIFIED |
未指定阈值。 |
BLOCK_LOW_AND_ABOVE |
系统将允许显示值为“NEGIBLE”的内容。 |
BLOCK_MEDIUM_AND_ABOVE |
系统将允许显示值为“NEGIBLE”和“LOW”的内容。 |
BLOCK_ONLY_HIGH |
允许使用“NEGIBLE”、“LOW”和“MEDIUM”这三种类型的内容。 |
BLOCK_NONE |
允许访问所有内容。 |