Compartilhar via

Início Rápido: introdução ao uso de Assistentes OpenAI do Azure (versão prévia)

  • Artigo

Os Assistentes OpenAI do Azure (versão prévia) permitem que você crie assistentes de IA adaptados às suas necessidades por meio de instruções personalizadas e aumentados por ferramentas avançadas, como o interpretador de códigos e funções personalizadas.

Importante

Os itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Pré-requisitos

Acesse o Estúdio de IA do Azure (versão prévia)

O Estúdio de IA do Azure permite que você use o Assistants v2, que oferece diversas atualizações, como a ferramenta de pesquisa de arquivos, que é mais rápida e suporta mais arquivos.

  1. Entre no Azure AI Studio.

  2. Acesse seu projeto ou crie um projeto no Estúdio de IA do Azure.

  3. Na visão geral do seu projeto, selecione Assistentes, localizado em Project Playground.

    O playground de Assistentes permite que você explore, crie protótipos e teste assistentes de IA sem a necessidade de executar nenhum código. Nesta página, você pode iterar e experimentar as novas ideias rapidamente.

    O playground oferece várias opções para configurar o Assistente. Nas etapas a seguir, você usará o painel Configuração do assistente, para criar um novo assistente de IA.

    Nome Descrição
    Nome do assistente O nome da implantação associado a um modelo específico.
    Instruções As instruções são semelhantes às mensagens do sistema, é aqui que você fornece as diretrizes ao modelo sobre como ele deve se comportar e os contextos que ele deve consultar ao gerar uma resposta. Você pode descrever a personalidade do assistente, dizer a ele o que ele deve ou não responder e como formatar as respostas. Você também pode fornecer exemplos das etapas que ele deve executar ao dar respostas.
    Implantação É nesse momento você define qual implantação de modelo usar com seu assistente.
    Funções Crie definições de funções personalizadas para os modelos para formular chamadas de API e estruturar saídas de dados, com base em suas especificações. Não usado nesse início rápido.
    Interpretador de códigos O interpretador de códigos fornece acesso a um ambiente Python em área restrita que pode ser usado para permitir que o modelo teste e execute o código.
    Arquivos Você pode carregar até 10.000 arquivos, com um tamanho máximo de 512 MB para usar com as ferramentas. Não usado nesse início rápido.

    Captura de tela da tela de configuração do Assistente sem todos os valores preenchidos.

Crie seu primeiro Assistente

  1. Selecione sua implantação na lista suspensa Implantações.

  2. No menu suspenso Configuração do assistente, selecione Novo.

  3. Dê um nome ao seu Assistente.

  4. Insira as instruções a seguir "Você é um assistente de IA que pode escrever código para ajudar a responder perguntas de matemática"

  5. Selecione uma implantação de modelo. Recomendamos testar com um dos modelos gpt-4 mais recentes.

  6. Selecione a alternância que habilita o interpretador de códigos.

  7. Selecione Salvar.

    Captura de tela do assistente com detalhes de configuração inseridos.

  8. Insira uma pergunta para o assistente responder: "Preciso resolver a equação 3x + 11 = 14. Consegue me ajudar?"

  9. Selecione o botão Adicionar e executar 

    The solution to the equation (3x + 11 = 14) is (x = 1).

    Embora possamos ver que a resposta está correta, para confirmar que o modelo usou o interpretador de códigos para elaborar essa resposta e que o código que ele escreveu é válido em vez de apenas repetir uma resposta dos dados de treinamento do modelo, faremos outra pergunta.

  10. Insira a pergunta complementar: "Mostre o código que você executou para obter esta solução".

    Sure. The code is very straightforward

    # calculation
x = (14 - 11) / 3
x


    First, we subtract 11 from 14, then divide the result by 3. This gives us the value of x which is 1.0.

    Captura de tela da sessão de conversa no playground do Assistente.

Você também pode consultar os logs no painel à direita para confirmar se o interpretador de códigos foi usado e validar o código que foi executado para gerar a resposta. É importante lembrar que, embora o interpretador de códigos dê ao modelo a capacidade de responder a perguntas matemáticas mais complexas convertendo as perguntas em código e executando um ambiente Python em área restrita, você ainda precisa validar a resposta para confirmar que o modelo traduziu corretamente sua pergunta em uma representação válida no código.

Conceitos principais

Ao usar o playground dos Assistentes, lembre-se dos seguintes conceitos.

Ferramentas

Um assistente individual pode acessar até 128 ferramentas, incluindo code interpreter, bem como as ferramentas personalizadas criadas por meio de funções.

Sessão de chat

A sessão de chat também conhecida como uma conversa dentro da API do Assistente é onde ocorre a conversa entre o usuário e o assistente. Ao contrário das chamadas de conclusão de chat tradicionais, não há limite para o número de mensagens em uma conversa. O assistente compactará automaticamente as solicitações para se ajustarem ao limite do token de entrada do modelo.

Isso também significa que você não está controlando quantos tokens são passados para o modelo durante cada turno da conversa. O gerenciamento de tokens é abstraído e tratado inteiramente pela API de Assistentes.

Selecione o botão Limpar chat para excluir o histórico da conversa atual.

Há dois botões abaixo da caixa de entrada de texto:

  • Adicione uma mensagem sem executar.
  • Adicionar e executar.

Logs

Os logs fornecem um instantâneo detalhado da atividade de API do assistente.

