Kể từ ngày 13 tháng 6 năm 2023, Hành động trò chuyện không còn được dùng nữa. Để biết thêm thông tin, hãy xem phần Hành động trò chuyện ngừng hoạt động.

Trang này được dịch bởi Cloud Translation API.

Package google.assistant.embedded.v1alpha1

Chỉ mục

EmbeddedAssistant (giao diện)
AudioInConfig (thông báo)
AudioInConfig.Encoding (enum)
AudioOut (thông báo)
AudioOutConfig (thông báo)
AudioOutConfig.Encoding (enum)
ConverseConfig (thông báo)
ConverseRequest (thông báo)
ConverseResponse (thông báo)
ConverseResponse.EventType (enum)
ConverseResult (thông báo)
ConverseResult.MicrophoneMode (enum)
ConverseState (thông báo)

EmbeddedAssistant

Dịch vụ triển khai API Trợ lý Google.

Converse

Converse
`rpc Converse(ConverseRequest) returns (ConverseResponse)` Bắt đầu hoặc tiếp tục cuộc trò chuyện với dịch vụ trợ lý được nhúng. Mỗi lệnh gọi sẽ thực hiện một lượt khứ hồi, gửi một yêu cầu âm thanh đến dịch vụ và nhận phản hồi bằng âm thanh. Sử dụng tính năng truyền trực tuyến hai chiều để nhận kết quả (chẳng hạn như sự kiện `END_OF_UTTERANCE`) trong khi gửi âm thanh. Một cuộc trò chuyện là một hoặc nhiều kết nối gRPC, mỗi kết nối bao gồm một số yêu cầu và phản hồi được truyền trực tuyến. Ví dụ: người dùng nói Thêm vào danh sách mua sắm của tôi và trợ lý trả lời Bạn muốn thêm gì?. Trình tự các yêu cầu và phản hồi được truyền trực tuyến trong thông báo gRPC đầu tiên có thể là: 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 Sau đó, người dùng nói bánh mì vòng và Trợ lý trả lời OK, tôi đã thêm bánh mì vòng vào danh sách mua sắm của bạn. Lệnh này được gửi dưới dạng một lệnh gọi kết nối gRPC khác đến phương thức `Converse`, lại với các yêu cầu và phản hồi được truyền trực tuyến, chẳng hạn như: 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 Mặc dù không đảm bảo thứ tự chính xác của các câu trả lời, các thông báo ConverseResponse.audio_out tuần tự sẽ luôn chứa các phần âm thanh tuần tự. Ủy quyền Yêu cầu phạm vi OAuth sau: `https://www.googleapis.com/auth/assistant-sdk-prototype` Để biết thêm thông tin, hãy xem Hướng dẫn xác thực.

rpc Converse(ConverseRequest) returns (ConverseResponse)

Bắt đầu hoặc tiếp tục cuộc trò chuyện với dịch vụ trợ lý được nhúng. Mỗi lệnh gọi sẽ thực hiện một lượt khứ hồi, gửi một yêu cầu âm thanh đến dịch vụ và nhận phản hồi bằng âm thanh. Sử dụng tính năng truyền trực tuyến hai chiều để nhận kết quả (chẳng hạn như sự kiện END_OF_UTTERANCE) trong khi gửi âm thanh.

Một cuộc trò chuyện là một hoặc nhiều kết nối gRPC, mỗi kết nối bao gồm một số yêu cầu và phản hồi được truyền trực tuyến. Ví dụ: người dùng nói Thêm vào danh sách mua sắm của tôi và trợ lý trả lời Bạn muốn thêm gì?. Trình tự các yêu cầu và phản hồi được truyền trực tuyến trong thông báo gRPC đầu tiên có thể là:

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

Sau đó, người dùng nói bánh mì vòng và Trợ lý trả lời OK, tôi đã thêm bánh mì vòng vào danh sách mua sắm của bạn. Lệnh này được gửi dưới dạng một lệnh gọi kết nối gRPC khác đến phương thức Converse, lại với các yêu cầu và phản hồi được truyền trực tuyến, chẳng hạn như:

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

