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 数据时应使用此音量，并将此值保留为当前音量，并在下一个 ConverseRequest 的 AudioOutConfig 中提供此值。（某些客户端可能还会实现其他方式来允许更改当前音量，例如提供用户可以旋转的旋钮。）

MicrophoneMode

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

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

ConverseState

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

字段
conversation_state

bytes

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