Compartir a través de

Inicio rápido: Introducción al uso de Azure OpenAI Assistants (versión preliminar)

  • Artículo

Azure OpenAI Assistants (versión preliminar) permite crear asistentes de IA adaptados a sus necesidades mediante instrucciones personalizadas y aumentadas por herramientas avanzadas como el intérprete de código y las funciones personalizadas.

Importante

Los elementos marcados (versión preliminar) en este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin acuerdo de nivel de servicio y no se recomienda para las cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. Para más información, consulte Términos de uso complementarios de las Versiones Preliminares de Microsoft Azure.

Requisitos previos

Ir a Azure AI Studio (versión preliminar)

Estudio de IA de Azure le permite usar Assistants v2, que proporciona varias actualizaciones, como la herramienta de Búsqueda de archivos, que es más rápida y admite más archivos.

  1. Inicie sesión en Azure AI Studio.

  2. Vaya al proyecto o cree un nuevo proyecto en Inteligencia artificial de Azure Studio.

  3. En la información general del proyecto, seleccione Asistentes, que se encuentra en Áreas de juegos.

    El área de juegos Assistants permite explorar, crear prototipos y probar asistentes de inteligencia artificial sin necesidad de ejecutar ningún código. Desde esta página puede iterar y experimentar rápidamente con nuevas ideas.

    El área de juegos proporciona varias opciones para configurar el Asistente. En los pasos siguientes, usará el panel de configuración para crear un asistente de IA.

    Nombre Descripción
    Nombre del asistente Su nombre de implementación asociado a un modelo específico.
    Instrucciones Las instrucciones son similares a los mensajes del sistema, donde se proporcionan las instrucciones del modelo sobre cómo debe comportarse y cualquier contexto al que debe hacerse referencia al generar una respuesta. Puede describir la personalidad del asistente, indicarle lo que debe y lo que no debe responder y cómo formatear las respuestas. También puede proporcionar ejemplos de los pasos que debe realizar al responder a las respuestas.
    Implementación Aquí es donde se establece la implementación de modelo que se va a usar con el asistente.
    Funciones Creación de definiciones de función personalizadas para los modelos para formular llamadas API y generar salidas de datos de estructura en función de las especificaciones. No se usa en este inicio rápido.
    Intérprete de código El intérprete de código proporciona acceso a un entorno de Python de espacio aislado que se puede usar para permitir que el modelo pruebe y ejecute el código.
    Archivos Puede cargar hasta 10 000 archivos, con un tamaño máximo de archivo de 512 MB para usarlo con herramientas. No se usa en este inicio rápido.

    Captura de pantalla de la pantalla de configuración del Asistente sin todos los valores rellenados.

Creación del primer Asistente

  1. Seleccione la implementación en la lista desplegable Implementaciones.

  2. En la lista desplegable de configuración del Asistente, seleccione Nuevo asistente.

  3. Asigne un nombre al Asistente.

  4. Escriba la instrucción siguiente: "Usted es un asistente de IA que puede escribir código para ayudar a responder preguntas matemáticas".

  5. Seleccione una implementación de modelo. Se recomienda realizar pruebas con uno de los modelos gpt-4 más recientes.

  6. Seleccione el botón de alternancia que habilita el intérprete de código.

  7. Seleccione Guardar.

    Captura de pantalla del asistente con los detalles de configuración especificados.

  8. Escriba una pregunta para que el asistente responda: "Necesito resolver la ecuación 3x + 11 = 14. ¿Puede ayudarme?"

  9. Seleccione el botón Agregar y ejecutar. 

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

    Aunque podemos ver que la respuesta es correcta, para confirmar que el modelo utilizó el intérprete de código para llegar a esta respuesta y que el código que escribió es válido, en lugar de limitarse a repetir una respuesta de los datos de entrenamiento del modelo, formularemos otra pregunta.

  10. Escriba la pregunta de seguimiento: "Muéstreme el código que ejecutó para llegar a esta solución".

    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 pantalla de la sesión de conversación en el área de juegos del Asistente.

También puede consultar los registros en el panel derecho para confirmar que se usó el intérprete de código y para validar el código que se ejecutó para generar la respuesta. Es importante recordar que, aunque el intérprete de código ofrece al modelo la capacidad de responder a preguntas matemáticas más complejas convirtiendo las preguntas en código y ejecutándose en un entorno de Python de espacio aislado, todavía debe validar la respuesta para confirmar que el modelo ha traducido correctamente la pregunta en una representación válida en el código.

Conceptos clave

Al usar el área de juegos de Asistentes, tenga en cuenta los siguientes conceptos.

Herramientas

Un asistente individual puede acceder a hasta 128 herramientas, como code interpreter, así como a cualquier herramienta personalizada que haya creado mediante funciones.

Sesión de chat

La sesión de chat, que también se conoce como un subproceso dentro de la API Assistants, es donde se produce la conversación entre el usuario y el asistente. A diferencia de las llamadas de finalización de chat tradicionales no hay ningún límite para el número de mensajes de un subproceso. El asistente comprimirá automáticamente las solicitudes para ajustarse al límite del token de entrada del modelo.

Esto también significa que no controla cuántos tokens se pasan al modelo durante cada turno de la conversación. La API Assistants abstrae y controla completamente los tokens de administración.

Seleccione el botón Borrar chat para eliminar el historial de conversaciones actual.

Debajo del cuadro de entrada de texto hay dos botones:

  • Agregue un mensaje sin ejecutar.
  • Agregue y ejecute.

Registros

Los registros proporcionan una instantánea detallada de la actividad de la API Assistants.

Mostrar paneles

De forma predeterminada, hay tres paneles: Configuración del asistente, Sesión de chat y Registros. Mostrar paneles permite agregar, quitar y reorganizar los paneles. Si alguna vez cierra un panel y necesita recuperarlo, use Mostrar paneles para restaurar el panel perdido.

Limpieza de recursos

Si quiere limpiar y quitar un recurso de Azure OpenAI, puede eliminar el recurso o el grupo de recursos. Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él.

También puede eliminar el asistente, o conversación a través de la API del Asistente.

Consulte también

Documentación de referencia | Código fuente de la biblioteca | Paquete (PyPi) |

Requisitos previos

Para la autenticación sin contraseña, se necesita:

  1. Use el paquete azure-identity.
  2. Asignar el rol Cognitive Services User a su cuenta de usuario. Esto se puede hacer en Azure Portal en Control de acceso (IAM)>Agregar asignación de roles.
  3. Inicie sesión con la CLI de Azure, como az login.

Configuración

  1. Instalar la biblioteca cliente de OpenAI Python con:
pip install openai
  1. Para conocer la autenticación sin contraseña recomendada:
pip install azure-identity

Nota:

  • La búsqueda de archivos puede ingerir hasta 10 000 archivos por asistente, 500 veces más que antes. Es rápida, compatible con consultas paralelas a través de búsquedas multiproceso y presenta características mejoradas de reordenación y reescritura de consultas.
    • El almacén de vectores es un nuevo objeto de la API. Una vez que un archivo se agrega a un almacén de vectores, se analiza automáticamente, se divide en fragmentos y se inserta, quedando listo para su búsqueda. Los almacenes de vectores se pueden usar entre asistentes y subprocesos, lo que simplifica la administración de archivos y la facturación.
  • Hemos agregado compatibilidad con el parámetro tool_choice que se puede usar para forzar el uso de una herramienta específica (como la búsqueda de archivos, el intérprete de código o una función) en una ejecución determinada.

Nota:

OpenAI mantiene esta biblioteca. Consulte el historial de versiones para realizar el seguimiento de las actualizaciones más recientes de la biblioteca.

Recuperación de la clave y el punto de conexión

Para realizar correctamente una llamada en el servicio Azure OpenAI, necesitará lo siguiente:

Nombre de la variable Valor
ENDPOINT Este valor se puede encontrar en la sección Claves y punto de conexión al examinar su recurso en Azure Portal. También puede encontrar el punto de conexión a través de la página Implementaciones de Estudio de IA de Azure. Punto de conexión de ejemplo: https://docs-test-001.openai.azure.com/.
API-KEY Este valor se puede encontrar en la sección Claves y punto de conexión al examinar su recurso en Azure Portal. Puede usar KEY1 o KEY2.
DEPLOYMENT-NAME Este valor corresponderá al nombre personalizado que eligió para la implementación al implementar un modelo. Este valor se puede encontrar en Administración de recursos>Implementaciones de modelos en Azure Portal o a través de la página Implementaciones en Estudio de IA de Azure.

