Compartir a través de

Referencia de la API de Asistentes (versión preliminar)

  • Artículo

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.

Este artículo proporciona documentación de referencia para Python y REST para la nueva API de Asistentes (versión preliminar). Se proporcionan instrucciones paso a paso más detalladas en la guía de introducción.

Creación de un asistente

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview

Cree un asistente con un modelo e instrucciones.

Cuerpo de la solicitud

Nombre Type Obligatorio Descripción
model string Obligatorio Nombre de implementación del modelo que se va a usar.
name cadena o null Opcionales Nombre del asistente. La longitud máxima es de 256 caracteres.
descripción cadena o null Opcionales Descripción del asistente. La longitud máxima es de 512 caracteres.
detalladas cadena o null Opcionales Las instrucciones del sistema que usa el asistente. La longitud máxima es de 256 000 caracteres.
tools array Opcionales El valor predeterminado es []. Lista de herramientas habilitadas en el asistente. Puede haber un máximo de 128 herramientas por asistente. Actualmente, las herramientas pueden ser de tipos code_interpreter o function. Una descripción de function puede tener un máximo de 1024 caracteres.
metadata map Opcionales Conjunto de 16 pares clave-valor que se pueden adjuntar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado. Las claves pueden tener un máximo de 64 caracteres y los valores pueden tener un máximo de 512 caracteres.
temperatura número o null Opcionales De manera predeterminada, su valor es 1. Determina la temperatura de muestreo que se va a usar, entre 0 y 2. Los valores más altos, como 0,8, harán que la salida sea más aleatoria, mientras que los valores más bajos, como 0,2, la harán más enfocada y determinista.
top_p número o null Opcionales De manera predeterminada, su valor es 1. Una alternativa al muestreo con temperatura, llamada muestreo de núcleo, donde el modelo considera los resultados de los tokens con masa de probabilidad top_p. Así, 0,1 significa que solo se consideran los tokens que comprenden la masa de probabilidad del 10% superior. Por lo general, recomendamos modificar esto o la temperatura, pero no ambos.
response_format cadena u objeto Opcionales Especifica el formato que debe generar el modelo. Compatible con GPT-4 Turbo y todos los modelos GPT-3.5 Turbo desde gpt-3.5-turbo-1106. Al establecer este parámetro en { "type": "json_object" } se habilita el modo JSON, lo que garantiza que el mensaje que genera el modelo es JSON válido. Importantemente, al usar el modo JSON, también debe indicar al modelo que genere JSON usted mismo mediante un mensaje de usuario o sistema. Sin esta instrucción, el modelo puede generar una secuencia de espacios en blanco no deseada hasta que la generación alcance el límite del token, lo que da lugar a una solicitud de larga duración y aparentemente "bloqueada". Además, el contenido del mensaje puede cortarse parcialmente si usa finish_reason="length", lo que indica que la generación superó max_tokens o la conversación superó la longitud máxima del contexto.
tool_resources objeto Opcionales Conjunto de recursos que usan las herramientas del asistente. Los recursos son específicos del tipo de herramienta. Por ejemplo, la herramienta code_interpreter requiere una lista de identificadores de archivo, mientras que la file_search herramienta requiere una lista de identificadores de almacén de vectores.

Devoluciones

Objeto assistant.

Ejemplo de solicitud de creación del asistente

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

assistant = client.beta.assistants.create(
  instructions="You are an AI assistant that can write code to help answer math questions",
  model="<REPLACE WITH MODEL DEPLOYMENT NAME>", # replace with model deployment name. 
  tools=[{"type": "code_interpreter"}]
)

Enumerar asistentes

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview

Devuelve una lista de todos los asistentes.

Parámetros de consulta

