Guida introduttiva: Sintesi vocale con il Servizio OpenAI di Azure

Articolo
10/30/2024

In questa guida introduttiva verrà usato il Servizio OpenAI di Azure per la sintesi vocale con voci OpenAI.

Le voci disponibili sono: alloy, echo, fable, onyx, nova e shimmer. Per altre informazioni, vedere la Documentazione di riferimento del Servizio OpenAI di Azure per la sintesi vocale.

Prerequisiti

Una sottoscrizione di Azure: crearne una gratuitamente.
Una risorsa Azure OpenAI creata nelle regioni degli Stati Uniti centro-settentrionali o della Svezia centrale con il modello tts-1 o tts-1-hd distribuito. Per altre informazioni, vedere Creare una risorsa e distribuire un modello con Azure OpenAI.

Impostazione

Recuperare la chiave e l'endpoint

Per effettuare correttamente una chiamata ad Azure OpenAI, sono necessari un endpoint e una chiave.

Nome variabile	Valore
`AZURE_OPENAI_ENDPOINT`	L'endpoint di servizio è disponibile nella sezione Chiavi ed endpoint quando si esamina la risorsa dal portale di Azure. In alternativa, è possibile trovare l'endpoint tramite la pagina Distribuzioni in Azure AI Studio. Un endpoint di esempio è `https://docs-test-001.openai.azure.com/`.
`AZURE_OPENAI_API_KEY`	Questo valore è disponibile nella sezione Chiavi ed endpoint durante l'esame della risorsa dalla portale di Azure. Puoi usare entrambi `KEY1` o `KEY2`.

Passare alla risorsa nel portale di Azure. L'Endpoint e le chiavi sono disponibili nella sezione Gestione risorse. Copiare l'endpoint e la chiave di accesso in base alle esigenze per l'autenticazione delle chiamate API. Puoi usare entrambi KEY1 o KEY2. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.

Variabili di ambiente

Creare e assegnare variabili di ambiente persistenti per la chiave e l'endpoint.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE"

setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_API_KEY', 'REPLACE_WITH_YOUR_KEY_VALUE_HERE', 'User')

[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_ENDPOINT', 'REPLACE_WITH_YOUR_ENDPOINT_HERE', 'User')

echo export AZURE_OPENAI_API_KEY="REPLACE_WITH_YOUR_KEY_VALUE_HERE" >> /etc/environment && source /etc/environment

echo export AZURE_OPENAI_ENDPOINT="REPLACE_WITH_YOUR_ENDPOINT_HERE" >> /etc/environment && source /etc/environment

Creare una richiesta e una risposta REST

Nella shell BASH eseguire il comando seguente. È necessario sostituire YourDeploymentName con il nome di distribuzione scelto durante la distribuzione del modello di sintesi vocale. Il nome della distribuzione non corrisponde necessariamente al nome del modello. Se si immette il nome del modello, viene generato un errore, a meno che non sia stato scelto un nome di distribuzione identico a quello del modello sottostante.

curl $AZURE_OPENAI_ENDPOINT/openai/deployments/YourDeploymentName/audio/speech?api-version=2024-02-15-preview \
 -H "api-key: $AZURE_OPENAI_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "model": "tts-1-hd",
    "input": "I'm excited to try text to speech.",
    "voice": "alloy"
}' --output speech.mp3

Il formato della prima riga del comando con un endpoint di esempio viene visualizzato come indicato di seguito curl https://aoai-docs.openai.azure.com/openai/deployments/{YourDeploymentName}/audio/speech?api-version=2024-02-15-preview \.

Importante

Per la produzione, usare un metodo sicuro per l'archiviazione e l'accesso alle proprie credenziali, ad esempio Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere l'articolo sulla sicurezza dei servizi di Azure AI.

Codice sorgente | Pacchetto (npm) | Esempi

Prerequisiti

Una sottoscrizione di Azure: creare un account gratuitamente
Versioni LTS di Node.js
Interfaccia della riga di comando di Azure usata per l'autenticazione senza password in un ambiente di sviluppo locale, creare il contesto necessario eseguendo l'accesso tramite l'interfaccia della riga di comando di Azure.
Una risorsa OpenAI di Azure creata in un'area supportata (vedere Disponibilità dell'area). Per altre informazioni, vedere Creare una risorsa e distribuire un modello con Azure OpenAI.

Impostazione