Vaya al recurso en Azure Portal. Las claves y el punto de conexión se pueden encontrar en la sección Administración de recursos. Copie el punto de conexión y la clave de acceso, ya que los necesitará para autenticar las llamadas API. Puede usar KEY1 o KEY2. Tener siempre dos claves permite rotar y regenerar las claves de forma segura sin provocar una interrupción del servicio.

Captura de pantalla de la hoja de información general de un recurso de Azure OpenAI en Azure Portal con la ubicación del punto de conexión y las claves de acceso en círculo rojo.

Variables de entorno

Cree y asigne variables de entorno persistentes para la clave y el punto de conexión.

Importante

Si usa una clave de API, almacénela de forma segura en otro lugar, como en Azure Key Vault. No incluya la clave de API directamente en el código ni la exponga nunca públicamente.

Para más información sobre la seguridad de los servicios de AI, consulte Autenticación de solicitudes a los servicios de Azure AI.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

Creación de un asistente

En nuestro código vamos a especificar los siguientes valores:

Nombre Descripción
Nombre del asistente Su nombre de implementación asociado a un modelo específico.
Instrucciones Las instrucciones son similares a los mensajes del sistema, donde se proporcionan las instrucciones del modelo sobre cómo debe comportarse y cualquier contexto al que debe hacerse referencia al generar una respuesta. Puede describir la personalidad del asistente, indicarle lo que debe y lo que no debe responder y cómo formatear las respuestas. También puede proporcionar ejemplos de los pasos que debe realizar al responder a las respuestas.
Modelo Aquí es donde se establece el nombre de implementación de modelo que se usará con el asistente. La herramienta de recuperación requiere el modelo gpt-35-turbo (1106) o gpt-4 (1106-preview). Establezca este valor en el nombre de la implementación, no en el nombre del modelo, a menos que sea el mismo.
Intérprete de código El intérprete de código proporciona acceso a un entorno de Python de espacio aislado que se puede usar para permitir que el modelo pruebe y ejecute el código.

Herramientas

Un asistente individual puede acceder a hasta 128 herramientas, como code interpreter, así como a cualquier herramienta personalizada que haya creado mediante funciones.

Crear la aplicación de Python

Inicie sesión en Azure con az login y, a continuación, cree y ejecute un asistente con el siguiente ejemplo de Python sin contraseña 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 la clave de API de servicio para la autenticación, puede crear un asistente y ejecutarlo con el siguiente ejemplo de 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))

Output

La ejecución se ha completado con el estado: completado.

{
  "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
}

Descripción de los resultados

En este ejemplo se crea un asistente con el intérprete de código habilitado. Cuando formulamos una pregunta matemática al asistente, este traduce la pregunta a código de python y ejecuta el código en un entorno de espacio aislado para determinar la respuesta a la pregunta. El código que el modelo crea y prueba para llegar a una respuesta es el siguiente:

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

Es importante recordar que, aunque el intérprete de código proporciona al modelo la capacidad de responder a consultas más complejas convirtiendo las preguntas en código y ejecutando ese código de forma iterativa en el espacio aislado de Python hasta llegar a una solución, todavía debe validar la respuesta para confirmar que el modelo ha traducido correctamente la pregunta en una representación válida en el código.

Limpieza de recursos

Si quiere limpiar y quitar un recurso de Azure OpenAI, puede eliminar el recurso o el grupo de recursos. Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él.

Consulte también

Documentación de referencia de la API | Código fuente | Paquete (NuGet)

Requisitos previos

Configuración

Creación de una aplicación de .NET Core

  1. En una ventana de la consola (como cmd, PowerShell o Bash), use el comando dotnet new para crear una aplicación de consola con el nombre azure-openai-quickstart:

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

  2. Cambie al directorio de la carpeta de la aplicación recién creada y compile la aplicación con el comando dotnet build:

    dotnet build

    La salida de la compilación no debe contener advertencias ni errores.

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

  3. Instale la biblioteca cliente de OpenAI .NET con el comando dotnet add package:

    dotnet add package Azure.AI.OpenAI --prerelease

Recuperación de la clave y el punto de conexión

Para realizar correctamente una llamada en Azure OpenAI, necesita un punto de conexión y una clave.

