Package google.assistant.embedded.v1alpha1

ดัชนี

EmbeddedAssistant

บริการที่ใช้งาน Google Assistant API

Converse

rpc Converse(ConverseRequest) returns (ConverseResponse)

เริ่มหรือสนทนาต่อด้วยบริการผู้ช่วยที่ฝังไว้ การโทรแต่ละครั้งจะดำเนินการไป-กลับ 1 รอบ โดยจะส่งคำขอแบบเสียงไปยังบริการและรับสายตอบกลับ ใช้การสตรีมแบบ 2 ทิศทางเพื่อรับผลลัพธ์ เช่น เหตุการณ์ END_OF_UTTERANCE ขณะส่งเสียง

การสนทนาคือการเชื่อมต่อ gRPC อย่างน้อย 1 รายการ โดยแต่ละรายการประกอบด้วยคำขอและการตอบกลับที่สตรีมหลายรายการ ตัวอย่างเช่น ผู้ใช้พูดว่าเพิ่มลงในรายการช็อปปิ้งของฉัน และ Assistant ตอบกลับว่าคุณต้องการเพิ่มอะไร ลำดับของคำขอและการตอบกลับที่สตรีมในข้อความ 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 ที่จะมีการระบุในคำขอที่ตามมา โปรดดูการตั้งค่าที่แนะนำในแนวทางปฏิบัติแนะนำเกี่ยวกับ gRPC API ของ Google Assistant

ช่อง
encoding

Encoding

จำเป็น การเข้ารหัสข้อมูลเสียงที่ส่งในข้อความ audio_in ทั้งหมด

sample_rate_hertz

int32

จำเป็น อัตราการสุ่มตัวอย่าง (หน่วยเป็นเฮิรตซ์) ของข้อมูลเสียงที่ส่งในข้อความ audio_in ทั้งหมด ค่าที่ใช้ได้คือตั้งแต่ 16000-24000 แต่ 16, 000 ถือว่าเหมาะสมที่สุด เพื่อผลลัพธ์ที่ดีที่สุด ให้ตั้งค่าอัตราการสุ่มตัวอย่างของแหล่งที่มาของเสียงเป็น 16000 Hz หากทำไม่ได้ ให้ใช้อัตราการสุ่มตัวอย่างแบบดั้งเดิมของแหล่งที่มาของเสียง (แทนการสุ่มตัวอย่างซ้ำ)

การเข้ารหัส

การเข้ารหัสเสียงของข้อมูลที่ส่งในข้อความเสียง เสียงต้องเป็นแบบช่องเดียว (โมโน) ภาษาที่รองรับคือ "en-US"

Enum
ENCODING_UNSPECIFIED ไม่ได้ระบุ จะให้ผลลัพธ์เป็น google.rpc.Code.INVALID_ARGUMENT
LINEAR16 ตัวอย่าง Endian แบบมีเครื่องหมาย 16 บิตที่ไม่มีการบีบอัด (PCM เชิงเส้น) การเข้ารหัสนี้จะไม่มีส่วนหัว แต่ระบุเฉพาะไบต์ของเสียงแบบ RAW เท่านั้น
FLAC FLAC (ตัวแปลงสัญญาณเสียงแบบ Free Lossless) คือการเข้ารหัสที่แนะนำเนื่องจากเป็นแบบไม่สูญเสียรายละเอียด การจดจำจึงจะไม่ได้รับผลกระทบ และใช้แบนด์วิดท์ประมาณครึ่งหนึ่งของ LINEAR16 เท่านั้น การเข้ารหัสนี้รวมถึงส่วนหัวของสตรีม FLAC ตามด้วยข้อมูลเสียง โดยจะรองรับตัวอย่าง 16 บิตและ 24 บิต แต่ก็ไม่รองรับบางฟิลด์ใน STREAMINFO

AudioOut

เสียงที่มีคําตอบของ Assistant สําหรับคําถาม ได้รับข้อความ "ConverseResponse" ที่เรียงกันตามลำดับของข้อมูลเสียง

ช่อง
audio_data

bytes

Export-only ข้อมูลเสียงที่มีคําตอบของ Assistant ต่อคําถาม ได้รับข้อความ "ConverseResponse" ที่เรียงกันตามลำดับของข้อมูลเสียง

AudioOutConfig

ระบุรูปแบบที่ต้องการให้เซิร์ฟเวอร์ใช้เมื่อแสดงผลข้อความ audio_out

ช่อง
encoding

Encoding

จำเป็น การเข้ารหัสข้อมูลเสียงที่จะแสดงในข้อความ audio_out ทั้ง 2 ข้อความ

sample_rate_hertz

int32

จำเป็น อัตราตัวอย่างเป็นเฮิรตซ์ของข้อมูลเสียงที่แสดงใน audio_out ข้อความ ค่าที่ใช้ได้คือ 16000-24000

volume_percentage

int32