Mostrar painéis

Por padrão, existem três painéis: configuração do assistente, sessão de chat e registros. Mostrar painéis permite adicionar, remover e reorganizar os painéis. Se você fechar um painel e precisar recuperá-lo, use Mostrar painéis para restaurar o painel perdido.

Limpar os recursos

Caso queria limpar e remover um recurso do OpenAI do Azure, é possível excluir o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.

Alternativamente, exclua o assistente ou thread por meio da API do Assistente.

Confira também

Documentação de referência | Código-fonte da biblioteca | Pacote (PyPi) |

Pré-requisitos

Para autenticação sem senha, você precisa

  1. Usar o pacote azure-identity.
  2. Atribua a função de Cognitive Services User à sua conta de usuário. Isto pode ser feito no portal do Azure em Controle de acesso (IAM)>Adicionar atribuição de função.
  3. Entre com a CLI do Azure, como az login.

Configuração

  1. Instalar a biblioteca de clientes do OpenAI Python com:
pip install openai
  1. Para a autenticação sem senha recomendada:
pip install azure-identity

Observação

  • A pesquisa de arquivos pode ingerir até 10.000 arquivos por assistente – 500 vezes mais do que antes. Ela é rápida, dá suporte a consultas paralelas por meio de pesquisas com vários threads e recursos aprimorados de reclassificação e reescrita de consulta.
    • O repositório de vetores é um novo objeto na API. Depois que um arquivo é adicionado a um repositório de vetores, ele é analisado automaticamente, em partes e inserido, pronto para ser pesquisado. Os repositórios de vetores podem ser usados entre assistentes e threads, simplificando o gerenciamento de arquivos e a cobrança.
  • Adicionamos suporte para o parâmetro tool_choice que pode ser usado para forçar o uso de uma ferramenta específica (como pesquisa de arquivo, interpretador de código ou uma função) em uma execução específica.

Observação

Essa biblioteca é mantida pelo OpenAI. Consulte o histórico de lançamentos para acompanhar as atualizações mais recentes na biblioteca.

Recuperar chave e ponto de extremidade

Para efetuar uma chamada com êxito no Serviço OpenAI do Azure, será preciso o seguinte:

Nome da variável Valor
ENDPOINT Esse valor pode ser encontrado na seção Chaves e Ponto de Extremidade ao examinar seu recurso no portal do Azure. Como alternativa, você também pode encontrar o ponto de extremidade por meio da página Implantações no Estúdio de IA do Azure. Um ponto de extremidade de exemplo é: https://docs-test-001.openai.azure.com/.
API-KEY Esse valor pode ser encontrado na seção Chaves e Ponto de Extremidade ao examinar seu recurso no portal do Azure. Você pode usar KEY1 ou KEY2.
DEPLOYMENT-NAME Esse valor corresponderá ao nome personalizado escolhido para sua implantação ao implantar um modelo. Esse valor pode ser encontrado em Gerenciamento de Recursos>Implantações de Modelo no portal do Azure ou por meio da página Implantações no Estúdio de IA do Azure.

Acesse o seu recurso no portal do Azure. As Chaves e Ponto de Extremidade podem ser encontrados na seção Gerenciamento de Recursos. Copie o ponto de extremidade e as chave de acesso, pois você precisará de ambos para autenticar suas chamadas à API. Você pode usar KEY1 ou KEY2. Ter sempre duas chaves permite girar e regenerar chaves com segurança, sem causar interrupção de serviço.

Captura de tela da folha de visão geral de um recurso OpenAI do Azure no portal do Azure com o ponto de extremidade e a localização das chaves de acesso circuladas em vermelho.

Variáveis de ambiente

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

Importante

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

Para obter mais informações sobre a segurança dos serviços de IA, confira 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 um assistente

Especificaremos os seguintes valores em nosso código:

Nome Descrição
Nome do assistente O nome da implantação associado a um modelo específico.
Instruções As instruções são semelhantes às mensagens do sistema, é aqui que você fornece as diretrizes ao modelo sobre como ele deve se comportar e os contextos que ele deve consultar ao gerar uma resposta. Você pode descrever a personalidade do assistente, dizer a ele o que ele deve ou não responder e como formatar as respostas. Você também pode fornecer exemplos das etapas que ele deve executar ao dar respostas.
Modelo É nesse momento que você define qual nome de implantação de modelo usar com seu assistente. A ferramenta de recuperação requer o modelo gpt-35-turbo (1106) ou gpt-4 (1106-preview). Defina esse valor como o nome da implantação, não o nome do modelo, a menos que seja o mesmo.
Interpretador de códigos O interpretador de códigos fornece acesso a um ambiente Python em área restrita que pode ser usado para permitir que o modelo teste e execute o código.

Ferramentas

Um assistente individual pode acessar até 128 ferramentas, incluindo code interpreter, bem como as ferramentas personalizadas criadas por meio de funções.

Criar o aplicativo do Python

Entrar no Azure com az login, em seguida, criar e executar um assistente com o seguinte exemplo Python sem senha recomendado:

import os
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import AzureOpenAI

token_provider = get_bearer_token_provider(DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default")

client = AzureOpenAI(
    azure_ad_token_provider=token_provider,
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-05-01-preview",
)

# Create an assistant
assistant = client.beta.assistants.create(
    name="Math Assist",
    instructions="You are an AI assistant that can write code to help answer math questions.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-1106-preview" # You must replace this value with the deployment name for your model.
)

# Create a thread
thread = client.beta.threads.create()

# Add a user question to the thread
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)

# Run the thread and poll for the result
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions="Please address the user as Jane Doe. The user has a premium account.",
)

print("Run completed with status: " + run.status)

if run.status == "completed":
    messages = client.beta.threads.messages.list(thread_id=thread.id)
    print(messages.to_json(indent=2))

Para usar a chave de API de serviço para autenticação, crie e execute um assistente com o seguinte exemplo Python:

import os
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-05-01-preview",
)

# Create an assistant
assistant = client.beta.assistants.create(
    name="Math Assist",
    instructions="You are an AI assistant that can write code to help answer math questions.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-1106-preview" # You must replace this value with the deployment name for your model.
)

# Create a thread
thread = client.beta.threads.create()

# Add a user question to the thread
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)

# Run the thread and poll for the result
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions="Please address the user as Jane Doe. The user has a premium account.",
)

print("Run completed with status: " + run.status)

if run.status == "completed":
    messages = client.beta.threads.messages.list(thread_id=thread.id)
    print(messages.to_json(indent=2))

Saída

Execução concluída com o status: concluído

{
  "data": [
    {
      "id": "msg_4SuWxTubHsHpt5IlBTO5Hyw9",
      "assistant_id": "asst_cYqL1RuwLyFV3HU1gkaE2k0K",
      "attachments": [],
      "content": [
        {
          "text": {
            "annotations": [],
            "value": "The solution to the equation \\(3x + 11 = 14\\) is \\(x = 1\\)."
          },
          "type": "text"
        }
      ],
      "created_at": 1716397091,
      "metadata": {},
      "object": "thread.message",
      "role": "assistant",
      "run_id": "run_hFgBPbUtO8ZNTnNPC8PgpH1S",
      "thread_id": "thread_isb7spwRycI5ueT9E7357aOm"
    },
    {
      "id": "msg_Z32w2E7kY5wEWhZqQWxIbIUB",
      "assistant_id": null,
      "attachments": [],
      "content": [
        {
          "text": {
            "annotations": [],
            "value": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
          },
          "type": "text"
        }
      ],
      "created_at": 1716397025,
      "metadata": {},
      "object": "thread.message",
      "role": "user",
      "run_id": null,
      "thread_id": "thread_isb7spwRycI5ueT9E7357aOm"
    }
  ],
  "object": "list",
  "first_id": "msg_4SuWxTubHsHpt5IlBTO5Hyw9",
  "last_id": "msg_Z32w2E7kY5wEWhZqQWxIbIUB",
  "has_more": false
}

Compreensão dos resultados

Neste exemplo, criamos um assistente com o interpretador de códigos habilitado. Quando fazemos uma pergunta de matemática ao assistente, ele converte a pergunta em código Python e executa o código no ambiente de área restrita para determinar a resposta à pergunta. O código que o modelo cria e testa para chegar a uma resposta é:

from sympy import symbols, Eq, solve  
  
# Define the variable  
x = symbols('x')  
  
# Define the equation  
equation = Eq(3*x + 11, 14)  
  
# Solve the equation  
solution = solve(equation, x)  
solution

É importante lembrar que, embora o interpretador de códigos dê ao modelo a capacidade de responder a consultas mais complexas convertendo as perguntas em código e executando esse código iterativamente na área restrita do Python até chegar a uma solução, você ainda precisa validar a resposta para confirmar que o modelo traduziu corretamente sua pergunta em uma representação válida no código.

Limpar os recursos

Caso queria limpar e remover um recurso do OpenAI do Azure, é possível excluir o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.

Confira também

Documentação de referência | Código-fonte | Pacote (NuGet)

Pré-requisitos

Configuração

Criar um aplicativo .NET Core

  1. Em uma janela de console (como cmd, PowerShell ou Bash), use o comando dotnet new para criar um aplicativo de console com o nome azure-openai-quickstart:

    dotnet new console -n azure-openai-assistants-quickstart

  2. Altere para o diretório da pasta de aplicativo recém-criada e crie o aplicativo com o comando dotnet build:

    dotnet build

    A saída de compilação não deve conter nenhum aviso ou erro.

    ...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

  3. Instale a biblioteca de clientes .NET do OpenAI com o comando dotnet add package:

    dotnet add package Azure.AI.OpenAI --prerelease

Recuperar chave e ponto de extremidade

Para efetuar uma chamada com êxito no Serviço OpenAI do Azure, um ponto de extremidade e uma chave serão necessários.

Nome da variável Valor
ENDPOINT O ponto de extremidade de serviço pode ser encontrado na seção Chaves e Ponto de extremidade ao examinar seu recurso no portal do Azure. Como alternativa, você pode encontrar o ponto de extremidade na página Implantações no Estúdio de IA do Azure. Um ponto de extremidade de exemplo é: https://docs-test-001.openai.azure.com/.
API-KEY Esse valor pode ser encontrado na seção Chaves & Ponto de Extremidade ao examinar o recurso no portal do Azure. Você pode usar KEY1 ou KEY2.