Recuperare la chiave e l'endpoint

Per effettuare correttamente una chiamata ad Azure OpenAI, sono necessari un endpoint e una chiave.

Nome variabile	Valore
`AZURE_OPENAI_ENDPOINT`	L'endpoint di servizio è disponibile nella sezione Chiavi ed endpoint quando si esamina la risorsa dal portale di Azure. In alternativa, è possibile trovare l'endpoint tramite la pagina Distribuzioni in Azure AI Studio. Un endpoint di esempio è `https://docs-test-001.openai.azure.com/`.
`AZURE_OPENAI_API_KEY`	Questo valore è disponibile nella sezione Chiavi ed endpoint durante l'esame della risorsa dalla portale di Azure. Puoi usare entrambi `KEY1` o `KEY2`.

Variabili di ambiente

Creare e assegnare variabili di ambiente persistenti per la chiave e l'endpoint.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE"

setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_API_KEY', 'REPLACE_WITH_YOUR_KEY_VALUE_HERE', 'User')

[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_ENDPOINT', 'REPLACE_WITH_YOUR_ENDPOINT_HERE', 'User')

echo export AZURE_OPENAI_API_KEY="REPLACE_WITH_YOUR_KEY_VALUE_HERE" >> /etc/environment && source /etc/environment

echo export AZURE_OPENAI_ENDPOINT="REPLACE_WITH_YOUR_ENDPOINT_HERE" >> /etc/environment && source /etc/environment

Creare un'applicazione Node

In una finestra della console, ad esempio cmd, PowerShell o Bash, creare e passare a una nuova directory per l'app. Quindi, eseguire il comando npm init per creare un'applicazione node con un file package.json.

npm init

Installare la libreria client

Installare le librerie client con:

npm install openai @azure/identity

Il file package.json dell'app verrà aggiornato con le dipendenze.

Creare un nuovo file denominato Text-to-speech.js e aprirlo nell’editor di codice preferito. Copiare il codice seguente nel file Text-to-speech.js:

const { writeFile } = require("fs/promises");
const { AzureOpenAI } = require("openai");
const { DefaultAzureCredential, getBearerTokenProvider } = require("@azure/identity");
require("openai/shims/node");

// You will need to set these environment variables or edit the following values
const endpoint = process.env["AZURE_OPENAI_ENDPOINT"] || "<endpoint>";
const speechFilePath = "<path to save the speech file>";

// Required Azure OpenAI deployment name and API version
const deploymentName = "tts";
const apiVersion = "2024-08-01-preview";

// keyless authentication    
const credential = new DefaultAzureCredential();
const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(credential, scope);

function getClient() {
  return new AzureOpenAI({
    endpoint,
    azureADTokenProvider,
    apiVersion,
    deployment: deploymentName,
  });
}

async function generateAudioStream(
  client,
  params
) {
  const response = await client.audio.speech.create(params);
  if (response.ok) return response.body;
  throw new Error(`Failed to generate audio stream: ${response.statusText}`);
}
export async function main() {
  console.log("== Text to Speech Sample ==");

  const client = getClient();
  const streamToRead = await generateAudioStream(client, {
    model: deploymentName,
    voice: "alloy",
    input: "the quick brown chicken jumped over the lazy dogs",
  });

  console.log(`Streaming response to ${speechFilePath}`);
  await writeFile(speechFilePath, streamToRead);
  console.log("Finished streaming");
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Eseguire lo script con il comando seguente:
```
node Text-to-speech.js
```

Creare un nuovo file denominato Text-to-speech.js e aprirlo nell’editor di codice preferito. Copiare il codice seguente nel file Text-to-speech.js:

const { writeFile } = require("fs/promises");
const { AzureOpenAI } = require("openai");
require("openai/shims/node");

// You will need to set these environment variables or edit the following values
const endpoint = process.env["AZURE_OPENAI_ENDPOINT"] || "<endpoint>";
const apiKey = process.env["AZURE_OPENAI_API_KEY"] || "<api key>";
const speechFilePath = "<path to save the speech file>";

// Required Azure OpenAI deployment name and API version
const deploymentName = "tts";
const apiVersion = "2024-08-01-preview";

function getClient() {
  return new AzureOpenAI({
    endpoint,
    apiKey,
    apiVersion,
    deployment: deploymentName,
  });
}

async function generateAudioStream(
  client,
  params
) {
  const response = await client.audio.speech.create(params);
  if (response.ok) return response.body;
  throw new Error(`Failed to generate audio stream: ${response.statusText}`);
}
export async function main() {
  console.log("== Text to Speech Sample ==");

  const client = getClient();
  const streamToRead = await generateAudioStream(client, {
    model: deploymentName,
    voice: "alloy",
    input: "the quick brown chicken jumped over the lazy dogs",
  });

  console.log(`Streaming response to ${speechFilePath}`);
  await writeFile(speechFilePath, streamToRead);
  console.log("Finished streaming");
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Eseguire lo script con il comando seguente:
```
node Text-to-speech.js
```

Codice sorgente | Pacchetto (npm) | Esempi

Prerequisiti

Una sottoscrizione di Azure: creare un account gratuitamente
Versioni LTS di Node.js
TypeScript
Interfaccia della riga di comando di Azure usata per l'autenticazione senza password in un ambiente di sviluppo locale, creare il contesto necessario eseguendo l'accesso tramite l'interfaccia della riga di comando di Azure.
Una risorsa OpenAI di Azure creata in un'area supportata (vedere Disponibilità dell'area). Per altre informazioni, vedere Creare una risorsa e distribuire un modello con Azure OpenAI.

Impostazione

Recuperare la chiave e l'endpoint

Per effettuare correttamente una chiamata ad Azure OpenAI, sono necessari un endpoint e una chiave.

Nome variabile	Valore
`AZURE_OPENAI_ENDPOINT`	Questo valore è disponibile nella sezione Chiavi &ed endpoint durante l'esame della risorsa dalla portale di Azure. In alternativa, è possibile trovare il valore in OpenAI Studio di Azure>Playground>Visualizzazione codice. Un endpoint di esempio è `https://aoai-docs.openai.azure.com/`.
`AZURE_OPENAI_API_KEY`	Questo valore è disponibile nella sezione Chiavi ed endpoint durante l'esame della risorsa dalla portale di Azure. Puoi usare entrambi `KEY1` o `KEY2`.

Variabili di ambiente

Creare e assegnare variabili di ambiente persistenti per la chiave e l'endpoint.

Importante

Se si usa una chiave API, archiviarla in modo sicuro in un'altra posizione, ad esempio in Azure Key Vault. Non includere la chiave API direttamente nel codice e non esporla mai pubblicamente.

Per altre informazioni sulla sicurezza dei servizi IA, vedere Autenticare richieste in Servizi di Azure AI.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE"

setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_API_KEY', 'REPLACE_WITH_YOUR_KEY_VALUE_HERE', 'User')

[System.Environment]::SetEnvironmentVariable('AZURE_OPENAI_ENDPOINT', 'REPLACE_WITH_YOUR_ENDPOINT_HERE', 'User')

echo export AZURE_OPENAI_API_KEY="REPLACE_WITH_YOUR_KEY_VALUE_HERE" >> /etc/environment && source /etc/environment

echo export AZURE_OPENAI_ENDPOINT="REPLACE_WITH_YOUR_ENDPOINT_HERE" >> /etc/environment && source /etc/environment

Creare un'applicazione Node

npm init

Installare la libreria client

Installare le librerie client con:

npm install openai @azure/identity

Il file package.json dell'app verrà aggiornato con le dipendenze.

Creare un file voce

Microsoft Entra ID
Chiave API

Creare un nuovo file denominato Text-to-speech.ts e aprirlo nell’editor di codice preferito. Copiare il codice seguente nel file Text-to-speech.ts:

import { writeFile } from "fs/promises";
import { AzureOpenAI } from "openai";
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
import type { SpeechCreateParams } from "openai/resources/audio/speech";
import "openai/shims/node";

// You will need to set these environment variables or edit the following values
const endpoint = process.env["AZURE_OPENAI_ENDPOINT"] || "<endpoint>";
const speechFilePath = "<path to save the speech file>";

// Required Azure OpenAI deployment name and API version
const deploymentName = "tts";
const apiVersion = "2024-08-01-preview";

// keyless authentication    
const credential = new DefaultAzureCredential();
const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(credential, scope);

function getClient(): AzureOpenAI {
  return new AzureOpenAI({
    endpoint,
    azureADTokenProvider,
    apiVersion,
    deployment: deploymentName,
  });
}

async function generateAudioStream(
  client: AzureOpenAI,
  params: SpeechCreateParams
): Promise<NodeJS.ReadableStream> {
  const response = await client.audio.speech.create(params);
  if (response.ok) return response.body;
  throw new Error(`Failed to generate audio stream: ${response.statusText}`);
}
export async function main() {
  console.log("== Text to Speech Sample ==");

  const client = getClient();
  const streamToRead = await generateAudioStream(client, {
    model: deploymentName,
    voice: "alloy",
    input: "the quick brown chicken jumped over the lazy dogs",
  });

  console.log(`Streaming response to ${speechFilePath}`);
  await writeFile(speechFilePath, streamToRead);
  console.log("Finished streaming");
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

L'importazione di "openai/shims/node" è necessaria quando si esegue il codice in un ambiente Node.js. Garantisce che il tipo di output del metodo client.audio.speech.create sia impostato correttamente su NodeJS.ReadableStream.

Compilare l'applicazione con il comando seguente:
```
tsc
```
Eseguire l'applicazione con il comando seguente:
```
node Text-to-speech.js
```

Creare un nuovo file denominato Text-to-speech.ts e aprirlo nell’editor di codice preferito. Copiare il codice seguente nel file Text-to-speech.ts:

import { writeFile } from "fs/promises";
import { AzureOpenAI } from "openai";
import type { SpeechCreateParams } from "openai/resources/audio/speech";
import "openai/shims/node";

// You will need to set these environment variables or edit the following values
const endpoint = "<endpoint>";
const apiKey = process.env["AZURE_OPENAI_API_KEY"] || "<api key>";
const speechFilePath =
  process.env["SPEECH_FILE_PATH"] || "<path to save the speech file>";

// Required Azure OpenAI deployment name and API version
const deploymentName = "tts";
const apiVersion = "2024-08-01-preview";

function getClient(): AzureOpenAI {
  return new AzureOpenAI({
    endpoint,
    apiKey,
    apiVersion,
    deployment: deploymentName,
  });
}

async function generateAudioStream(
  client: AzureOpenAI,
  params: SpeechCreateParams
): Promise<NodeJS.ReadableStream> {
  const response = await client.audio.speech.create(params);
  if (response.ok) return response.body;
  throw new Error(`Failed to generate audio stream: ${response.statusText}`);
}
export async function main() {
  console.log("== Text to Speech Sample ==");

  const client = getClient();
  const streamToRead = await generateAudioStream(client, {
    model: deploymentName,
    voice: "alloy",
    input: "the quick brown chicken jumped over the lazy dogs",
  });

  console.log(`Streaming response to ${speechFilePath}`);
  await writeFile(speechFilePath, streamToRead);
  console.log("Finished streaming");
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Compilare l'applicazione con il comando seguente:
```
tsc
```
Eseguire l'applicazione con il comando seguente:
```
node Text-to-speech.js
```

Prerequisiti

Una sottoscrizione di Azure. È possibile crearne uno gratuitamente.
Una risorsa di Azure OpenAI con un modello Whisper distribuito in un'area supportata. Per altre informazioni, vedere Creare una risorsa e distribuire un modello con Azure OpenAI.
The .NET 8.0 SDK

Creare l'app .NET

Creare un'app .NET usando il dotnet new comando :
```
dotnet new console -n TextToSpeech
```
Passare alla directory della nuova app:
```
cd OpenAISpeech
```
Installare la Azure.OpenAI libreria client:
```
dotnet add package Azure.AI.OpenAI
```

Autenticare e connettersi ad Azure OpenAI

Per effettuare richieste al servizio Azure OpenAI, sono necessari l'endpoint di servizio e le credenziali di autenticazione tramite una delle opzioni seguenti:

Microsoft Entra ID è l'approccio consigliato per l'autenticazione ai servizi di Azure ed è più sicuro rispetto alle alternative basate su chiavi.
Le chiavi di accesso consentono di fornire una chiave privata per connettersi alla risorsa.

Importante

I tasti di scelta devono essere usati con cautela. Se la chiave di accesso al servizio viene persa o accidentalmente esposta in una posizione non sicura, il servizio potrebbe diventare vulnerabile. Chiunque abbia la chiave di accesso è in grado di autorizzare le richieste nel servizio Azure OpenAI.

Ottenere l'endpoint OpenAI di Azure

L'endpoint di servizio è disponibile nella sezione Chiavi ed endpoint quando si esamina la risorsa dal portale di Azure. In alternativa, è possibile trovare l'endpoint tramite la pagina Distribuzioni in Azure AI Studio. Un endpoint di esempio è https://docs-test-001.openai.azure.com/.

Eseguire l'autenticazione con Microsoft Entra ID

Se si sceglie di usare l'autenticazione microsoft Entra ID, è necessario completare le operazioni seguenti:

Aggiungere il pacchetto Azure.Identity.
```
dotnet add package Azure.Identity
```
Assegnare il ruolo Cognitive Services User all'account utente. Questa operazione può essere eseguita nella portale di Azure nella risorsa OpenAI in Controllo di accesso (IAM)>Aggiungi assegnazione di ruolo.
Accedere ad Azure usando Visual Studio o l'interfaccia della riga di comando di Azure tramite az login.

Eseguire l'autenticazione con le chiavi

Il valore della chiave di accesso è disponibile nella sezione Chiavi ed endpoint quando si esamina la risorsa dal portale di Azure. Puoi usare entrambi KEY1 o KEY2. Disporre sempre di due chiavi consente di ruotare e rigenerare in modo sicuro le chiavi senza causare un'interruzione del servizio.

Aggiornare il codice dell'app

Sostituire il contenuto di program.cs con il codice seguente e aggiornare i valori segnaposto con i propri.

using Azure;
using Azure.AI.OpenAI;
using Azure.Identity; // Required for Passwordless auth

var endpoint = new Uri(
    Environment.GetEnvironmentVariable("YOUR_OPENAI_ENDPOINT") ?? throw new ArgumentNullException());
var credentials = new DefaultAzureCredential();

// Use this line for key auth
// var credentials = new AzureKeyCredential(
//    Environment.GetEnvironmentVariable("YOUR_OPENAI_KEY") ?? throw new ArgumentNullException());

var deploymentName = "tts"; // Default deployment name, update with your own if necessary
var speechFilePath = "YOUR_AUDIO_FILE_PATH";

var openAIClient = new AzureOpenAIClient(endpoint, credentials);
var audioClient = openAIClient.GetAudioClient(deploymentName);

var result = await audioClient.GenerateSpeechAsync(
                "the quick brown chicken jumped over the lazy dogs");

Console.WriteLine("Streaming response to ${speechFilePath}");
await File.WriteAllBytesAsync(speechFilePath, result.Value.ToArray());
Console.WriteLine("Finished streaming");

Importante

Per la produzione, archiviare e accedere alle credenziali usando un modo sicuro, ad esempio Azure Key Vault. Per altre informazioni sulla sicurezza delle credenziali, vedere Sicurezza dei Servizi di Azure AI.

Eseguire l'applicazione usando il dotnet run comando o il pulsante Esegui nella parte superiore di Visual Studio:
```
dotnet run
```
L'app genera un file audio nel percorso specificato per la speechFilePath variabile. Riprodurre il file nel dispositivo per ascoltare l'audio generato.

Pulire le risorse

Se si vuole ripulire e rimuovere una risorsa OpenAI di Azure, è possibile eliminare la risorsa. Prima di eliminare la risorsa, è necessario eliminare i modelli distribuiti.

Passaggi successivi

Altre informazioni su come usare la sintesi vocale con il Servizio OpenAI di Azure nella Documentazione di riferimento del Servizio OpenAI di Azure.
Per altri esempi, vedere il repository GitHub degli esempi di OpenAI di Azure

Condividi tramite

Guida introduttiva: Sintesi vocale con il Servizio OpenAI di Azure

Prerequisiti

Impostazione

Recuperare la chiave e l'endpoint

Variabili di ambiente

Creare una richiesta e una risposta REST

Prerequisiti

Impostazione

Recuperare la chiave e l'endpoint

Variabili di ambiente

Creare un'applicazione Node

Installare la libreria client

Creare un file voce

Prerequisiti

Impostazione

Recuperare la chiave e l'endpoint

Variabili di ambiente

Creare un'applicazione Node

Installare la libreria client

Creare un file voce

Prerequisiti

Creare l'app .NET

Autenticare e connettersi ad Azure OpenAI

Ottenere l'endpoint OpenAI di Azure

Eseguire l'autenticazione con Microsoft Entra ID

Eseguire l'autenticazione con le chiavi

Aggiornare il codice dell'app

Pulire le risorse

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive