Package google.assistant.embedded.v1alpha2

Chỉ mục

EmbeddedAssistant

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

Kiến tạo

rpc Assist(AssistRequest) returns (AssistResponse)

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à:

  • AssistRequest.config
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistResponse.event_type.END_OF_UTTERANCE
  • AssistResponse.speech_results.transcript "thêm vào danh sách mua sắm của tôi"
  • AssistResponse.dialog_state_out.microphone_mode.DIALOG_FOLLOW_ON
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.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 Assist, 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ư:

  • AssistRequest.config
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistResponse.event_type.END_OF_UTTERANCE
  • AssistResponse.dialog_state_out.microphone_mode.CLOSE_MICROPHONE
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out

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

Phạm vi uỷ 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.

AssistConfig

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

Các trường
audio_out_config

AudioOutConfig

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

screen_out_config

ScreenOutConfig

Không bắt buộc Chỉ định định dạng mong muốn để sử dụng khi máy chủ trả về phản hồi màn hình bằng hình ảnh.

dialog_state_in

DialogStateIn

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

device_config

DeviceConfig

Cấu hình thiết bị xác định duy nhất một thiết bị cụ thể.

debug_config

DebugConfig

Không bắt buộc Gỡ lỗi tham số cho toàn bộ RPC Assist.

Trường nhóm type.

type chỉ có thể là một trong những trạng thái sau đây:
audio_in_config

AudioInConfig

Chỉ định cách xử lý âm thanh đầu đến tiếp theo. Bắt buộc nếu AssistRequest.audio_in byte được cung cấp trong các yêu cầu tiếp theo.

text_query

string

Nội dung nhập bằng văn bản sẽ được gửi tới Trợ lý. Bạn có thể điền sẵn dữ liệu này từ giao diện văn bản nếu không có đầu vào âm thanh.

AssistRequest

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 AssistRequest. 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
Trường nhóm type. Bạn phải chỉ định chính xác một trong các trường này trong mỗi AssistRequest. type chỉ có thể là một trong những trạng thái sau đây:
config

AssistConfig

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. AssistRequest 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 AssistRequest tuần tự. Thông báo AssistRequest đầu tiên không được chứa dữ liệu audio_in và tất cả thông báo AssistRequest 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ể.

AssistResponse

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 AssistResponse được truyền trực tuyến trở lại ứng dụng.

Các trường
event_type

EventType

Chỉ có dữ liệu đầu ra Cho biết loại sự kiện.

audio_out

AudioOut

Chỉ xuất Âm thanh có chứa phản hồi của Trợ lý cho yêu cầu.

screen_out

ScreenOut

Output-only (Chỉ đầu ra) Chứa phản hồi bằng hình ảnh của Trợ lý cho truy vấn.

device_action

DeviceAction

Output-only (Chỉ đầu ra) Chứa hành động được kích hoạt bởi truy vấn với các tải trọng phù hợp và phân tích cú pháp ngữ nghĩa.

speech_results[]

SpeechRecognitionResult

Chỉ có đầu ra Danh sách lặp lại này không chứa hoặc có nhiều kết quả nhận dạng lời nói tương ứng với các phần liên tiếp của âm thanh hiện đang được xử lý, bắt đầu với phần tương ứng với âm thanh đầu tiên (và phần ổn định nhất) so với phần tương ứng với âm thanh gần đây nhất. Bạn có thể nối các chuỗi này để xem toàn bộ phản hồi đang diễn ra. Khi quá trình nhận dạng lời nói hoàn tất, danh sách này sẽ chứa một mục có stability/1.0.

dialog_state_out

DialogStateOut

Output-only (Chỉ đầu ra) Chứa kết quả liên quan đến truy vấn của người dùng.

debug_info

DebugInfo

Thông tin gỡ lỗi chỉ xuất dành cho nhà phát triển. Chỉ được trả về nếu yêu cầu đặt return_debug_info thành true.

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.

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ề SDK Trợ lý Google.

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).

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).

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

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

Các trường
audio_data

bytes

Chỉ xuất Dữ liệu âm thanh chứa câu trả lời của Trợ lý cho yêu cầu. Các phần dữ liệu âm thanh tuần tự sẽ được nhận trong thông báo AssistResponse 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
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.

DebugConfig

