Package google.assistant.embedded.v1alpha1

索引

EmbeddedAssistant

实现 Google Assistant API 的服务。

Converse

rpc Converse(ConverseRequest) returns (ConverseResponse)

发起或继续与嵌入式 Google 助理服务对话。每个调用都会执行一次往返,即向服务发送音频请求并接收音频响应。使用双向流式传输在发送音频时接收结果,例如 END_OF_UTTERANCE 事件。

对话是一个或多个 gRPC 连接,每个连接都由多个流式传输请求和响应组成。例如,用户说“添加到我的购物清单”,助理会回复“你想添加什么?”。第一条 gRPC 消息中的流式传输请求和响应的顺序可能是:

  • ConverseRequest.config
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseResponse.event_type.END_OF_UTTERANCE
  • ConverseResponse.result.microphone_mode.DIALOG_FOLLOW_ON
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out

然后,用户说出“百吉饼”,智能助理回复“好的,我已将百吉饼添加到你的购物清单中”。这将作为另一个 gRPC 连接调用发送到 Converse 方法,再次包含流式传输的请求和响应,例如:

  • ConverseRequest.config
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseResponse.event_type.END_OF_UTTERANCE
  • ConverseResponse.result.microphone_mode.CLOSE_MICROPHONE
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out

虽然无法保证响应的精确顺序,但顺序 ConverseResponse.audio_out 消息将始终包含顺序的音频部分。

授权

需要以下 OAuth 作用域:

  • https://www.googleapis.com/auth/assistant-sdk-prototype

如需了解详情,请参阅身份验证指南

AudioInConfig

指定如何处理后续请求中提供的 audio_in 数据。如需了解推荐的设置,请参阅 Google Assistant gRPC API 最佳实践

字段
encoding

Encoding

必需:对所有 audio_in 消息中发送的音频数据的编码。

sample_rate_hertz

int32

必需:所有 audio_in 消息中发送的音频数据的采样率(以赫兹为单位)。有效值为 16000-24000,但最佳值为 16000。为获得最佳结果,请将音频源的采样率设置为 16000 Hz。如果无法做到这一点,请使用音频源的原生采样率(而不是重新采样)。

编码

语音消息中发送的数据的音频编码。音频必须为单声道(单声道)。唯一支持的语言是“en-US”。

枚举
ENCODING_UNSPECIFIED 未指定。将返回结果 google.rpc.Code.INVALID_ARGUMENT
LINEAR16 未压缩的 16 位有符号小端字节序采样(线性 PCM)。这种编码不含标头,只包括原始音频字节。
FLAC 推荐使用 FLAC(免费无损音频编解码器)编码,因为它是无损的,因此丝毫不会影响到识别,而且所需带宽仅为 LINEAR16 的大约一半。此编码包括后跟音频数据的 FLAC 流标头。它支持 16 位和 24 位样本,但并非 STREAMINFO 中的所有字段都受支持。

AudioOut

包含 Google 助理对询问的回复的音频。在连续的 ConverseResponse 消息中接收连续的音频数据块。

字段
audio_data

bytes

仅限输出:包含 Google 助理对询问的回复的音频数据。连续的音频数据块在顺序 ConverseResponse 消息中接收。

AudioOutConfig

指定服务器在返回 audio_out 消息时要使用的格式。

字段
encoding

Encoding

必需字段。要在所有 audio_out 消息中返回的音频数据的编码。

sample_rate_hertz

int32

必需audio_out 消息中返回的音频数据的采样率(以赫兹为单位)。有效值为:16000-24000。

volume_percentage

int32

必需:设备音频输出的当前音量设置。有效值为 1 到 100(对应于 1% 到 100%)。

编码

语音消息中返回的数据的音频编码。所有编码都是不含标头的原始音频字节,下面指明的情况除外。

枚举
ENCODING_UNSPECIFIED 未指定。将返回结果 google.rpc.Code.INVALID_ARGUMENT
LINEAR16 未压缩的 16 位有符号小端字节序采样(线性 PCM)。
MP3 MP3 音频编码。采样率在载荷中进行编码。
OPUS_IN_OGG 封装在 Ogg 容器中的 Opus 编码音频。结果会得到一个可在 Android 和某些浏览器(例如 Chrome)中原生播放的文件。在比特率相同的情况下,编码的质量远高于 MP3。采样率在载荷中进行编码。

ConverseConfig

指定如何处理 ConverseRequest 消息。

字段
audio_in_config