Acesse o seu recurso no portal do Azure. A seção Chaves e Ponto de Extremidade pode ser encontrada na seção Gerenciamento de Recursos. Copie o ponto de extremidade e as chave de acesso, pois você precisará de ambos para autenticar suas chamadas à API. Você pode usar KEY1 ou KEY2. Ter sempre duas chaves permite girar e regenerar chaves com segurança, sem causar interrupção de serviço.

Captura de tela da visão geral da interface do usuário de um recurso OpenAI do Azure no portal do Azure com o ponto de extremidade e a localização das chaves de acesso ressaltadas com um círculo vermelho.

Variáveis de ambiente

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

Importante

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

Para obter mais informações sobre a segurança dos serviços de IA, confira 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"

A autenticação sem senha é mais segura do que as alternativas baseadas em chave e é a abordagem recomendada para conectar-se aos serviços do Azure. Se você optar pela Autenticação sem senha, você precisará concluir o seguinte:

  1. Adicione o pacote Azure.Identity.

    dotnet add package Azure.Identity

  2. Atribua a função de Cognitive Services User à sua conta de usuário. Isso pode ser feito no portal do Azure no 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.

Criar o assistente

Atualize o arquivo Program.cs com o seguinte código para criar um assistente:

using Azure;
using Azure.AI.OpenAI.Assistants;

// Assistants is a beta API and subject to change
// Acknowledge its experimental status by suppressing the matching warning.
string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
string key = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY");

var openAIClient = new AzureOpenAIClient(new Uri(endpoint), new AzureKeyCredential(key));

// Use for passwordless auth
//var openAIClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential()); 

FileClient fileClient = openAIClient.GetFileClient();
AssistantClient assistantClient = openAIClient.GetAssistantClient();

// First, let's contrive a document we'll use retrieval with and upload it.
using Stream document = BinaryData.FromString("""
            {
                "description": "This document contains the sale history data for Contoso products.",
                "sales": [
                    {
                        "month": "January",
                        "by_product": {
                            "113043": 15,
                            "113045": 12,
                            "113049": 2
                        }
                    },
                    {
                        "month": "February",
                        "by_product": {
                            "113045": 22
                        }
                    },
                    {
                        "month": "March",
                        "by_product": {
                            "113045": 16,
                            "113055": 5
                        }
                    }
                ]
            }
            """).ToStream();

OpenAIFileInfo salesFile = await fileClient.UploadFileAsync(
    document,
    "monthly_sales.json",
    FileUploadPurpose.Assistants);

// Now, we'll create a client intended to help with that data
AssistantCreationOptions assistantOptions = new()
{
    Name = "Example: Contoso sales RAG",
    Instructions =
        "You are an assistant that looks up sales data and helps visualize the information based"
        + " on user queries. When asked to generate a graph, chart, or other visualization, use"
        + " the code interpreter tool to do so.",
    Tools =
            {
                new FileSearchToolDefinition(),
                new CodeInterpreterToolDefinition(),
            },
    ToolResources = new()
    {
        FileSearch = new()
        {
            NewVectorStores =
                    {
                        new VectorStoreCreationHelper([salesFile.Id]),
                    }
        }
    },
};

Assistant assistant = await assistantClient.CreateAssistantAsync(deploymentName, assistantOptions);

// Create and run a thread with a user query about the data already associated with the assistant
ThreadCreationOptions threadOptions = new()
{
    InitialMessages = { "How well did product 113045 sell in February? Graph its trend over time." }
};

ThreadRun threadRun = await assistantClient.CreateThreadAndRunAsync(assistant.Id, threadOptions);

// Check back to see when the run is done
do
{
    Thread.Sleep(TimeSpan.FromSeconds(1));
    threadRun = assistantClient.GetRun(threadRun.ThreadId, threadRun.Id);
} while (!threadRun.Status.IsTerminal);

// Finally, we'll print out the full history for the thread that includes the augmented generation
AsyncCollectionResult<ThreadMessage> messages
    = assistantClient.GetMessagesAsync(
        threadRun.ThreadId,
        new MessageCollectionOptions() { Order = MessageCollectionOrder.Ascending });

await foreach (ThreadMessage message in messages)
{
    Console.Write($"[{message.Role.ToString().ToUpper()}]: ");
    foreach (MessageContent contentItem in message.Content)
    {
        if (!string.IsNullOrEmpty(contentItem.Text))
        {
            Console.WriteLine($"{contentItem.Text}");

            if (contentItem.TextAnnotations.Count > 0)
            {
                Console.WriteLine();
            }

            // Include annotations, if any.
            foreach (TextAnnotation annotation in contentItem.TextAnnotations)
            {
                if (!string.IsNullOrEmpty(annotation.InputFileId))
                {
                    Console.WriteLine($"* File citation, file ID: {annotation.InputFileId}");
                }
                if (!string.IsNullOrEmpty(annotation.OutputFileId))
                {
                    Console.WriteLine($"* File output, new file ID: {annotation.OutputFileId}");
                }
            }
        }
        if (!string.IsNullOrEmpty(contentItem.ImageFileId))
        {
            OpenAIFileInfo imageInfo = await fileClient.GetFileAsync(contentItem.ImageFileId);
            BinaryData imageBytes = await fileClient.DownloadFileAsync(contentItem.ImageFileId);
            using FileStream stream = File.OpenWrite($"{imageInfo.Filename}.png");
            imageBytes.ToStream().CopyTo(stream);

            Console.WriteLine($"<image: {imageInfo.Filename}.png>");
        }
    }
    Console.WriteLine();
}

Execute o aplicativo usando o comando dotnet run:

dotnet run

A saída do console deve ser semelhante ao seguinte:

[USER]: How well did product 113045 sell in February? Graph its trend over time.

[ASSISTANT]: Product 113045 sold 22 units in February. Let's visualize its sales trend over the given months (January through March).

I'll create a graph to depict this trend.

[ASSISTANT]: <image: 553380b7-fdb6-49cf-9df6-e8e6700d69f4.png>
The graph above visualizes the sales trend for product 113045 from January to March. As seen, the sales peaked in February with 22 units sold, and fluctuated over the period from January (12 units) to March (16 units).

If you need further analysis or more details, feel free to ask!

Limpar os recursos

Caso queria limpar e remover um recurso do OpenAI do Azure, é possível excluir o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.

Confira também

Documentação de referência | Código-fonte da biblioteca | Pacote (npm) |

Pré-requisitos

Para autenticação sem chave, você precisa

  1. Usar o pacote @azure/identity.
  2. Atribua a função de Cognitive Services User à sua conta de usuário. Isto pode ser feito no portal do Azure em Controle de acesso (IAM)>Adicionar atribuição de função.
  3. Entre com a CLI do Azure, como az login.

Configuração

  1. Crie uma nova pasta assistants-quickstart para conter o aplicativo e abra o Visual Studio Code nessa pasta com o seguinte comando:

    mkdir assistants-quickstart && code assistants-quickstart

  2. Crie o package.json com o seguinte comando:

    npm init -y

  3. Atualize o package.json para ECMAScript com o seguinte comando:

    npm pkg set type=module

  4. Instale a biblioteca de clientes dos Assistentes do OpenAI para JavaScript com:

    npm install openai

  5. Para a autenticação sem senha recomendada:

    npm install @azure/identity

Recuperar as informações do recurso

Nome da variável Valor
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 Esse valor corresponderá ao nome personalizado escolhido para sua implantação ao implantar um modelo. Esse valor pode ser encontrado em Gerenciamento de Recursos>Implantações de Modelos no portal do Azure.
OPENAI_API_VERSION Saiba mais sobre as Versões de API.

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

Cuidado

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

Criar um assistente

Especificaremos os seguintes valores em nosso código:

Nome Descrição
Nome do assistente O nome da implantação associado a um modelo específico.
Instruções As instruções são semelhantes às mensagens do sistema, é aqui que você fornece as diretrizes ao modelo sobre como ele deve se comportar e os contextos que ele deve consultar ao gerar uma resposta. Você pode descrever a personalidade do assistente, dizer a ele o que ele deve ou não responder e como formatar as respostas. Você também pode fornecer exemplos das etapas que ele deve executar ao dar respostas.
Modelo Esse é o nome da implantação.
Interpretador de códigos O interpretador de códigos fornece acesso a um ambiente Python em área restrita que pode ser usado para permitir que o modelo teste e execute o código.

Ferramentas

Um assistente individual pode acessar até 128 ferramentas, incluindo code interpreter, e as ferramentas personalizadas criadas por meio de funções.

Criar um aplicativo JavaScript

  1. Crie o arquivo index.js com o seguinte código:

    const { AzureOpenAI } = require("openai");
const {
  DefaultAzureCredential,
  getBearerTokenProvider,
} = require("@azure/identity");

// Get environment variables
const azureOpenAIEndpoint = process.env.AZURE_OPENAI_ENDPOINT;
const azureOpenAIDeployment = process.env.AZURE_OPENAI_DEPLOYMENT_NAME;
const azureOpenAIVersion = process.env.OPENAI_API_VERSION;

// Check env variables
if (!azureOpenAIEndpoint || !azureOpenAIDeployment || !azureOpenAIVersion) {
  throw new Error(
    "Please ensure to set AZURE_OPENAI_DEPLOYMENT_NAME and AZURE_OPENAI_ENDPOINT in your environment variables."
  );
}

// Get Azure SDK client
const getClient = () => {
  const credential = new DefaultAzureCredential();
  const scope = "https://cognitiveservices.azure.com/.default";
  const azureADTokenProvider = getBearerTokenProvider(credential, scope);

  const assistantsClient = new AzureOpenAI({
    endpoint: azureOpenAIEndpoint,
    apiVersion: azureOpenAIVersion,
    azureADTokenProvider,
  });
  return assistantsClient;
};

const assistantsClient = getClient();

const options = {
  model: azureOpenAIDeployment, // Deployment name seen in Azure AI Studio
  name: "Math Tutor",
  instructions:
    "You are a personal math tutor. Write and run JavaScript code to answer math questions.",
  tools: [{ type: "code_interpreter" }],
};
const role = "user";
const message = "I need to solve the equation `3x + 11 = 14`. Can you help me?";

// Create an assistant
const assistantResponse = await assistantsClient.beta.assistants.create(
  options
);
console.log(`Assistant created: ${JSON.stringify(assistantResponse)}`);

// Create a thread
const assistantThread = await assistantsClient.beta.threads.create({});
console.log(`Thread created: ${JSON.stringify(assistantThread)}`);

// Add a user question to the thread
const threadResponse = await assistantsClient.beta.threads.messages.create(
  assistantThread.id,
  {
    role,
    content: message,
  }
);
console.log(`Message created:  ${JSON.stringify(threadResponse)}`);

