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.

Pré-requisitos

Vá para o Estúdio OpenAI do Azure

Navegue até o Estúdio do OpenAI do Azure em https://oai.azure.com/ e entre com credenciais que tenham acesso ao recurso do OpenAI. Durante o fluxo de trabalho de entrada, selecione o diretório apropriado, a assinatura do Azure e o recurso OpenAI do Azure.

Na página de aterrissagem do estúdio do OpenAI do Azure, inicie o playground do Assistente a partir do painel de navegação à esquerda Playground>Assistentes (versão prévia)

Captura de tela da página de aterrissagem do Azure OpenAI Studio.

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.

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

Configuração do assistente

Use o painel de Configuração do assistente para criar um novo assistente de IA ou selecionar um assistente.

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 Criar definições de função personalizada para os modelos a fim de formular chamadas à API e estruturar saídas de dados com base em suas especificações
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é 20 arquivos, com um tamanho máximo de arquivo de 512 MB para usar com ferramentas.

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.

Criar seu primeiro assistente

  1. Na lista suspensa de configuração do assistente, selecione Novo

  2. Nomeie o assistente

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

  4. Selecione uma implantação de gpt-4 (1106-preview). A lista suspensa exibirá os nomes de implantação personalizados, portanto, se os nomes de modelo/implantação forem diferentes, você deverá escolher uma implantação em que o modelo subjacente seja equivalente ao modelo de versão prévia 1106.

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

  6. Selecione Salvar.

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

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

  8. 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.

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

    Certainly! Here's the Python code I ran to find the solution for the equation (3x + 11 = 14):

    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

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.

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

Importante

Alguns dos recursos descritos nesse artigo podem estar disponíveis apenas na versão prévia. 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)

  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é 20 arquivos, com um tamanho máximo de arquivo de 512 MB para usar com 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

  • Uma assinatura do Azure – crie uma gratuitamente

  • Acesso concedido ao Serviço OpenAI do Azure na assinatura do Azure desejada

    No momento, o acesso a esse serviço é permitido somente por aplicativo. Você pode solicitar acesso ao Serviço OpenAI do Azure preenchendo o formulário em https://aka.ms/oai/access. Abra um problema neste repositório para entrar em contato conosco se você tiver algum problema.

  • Python 3.8 ou versão posterior

  • As seguintes bibliotecas do Python: os, openai (A versão 1.x é obrigatória)

  • A CLI do Azure usada para autenticação sem senha em um ambiente de desenvolvimento local, crie o contexto necessário entrando com a CLI do Azure.

  • Um recurso Azure OpenAI com um modelo compatível numa região suportada.

  • Recomendamos revisar a Nota de transparência da IA responsável e outros Recursos de IA responsável para conhecer melhor os recursos e limitações do Serviço OpenAI do Azure.

  • Um recurso de OpenAI do Azure com o modelo gpt-4 (1106-preview) implantado foi usado testando este exemplo.

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ê pode encontrar o valor em Estúdio do OpenAI do Azure>Playground>Exibição de código. 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, como alternativa, em Gerenciamento>Implantações no Estúdio OpenAI 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.

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

Variáveis de ambiente

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

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

Em uma janela de console (como cmd, PowerShell ou Bash), use o comando dotnet new para criar um novo aplicativo do console com o nome azure-openai-quickstart. Este comando cria um projeto "Olá, Mundo" simples com um único arquivo de origem C#: Program.cs.

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

Altere o diretório para a pasta do aplicativo recém-criado. É possível criar o aplicativo com:

dotnet build

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

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

Instalar a biblioteca de clientes do OpenAI .NET com:

dotnet add package Azure.AI.OpenAI.Assistants --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 Esse valor pode ser encontrado na seção Chaves & Ponto de Extremidade ao examinar o recurso no portal do Azure. Como alternativa, você pode encontrar o valor em Estúdio OpenAI do Azure>Playground>Exibição de código. 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.

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.

Crie e execute um assistente com o seguinte:

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

string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new ArgumentNullException("AZURE_OPENAI_ENDPOINT");
string key = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY") ?? throw new ArgumentNullException("AZURE_OPENAI_API_KEY");
AssistantsClient client = new AssistantsClient(new Uri(endpoint), new AzureKeyCredential(key));

// Create an assistant
Assistant assistant = await client.CreateAssistantAsync(
    new AssistantCreationOptions("gpt-4-1106-preview") // Replace this with the name of your model deployment
    {
        Name = "Math Tutor",
        Instructions = "You are a personal math tutor. Write and run code to answer math questions.",
        Tools = { new CodeInterpreterToolDefinition() }
    });