จำเป็น การตั้งค่าระดับเสียงปัจจุบันของเอาต์พุตเสียงของอุปกรณ์ ค่าที่ใช้ได้คือ 1 ถึง 100 (ตรงกับ 1% ถึง 100%)

การเข้ารหัส

การเข้ารหัสเสียงของข้อมูลที่แสดงในข้อความเสียง การเข้ารหัสทั้งหมดเป็นไบต์เสียงดิบที่ไม่มีส่วนหัว ยกเว้นตามที่ระบุไว้ด้านล่าง

Enum
ENCODING_UNSPECIFIED ไม่ได้ระบุ จะให้ผลลัพธ์เป็น google.rpc.Code.INVALID_ARGUMENT
LINEAR16 ตัวอย่าง Endian แบบมีเครื่องหมาย 16 บิตที่ไม่มีการบีบอัด (PCM เชิงเส้น)
MP3 การเข้ารหัสเสียง MP3 ระบบจะเข้ารหัสอัตราการสุ่มตัวอย่างในเพย์โหลด
OPUS_IN_OGG ระบบเสียงที่เข้ารหัส Opus ในที่เก็บ Ogg ผลที่ได้ที่ได้ก็จะเป็นไฟล์ที่สามารถเล่นได้ในเครื่อง Android และในบางเบราว์เซอร์ (เช่น Chrome) การเข้ารหัสมีคุณภาพสูงกว่า MP3 เป็นอย่างมากในขณะที่ใช้อัตราบิตเดียวกัน ระบบจะเข้ารหัสอัตราการสุ่มตัวอย่างในเพย์โหลด

ConverseConfig

ระบุวิธีประมวลผลข้อความ ConverseRequest

ช่อง
audio_in_config

AudioInConfig

ต้องระบุ ระบุวิธีประมวลผลเสียงขาเข้าที่ตามมา

audio_out_config

AudioOutConfig

ต้องระบุ ระบุวิธีจัดรูปแบบเสียงที่จะแสดง

converse_state

ConverseState

ต้องระบุ แสดงสถานะปัจจุบันของกล่องโต้ตอบ

ConverseRequest

ข้อความระดับบนสุดที่ลูกค้าส่ง โดยไคลเอ็นต์จะต้องส่งข้อความอย่างน้อย 2 ข้อความ ซึ่งโดยทั่วไปจะConverseRequest เป็นจำนวนมาก ข้อความแรกต้องมีข้อความ config และต้องไม่มีข้อมูล audio_in ข้อความที่ตามมาทั้งหมดต้องมีข้อมูล audio_in และต้องไม่มีข้อความ config

ช่อง
ฟิลด์การรวม converse_request ต้องระบุ 1 ช่องเหล่านี้ในแต่ละ ConverseRequest converse_request ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
config

ConverseConfig

ข้อความ config จะให้ข้อมูลแก่โปรแกรมจดจำที่ระบุวิธีประมวลผลคำขอ ข้อความ ConverseRequest แรกต้องมีข้อความ config

audio_in

bytes

ข้อมูลเสียงที่จะจดจำ ระบบจะส่งข้อมูลเสียงเป็นกลุ่มตามลําดับในข้อความ ConverseRequest ตามลำดับ ข้อความ ConverseRequest แรกต้องไม่มีข้อมูล audio_in และข้อความ ConverseRequest ที่ตามมาทั้งหมดต้องมีข้อมูล audio_in ต้องเข้ารหัสไบต์เสียงตามที่ระบุไว้ใน AudioInConfig คุณจะต้องส่งข้อมูลเสียงแบบเรียลไทม์โดยประมาณ (16,000 ตัวอย่างต่อวินาที) ระบบจะแสดงผลข้อผิดพลาดหากเสียงส่งมาเร็วขึ้นหรือช้าลงมาก

ConverseResponse

ข้อความระดับบนสุดที่ลูกค้าได้รับ ระบบจะสตรีมชุดข้อความ ConverseResponse อย่างน้อย 1 ข้อความกลับไปยังไคลเอ็นต์

ช่อง
ฟิลด์การรวม converse_response ระบบจะป้อนข้อมูลในช่องใดช่องหนึ่งเหล่านี้อยู่เสมอใน ConverseResponse แต่ละรายการ converse_response ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
error

Status

เอาต์พุตเท่านั้น หากมีการตั้งค่า ระบบจะแสดงข้อความ google.rpc.Status ที่ระบุข้อผิดพลาดสำหรับการดำเนินการ หากเกิดข้อผิดพลาดระหว่างการประมวลผล ระบบจะตั้งค่าข้อความนี้และจะไม่มีการส่งข้อความอีก

event_type

EventType

เอาต์พุตเท่านั้น ระบุประเภทของเหตุการณ์

audio_out

AudioOut

Export-only เสียงที่มีคําตอบของ Assistant สําหรับคําถาม

result

ConverseResult