// Run the thread and poll it until it is in a terminal state
const runResponse = await assistantsClient.beta.threads.runs.createAndPoll(
  assistantThread.id,
  {
    assistant_id: assistantResponse.id,
  },
  { pollIntervalMs: 500 }
);
console.log(`Run created:  ${JSON.stringify(runResponse)}`);

// Get the messages
const runMessages = await assistantsClient.beta.threads.messages.list(
  assistantThread.id
);
for await (const runMessageDatum of runMessages) {
  for (const item of runMessageDatum.content) {
    // types are: "image_file" or "text"
    if (item.type === "text") {
      console.log(`Message content: ${JSON.stringify(item.text?.value)}`);
    }
  }
}

  2. Entre no Azure com o seguinte comando:

    az login

  3. Execute o arquivo JavaScript.

    node index.js

Saída

Assistant created: {"id":"asst_zXaZ5usTjdD0JGcNViJM2M6N","createdAt":"2024-04-08T19:26:38.000Z","name":"Math Tutor","description":null,"model":"daisy","instructions":"You are a personal math tutor. Write and run JavaScript code to answer math questions.","tools":[{"type":"code_interpreter"}],"fileIds":[],"metadata":{}}
Thread created: {"id":"thread_KJuyrB7hynun4rvxWdfKLIqy","createdAt":"2024-04-08T19:26:38.000Z","metadata":{}}
Message created:  {"id":"msg_o0VkXnQj3juOXXRCnlZ686ff","createdAt":"2024-04-08T19:26:38.000Z","threadId":"thread_KJuyrB7hynun4rvxWdfKLIqy","role":"user","content":[{"type":"text","text":{"value":"I need to solve the equation `3x + 11 = 14`. Can you help me?","annotations":[]},"imageFile":{}}],"assistantId":null,"runId":null,"fileIds":[],"metadata":{}}
Created run
Run created:  {"id":"run_P8CvlouB8V9ZWxYiiVdL0FND","object":"thread.run","status":"queued","model":"daisy","instructions":"You are a personal math tutor. Write and run JavaScript code to answer math questions.","tools":[{"type":"code_interpreter"}],"metadata":{},"usage":null,"assistantId":"asst_zXaZ5usTjdD0JGcNViJM2M6N","threadId":"thread_KJuyrB7hynun4rvxWdfKLIqy","fileIds":[],"createdAt":"2024-04-08T19:26:39.000Z","expiresAt":"2024-04-08T19:36:39.000Z","startedAt":null,"completedAt":null,"cancelledAt":null,"failedAt":null}
Message content: "The solution to the equation \\(3x + 11 = 14\\) is \\(x = 1\\)."
Message content: "Yes, of course! To solve the equation \\( 3x + 11 = 14 \\), we can follow these steps:\n\n1. Subtract 11 from both sides of the equation to isolate the term with x.\n2. Then, divide by 3 to find the value of x.\n\nLet me calculate that for you."
Message content: "I need to solve the equation `3x + 11 = 14`. Can you help me?"

É importante lembrar que, embora o intérprete de código dê ao modelo a capacidade de responder a consultas mais complexas convertendo as perguntas em código e executando esse código iterativamente em JavaScript até chegar a uma solução, você ainda precisará validar a resposta para confirmar se o modelo traduziu corretamente sua pergunta em uma representação válida no código.

Limpar os recursos

Caso queria limpar e remover um recurso do OpenAI do Azure, é possível excluir o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.

Código de exemplo

Confira também

Documentação de referência | Código-fonte da biblioteca | Pacote (npm) |

Pré-requisitos

Para autenticação sem senha, você precisa

  1. Usar o pacote @azure/identity.
  2. Atribua a função de Cognitive Services User à sua conta de usuário. Isto pode ser feito no portal do Azure em Controle de acesso (IAM)>Adicionar atribuição de função.
  3. Entre com a CLI do Azure, como az login.

Configuração

  1. Crie uma nova pasta assistants-quickstart para conter o aplicativo e abra o Visual Studio Code nessa pasta com o seguinte comando:

    mkdir assistants-quickstart && code assistants-quickstart

  2. Crie o package.json com o seguinte comando:

    npm init -y

  3. Atualize o package.json para ECMAScript com o seguinte comando:

    npm pkg set type=module

  4. Instale a biblioteca de clientes dos Assistentes do OpenAI para JavaScript com:

    npm install openai

  5. Para a autenticação sem senha recomendada:

    npm install @azure/identity

Recuperar as informações do recurso

Nome da variável Valor
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 Esse valor corresponderá ao nome personalizado escolhido para sua implantação ao implantar um modelo. Esse valor pode ser encontrado em Gerenciamento de Recursos>Implantações de Modelos no portal do Azure.
OPENAI_API_VERSION Saiba mais sobre as Versões de API.

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

Cuidado

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

Criar um assistente

Especificaremos os seguintes valores em nosso código:

Nome Descrição
Nome do assistente O nome da implantação associado a um modelo específico.
Instruções As instruções são semelhantes às mensagens do sistema, é aqui que você fornece as diretrizes ao modelo sobre como ele deve se comportar e os contextos que ele deve consultar ao gerar uma resposta. Você pode descrever a personalidade do assistente, dizer a ele o que ele deve ou não responder e como formatar as respostas. Você também pode fornecer exemplos das etapas que ele deve executar ao dar respostas.
Modelo Esse é o nome da implantação.
Interpretador de códigos O interpretador de códigos fornece acesso a um ambiente Python em área restrita que pode ser usado para permitir que o modelo teste e execute o código.