Nombre de la variable Valor
ENDPOINT El punto de conexión de servicio se puede encontrar en la sección Claves y punto de conexión al examinar su recurso en Azure Portal. También puede encontrar el punto de implementación a través de la página Implementaciones de Estudio de IA de Azure. Punto de conexión de ejemplo: https://docs-test-001.openai.azure.com/.
API-KEY Este valor se puede encontrar en la sección Claves y punto de conexión al examinar el recurso en Azure Portal. Puede usar KEY1 o KEY2.

Vaya al recurso en Azure Portal. La sección Claves y puntos de conexión se puede encontrar en la sección Administración de recursos. Copie el punto de conexión y la clave de acceso, ya que los necesitará para autenticar las llamadas API. Puede usar KEY1 o KEY2. Tener siempre dos claves permite rotar y regenerar las claves de forma segura sin provocar una interrupción del servicio.

Captura de pantalla de la interfaz de usuario de información general de un recurso de Azure OpenAI en Azure Portal con el punto de conexión y la ubicación de las claves de acceso en círculo en rojo.

Variables de entorno

Cree y asigne variables de entorno persistentes para la clave y el punto de conexión.

Importante

Si usa una clave de API, almacénela de forma segura en otro lugar, como en Azure Key Vault. No incluya la clave de API directamente en el código ni la exponga nunca públicamente.

Para más información sobre la seguridad de los servicios de AI, consulte Autenticación de solicitudes a los servicios de Azure AI.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

La autenticación sin contraseña es más segura que las alternativas basadas en claves y es el enfoque recomendado para conectarse a los servicios de Azure. Si elige Autenticación sin contraseña, deberá completar lo siguiente:

  1. Agregue el paquete Azure.Identity.

    dotnet add package Azure.Identity

  2. Asignar el rol Cognitive Services User a su cuenta de usuario. Esto se puede hacer en Azure Portal o en el recurso de OpenAI en Control de acceso (IAM)>Agregar asignación de roles.

  3. Inicie sesión en Azure mediante Visual Studio o la CLI de Azure a través de az login.

Crear el asistente

Actualice el archivo Program.cs con el código siguiente para crear un asistente:

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();
}

Ejecute la aplicación con el comando dotnet run:

dotnet run

La salida de la consola debe ser similar a la siguiente:

