Giọng nói và bộ thực thi hội thoại

Orbz giữ im lặng khi kết nối. Trong @neongate-ai/orbz@1.0.3, gói không cung cấp lời chào, nhân vật hay hội thoại: talk là đối tượng rỗng đóng băng và DEFAULT_TALK_FLOW là mảng rỗng đóng băng. Ứng dụng chủ cung cấp speech cho một câu hoặc talkFlow có kiểu cho hội thoại, cấu hình bộ máy và chỉ khởi động sau thao tác tường minh của người dùng.

speech được ưu tiên hơn talkFlow. Nếu không có cả hai, startTalking() không làm gì. Bắt đầu luồng không rỗng sẽ đặt lại ngữ cảnh; bước ask lưu đầu vào dưới khóa capture khi ứng dụng gọi receive(). Bước sau có thể nội suy khóa này. Ngữ cảnh không được lưu lâu dài vào cookie, local storage, IndexedDB hay backend.

Dữ liệu hội thoại tích hợp

import { DEFAULT_TALK_FLOW, talk } from "@neongate-ai/orbz";
 
console.log(talk); // {}
console.log(DEFAULT_TALK_FLOW); // []

Tiếp tục luồng

Sau khi luồng tùy chỉnh bên dưới chạy đến bước ask, truyền đầu vào người dùng gửi vào receive(). Khóa fullName có vì ví dụ khai báo capture: "fullName", không phải dữ liệu hội thoại tích hợp.

import "@neongate-ai/orbz/browser";
import type { OrbzElement } from "@neongate-ai/orbz";
 
const orb = document.querySelector<OrbzElement>("orb-z");
 
await orb?.receive("Jonatas");
console.log(orb?.talkContext.fullName);

Giọng tiếng Anh trong trình duyệt

Trong gói đã cài, WebSpeechAdapter mặc định dùng pt-BR. Ví dụ chọn rõ en-US vì câu mẫu bằng tiếng Anh. Với ngôn ngữ khác, đặt cả văn bản của ứng dụng và ngôn ngữ adapter. Adapter chờ danh sách giọng bất đồng bộ và ưu tiên giọng khớp ngôn ngữ yêu cầu; giọng khả dụng vẫn tùy môi trường người dùng.

import '@neongate-ai/orbz/browser'
import {
  WebSpeechAdapter,
  type OrbzElement
} from "@neongate-ai/orbz";
 
const orb = document.createElement("orb-z") as OrbzElement;
orb.speech = "Hello. This is an explicit speech example.";
orb.voiceEngine = new WebSpeechAdapter({
  language: "en-US",
  preferredVoices: ["Google US English", "Microsoft Aria Online"]
});
document.body.append(orb);
 
const startVoiceButton = document.querySelector<HTMLButtonElement>("[data-start-voice]");
 
startVoiceButton?.addEventListener("click", async () => {
  await orb.startTalking();
});

Các giọng thực sự được cài đặt vẫn phụ thuộc vào trình duyệt và hệ điều hành của người truy cập. WebSpeechAdapter cải thiện việc lựa chọn; nó không thể biến giọng hệ thống thành giọng OpenAI.

Giọng nói chất lượng OpenAI

Trong 1.0.3, OpenAISpeechAdapter mặc định dùng gpt-4o-mini-tts, marin, MP3 và chỉ dẫn nói tiếng Bồ Đào Nha Brazil. Ví dụ tiếng Anh ghi đè instructions cho khớp văn bản của ứng dụng. Ứng dụng phải triển khai và bảo vệ endpoint mẫu.

import '@neongate-ai/orbz/browser'
import {
  OpenAISpeechAdapter,
  type OrbzElement
} from "@neongate-ai/orbz";
 
const orb = document.createElement("orb-z") as OrbzElement;
orb.speech = "Hello. This is an explicit speech example.";
orb.voiceEngine = new OpenAISpeechAdapter({
  endpoint: "/api/orbz/speech",
  instructions: "Speak in natural American English. Do not change the supplied text."
});
document.body.append(orb);
 
const startVoiceButton = document.querySelector<HTMLButtonElement>("[data-start-voice]");
 
startVoiceButton?.addEventListener("click", async () => {
  await orb.startTalking();
});

Endpoint thuộc trách nhiệm của ứng dụng triển khai tích hợp. Nó nhận nội dung JSON tương thích OpenAI gồm input, instructions, model, response_format và voice, rồi trả về âm thanh đã tạo. Giữ khóa API OpenAI tại endpoint phía máy chủ đó; không bao giờ đặt khóa trong mã trình duyệt hay gói npm.

Ứng dụng dùng giọng nói được tạo tự động cần thông báo rõ rằng giọng nói do AI tạo ra.

Kích hoạt tường minh và chính sách trình duyệt

Hiển thị một <button> gốc với nhãn rõ ràng như Bắt đầu giọng nói, rồi gọi startTalking() từ trình xử lý nhấp chuột. Kết nối quả cầu, gán bộ máy giọng nói hay điều hướng đến trang đều không bắt đầu phát âm thanh.

Nếu trình duyệt vẫn từ chối âm thanh được yêu cầu bằng NotAllowedError, Orbz phát orbz-talk-error kèm lỗi gốc và thử lại luồng đã yêu cầu sau lần tương tác con trỏ, bàn phím hoặc cảm ứng tiếp theo. Điều khiển đặt lại không nên gắn lại phần tử chỉ để mở khóa giọng nói.

Cung cấp luồng tùy chỉnh

import "@neongate-ai/orbz/browser";
import { WebSpeechAdapter, type OrbzElement, type OrbzTalkStep } from "@neongate-ai/orbz";
 
const flow = [
  { id: "welcome", kind: "say", needsAuth: false, text: "Hello." },
  { id: "name", kind: "ask", needsAuth: false, text: "What is your name?", capture: "fullName" },
  { id: "help", kind: "say", needsAuth: false, text: "How can I help, {{fullName}}?" },
  { id: "answer", kind: "respond", needsAuth: false, strategy: "openai", fallback: "I cannot answer that right now." }
] as const satisfies readonly OrbzTalkStep[];
 
const orb = document.createElement("orb-z") as OrbzElement;
orb.talkFlow = flow;
orb.voiceEngine = new WebSpeechAdapter({ language: "en-US" });
document.body.append(orb);
 
const startVoiceButton = document.querySelector<HTMLButtonElement>("[data-start-voice]");
startVoiceButton?.addEventListener("click", async () => {
  await orb.startTalking();
});

Gán voiceEngine, talkFlow và intelligence trước khi gọi startTalking() để lần chạy được kích hoạt tường minh sử dụng chúng.

Trí tuệ tùy chọn

import type {
  OrbzElement,
  OrbzIntelligencePort
} from "@neongate-ai/orbz";
 
const intelligence: OrbzIntelligencePort = {
  async respond(input, context) {
    return productAgent.respond({ context, input });
  }
};
 
orb.intelligence = intelligence;

Sự kiện và trạng thái trực quan

Trong khi phát âm thanh, Orbz tạm thời dùng trạng thái trực quan speaking, sau đó khôi phục trạng thái trước đó.

Các luồng chuyển văn bản thành giọng nói ở trên không thu micrô. Ứng dụng quản lý đầu vào, quyền, bản chép lời, logic và lời gọi receive(). Orbz cũng có API hội thoại Realtime riêng; các ví dụ startTalking() này không khởi động API đó.