Export-only ผลลัพธ์เชิงความหมายสำหรับคำค้นหาที่ผู้ใช้พูด

EventType

ระบุประเภทของเหตุการณ์

Enum
EVENT_TYPE_UNSPECIFIED ไม่ได้ระบุเหตุการณ์
END_OF_UTTERANCE เหตุการณ์นี้แสดงว่าเซิร์ฟเวอร์ตรวจพบเสียงพูดของผู้ใช้สิ้นสุดลงและคาดว่าจะไม่มีเสียงพูดเพิ่มเติม ดังนั้น เซิร์ฟเวอร์จะไม่ประมวลผลเสียงเพิ่มเติม (แม้ว่าอาจมีผลลัพธ์เพิ่มเติมในภายหลัง) ไคลเอ็นต์ควรหยุดส่งข้อมูลเสียงเพิ่มเติม ปิดการเชื่อมต่อ gRPC ครึ่งหนึ่ง และรอผลลัพธ์เพิ่มเติมจนกว่าเซิร์ฟเวอร์จะปิดการเชื่อมต่อ gRPC

ConverseResult

ผลลัพธ์เชิงความหมายสำหรับคำค้นหาที่ผู้ใช้พูด

ช่อง
spoken_request_text

string

เอาต์พุตเท่านั้น ข้อความถอดเสียงที่ระบบรู้จักของสิ่งที่ผู้ใช้พูด

spoken_response_text

string

Export-only ข้อความตอบกลับที่ Assistant พูด ซึ่งจะแสดงผลสำหรับการดำเนินการ IFTTT เท่านั้น

conversation_state

bytes

ข้อมูลสถานะเอาต์พุตเท่านั้นสำหรับ ConverseRequest ที่ตามมา ค่านี้ควรบันทึกไว้ในไคลเอ็นต์และแสดงผลใน conversation_state พร้อมกับ ConverseRequest ถัดไป (ไคลเอ็นต์ไม่จำเป็นต้องแปลความหมายหรือใช้ค่านี้) คุณไม่จําเป็นต้องบันทึกข้อมูลนี้เมื่อรีสตาร์ทอุปกรณ์

microphone_mode

MicrophoneMode

เอาต์พุตเท่านั้น ระบุโหมดของไมโครโฟนหลังจากประมวลผล Converse RPC นี้แล้ว

volume_percentage

int32

ระดับเสียงเท่านั้น อัปเดตระดับเสียงแล้ว ค่าจะเป็น 0 หรือไม่ใส่ (หมายความว่าไม่มีการเปลี่ยนแปลง) เว้นแต่คำสั่งเสียง เช่น "เพิ่มระดับเสียง" หรือ "ตั้งระดับเสียง 4" ซึ่งในกรณีนี้ ค่าจะอยู่ระหว่าง 1 ถึง 100 (ตรงกับระดับเสียงใหม่ 1% ถึง 100%) โดยปกติแล้ว ลูกค้าควรใช้ระดับเสียงนี้เมื่อเล่นข้อมูล audio_out และรักษาค่านี้เป็นระดับเสียงปัจจุบันและนำไปใช้ใน AudioOutConfig ของ ConverseRequest ถัดไป (ไคลเอ็นต์บางคนอาจใช้วิธีอื่นด้วยเพื่อให้ผู้ใช้เปลี่ยนระดับเสียงในปัจจุบันได้ เช่น โดยการให้ปุ่มที่ผู้ใช้สามารถหมุนได้)

MicrophoneMode

สถานะที่เป็นไปได้ของไมโครโฟนหลังจาก RPC Converse เสร็จสมบูรณ์

Enum
MICROPHONE_MODE_UNSPECIFIED ไม่ได้ระบุโหมด
CLOSE_MICROPHONE บริการไม่ต้องการคําถามต่อเนื่องจากผู้ใช้ ไมโครโฟนควรปิดอยู่จนกว่าผู้ใช้จะเปิดใช้งานอีกครั้ง
DIALOG_FOLLOW_ON บริการคาดว่าจะมีคำถามจากผู้ใช้ต่อเนื่อง ไมโครโฟนควรเปิดอีกครั้งเมื่อ AudioOut เล่นจบ (ด้วยการเริ่มเรียก Converse RPC ใหม่เพื่อส่งเสียงใหม่)

ConverseState

ให้ข้อมูลเกี่ยวกับสถานะของกล่องโต้ตอบปัจจุบัน

ช่อง
conversation_state

bytes

ต้องระบุ ค่า conversation_state ที่แสดงผลใน ConverseResponse ก่อนหน้า เว้น (ไม่ตั้งค่าช่อง) หากไม่มี ConverseResponse ก่อนหน้า หากมี ConverseResponse อยู่ก่อนหน้า โปรดอย่าเว้นช่องนี้ไว้ เนื่องจากจะทำให้การสนทนาดังกล่าวสิ้นสุดลง (และคำขอใหม่นี้จะเริ่มการสนทนาใหม่)