> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# AWS Nova Sonic Voice

`NovaSonicVoice` 類別提供由 [AWS Bedrock Nova 2 Sonic](https://docs.aws.amazon.com/nova/latest/userguide/speech.html) 支援的即時語音對語音功能。它會開啟與模型之間的雙向資料流，並針對助理音訊、轉錄文字、Tool 呼叫、對話輪次邊界與中斷發出事件。

## 使用範例

```typescript
import { NovaSonicVoice } from '@mastra/voice-aws-nova-sonic'
import { playAudio, getMicrophoneStream } from '@mastra/node-audio'

// Initialize using the default AWS credential provider chain
const voice = new NovaSonicVoice({
  region: 'us-east-1',
  speaker: 'matthew',
})

// Or pass explicit credentials
const voiceWithCredentials = new NovaSonicVoice({
  region: 'us-east-1',
  speaker: 'tiffany',
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
})

// Establish the bidirectional stream
await voice.connect()

// Listen for assistant audio (Int16Array PCM)
voice.on('speaking', ({ audioData }) => {
  if (audioData) playAudio(audioData)
})

// Listen for transcribed text from the user and assistant
voice.on('writing', ({ text, role, generationStage }) => {
  console.log(`${role} (${generationStage ?? 'FINAL'}): ${text}`)
})

// Stream microphone audio in real time
const microphoneStream = getMicrophoneStream()
await voice.send(microphoneStream)

// Disconnect when done
voice.close()
```

## 驗證

若未傳入 `credentials` 選項，`NovaSonicVoice` 會使用 AWS SDK 認證資訊解析鏈。Mastra 會呼叫 `@aws-sdk/credential-provider-node` 的 `defaultProvider()`，依序檢查環境變數、共用認證資訊檔、EC2 的 IAM 角色、ECS、EKS 及其他標準來源。

若要使用靜態認證資訊，請將其傳入建構函式：

```typescript
new NovaSonicVoice({
  region: 'us-east-1',
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    sessionToken: process.env.AWS_SESSION_TOKEN,
  },
})
```

此 Voice Provider 絕不會將認證資訊值寫入記錄。

## 設定

### 建構函式選項

**region** (`'us-east-1' | 'us-west-2' | 'ap-northeast-1'`): 託管 Nova Sonic 模型的 AWS 區域。 (Default: `'us-east-1'`)

**model** (`string`): 雙向資料流使用的 Bedrock 模型 ID。 (Default: `'amazon.nova-2-sonic-v1:0'`)

**credentials** (`AwsCredentialIdentity`): 靜態 AWS 認證資訊。省略時會使用預設的 AWS 認證資訊 Provider 鏈。

**speaker** (`string | NovaSonicVoiceConfigDetails`): 助理的預設語音。可傳入 'matthew' 等語音 ID 字串，或包含語言程式碼與性別的物件。 (Default: `'matthew'`)

**languageCode** (`NovaSonicLanguageCode`): 工作階段使用的語言程式碼。多語言語音支援所有列出的語言。

**instructions** (`string`): 工作階段開始時傳送的系統提示。等同於在 connect() 前呼叫 addInstructions()。

**tools** (`NovaSonicToolConfig[]`): 向模型公開的 Tools。Voice 執行個體附加至 Agent 時，系統會自動加入 Agent 的 Tools。

**sessionConfig** (`NovaSonicSessionConfig`): 推論、對話輪次偵測與 Tool 選擇設定。請參閱下方的工作階段設定。

**debug** (`boolean`): 啟用資料流事件的詳細記錄。敏感欄位會被遮蔽。 (Default: `false`)

### 工作階段設定

`sessionConfig` 控制推論參數與對話輪替行為。所有欄位皆為選填。

**inferenceConfiguration** (`object`): 取樣與解碼參數。

**inferenceConfiguration.maxTokens** (`number`): 每個對話輪次產生的權杖數上限。

**inferenceConfiguration.temperature** (`number`): 取樣溫度。

**inferenceConfiguration.topP** (`number`): 核心取樣機率。

**inferenceConfiguration.topK** (`number`): Top-k 取樣。

**inferenceConfiguration.stopSequences** (`string[]`): 結束生成的序列。

**turnDetectionConfiguration** (`object`): 對話輪次偵測的端點判定靈敏度。

**turnDetectionConfiguration.endpointingSensitivity** (`'HIGH' | 'MEDIUM' | 'LOW'`): 模型判定對話輪次完成前的暫停時間。HIGH 最快結束輪次（約暫停 1.5 秒）、MEDIUM 較為均衡（約 1.75 秒）、LOW 等待最久（約 2 秒）。

**toolChoice** (`'auto' | 'any' | { tool: { name: string } }`): 模型決定是否呼叫 Tool 的方式。

**enableKnowledgeGrounding** (`boolean`): 啟用以 Bedrock 知識庫為依據的檢索增強功能。

**knowledgeBaseConfig** (`{ knowledgeBaseId?: string; dataSourceId?: string }`): 啟用知識依據功能時使用的知識庫。

## 方法

### `connect()`

開啟與 AWS Bedrock 之間的雙向資料流，並傳送初始工作階段、提示與系統事件。請先呼叫此方法，再呼叫 `speak`、`listen` 或 `send`。

**options** (`{ requestContext?: RequestContext }`): 選用的請求內容，會傳播至工作階段期間進行的 Tool 呼叫。

回傳：`Promise<void>`

### `speak()`

合成文字提示的語音，並在產生音訊時發出 `speaking` 事件。

**input** (`string | NodeJS.ReadableStream`): 要合成的文字或文字資料流。

**options** (`NovaSonicVoiceOptions`): 單次呼叫的覆寫設定，例如語音或語言程式碼。

回傳：`Promise<void>`

### `send()`

將麥克風音訊（或任何 PCM 來源）串流傳送至模型。適用於即時且持續的對話。

**audioData** (`NodeJS.ReadableStream | Int16Array`): 要轉送至模型的 16 位元 PCM 音訊。

回傳：`Promise<void>`

### `listen()`

委派給 `send()` 的便利包裝函式。當您要對有限的音訊資料流執行單次轉錄時使用。

**audioData** (`NodeJS.ReadableStream`): 要轉錄的音訊資料流。

回傳：`Promise<void>`

### `endAudioInput()`

指示目前音訊輪次結束，讓模型完成回應。當使用者停止說話，且 Provider 未設定伺服器端對話輪次偵測時，請呼叫此方法。

回傳：`Promise<void>`

### `addInstructions()`

更新作用中工作階段的系統提示。

**instructions** (`string`): 要套用至工作階段的系統提示。

回傳：`void`

### `addTools()`

在 Voice 執行個體註冊 Tools。`NovaSonicVoice` 附加至 Agent 時，系統會自動加入 Agent 的 Tools。

**tools** (`ToolsInput`): 向模型公開的 Tools。

回傳：`void`

### `getSpeakers()`

回傳 Nova 2 Sonic 支援的語音清單。

回傳：`Promise<Array<{ voiceId: string; name: string; language: string; locale: string; gender: 'masculine' | 'feminine'; polyglot: boolean }>>`

### `getListener()`

回傳 Voice 執行個體目前是否維持開啟的資料流。

回傳：`Promise<{ enabled: boolean }>`

### `close()`

關閉雙向資料流並終止底層 Bedrock 使用者端。對話結束時請呼叫此方法。

回傳：`void`

### `on()` / `off()`

註冊及移除事件監聽器。共用事件 API 請參閱 [Voice 事件](https://mastra.zisheng.pro/zh-TW/reference/voice/voice.events)。

## 事件

`NovaSonicVoice` 會發出下列事件：

**speaking** (`event`): 助理音訊區塊。回呼會收到 { audioData: Int16Array, sampleRate?: number }。

**writing** (`event`): 來自使用者或助理的轉錄文字。回呼會收到 { text: string, role: 'assistant' | 'user', generationStage?: 'SPECULATIVE' | 'FINAL' }。

**toolCall** (`event`): 模型請求呼叫 Tool。回呼會收到 { name: string, args: Record\<string, any>, id: string }。

**interrupt** (`event`): 使用者或模型中斷目前的對話輪次。回呼會收到 { type: 'user' | 'model', timestamp: number }。

**turnComplete** (`event`): 模型已完成對話輪次。回呼會收到 { timestamp: number }。

**session** (`event`): 工作階段狀態轉換。回呼會收到 { state: 'connecting' | 'connected' | 'disconnected' | 'disconnecting' | 'error' }。

**usage** (`event`): 對話輪次的權杖用量。回呼會收到 { inputTokens: number, outputTokens: number, totalTokens: number }。

**error** (`event`): 資料流或 Provider 錯誤。回呼會收到 { message: string, code?: string, details?: unknown }。

`generationStage` 可區分暫定轉錄（`'SPECULATIVE'`）與最終轉錄（`'FINAL'`）。持久儲存請使用 `'FINAL'` 文字，即時字幕則使用 `'SPECULATIVE'` 文字。

## 可用語音

Nova 2 Sonic 提供十個語系的語音。Tiffany 與 Matthew 為多語言語音，可說任何支援的語言。

| 語音 ID      | 名稱       | 語言   | 語系    | 性別 | 多語言 |
| ---------- | -------- | ---- | ----- | -- | --- |
| `tiffany`  | Tiffany  | 英文   | en-US | 女性 | 是   |
| `matthew`  | Matthew  | 英文   | en-US | 男性 | 是   |
| `amy`      | Amy      | 英文   | en-GB | 女性 | 否   |
| `olivia`   | Olivia   | 英文   | en-AU | 女性 | 否   |
| `kiara`    | Kiara    | 英文   | en-IN | 女性 | 否   |
| `arjun`    | Arjun    | 英文   | en-IN | 男性 | 否   |
| `ambre`    | Ambre    | 法文   | fr-FR | 女性 | 否   |
| `florian`  | Florian  | 法文   | fr-FR | 男性 | 否   |
| `beatrice` | Beatrice | 義大利文 | it-IT | 女性 | 否   |
| `lorenzo`  | Lorenzo  | 義大利文 | it-IT | 男性 | 否   |
| `tina`     | Tina     | 德文   | de-DE | 女性 | 否   |
| `lennart`  | Lennart  | 德文   | de-DE | 男性 | 否   |
| `lupe`     | Lupe     | 西班牙文 | es-US | 女性 | 否   |
| `carlos`   | Carlos   | 西班牙文 | es-US | 男性 | 否   |
| `carolina` | Carolina | 葡萄牙文 | pt-BR | 女性 | 否   |
| `leo`      | Leo      | 葡萄牙文 | pt-BR | 男性 | 否   |
| `kiara`    | Kiara    | 印地文  | hi-IN | 女性 | 否   |
| `arjun`    | Arjun    | 印地文  | hi-IN | 男性 | 否   |

## 注意事項

- 音訊以 16 位元 PCM 串流傳送。助理音訊會在 `speaking` 事件上以 `Int16Array` 發出。
- Voice 執行個體必須先呼叫 `connect()`，才能呼叫其他串流方法。
- `close()` 會終止底層 `BedrockRuntimeClient`，以釋放 HTTP/2 工作階段。
- Nova 2 Sonic 可在 `us-east-1`、`us-west-2` 與 `ap-northeast-1` 使用。其他區域會在建構期間擲回設定錯誤。