[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!

Limpieza de recursos

Si quiere limpiar y quitar un recurso de Azure OpenAI, puede eliminar el recurso o el grupo de recursos. Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él.

Consulte también

Documentación de referencia | Código fuente de la biblioteca | Paquete (npm) |

Requisitos previos

Para Autenticación sin claves, debe

  1. Usar el paquete @azure/identity.
  2. Asignar el rol Cognitive Services User a su cuenta de usuario. Esto se puede hacer en Azure Portal en Control de acceso (IAM)>Agregar asignación de roles.
  3. Inicie sesión con la CLI de Azure, como az login.

Configurar

  1. Cree una nueva carpeta assistants-quickstart para que contenga la aplicación y abra Visual Studio Code en esa carpeta con el siguiente comando:

    mkdir assistants-quickstart && code assistants-quickstart

  2. Cree el package.json con el comando siguiente:

    npm init -y

  3. Actualice el package.json a ECMAScript con el siguiente comando:

    npm pkg set type=module

  4. Instale la biblioteca cliente de OpenAI Assistants para JavaScript con:

    npm install openai

  5. Para conocer la autenticación sin contraseña recomendada:

    npm install @azure/identity

Recuperación de información de recursos

Nombre de la variable Valor
AZURE_OPENAI_ENDPOINT Este valor se puede encontrar en la sección Claves y punto de conexión al examinar su recurso en Azure Portal.
AZURE_OPENAI_DEPLOYMENT_NAME Este valor corresponderá al nombre personalizado que eligió para la implementación al implementar un modelo. Este valor se puede encontrar en Administración de recursos>Implementaciones de modelos en Azure Portal.
OPENAI_API_VERSION Obtenga más información sobre las versiones de API.

Obtenga más información sobre la autenticación sin claves y la configuración de variables de entorno.

Precaución

Para usar la autenticación sin clave recomendada con el SDK, asegúrese de que la variable de entorno AZURE_OPENAI_API_KEY no esté establecida.

Creación de un asistente

En nuestro código vamos a especificar los siguientes valores:

Nombre Descripción
Nombre del asistente Su nombre de implementación asociado a un modelo específico.
Instrucciones Las instrucciones son similares a los mensajes del sistema, donde se proporcionan las instrucciones del modelo sobre cómo debe comportarse y cualquier contexto al que debe hacerse referencia al generar una respuesta. Puede describir la personalidad del asistente, indicarle lo que debe y lo que no debe responder y cómo formatear las respuestas. También puede proporcionar ejemplos de los pasos que debe realizar al responder a las respuestas.
Modelo Este es el nombre de la implementación.
Intérprete de código El intérprete de código proporciona acceso a un entorno de Python de espacio aislado que se puede usar para permitir que el modelo pruebe y ejecute el código.

Herramientas

Un asistente individual puede acceder a hasta 128 herramientas, como code interpreter, así como a cualquier herramienta personalizada que haya creado mediante funciones.

Creación de una aplicación de JavaScript

  1. Cree el archivo index.js con el código siguiente:

    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. Inicie sesión en Azure con el siguiente comando:

    az login

  3. Ejecute el archivo JavaScript.

    node index.js

Output

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?"

Es importante recordar que, aunque el intérprete de código proporciona al modelo la capacidad de responder a consultas más complejas convirtiendo las preguntas en código y ejecutando ese código de forma iterativa en JavaScript hasta llegar a una solución, todavía debe validar la respuesta para confirmar que el modelo ha traducido correctamente la pregunta en una representación válida en el código.

Limpieza de recursos

Si quiere limpiar y quitar un recurso de Azure OpenAI, puede eliminar el recurso o el grupo de recursos. Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él.

Código de ejemplo

Consulte también

Documentación de referencia | Código fuente de la biblioteca | Paquete (npm) |

Requisitos previos

Para la autenticación sin contraseña, se necesita:

  1. Usar el paquete @azure/identity.
  2. Asignar el rol Cognitive Services User a su cuenta de usuario. Esto se puede hacer en Azure Portal en Control de acceso (IAM)>Agregar asignación de roles.
  3. Inicie sesión con la CLI de Azure, como az login.

Configurar

  1. Cree una nueva carpeta assistants-quickstart para que contenga la aplicación y abra Visual Studio Code en esa carpeta con el siguiente comando:

    mkdir assistants-quickstart && code assistants-quickstart

  2. Cree el package.json con el comando siguiente:

    npm init -y

  3. Actualice el package.json a ECMAScript con el siguiente comando:

    npm pkg set type=module

  4. Instale la biblioteca cliente de OpenAI Assistants para JavaScript con:

    npm install openai

  5. Para conocer la autenticación sin contraseña recomendada:

    npm install @azure/identity

Recuperación de información de recursos

Nombre de la variable Valor
AZURE_OPENAI_ENDPOINT Este valor se puede encontrar en la sección Claves y punto de conexión al examinar su recurso en Azure Portal.
AZURE_OPENAI_DEPLOYMENT_NAME Este valor corresponderá al nombre personalizado que eligió para la implementación al implementar un modelo. Este valor se puede encontrar en Administración de recursos>Implementaciones de modelos en Azure Portal.
OPENAI_API_VERSION Obtenga más información sobre las versiones de API.

Obtenga más información sobre la autenticación sin claves y la configuración de variables de entorno.

Precaución

Para usar la autenticación sin clave recomendada con el SDK, asegúrese de que la variable de entorno AZURE_OPENAI_API_KEY no esté establecida.

Creación de un asistente

En nuestro código vamos a especificar los siguientes valores:

Nombre Descripción
Nombre del asistente Su nombre de implementación asociado a un modelo específico.
Instrucciones Las instrucciones son similares a los mensajes del sistema, donde se proporcionan las instrucciones del modelo sobre cómo debe comportarse y cualquier contexto al que debe hacerse referencia al generar una respuesta. Puede describir la personalidad del asistente, indicarle lo que debe y lo que no debe responder y cómo formatear las respuestas. También puede proporcionar ejemplos de los pasos que debe realizar al responder a las respuestas.
Modelo Este es el nombre de la implementación.
Intérprete de código El intérprete de código proporciona acceso a un entorno de Python de espacio aislado que se puede usar para permitir que el modelo pruebe y ejecute el código.

Herramientas

Un asistente individual puede acceder a hasta 128 herramientas, como code interpreter, así como a cualquier herramienta personalizada que haya creado mediante funciones.

Creación de una nueva aplicación TypeScript

  1. Cree el archivo index.ts con el código siguiente:

    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. Cree el archivo tsconfig.json para transpilar el código TypeScript y copie el código siguiente 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 a JavaScript.

    tsc

  4. Inicie sesión en Azure con el siguiente comando:

    az login

  5. Ejecute el código con el siguiente comando:

    node index.js

Output

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?"

Es importante recordar que, aunque el intérprete de código proporciona al modelo la capacidad de responder a consultas más complejas convirtiendo las preguntas en código y ejecutando ese código de forma iterativa en JavaScript hasta llegar a una solución, todavía debe validar la respuesta para confirmar que el modelo ha traducido correctamente la pregunta en una representación válida en el código.

Limpieza de recursos

Si quiere limpiar y quitar un recurso de Azure OpenAI, puede eliminar el recurso o el grupo de recursos. Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él.

Código de ejemplo

Consulte también

Requisitos previos

Configuración

Recuperación de la clave y el punto de conexión

Para realizar correctamente una llamada a Azure OpenAI, necesitará lo siguiente:

Nombre de la variable Valor
ENDPOINT El punto de conexión de servicio se puede encontrar en la sección Claves y punto de conexión al examinar su recurso en Azure Portal. También puede encontrar el punto de implementación a través de la página Implementaciones de Estudio de IA de Azure. Punto de conexión de ejemplo: https://docs-test-001.openai.azure.com/.
API-KEY Este valor se puede encontrar en la sección Claves y punto de conexión al examinar el recurso en Azure Portal. Puede usar KEY1 o KEY2.
DEPLOYMENT-NAME Este valor corresponderá al nombre personalizado que eligió para la implementación al implementar un modelo. Este valor se puede encontrar en Administración de recursos>Implementaciones en Azure Portal o a través de la página Implementaciones en Estudio de IA de Azure.

Vaya al recurso en Azure Portal. El punto de conexión y las claves se pueden encontrar en la sección Administración de recursos. Copie el punto de conexión y la clave de acceso, ya que los necesitará para autenticar las llamadas API. Puede usar KEY1 o KEY2. Tener siempre dos claves permite rotar y regenerar las claves de forma segura sin provocar una interrupción del servicio.

Captura de pantalla de la hoja de información general de un recurso de Azure OpenAI en Azure Portal con la ubicación del punto de conexión y las claves de acceso en círculo rojo.

Variables de entorno

Cree y asigne variables de entorno persistentes para la clave y el punto de conexión.

Importante

Si usa una clave de API, almacénela de forma segura en otro lugar, como en Azure Key Vault. No incluya la clave de API directamente en el código ni la exponga nunca públicamente.

Para más información sobre la seguridad de los servicios de AI, consulte Autenticación de solicitudes a los servicios de Azure AI.

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE"

REST API

Creación de un asistente

Nota:

Con Azure OpenAI, el parámetro model necesita el nombre de implementación del modelo. Si el nombre de implementación de modelo es diferente al del modelo subyacente, tendría que ajustar el código a "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"
  }'

Herramientas

Un asistente individual puede acceder a hasta 128 herramientas, como code interpreter, así como a cualquier herramienta personalizada que haya creado mediante funciones.

Creación de un subproceso

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

Adición de una pregunta de usuario al subproceso

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?"
    }'

Ejecución del subproceso

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",
  }'

Recuperación del estado de la ejecución

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

Respuesta del asistente

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" \

Descripción de los resultados

En este ejemplo se crea un asistente con el intérprete de código habilitado. Cuando formulamos una pregunta matemática al asistente, este traduce la pregunta a código de python y ejecuta el código en un entorno de espacio aislado para determinar la respuesta a la pregunta. El código que el modelo crea y prueba para llegar a una respuesta es el siguiente:

    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

Es importante recordar que, aunque el intérprete de código proporciona al modelo la capacidad de responder a consultas más complejas convirtiendo las preguntas en código y ejecutando ese código de forma iterativa en el espacio aislado de Python hasta llegar a una solución, todavía debe validar la respuesta para confirmar que el modelo ha traducido correctamente la pregunta en una representación válida en el código.

Limpieza de recursos

Si quiere limpiar y quitar un recurso de Azure OpenAI, puede eliminar el recurso o el grupo de recursos. Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él.

Consulte también