Mặc dù không đảm bảo thứ tự chính xác của các câu trả lời, các thông báo ConverseResponse.audio_out tuần tự sẽ luôn chứa các phần âm thanh tuần tự.

Ủy quyền

Yêu cầu phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem Hướng dẫn xác thực.

AudioInConfig

Chỉ định cách xử lý dữ liệu audio_in sẽ được cung cấp trong các yêu cầu tiếp theo. Để biết các chế độ cài đặt được đề xuất, hãy xem các phương pháp hay nhất về API gRPC của Trợ lý Google.

Các trường

Các trường
`encoding`	`Encoding` Bắt buộc Mã hoá dữ liệu âm thanh được gửi trong tất cả tin nhắn `audio_in`.
`sample_rate_hertz`	`int32` Bắt buộc Tốc độ lấy mẫu (tính bằng Hertz) của dữ liệu âm thanh gửi trong tất cả tin nhắn `audio_in`. Các giá trị hợp lệ là từ 16000-24000, nhưng 16000 là tối ưu. Để có kết quả tốt nhất, hãy đặt tốc độ lấy mẫu của nguồn âm thanh thành 16000 Hz. Nếu không thể, hãy sử dụng tốc độ lấy mẫu gốc của nguồn âm thanh (thay vì lấy mẫu lại).

encoding

Encoding

Bắt buộc Mã hoá dữ liệu âm thanh được gửi trong tất cả tin nhắn audio_in.

sample_rate_hertz

int32

Bắt buộc Tốc độ lấy mẫu (tính bằng Hertz) của dữ liệu âm thanh gửi trong tất cả tin nhắn audio_in. Các giá trị hợp lệ là từ 16000-24000, nhưng 16000 là tối ưu. Để có kết quả tốt nhất, hãy đặt tốc độ lấy mẫu của nguồn âm thanh thành 16000 Hz. Nếu không thể, hãy sử dụng tốc độ lấy mẫu gốc của nguồn âm thanh (thay vì lấy mẫu lại).

Mã hoá

Mã hoá âm thanh của dữ liệu được gửi trong tin nhắn âm thanh. Âm thanh phải là một kênh (đơn âm). Ngôn ngữ duy nhất được hỗ trợ là "en-US".

Enum
`ENCODING_UNSPECIFIED`	Chưa xác định. Sẽ trả về kết quả `google.rpc.Code.INVALID_ARGUMENT`.
`LINEAR16`	Các mẫu 16 bit có chữ ký nhỏ không nén (Linear PCM). Phương thức mã hoá này không bao gồm tiêu đề, chỉ bao gồm các byte âm thanh thô.
`FLAC`	`FLAC` (Bộ mã hoá âm thanh miễn phí không tổn hao) là phương thức mã hoá được đề xuất vì đây là phương thức mã hoá không tổn hao – do đó, khả năng nhận dạng không bị xâm phạm và chỉ cần khoảng một nửa băng thông của `LINEAR16`. Quá trình mã hoá này bao gồm tiêu đề luồng `FLAC`, theo sau là dữ liệu âm thanh. Thư viện này hỗ trợ các mẫu 16 bit và 24 bit. Tuy nhiên, không phải trường nào trong `STREAMINFO` cũng được hỗ trợ.

AudioOut

Âm thanh có chứa câu trả lời của trợ lý cho truy vấn. Các phần dữ liệu âm thanh tuần tự sẽ được nhận trong thông báo ConverseResponse tuần tự.

Các trường

Các trường
`audio_data`	`bytes` Chỉ đầu ra Dữ liệu âm thanh chứa phản hồi của trợ lý cho truy vấn. Các phần dữ liệu âm thanh tuần tự sẽ được nhận trong thông báo `ConverseResponse` tuần tự.

audio_data

bytes

Chỉ đầu ra Dữ liệu âm thanh chứa phản hồi của trợ lý cho truy vấn. Các phần dữ liệu âm thanh tuần tự sẽ được nhận trong thông báo ConverseResponse tuần tự.

AudioOutConfig

Chỉ định định dạng mong muốn để máy chủ sử dụng khi trả về thông báo audio_out.