Parámetro Type Obligatorio Descripción
limit integer Opcionales Límite en el número de objetos que se van a devolver. El límite puede oscilar entre 1 y 100 y el valor predeterminado es 20.
order string Opcional: el valor predeterminado es desc Orden de clasificación por la marca de tiempo created_at de los objetos. asc para orden ascendente y desc para orden descendente.
after string Opcionales Cursor para su uso en la paginación. after es un identificador de objeto que define su lugar en la lista. Por ejemplo, si realiza una solicitud de lista y recibe 100 objetos que terminan en obj_foo, su llamada posterior puede incluir after=obj_foo para recuperar la siguiente página de la lista.
before string Opcionales Cursor para su uso en la paginación. before es un identificador de objeto que define su lugar en la lista. Por ejemplo, si realiza una solicitud de lista y recibe 100 objetos que terminan en obj_foo, su llamada posterior puede incluir before=obj_foo para recuperar la página anterior de la lista.

Devoluciones

Lista de objetos assistant

Lista de ejemplo de asistentes

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_assistants = client.beta.assistants.list(
    order="desc",
    limit="20",
)
print(my_assistants.data)

Recuperar asistente

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

Recupera un asistente.

Parámetros de la ruta de acceso

Parámetro Type Obligatorio Description
assistant_id string Obligatorio Identificador del asistente que se va a recuperar.

Devuelve

Objeto assistant que coincide con el identificador especificado.

Asistente de recuperación de ejemplo

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)

Modificar asistente

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

Modifica un asistente.

Parámetros de la ruta de acceso

Parámetro Type Obligatorio Descripción
assistant_id string Obligatorio Identificador del asistente al que pertenece el archivo.

Cuerpo de la solicitud

Parámetro Type Obligatorio Descripción
model Opcionales Nombre de la implementación del modelo que se va a usar.
name cadena o null Opcionales Nombre del asistente. La longitud máxima es de 256 caracteres.
description cadena o null Opcionales Descripción del asistente. La longitud máxima es de 512 caracteres.
instructions cadena o null Opcionales Las instrucciones del sistema que usa el asistente. La longitud máxima es de 32768 caracteres.
tools array Opcionales El valor predeterminado es []. Lista de herramientas habilitadas en el asistente. Puede haber un máximo de 128 herramientas por asistente. Las herramientas pueden ser de tipos code_interpreter o función. Una descripción de function puede tener un máximo de 1024 caracteres.
metadata map Opcionales Conjunto de 16 pares clave-valor que se pueden adjuntar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado. Las claves pueden tener un máximo de 64 caracteres y los valores pueden tener un máximo de 512 caracteres.
temperature número o null Opcionales De manera predeterminada, su valor es 1. Determina la temperatura de muestreo que se va a usar, entre 0 y 2. Los valores más altos, como 0,8, harán que la salida sea más aleatoria, mientras que los valores más bajos, como 0,2, la harán más enfocada y determinista.
top_p número o null Opcionales De manera predeterminada, su valor es 1. Una alternativa al muestreo con temperatura, llamada muestreo de núcleo, donde el modelo considera los resultados de los tokens con masa de probabilidad top_p. Así, 0,1 significa que solo se consideran los tokens que comprenden la masa de probabilidad del 10% superior. Por lo general, recomendamos modificar esto o la temperatura, pero no ambos.
response_format cadena u objeto Opcionales Especifica el formato que debe generar el modelo. Compatible con GPT-4 Turbo y todos los modelos GPT-3.5 Turbo desde gpt-3.5-turbo-1106. Al establecer este parámetro en { "type": "json_object" } se habilita el modo JSON, lo que garantiza que el mensaje que genera el modelo es JSON válido. Importantemente, al usar el modo JSON, también debe indicar al modelo que genere JSON usted mismo mediante un mensaje de usuario o sistema. Sin esta instrucción, el modelo puede generar una secuencia de espacios en blanco no deseada hasta que la generación alcance el límite del token, lo que da lugar a una solicitud de larga duración y aparentemente "bloqueada". Además, el contenido del mensaje puede cortarse parcialmente si usa finish_reason="length", lo que indica que la generación superó max_tokens o la conversación superó la longitud máxima del contexto.
tool_resources objeto Opcionales Conjunto de recursos que usan las herramientas del asistente. Los recursos son específicos del tipo de herramienta. Por ejemplo, la herramienta code_interpreter requiere una lista de identificadores de archivo, mientras que la file_search herramienta requiere una lista de identificadores de almacén de vectores.