Gỡ lỗi tham số cho yêu cầu hiện tại.

Các trường
return_debug_info

bool

Khi bạn đặt trường này thành true (đúng), trường debug_info trong AssistResponse có thể được điền sẵn. Tuy nhiên, việc này sẽ làm tăng đáng kể độ trễ của phản hồi.

DebugInfo

Thông tin gỡ lỗi cho nhà phát triển. Chỉ được trả về nếu yêu cầu đặt return_debug_info thành true.

Các trường
aog_agent_to_assistant_json

string

Phản hồi JSON ban đầu từ tác nhân Hành động trên Google đến máy chủ Google. Xem AppResponse. Tệp này sẽ chỉ được điền sẵn nếu người tạo yêu cầu sở hữu dự án AoG và dự án AoG đang ở chế độ xem trước.

DeviceAction

Phản hồi được trả về thiết bị nếu người dùng đã kích hoạt một Hành động trên thiết bị. Ví dụ: một thiết bị hỗ trợ truy vấn Turn on the light (Bật đèn) sẽ nhận được DeviceAction với tải trọng JSON chứa ngữ nghĩa của yêu cầu.

Các trường
device_request_json

string

JSON chứa phản hồi lệnh thiết bị được tạo từ ngữ pháp Hành động trên thiết bị đã kích hoạt. Định dạng này do ý định action.devices.EXECUTE cung cấp cho một đặc điểm nhất định.

DeviceConfig

Bắt buộc Các trường xác định thiết bị với Trợ lý.

Xem thêm:

Các trường
device_id

string

Bắt buộc Giá trị nhận dạng duy nhất của thiết bị. Mã nhận dạng chỉ được dài tối đa 128 ký tự. Ví dụ: DBCDW098234. Giá trị này PHẢI khớp với device_id được trả về trong quá trình đăng ký thiết bị. device_id này được dùng để so khớp với các thiết bị đã đăng ký của người dùng nhằm tra cứu các đặc điểm và khả năng được hỗ trợ của thiết bị này. Thông tin này không được thay đổi sau khi thiết bị khởi động lại. Tuy nhiên, bạn không nên lưu dữ liệu này trong các lần đặt lại mặc định về trạng thái ban đầu.

device_model_id

string

Bắt buộc Giá trị nhận dạng duy nhất cho mẫu thiết bị. Phải từng liên kết device_model_id và device_id thông qua quy trình đăng ký thiết bị.

DeviceLocation

Có 3 nguồn thông tin về vị trí. Các tham số này được sử dụng với mức độ ưu tiên sau:

  1. DeviceLocation này, chủ yếu được sử dụng cho thiết bị di động có GPS .
  2. Vị trí do người dùng chỉ định trong quá trình thiết lập thiết bị; đây là vị trí cho mỗi người dùng cho mỗi thiết bị. Vị trí này được sử dụng nếu bạn không chỉ định DeviceLocation.
  3. Vị trí được suy luận dựa trên địa chỉ IP. Thuộc tính này chỉ được sử dụng nếu không chỉ định đối tượng nào ở trên.
Các trường
coordinates

LatLng

Vĩ độ và kinh độ của thiết bị.

DialogStateIn

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
conversation_state

bytes

Bắt buộc Bạn phải luôn đặt trường này thành giá trị DialogStateOut.conversation_state được trả về trong Assist RPC trước đó. Bạn chỉ nên bỏ qua (không đặt trường) nếu không có RPC Assist trước đó vì đây là RPC Assist đầu tiên do thiết bị này tạo ra sau lần thiết lập đầu tiên và/hoặc được đặt lại về trạng thái mặc định về trạng thái ban đầu.

language_code

string

Bắt buộc Ngôn ngữ của yêu cầu theo cú pháp IETF BCP 47 (ví dụ: "en-US"). Xem Hỗ trợ ngôn ngữ để biết thêm thông tin. Nếu bạn đã chọn ngôn ngữ cho device_id này bằng trình đơn Cài đặt trong ứng dụng Trợ lý Google trên điện thoại, thì lựa chọn đó sẽ ghi đè giá trị này.

device_location

DeviceLocation

Không bắt buộc Vị trí của thiết bị phát sinh cụm từ tìm kiếm.

is_new_conversation

bool