AudioInConfig

必需 - 指定如何处理后续传入音频。

audio_out_config

AudioOutConfig

必需字段。用于指定要返回的音频的格式。

converse_state

ConverseState

必需:表示当前的对话框状态。

ConverseRequest

客户端发送的顶级消息。客户端必须至少发送两条 ConverseRequest 消息,通常数量较多。第一条消息必须包含 config 消息,且不得包含 audio_in 数据。所有后续消息都必须包含 audio_in 数据,且不得包含 config 消息。

字段
联合字段 converse_request。在每个 ConverseRequest 中,只能指定其中一个字段。converse_request 只能是下列其中一项:
config

ConverseConfig

config 消息会向识别器提供指定如何处理请求的信息。第一条 ConverseRequest 消息必须包含 config 消息。

audio_in

bytes

要识别的音频数据。连续的音频数据块在连续的 ConverseRequest 消息中发送。第一个 ConverseRequest 消息不得包含 audio_in 数据,所有后续 ConverseRequest 消息必须包含 audio_in 数据。必须按照 AudioInConfig 中所述对音频字节进行编码。音频必须以近乎实时的速度发送(每秒 16000 个样本)。如果音频发送速度明显变快或变慢,系统将会返回错误。

ConverseResponse

客户端收到的顶级消息。将一系列一个或多个 ConverseResponse 消息流式传输回客户端。

字段
联合字段 converse_response。在每个 ConverseResponse 中,系统将仅填充其中一个字段。converse_response 只能是下列其中一项:
error

Status

仅限输出:如果设置,则返回 google.rpc.Status 消息,说明操作发生的错误。如果在处理过程中发生错误,系统将设置此消息,之后不会再发送任何消息。

event_type

EventType

仅限输出:表示事件类型。

audio_out

AudioOut

仅限输出:包含 Google 助理对询问的回复的音频。

result

ConverseResult

仅限输出:用户语音查询的语义结果。

EventType

指明事件的类型。

枚举
EVENT_TYPE_UNSPECIFIED 未指定事件。
END_OF_UTTERANCE 该事件表明服务器已经检测到用户所说话语结束,并且预计不会有额外的语音。因此,服务器不会处理额外的音频(尽管后续可能会返回额外的结果)。客户端应停止发送额外的音频数据,半关闭 gRPC 连接,并等待任何其他结果,直到服务器关闭 gRPC 连接为止。

ConverseResult

用户语音查询的语义结果。

字段
spoken_request_text

string

仅限输出:系统可识别的用户所说内容的转写内容。

spoken_response_text

string

仅限输出:Google 助理的语音回复文字。系统仅会针对 IFTTT 操作返回此值。

conversation_state

bytes

后续 ConverseRequest仅限输出状态信息。此值应保存在客户端中,并与下一个 ConverseRequest 一起在 conversation_state 中返回。(客户端无需解释或使用此值。)无需在设备重启后保存此信息。

microphone_mode

MicrophoneMode

仅限输出,用于指定处理此 Converse RPC 后麦克风的模式。

volume_percentage

int32

仅限输出:更新了音量。除非系统识别出“调高音量”或“将音量设为 4”等语音指令,否则该值将为 0 或省略(表示没有变化),在这种情况下,该值将介于 1 到 100 之间(对应于 1% 到 100% 的新音量级别)。通常,客户端在播放 audio_out 数据时应使用此音量,并将此值保留为当前音量,并在下一个 ConverseRequestAudioOutConfig 中提供此值。(某些客户端可能还会实现其他方式来允许更改当前音量,例如提供用户可以旋转的旋钮。)

MicrophoneMode

Converse RPC 完成后麦克风可能的状态。

枚举
MICROPHONE_MODE_UNSPECIFIED 未指定模式。
CLOSE_MICROPHONE 服务不希望用户提出后续问题。麦克风应保持关闭状态,直到用户重新启用它。
DIALOG_FOLLOW_ON 服务会期待用户提出后续问题。在 AudioOut 播放完成(通过启动新的 Converse RPC 调用以发送新音频)时,应重新打开麦克风。

ConverseState

提供有关当前对话框状态的信息。

字段
conversation_state

bytes

必需元素。之前的 ConverseResponse 中返回的 conversation_state 值。如果不存在前面的 ConverseResponse,请省略(不要设置该字段)。如果之前已有 ConverseResponse,请勿省略此字段;否则会结束相应对话(此新请求将启动新对话)。