Các trường

Các trường
`encoding`	`Encoding` Bắt buộc Mã hoá dữ liệu âm thanh trả về trong tất cả thông báo `audio_out`.
`sample_rate_hertz`	`int32` Bắt buộc Tốc độ lấy mẫu tính bằng Hertz của dữ liệu âm thanh được trả về trong `audio_out` tin nhắn. Các giá trị hợp lệ là: 16000-24000.
`volume_percentage`	`int32` Bắt buộc Chế độ cài đặt âm lượng hiện tại cho đầu ra âm thanh của thiết bị. Giá trị hợp lệ là từ 1 đến 100 (tương ứng với 1% đến 100%).

encoding

Encoding

Bắt buộc Mã hoá dữ liệu âm thanh trả về trong tất cả thông báo audio_out.

sample_rate_hertz

int32

Bắt buộc Tốc độ lấy mẫu tính bằng Hertz của dữ liệu âm thanh được trả về trong audio_out tin nhắn. Các giá trị hợp lệ là: 16000-24000.

volume_percentage

int32

Bắt buộc Chế độ cài đặt âm lượng hiện tại cho đầu ra âm thanh của thiết bị. Giá trị hợp lệ là từ 1 đến 100 (tương ứng với 1% đến 100%).

Mã hoá

Mã hoá âm thanh của dữ liệu được trả về trong tin nhắn âm thanh. Tất cả chế độ mã hoá đều là các byte âm thanh thô không có tiêu đề, ngoại trừ những trường hợp được nêu dưới đây.

Enum
`ENCODING_UNSPECIFIED`	Chưa xác định. Sẽ trả về kết quả `google.rpc.Code.INVALID_ARGUMENT`.
`LINEAR16`	Các mẫu 16 bit có chữ ký nhỏ không nén (Linear PCM).
`MP3`	Mã hoá âm thanh MP3. Tốc độ lấy mẫu được mã hoá trong tải trọng.
`OPUS_IN_OGG`	Âm thanh được mã hoá Opus được gói trong một vùng chứa ogg. Kết quả sẽ là một tệp có thể được phát nguyên gốc trên Android và trong một số trình duyệt (như Chrome). Chất lượng mã hoá cao hơn đáng kể so với MP3 trong khi sử dụng cùng tốc độ bit. Tốc độ lấy mẫu được mã hoá trong tải trọng.

ConverseConfig

Chỉ định cách xử lý thông báo ConverseRequest.

Các trường

Các trường
`audio_in_config`	`AudioInConfig` Bắt buộc Chỉ định cách xử lý âm thanh đầu đến tiếp theo.
`audio_out_config`	`AudioOutConfig` Bắt buộc Chỉ định cách định dạng âm thanh sẽ được trả về.
`converse_state`	`ConverseState` Bắt buộc Đại diện cho trạng thái hộp thoại hiện tại.

audio_in_config

AudioInConfig

Bắt buộc Chỉ định cách xử lý âm thanh đầu đến tiếp theo.

audio_out_config

AudioOutConfig

Bắt buộc Chỉ định cách định dạng âm thanh sẽ được trả về.

converse_state

ConverseState

Bắt buộc Đại diện cho trạng thái hộp thoại hiện tại.

ConverseRequest

Tin nhắn cấp cao nhất do ứng dụng gửi. Ứng dụng phải gửi ít nhất 2 và thường là nhiều tin nhắn ConverseRequest. Tin nhắn đầu tiên phải chứa thông báo config và không được chứa dữ liệu audio_in. Tất cả thông báo tiếp theo phải chứa dữ liệu audio_in và không được chứa thông báo config.

Các trường

