Referencia de la API de Asistentes (versión preliminar)
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_choiceque 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 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. Actualmente, las herramientas pueden ser de tipos code_interpreter o function. |
| file_ids | array | Opcionales | El valor predeterminado es []. Lista de identificadores de archivo adjuntos a este asistente. Puede haber un máximo de 20 archivos adjuntos al asistente. Los archivos se ordenan por su fecha de creación en orden ascendente. |
| 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. |
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-05-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"}]
)
Crear archivo del asistente
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview
Cree un archivo de asistente adjuntando un objeto File a assistant.
Parámetros de la ruta de acceso
| Parámetro | Type | Obligatorio | Description |
|---|---|---|---|
assistant_id |
string | Obligatorio | Identificador del asistente al que se debe adjuntar el archivo. |
Cuerpo de la solicitud
| Nombre | Type | Obligatorio | Descripción |
|---|---|---|---|
| file_id | string | Obligatorio | Identificador de archivo (con purpose="assistants") que el asistente debe usar. Útil para herramientas como code_interpreter que pueden acceder a archivos. |
Devoluciones
Objeto assistant file.
Ejemplo de solicitud de creación de archivos del asistente
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
assistant_file = client.beta.assistants.files.create(
assistant_id="asst_abc123",
file_id="assistant-abc123"
)
print(assistant_file)
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-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
my_assistants = client.beta.assistants.list(
order="desc",
limit="20",
)
print(my_assistants.data)
Enumerar archivos del asistente
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview
Devuelve una lista de archivos del 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. |
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 file
Lista de ejemplo de archivos de asistente
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
assistant_files = client.beta.assistants.files.list(
assistant_id="asst_abc123"
)
print(assistant_files)
Recuperar asistente
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-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-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)
Recuperación del archivo del asistente
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview
Recupera un archivo Assistant.
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. |
| file_id | string | Obligatorio | El identificador del archivo que obtenemos |
Devoluciones
Objeto assistant file que coincide con el identificador especificado
Ejemplo de recuperación del archivo del asistente
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
assistant_file = client.beta.assistants.files.retrieve(
assistant_id="asst_abc123",
file_id="assistant-abc123"
)
print(assistant_file)
Modificar asistente
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-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. |
file_ids |
array | Opcionales | El valor predeterminado es []. Lista de identificadores de archivo adjuntos a este asistente. Puede haber un máximo de 20 archivos adjuntos al asistente. Los archivos se ordenan por su fecha de creación en orden ascendente. Si un archivo se adjuntó previamente a la lista, pero no aparece en la lista, se eliminará del asistente. |
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. |
Devuelve
Objeto assistant object modificado.
Ejemplo de modificación de asistente
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-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
file_ids=["assistant-abc123", "assistant-abc456"],
)
print(my_updated_assistant)
Eliminar asistente
DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-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-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
response = client.beta.assistants.delete("asst_abc123")
print(response)
Eliminar archivo del asistente
DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview
Elimine un archivo del 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. |
file_id |
string | Obligatorio | Identificador del archivo que se va a eliminar |
Devuelve
Estado de eliminación de archivos
Ejemplo de eliminación del archivo del asistente
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-05-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
deleted_assistant_file = client.beta.assistants.files.delete(
assistant_id="asst_abc123",
file_id="assistant-abc123"
)
print(deleted_assistant_file)
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. |
file_ids |
array | Lista de identificadores de archivo adjuntos a este asistente. Puede haber un máximo de 20 archivos adjuntos al asistente. Los archivos se ordenan por su fecha de creación en orden ascendente. |
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. |
Objeto Assistant file
| 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 assistant.file |
created_at |
integer | Marca de tiempo de Unix (en segundos) para cuando se creó el archivo del asistente. |
assistant_id |
string | Identificador del asistente al que está asociado el archivo. |