Devuelve

Objeto assistant object modificado.

Ejemplo de modificación de asistente

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_updated_assistant = client.beta.assistants.update(
  "asst_abc123",
  instructions="You are an HR bot, and you have access to files to answer employee questions about company policies. Always respond with info from either of the files.",
  name="HR Helper",
  tools=[{"type": "code-interpreter"}],
  model="gpt-4", #model = model deployment name
)

print(my_updated_assistant)

Eliminar asistente

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

Elimina un asistente.

Parámetros de la ruta de acceso

Parámetro Type Obligatorio Description
assistant_id string Obligatorio Identificador del asistente al que pertenece el archivo.

Devuelve

Estado de eliminación.

Ejemplo de eliminación de asistente

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

response = client.beta.assistants.delete("asst_abc123")
print(response)

Referencia de API de carga de archivos

Los asistentes usan la misma API para la carga de archivos como ajuste preciso. Al cargar un archivo, debe especificar un valor adecuado para el parámetro de propósito.

Objeto Assistant

Campo Tipo Description
id string Identificador al que se puede hacer referencia en puntos de conexión de API.
object string Tipo de objeto, que siempre es asistente.
created_at integer Marca de tiempo de Unix (en segundos) para cuando se creó el asistente.
name cadena o null Nombre del asistente. La longitud máxima es de 256 caracteres.
description cadena o null Descripción del asistente. La longitud máxima es de 512 caracteres.
model string Nombre del nombre de implementación del modelo que se va a usar.
instructions cadena o null Las instrucciones del sistema que usa el asistente. La longitud máxima es de 32768 caracteres.
tools array Lista de herramientas habilitadas en el asistente. Puede haber un máximo de 128 herramientas por asistente. Las herramientas pueden ser de tipos code_interpreter o función. Una descripción de function puede tener un máximo de 1024 caracteres.
metadata map Conjunto de 16 pares clave-valor que se pueden adjuntar a un objeto. Esto puede ser útil para almacenar información adicional sobre el objeto en un formato estructurado. Las claves pueden tener un máximo de 64 caracteres y los valores pueden tener un máximo de 512 caracteres.
temperature número o null De manera predeterminada, su valor es 1. Determina la temperatura de muestreo que se va a usar, entre 0 y 2. Los valores más altos, como 0,8, harán que la salida sea más aleatoria, mientras que los valores más bajos, como 0,2, la harán más enfocada y determinista.
top_p número o null De manera predeterminada, su valor es 1. Una alternativa al muestreo con temperatura, llamada muestreo de núcleo, donde el modelo considera los resultados de los tokens con masa de probabilidad top_p. Así, 0,1 significa que solo se consideran los tokens que comprenden la masa de probabilidad del 10% superior. Por lo general, recomendamos modificar esto o la temperatura, pero no ambos.
response_format cadena u objeto Especifica el formato que debe generar el modelo. Compatible con GPT-4 Turbo y todos los modelos GPT-3.5 Turbo desde gpt-3.5-turbo-1106. Al establecer este parámetro en { "type": "json_object" } se habilita el modo JSON, lo que garantiza que el mensaje que genera el modelo es JSON válido. Importantemente, al usar el modo JSON, también debe indicar al modelo que genere JSON usted mismo mediante un mensaje de usuario o sistema. Sin esta instrucción, el modelo puede generar una secuencia de espacios en blanco no deseada hasta que la generación alcance el límite del token, lo que da lugar a una solicitud de larga duración y aparentemente "bloqueada". Además, el contenido del mensaje puede cortarse parcialmente si usa finish_reason="length", lo que indica que la generación superó max_tokens o la conversación superó la longitud máxima del contexto.
tool_resources objeto Conjunto de recursos que usan las herramientas del asistente. Los recursos son específicos del tipo de herramienta. Por ejemplo, la herramienta code_interpreter requiere una lista de identificadores de archivo, mientras que la file_search herramienta requiere una lista de identificadores de almacén de vectores.