// Create a thread
AssistantThread thread = await client.CreateThreadAsync();

// Add a user question to the thread
ThreadMessage message = await client.CreateMessageAsync(
    thread.Id,
    MessageRole.User,
    "I need to solve the equation `3x + 11 = 14`. Can you help me?");

// Run the thread
ThreadRun run = await client.CreateRunAsync(
    thread.Id,
    new CreateRunOptions(assistant.Id)
);

// Wait for the assistant to respond
do
{
    await Task.Delay(TimeSpan.FromMilliseconds(500));
    run = await client.GetRunAsync(thread.Id, run.Id);
}
while (run.Status == RunStatus.Queued
    || run.Status == RunStatus.InProgress);

// Get the messages
PageableList<ThreadMessage> messagesPage = await client.GetMessagesAsync(thread.Id);
IReadOnlyList<ThreadMessage> messages = messagesPage.Data;

// Note: messages iterate from newest to oldest, with the messages[0] being the most recent
foreach (ThreadMessage threadMessage in messages.Reverse())
{
    Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
    foreach (MessageContent contentItem in threadMessage.ContentItems)
    {
        if (contentItem is MessageTextContent textItem)
        {
            Console.Write(textItem.Text);
        }
        Console.WriteLine();
    }
}

Isso imprimirá uma saída da seguinte maneira:

2024-03-05 03:38:17 -       user: I need to solve the equation `3x + 11 = 14`. Can you help me?
2024-03-05 03:38:25 -  assistant: The solution to the equation \(3x + 11 = 14\) is \(x = 1\).

Novas mensagens podem ser criadas no thread antes de executar novamente, o que fará com que o assistente use as mensagens passadas como contexto dentro do thread.

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 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. Instale a biblioteca de clientes dos Assistentes do OpenAI para JavaScript com:

    npm install openai

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

    npm install @azure/identity

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ê pode encontrar o valor em Estúdio do OpenAI do Azure>Playground>Exibição de código. 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, como alternativa, em Gerenciamento>Implantações no Estúdio OpenAI 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 no portal do Azure com o ponto de extremidade e a localização das chaves de acesso circuladas em vermelho.

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

Variáveis de ambiente

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

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

Adicione variáveis ​​de ambiente adicionais para o nome da implantação e a versão da API:

  • AZURE_OPENAI_DEPLOYMENT_NAME: O nome da sua implantação conforme mostrado no portal do Azure.
  • OPENAI_API_VERSION: Saiba mais sobre Versões da API.

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

setx AZURE_OPENAI_DEPLOYMENT_NAME "REPLACE_WITH_YOUR_DEPLOYMENT_NAME" 
setx OPENAI_API_VERSION "REPLACE_WITH_YOUR_API_VERSION"

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, bem como as ferramentas personalizadas criadas por meio de funções.

Entre no Azure e az login, em seguida, crie e execute um assistente com o seguinte módulo do TypeScript sem senha recomendado (index.ts):

import "dotenv/config";
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)}`);
    }
  }
}

Para usar a chave de serviço para autenticação, crie e execute um assistente com o seguinte módulo do TypeScript (index.ts):

import "dotenv/config";
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";

// Get environment variables
const azureOpenAIKey = process.env.AZURE_OPENAI_KEY as string;
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 (!azureOpenAIKey || !azureOpenAIEndpoint || !azureOpenAIDeployment || !openAIVersion) {
  throw new Error(
    "Please set AZURE_OPENAI_KEY and AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_DEPLOYMENT_NAME in your environment variables."
  );
}

// Get Azure SDK client
const getClient = (): AzureOpenAI => {
  const assistantsClient = new AzureOpenAI({
    endpoint: azureOpenAIEndpoint,
    apiVersion: openAIVersion,
    apiKey: azureOpenAIKey,
  });
  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)}`);
    }
  }
}

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 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 em JavaScript 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.

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 Esse valor pode ser encontrado na seção Chaves & Ponto de Extremidade ao examinar o recurso no portal do Azure. Como alternativa, você pode encontrar o valor em Estúdio do OpenAI do Azure>Playground>Exibição de Código. 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 emGerenciamento de recursos>Implantações no portal do Azure ou, como alternativa, em Gerenciamento>Implantações no Estúdio OpenAI 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.

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

Variáveis de ambiente

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

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