Ferramentas

Um assistente individual pode acessar até 128 ferramentas, incluindo code interpreter, e as ferramentas personalizadas criadas por meio de funções.

Criar um novo aplicativo TypeScript

  1. Crie o arquivo index.ts com o seguinte código:

    import { AzureOpenAI } from "openai";
import {
  Assistant,
  AssistantCreateParams,
  AssistantTool,
} from "openai/resources/beta/assistants";
import { Message, MessagesPage } from "openai/resources/beta/threads/messages";
import { Run } from "openai/resources/beta/threads/runs/runs";
import { Thread } from "openai/resources/beta/threads/threads";

// Add `Cognitive Services User` to identity for Azure OpenAI resource
import {
  DefaultAzureCredential,
  getBearerTokenProvider,
} from "@azure/identity";

// Get environment variables
const azureOpenAIEndpoint = process.env.AZURE_OPENAI_ENDPOINT as string;
const azureOpenAIDeployment = process.env
  .AZURE_OPENAI_DEPLOYMENT_NAME as string;
const openAIVersion = process.env.OPENAI_API_VERSION as string;

// Check env variables
if (!azureOpenAIEndpoint || !azureOpenAIDeployment || !openAIVersion) {
  throw new Error(
    "Please ensure to set AZURE_OPENAI_DEPLOYMENT_NAME and AZURE_OPENAI_ENDPOINT in your environment variables."
  );
}

// Get Azure SDK client
const getClient = (): AzureOpenAI => {
  const credential = new DefaultAzureCredential();
  const scope = "https://cognitiveservices.azure.com/.default";
  const azureADTokenProvider = getBearerTokenProvider(credential, scope);
  const assistantsClient = new AzureOpenAI({
    endpoint: azureOpenAIEndpoint,
    apiVersion: openAIVersion,
    azureADTokenProvider,
  });
  return assistantsClient;
};

const assistantsClient = getClient();

const options: AssistantCreateParams = {
  model: azureOpenAIDeployment, // Deployment name seen in Azure AI Studio
  name: "Math Tutor",
  instructions:
    "You are a personal math tutor. Write and run JavaScript code to answer math questions.",
  tools: [{ type: "code_interpreter" } as AssistantTool],
};
const role = "user";
const message = "I need to solve the equation `3x + 11 = 14`. Can you help me?";

// Create an assistant
const assistantResponse: Assistant =
  await assistantsClient.beta.assistants.create(options);
console.log(`Assistant created: ${JSON.stringify(assistantResponse)}`);

// Create a thread
const assistantThread: Thread = await assistantsClient.beta.threads.create({});
console.log(`Thread created: ${JSON.stringify(assistantThread)}`);

// Add a user question to the thread
const threadResponse: Message =
  await assistantsClient.beta.threads.messages.create(assistantThread.id, {
    role,
    content: message,
  });
console.log(`Message created:  ${JSON.stringify(threadResponse)}`);

// Run the thread and poll it until it is in a terminal state
const runResponse: Run = await assistantsClient.beta.threads.runs.createAndPoll(
  assistantThread.id,
  {
    assistant_id: assistantResponse.id,
  },
  { pollIntervalMs: 500 }
);
console.log(`Run created:  ${JSON.stringify(runResponse)}`);

// Get the messages
const runMessages: MessagesPage =
  await assistantsClient.beta.threads.messages.list(assistantThread.id);
for await (const runMessageDatum of runMessages) {
  for (const item of runMessageDatum.content) {
    // types are: "image_file" or "text"
    if (item.type === "text") {
      console.log(`Message content: ${JSON.stringify(item.text?.value)}`);
    }
  }
}

  2. Crie o arquivo tsconfig.json para transpilar o código TypeScript e copiar o código a seguir para ECMAScript.

    {
    "compilerOptions": {
      "module": "NodeNext",
      "target": "ES2022", // Supports top-level await
      "moduleResolution": "NodeNext",
      "skipLibCheck": true, // Avoid type errors from node_modules
      "strict": true // Enable strict type-checking options
    },
    "include": ["*.ts"]
}

  3. Transpile de TypeScript para JavaScript.

    tsc

  4. Entre no Azure com o seguinte comando:

    az login

  5. Execute o código com o seguinte comando:

    node index.js

Saída