Không bắt buộc Nếu đúng, máy chủ sẽ coi yêu cầu là một cuộc trò chuyện mới và không sử dụng trạng thái từ yêu cầu trước đó. Đặt trường này thành true khi cuộc trò chuyện sẽ được bắt đầu lại, chẳng hạn như sau khi khởi động lại thiết bị hoặc sau một khoảng thời gian trôi qua đáng kể kể từ truy vấn trước đó.

DialogStateOut

Trạng thái hộp thoại xuất phát từ truy vấn của người dùng. Có thể sẽ nhận được nhiều thư trong số các thư này.

Các trường
supplemental_display_text

string

Văn bản hiển thị bổ sung chỉ có thể xuất thông qua Trợ lý. Nội dung này có thể giống với lời nói trong AssistResponse.audio_out hoặc có thể là một số thông tin bổ sung giúp người dùng hiểu được nội dung.

conversation_state

bytes

Thông tin trạng thái chỉ có thể xuất của RPC Assist tiếp theo. Giá trị này phải được lưu trong ứng dụng và được trả về trong trường DialogStateIn.conversation_state với RPC Assist 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 phải lưu thông tin này sau khi khởi động lại thiết bị. Tuy nhiên, giá trị này sẽ bị xoá (không được lưu trong ứng dụng) trong quá trình đặt lại về mặc định ban đầu.

microphone_mode

MicrophoneMode

Chỉ đầu ra Chỉ định chế độ của micrô sau khi RPC Assist 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 (cho biết không thay đổi) trừ khi nhận dạng lệnh thoại như Tăng âm lượng hoặc Đặt mức âm lượng 4. 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 AssistRequest 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 Assist 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 Assist mới để gửi âm thanh mới).

ScreenOut

Phản hồi bằng hình ảnh của Trợ lý đối với yêu cầu. Do screen_out_config bật.

Các trường
format

Format

Chỉ có thể xuất Định dạng của dữ liệu màn hình được cung cấp.

data

bytes

Chỉ đầu ra Dữ liệu thô trên màn hình sẽ hiển thị khi có yêu cầu dành cho Trợ lý.

Định dạng

Các định dạng có thể có của dữ liệu màn hình.

Enum
FORMAT_UNSPECIFIED Chưa chỉ định định dạng nào.
HTML Dữ liệu sẽ chứa bố cục HTML5 định dạng đầy đủ được mã hoá bằng UTF-8, ví dụ: <html><body><div>...</div></body></html>. Mục đích của âm thanh này là được kết xuất cùng với phản hồi âm thanh. Lưu ý rằng bạn phải đưa loại tài liệu HTML5 vào dữ liệu HTML thực tế.

ScreenOutConfig

Chỉ định định dạng mong muốn để máy chủ sử dụng khi trả về phản hồi screen_out.

Các trường
screen_mode

ScreenMode

Chế độ màn hình trực quan hiện tại của thiết bị khi đưa ra truy vấn.

ScreenMode

Các chế độ có thể sử dụng cho đầu ra màn hình trực quan trên thiết bị.

Enum
SCREEN_MODE_UNSPECIFIED Chưa chỉ định chế độ video nào. Trợ lý có thể phản hồi như thể đang ở chế độ OFF.
OFF Màn hình đang tắt (hoặc được đặt độ sáng hoặc chế độ cài đặt khác quá thấp không nhìn thấy được). Thông thường, Trợ lý sẽ không trả về phản hồi trên màn hình ở chế độ này.
PLAYING Trợ lý thường sẽ trả về phản hồi chỉ chiếm một phần màn hình ở chế độ này.

SpeechRecognitionResult

Bản chép lời ước tính của cụm từ mà người dùng đã nói. Đây có thể là một phân đoạn hoặc phỏng đoán đầy đủ về truy vấn bằng giọng nói của người dùng.

Các trường
transcript

string

Văn bản chép lời chỉ có thể xuất trình bày những từ mà người dùng nói.

stability

float

Chỉ có đầu ra Ước tính khả năng Trợ lý sẽ không thay đổi dự đoán về kết quả này. Giá trị nằm trong khoảng từ 0,0 (hoàn toàn không ổn định) đến 1,0 (hoàn toàn ổn định và cuối cùng). Giá trị mặc định 0,0 là giá trị canh cho biết stability chưa được đặt.