Partilhar via


Guia de início rápido: conversão de texto em fala com o Serviço OpenAI do Azure

Neste início rápido, você usa o Serviço OpenAI do Azure para conversão de texto em fala com vozes OpenAI.

As vozes disponíveis são: alloy, echo, fable, onyx, nova, e shimmer. Para obter mais informações, consulte a documentação de referência do Serviço OpenAI do Azure para conversão de texto em fala.

Pré-requisitos

Configurar

Recuperar chave e ponto de extremidade

Para fazer uma chamada com êxito no Azure OpenAI, você precisa de um ponto de extremidade e uma chave.

Nome da variável Value
AZURE_OPENAI_ENDPOINT O ponto de extremidade do serviço pode ser encontrado na seção Chaves & Ponto de Extremidade ao examinar seu recurso no portal do Azure. Como alternativa, você pode encontrar o ponto de extremidade por meio da página Implantações no portal do Azure AI Foundry. Um exemplo de ponto de extremidade é: https://docs-test-001.openai.azure.com/.
AZURE_OPENAI_API_KEY Este valor pode ser encontrado na secção Chaves e Ponto Final ao examinar o recurso no portal do Azure. Pode utilizar KEY1 ou KEY2.

Vá para o seu recurso no portal do Azure. O Ponto de Extremidade e as Chaves podem ser encontrados na seção Gerenciamento de Recursos. Copie seu ponto de extremidade e chave de acesso conforme necessário para autenticar suas chamadas de API. Pode utilizar KEY1 ou KEY2. Ter sempre duas chaves permite-lhe rodar e regenerar chaves de forma segura sem causar uma interrupção do serviço.

Captura de ecrã da IU de descrição geral de um recurso OpenAI do Azure no portal do Azure com a localização das chaves de acesso do ponto de extremidade & realçada.

Variáveis de ambiente

Crie e atribua variáveis de ambiente persistentes para sua chave e endpoint.

Importante

Se você usar uma chave de API, armazene-a com segurança em outro lugar, como no Cofre de Chaves do Azure. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente.

Para obter mais informações sobre segurança de serviços de IA, consulte Autenticar solicitações para serviços de IA do Azure.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE" 

Criar uma solicitação e uma resposta REST

Em um shell bash, execute o seguinte comando. Você precisa substituir YourDeploymentName pelo nome de implantação escolhido quando implantou o modelo de texto em fala. O nome da implantação não é necessariamente o mesmo que o nome do modelo. Inserir o nome do modelo resulta em um erro, a menos que você escolha um nome de implantação idêntico ao nome do modelo subjacente.

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

O formato da sua primeira linha do comando com um ponto de extremidade de exemplo apareceria da seguinte forma: curl https://aoai-docs.openai.azure.com/openai/deployments/{YourDeploymentName}/audio/speech?api-version=2024-02-15-preview \.

Importante

Para produção, use uma maneira segura de armazenar e acessar suas credenciais, como o Azure Key Vault. Para obter mais informações sobre segurança de credenciais, consulte o artigo de segurança dos serviços de IA do Azure.

Pacote de código-fonte (npm) | Amostras |

Pré-requisitos

Pré-requisitos do Microsoft Entra ID

Para a autenticação sem chave recomendada com o Microsoft Entra ID, você precisa:

  • Instale a CLI do Azure usada para autenticação sem chave com o Microsoft Entra ID.
  • Atribua a Cognitive Services User função à sua conta de utilizador. Você pode atribuir funções no portal do Azure em Controle de acesso (IAM)>Adicionar atribuição de função.

Recuperar informações do recurso

Você precisa recuperar as seguintes informações para autenticar seu aplicativo com seu recurso do Azure OpenAI:

Nome da variável Value
AZURE_OPENAI_ENDPOINT Esse valor pode ser encontrado na seção Chaves e Ponto de Extremidade ao examinar seu recurso no portal do Azure.
AZURE_OPENAI_DEPLOYMENT_NAME Este valor corresponderá ao nome personalizado que escolheu para a implementação quando implementou um modelo. Esse valor pode ser encontrado em Implantações de Modelo de Gerenciamento de>Recursos no portal do Azure.
OPENAI_API_VERSION Saiba mais sobre as versões da API.

Saiba mais sobre autenticação sem chave e configuração de variáveis de ambiente.

Atenção

Para usar a autenticação sem chave recomendada com o SDK, verifique se a AZURE_OPENAI_API_KEY variável de ambiente não está definida.

Criar um aplicativo de nó

Numa janela de consola (como cmd, PowerShell ou Bash), crie um novo diretório para a sua aplicação e navegue para a mesma. Em seguida, execute o npm init comando para criar um aplicativo de nó com um arquivo package.json .

npm init

Instalar a biblioteca de cliente

Instale as bibliotecas de cliente com:

npm install openai @azure/identity

O arquivo de package.json do seu aplicativo será atualizado com as dependências.

Criar um arquivo de fala

  1. Crie um novo arquivo chamado Text-to-speech.js e abra-o no editor de códigos de sua preferência. Copie o seguinte código para o arquivo 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);
    });
    
    
  2. Execute o script com o seguinte comando:

    node Text-to-speech.js
    

Pacote de código-fonte (npm) | Amostras |

Pré-requisitos

Pré-requisitos do Microsoft Entra ID

Para a autenticação sem chave recomendada com o Microsoft Entra ID, você precisa:

  • Instale a CLI do Azure usada para autenticação sem chave com o Microsoft Entra ID.
  • Atribua a Cognitive Services User função à sua conta de utilizador. Você pode atribuir funções no portal do Azure em Controle de acesso (IAM)>Adicionar atribuição de função.