Assistant created: {"id":"asst_zXaZ5usTjdD0JGcNViJM2M6N","createdAt":"2024-04-08T19:26:38.000Z","name":"Math Tutor","description":null,"model":"daisy","instructions":"You are a personal math tutor. Write and run JavaScript code to answer math questions.","tools":[{"type":"code_interpreter"}],"fileIds":[],"metadata":{}}
Thread created: {"id":"thread_KJuyrB7hynun4rvxWdfKLIqy","createdAt":"2024-04-08T19:26:38.000Z","metadata":{}}
Message created:  {"id":"msg_o0VkXnQj3juOXXRCnlZ686ff","createdAt":"2024-04-08T19:26:38.000Z","threadId":"thread_KJuyrB7hynun4rvxWdfKLIqy","role":"user","content":[{"type":"text","text":{"value":"I need to solve the equation `3x + 11 = 14`. Can you help me?","annotations":[]},"imageFile":{}}],"assistantId":null,"runId":null,"fileIds":[],"metadata":{}}
Created run
Run created:  {"id":"run_P8CvlouB8V9ZWxYiiVdL0FND","object":"thread.run","status":"queued","model":"daisy","instructions":"You are a personal math tutor. Write and run JavaScript code to answer math questions.","tools":[{"type":"code_interpreter"}],"metadata":{},"usage":null,"assistantId":"asst_zXaZ5usTjdD0JGcNViJM2M6N","threadId":"thread_KJuyrB7hynun4rvxWdfKLIqy","fileIds":[],"createdAt":"2024-04-08T19:26:39.000Z","expiresAt":"2024-04-08T19:36:39.000Z","startedAt":null,"completedAt":null,"cancelledAt":null,"failedAt":null}
Message content: "The solution to the equation \\(3x + 11 = 14\\) is \\(x = 1\\)."
Message content: "Yes, of course! To solve the equation \\( 3x + 11 = 14 \\), we can follow these steps:\n\n1. Subtract 11 from both sides of the equation to isolate the term with x.\n2. Then, divide by 3 to find the value of x.\n\nLet me calculate that for you."
Message content: "I need to solve the equation `3x + 11 = 14`. Can you help me?"

É importante lembrar que, embora o intérprete de código dê ao modelo a capacidade de responder a consultas mais complexas convertendo as perguntas em código e executando esse código iterativamente em JavaScript até chegar a uma solução, você ainda precisará validar a resposta para confirmar se o modelo traduziu corretamente sua pergunta em uma representação válida no código.

Limpar os recursos

Caso queria limpar e remover um recurso do OpenAI do Azure, é possível excluir o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.

Código de exemplo

Confira também

Pré-requisitos

Configuração

Recuperar chave e ponto de extremidade

Para fazer uma chamada com sucesso no OpenAI do Azure, você precisará ter o seguinte:

Nome da variável Valor
ENDPOINT O ponto de extremidade de serviço pode ser encontrado na seção Chaves e Ponto de extremidade ao examinar seu recurso no portal do Azure. Como alternativa, você pode encontrar o ponto de extremidade na página Implantações no Estúdio de IA do Azure. Um ponto de extremidade de exemplo é: https://docs-test-001.openai.azure.com/.
API-KEY Esse valor pode ser encontrado na seção Chaves & Ponto de Extremidade ao examinar o recurso no portal do Azure. Você pode usar KEY1 ou KEY2.
DEPLOYMENT-NAME Esse valor corresponderá ao nome personalizado escolhido para sua implantação ao implantar um modelo. Esse valor pode ser encontrado em Gerenciamento de Recursos>Implantações no portal do Azure ou na página Implantações no Estúdio de IA do Azure.

Acesse o seu recurso no portal do Azure. O Ponto de extremidade e as Chaves podem ser encontrados na seção Gerenciamento de recursos. Copie o ponto de extremidade e as chave de acesso, pois você precisará de ambos para autenticar suas chamadas à API. Você pode usar KEY1 ou KEY2. Ter sempre duas chaves permite girar e regenerar chaves com segurança, sem causar interrupção de serviço.

Captura de tela da folha de visão geral de um recurso OpenAI do Azure no portal do Azure com o ponto de extremidade e a localização das chaves de acesso circuladas em vermelho.

Variáveis de ambiente

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

Importante

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

Para obter mais informações sobre a segurança dos serviços de IA, confira 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"

API REST

Criar um assistente

Observação

Com o OpenAI do Azure, o parâmetro model requer o nome da implantação de modelo. Se o nome da implantação de modelo for diferente do nome do modelo subjacente, você ajustará seu código para "model": "{your-custom-model-deployment-name}".

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "You are an AI assistant that can write code to help answer math questions.",
    "name": "Math Assist",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-1106-preview"
  }'

Ferramentas

Um assistente individual pode acessar até 128 ferramentas, incluindo code interpreter, bem como as ferramentas personalizadas criadas por meio de funções.

Criar um thread

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d ''

Adicionar uma pergunta do usuário ao thread

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
      "role": "user",
      "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
    }'

Executar o thread

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/runs \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

Recuperar o status da execução

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/runs/run_abc123 \
  -H "api-key: $AZURE_OPENAI_API_KEY" \

Resposta do assistente

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \

Compreensão dos resultados

Neste exemplo, criamos um assistente com o interpretador de códigos habilitado. Quando fazemos uma pergunta de matemática ao assistente, ele converte a pergunta em código Python e executa o código no ambiente de área restrita para determinar a resposta à pergunta. O código que o modelo cria e testa para chegar a uma resposta é:

    from sympy import symbols, Eq, solve  
      
    # Define the variable  
    x = symbols('x')  
      
    # Define the equation  
    equation = Eq(3*x + 11, 14)  
      
    # Solve the equation  
    solution = solve(equation, x)  
    solution

É importante lembrar que, embora o interpretador de códigos dê ao modelo a capacidade de responder a consultas mais complexas convertendo as perguntas em código e executando esse código iterativamente na área restrita do Python até chegar a uma solução, você ainda precisa validar a resposta para confirmar que o modelo traduziu corretamente sua pergunta em uma representação válida no código.

Limpar os recursos

Caso queria limpar e remover um recurso do OpenAI do Azure, é possível excluir o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.

Confira também