Các trường
Trường nhóm `converse_request`. Bạn phải chỉ định chính xác một trong các trường này trong mỗi `ConverseRequest`. `converse_request` chỉ có thể là một trong những trạng thái sau đây:
`config`	`ConverseConfig` Thông báo `config` cung cấp thông tin cho trình nhận dạng để chỉ định cách xử lý yêu cầu. `ConverseRequest` thông báo đầu tiên phải chứa một `config` thông báo.
`audio_in`	`bytes` Dữ liệu âm thanh cần được nhận dạng. Các đoạn dữ liệu âm thanh tuần tự sẽ được gửi trong thông báo `ConverseRequest` tuần tự. Thông báo `ConverseRequest` đầu tiên không được chứa dữ liệu `audio_in` và tất cả thông báo `ConverseRequest` tiếp theo phải chứa dữ liệu `audio_in`. Các byte âm thanh phải được mã hoá theo quy định trong `AudioInConfig`. Âm thanh phải được gửi theo thời gian gần đúng (16000 mẫu mỗi giây). Hệ thống sẽ trả về lỗi nếu âm thanh được gửi nhanh hơn hoặc chậm hơn đáng kể.

Trường nhóm converse_request. Bạn phải chỉ định chính xác một trong các trường này trong mỗi ConverseRequest. converse_request chỉ có thể là một trong những trạng thái sau đây:

config

ConverseConfig

Thông báo config cung cấp thông tin cho trình nhận dạng để chỉ định cách xử lý yêu cầu. ConverseRequest thông báo đầu tiên phải chứa một config thông báo.

audio_in

bytes

Dữ liệu âm thanh cần được nhận dạng. Các đoạn dữ liệu âm thanh tuần tự sẽ được gửi trong thông báo ConverseRequest tuần tự. Thông báo ConverseRequest đầu tiên không được chứa dữ liệu audio_in và tất cả thông báo ConverseRequest tiếp theo phải chứa dữ liệu audio_in. Các byte âm thanh phải được mã hoá theo quy định trong AudioInConfig. Âm thanh phải được gửi theo thời gian gần đúng (16000 mẫu mỗi giây). Hệ thống sẽ trả về lỗi nếu âm thanh được gửi nhanh hơn hoặc chậm hơn đáng kể.

ConverseResponse

Tin nhắn cấp cao nhất mà ứng dụng nhận được. Một loạt một hoặc nhiều thông báo ConverseResponse được truyền trực tuyến trở lại ứng dụng.

Các trường
Trường nhóm `converse_response`. Chính xác một trong các trường này sẽ được điền vào mỗi `ConverseResponse`. `converse_response` chỉ có thể là một trong những trạng thái sau đây:
`error`	`Status` Chỉ có thể xuất Nếu được đặt, sẽ trả về thông báo `google.rpc.Status` cho biết lỗi cho thao tác. Nếu xảy ra lỗi trong quá trình xử lý, thông báo này sẽ được thiết lập và hệ thống sẽ không gửi thêm tin nhắn nào nữa.
`event_type`	`EventType` Chỉ có dữ liệu đầu ra Cho biết loại sự kiện.
`audio_out`	`AudioOut` Chỉ đầu ra Âm thanh có chứa phản hồi của trợ lý cho truy vấn.
`result`	`ConverseResult` Chỉ có đầu ra Kết quả ngữ nghĩa cho truy vấn bằng giọng nói của người dùng.

EventType

Cho biết loại sự kiện.

Enum

EVENT_TYPE_UNSPECIFIED Chưa chỉ định sự kiện nào.

END_OF_UTTERANCE Sự kiện này cho biết rằng máy chủ đã phát hiện thấy kết thúc giọng nói của người dùng và không muốn nhận thêm giọng nói nào. Do đó, máy chủ sẽ không xử lý âm thanh bổ sung (mặc dù sau đó máy chủ có thể trả về kết quả bổ sung). Ứng dụng cần ngừng gửi dữ liệu âm thanh bổ sung, đóng một nửa kết nối gRPC và đợi tất cả kết quả bổ sung cho đến khi máy chủ đóng kết nối gRPC.

Enum
`EVENT_TYPE_UNSPECIFIED`	Chưa chỉ định sự kiện nào.
`END_OF_UTTERANCE`	Sự kiện này cho biết rằng máy chủ đã phát hiện thấy kết thúc giọng nói của người dùng và không muốn nhận thêm giọng nói nào. Do đó, máy chủ sẽ không xử lý âm thanh bổ sung (mặc dù sau đó máy chủ có thể trả về kết quả bổ sung). Ứng dụng cần ngừng gửi dữ liệu âm thanh bổ sung, đóng một nửa kết nối gRPC và đợi tất cả kết quả bổ sung cho đến khi máy chủ đóng kết nối gRPC.

ConverseResult

Kết quả ngữ nghĩa cho truy vấn bằng giọng nói của người dùng.

Các trường
`spoken_request_text`	`string` Chỉ có thể xuất Bản chép lời được ghi nhận trong nội dung người dùng nói.
`spoken_response_text`	`string` Chỉ xuất Nội dung câu trả lời bằng giọng nói của trợ lý. Dữ liệu này chỉ được trả về cho một thao tác IFTTT.
`conversation_state`	`bytes` Thông tin trạng thái chỉ có thể xuất thông tin trạng thái của `ConverseRequest` tiếp theo. Giá trị này phải được lưu trong ứng dụng và trả về trong `conversation_state` cùng với `ConverseRequest` tiếp theo. (Ứng dụng không cần phải diễn giải hoặc sử dụng giá trị này.) Bạn không cần phải lưu thông tin này khi thiết bị khởi động lại.
`microphone_mode`	`MicrophoneMode` Chỉ đầu ra Chỉ định chế độ của micrô sau khi RPC `Converse` này được xử lý.
`volume_percentage`	`int32` Chỉ đầu ra Đã cập nhật mức âm lượng. Giá trị sẽ là 0 hoặc bị bỏ qua (tức là không thay đổi) trừ khi lệnh thoại như "Tăng âm lượng" hoặc "Đặt mức âm lượng 4" đã được công nhận, trong trường hợp này, giá trị sẽ nằm trong khoảng từ 1 đến 100 (tương ứng với mức âm lượng mới từ 1% đến 100%). Thông thường, ứng dụng phải sử dụng mức âm lượng này khi phát dữ liệu `audio_out`, đồng thời giữ lại giá trị này làm mức âm lượng hiện tại và cung cấp giá trị đó trong `AudioOutConfig` của `ConverseRequest` tiếp theo. (Một số ứng dụng cũng có thể triển khai những cách khác để cho phép thay đổi mức âm lượng hiện tại, chẳng hạn như bằng cách cung cấp một núm mà người dùng có thể xoay.)

MicrophoneMode

Các trạng thái có thể có của micrô sau khi RPC Converse hoàn tất.

Enum
`MICROPHONE_MODE_UNSPECIFIED`	Chưa chỉ định chế độ nào.
`CLOSE_MICROPHONE`	Dịch vụ không mong đợi người dùng tiếp tục nhận câu hỏi. Micrô sẽ vẫn tắt cho đến khi người dùng bật lại.
`DIALOG_FOLLOW_ON`	Dịch vụ đang mong đợi người dùng tiếp tục nhận câu hỏi. Bạn phải mở lại micrô khi quá trình phát `AudioOut` hoàn tất (bằng cách bắt đầu một lệnh gọi RPC `Converse` mới để gửi âm thanh mới).

ConverseState

Cung cấp thông tin về trạng thái hiện tại của hộp thoại.

Các trường

Các trường
`conversation_state`	`bytes` Bắt buộc Giá trị `conversation_state` được trả về trong `ConverseResponse` trước đó. Bỏ qua (không đặt trường này) nếu trước đó không có `ConverseResponse`. Nếu đã có `ConverseResponse` trước đó, đừng bỏ qua trường này vì làm như vậy sẽ kết thúc cuộc trò chuyện đó (và yêu cầu mới này sẽ bắt đầu một cuộc trò chuyện mới).

conversation_state

bytes

Bắt buộc Giá trị conversation_state được trả về trong ConverseResponse trước đó. Bỏ qua (không đặt trường này) nếu trước đó không có ConverseResponse. Nếu đã có ConverseResponse trước đó, đừng bỏ qua trường này vì làm như vậy sẽ kết thúc cuộc trò chuyện đó (và yêu cầu mới này sẽ bắt đầu một cuộc trò chuyện mới).