Recuperar informações do recurso

Você precisa recuperar as seguintes informações para autenticar seu aplicativo com seu recurso do Azure OpenAI:

Nome da variável Value
AZURE_OPENAI_ENDPOINT Esse valor pode ser encontrado na seção Chaves e Ponto de Extremidade ao examinar seu recurso no portal do Azure.
AZURE_OPENAI_DEPLOYMENT_NAME Este valor corresponderá ao nome personalizado que escolheu para a implementação quando implementou um modelo. Esse valor pode ser encontrado em Implantações de Modelo de Gerenciamento de>Recursos no portal do Azure.
OPENAI_API_VERSION Saiba mais sobre as versões da API.

Saiba mais sobre autenticação sem chave e configuração de variáveis de ambiente.

Atenção

Para usar a autenticação sem chave recomendada com o SDK, verifique se a AZURE_OPENAI_API_KEY variável de ambiente não está definida.

Criar um aplicativo de nó

Numa janela de consola (como cmd, PowerShell ou Bash), crie um novo diretório para a sua aplicação e navegue para a mesma. Em seguida, execute o npm init comando para criar um aplicativo de nó com um arquivo package.json .

npm init

Instalar a biblioteca de cliente

Instale as bibliotecas de cliente com:

npm install openai @azure/identity

O arquivo de package.json do seu aplicativo será atualizado com as dependências.

Criar um arquivo de fala

  1. Crie um novo arquivo chamado Text-to-speech.ts e abra-o em seu editor de código preferido. Copie o seguinte código para o arquivo 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);
    });
    
    

    A importação de é necessária ao executar o código em um ambiente Node.js "openai/shims/node" . Ele garante que o tipo de saída do client.audio.speech.create método esteja corretamente definido como NodeJS.ReadableStream.

  2. Crie o aplicativo com o seguinte comando:

    tsc
    
  3. Execute o aplicativo com o seguinte comando:

    node Text-to-speech.js
    

Pré-requisitos

Criar o aplicativo .NET

  1. Crie um aplicativo .NET usando o dotnet new comando:

    dotnet new console -n TextToSpeech
    
  2. Mude para o diretório do novo aplicativo:

    cd OpenAISpeech
    
  3. Instale a biblioteca do Azure.OpenAI cliente:

    dotnet add package Azure.AI.OpenAI
    

Autenticar e conectar-se ao Azure OpenAI

Para fazer solicitações ao seu serviço Azure OpenAI, você precisa do ponto de extremidade do serviço, bem como credenciais de autenticação por meio de uma das seguintes opções:

  • O Microsoft Entra ID é a abordagem recomendada para autenticação nos serviços do Azure e é mais seguro do que as alternativas baseadas em chave.

  • As chaves de acesso permitem que você forneça uma chave secreta para se conectar ao seu recurso.

    Importante

    As teclas de acesso devem ser utilizadas com precaução. Se a sua chave de acesso de serviço for perdida ou acidentalmente exposta num local inseguro, o seu serviço poderá ficar vulnerável. Qualquer pessoa que tenha a chave de acesso pode autorizar solicitações no serviço Azure OpenAI.

Obter o ponto de extremidade do Azure OpenAI

O ponto de extremidade do serviço pode ser encontrado na seção Chaves & Ponto de Extremidade ao examinar seu recurso no portal do Azure. Como alternativa, você pode encontrar o ponto de extremidade por meio da página Implantações no portal do Azure AI Foundry. Um exemplo de ponto de extremidade é: https://docs-test-001.openai.azure.com/.

Captura de ecrã da IU de descrição geral de um recurso OpenAI do Azure no portal do Azure com a localização das chaves de acesso do ponto de extremidade & realçada.

Autenticar usando o Microsoft Entra ID

Se você optar por usar a autenticação do Microsoft Entra ID, precisará concluir o seguinte:

  1. Adicione o pacote Azure.Identity.

    dotnet add package Azure.Identity
    
  2. Atribua a Cognitive Services User função à sua conta de utilizador. Isso pode ser feito no portal do Azure em seu recurso OpenAI em Controle de acesso (IAM)>Adicionar atribuição de função.

  3. Entre no Azure usando o Visual Studio ou a CLI do Azure via az login.

Autenticar usando chaves

O valor da chave de acesso pode ser encontrado na seção Chaves & Ponto de Extremidade ao examinar seu recurso no portal do Azure. Pode utilizar KEY1 ou KEY2. Ter sempre duas chaves permite-lhe rodar e regenerar chaves de forma segura sem causar uma interrupção do serviço.

Atualizar o código do aplicativo

  1. Substitua o conteúdo do pelo código a seguir e atualize os valores de program.cs espaço reservado com os seus.

    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

    Para produção, armazene e acesse suas credenciais usando um método seguro, como o Azure Key Vault. Para obter mais informações sobre segurança de credenciais, consulte Segurança de serviços de IA do Azure.

  2. Execute o aplicativo usando o dotnet run comando ou o botão Executar na parte superior do Visual Studio:

    dotnet run
    

    O aplicativo gera um arquivo de áudio no local especificado para a speechFilePath variável. Reproduza o ficheiro no seu dispositivo para ouvir o áudio gerado.

Clean up resources (Limpar recursos)

Se quiser limpar e remover um recurso do Azure OpenAI, você pode excluir o recurso. Antes de excluir o recurso, você deve primeiro excluir todos os modelos implantados.

Próximos passos

  • Saiba mais sobre como trabalhar com conversão de texto em fala com o Serviço Azure OpenAI na documentação de referência do Serviço Azure OpenAI.
  • Para obter mais exemplos, confira o repositório do GitHub de amostras do Azure OpenAI