Skip to main content

Introducción a la API de Asistentes (Obsoleta)

La API de Asistentes proporciona un conjunto de herramientas de desarrollo para ayudarle a gestionar fácilmente los mensajes de conversación y llamar a herramientas. Este tema utiliza el ejemplo de la construcción de un asistente de pintura desde cero para ayudarle a aprender rápidamente los métodos básicos de codificación de la API de Asistentes.

La API de Assistant está siendo descontinuada. Migre a la API de Responses como alternativa. La API de Responses incluye múltiples herramientas integradas y admite la gestión de contexto de múltiples turnos.

Proceso típico

El siguiente es un proceso típico para crear una aplicación de agente (Asistente):
  1. Crear un asistente: Al crear un asistente, seleccione un modelo, proporcione instrucciones y agregue herramientas, como un intérprete de código y llamada a funciones.
  2. Crear un hilo: Cuando un usuario inicia una conversación, cree un hilo de sesión para rastrear el historial de la conversación.
  3. Enviar un mensaje al hilo: Agregue el mensaje del usuario a la conversación.
  4. Iniciar una ejecución: Ejecute el asistente en el hilo de sesión. El asistente analiza el mensaje, llama a las herramientas o servicios apropiados, genera una respuesta y se la devuelve.

Escenario de ejemplo

Los modelos de generación de texto no pueden generar imágenes por sí mismos. Por lo general, se requiere un modelo específico de texto a imagen para convertir texto en imágenes. Una aplicación de agente creada con la API de Asistentes puede optimizar automáticamente las palabras descriptivas proporcionadas por el usuario y llamar a una herramienta de texto a imagen para generar imágenes de alta calidad. Por ejemplo, para generar una imagen realista de un gato mascota, solo necesita proporcionar una descripción básica. El asistente de dibujo refina automáticamente el prompt y lo pasa directamente a la herramienta de texto a imagen para completar eficientemente la tarea de creación de imágenes.

Procedimiento

Los siguientes pasos le guían a través del proceso en Python para el modo de salida sin streaming. Para ver el código completo de los SDK de Python y Java tanto para salida con streaming como sin streaming, consulte Código completo al final de este tema.
imagen

Paso 1: Preparar el entorno de desarrollo

  • Solicitar permiso para usar plugins: Primero debe solicitar permiso para usar el plugin de Generación de imágenes. Vaya a la página de Plugins en la consola de Model Studio y haga clic en Apply for Plug-in en la tarjeta correspondiente.
  • Intérprete de Python: La API de Asistentes requiere Python 3.9 o posterior. Puede verificar su versión de Python. Para instalar una versión específica de Python, consulte Descargar Python.
  • SDK de DashScope: Le recomendamos que utilice la última versión del SDK de DashScope. Puede usar el comando de la derecha para verificar su versión. Para instalar una versión específica del SDK de DashScope, use pip.
  • Clave de API: La API de Asistentes requiere una clave de API de Alibaba Cloud Model Studio. Puede obtener una clave de API aquí. Cuando utilice el SDK de DashScope por primera vez, le recomendamos que configure la clave de API como una variable de entorno para evitar exponer información sensible.
# Check the Python interpreter version
python --version

# Check the DashScope SDK
pip list | grep dashscope

# Install DashScope SDK version 1.17.0
pip install dashscope==1.17.0

Paso 2: Crear un asistente

Después de importar el SDK de DashScope, utilice el método create de la clase Assistant para crear un agente Asistente. Este proceso implica configurar los siguientes parámetros clave:
  • model: el nombre del modelo de lenguaje grande, utilizado para configurar el LLM para el agente
  • name: el nombre del agente, utilizado para distinguirlo
  • description: una descripción de la función del agente
  • instructions: instrucciones en lenguaje natural que definen el rol y la tarea del agente
  • tools: una lista de herramientas configuradas para el agente
En nuestro ejemplo, el objetivo es construir un Asistente enfocado en la pintura. Dado que la herramienta de texto a imagen tiene altos requisitos de comprensión del lenguaje, seleccionamos Qwen-Max como modelo de razonamiento para mejorar las capacidades de comprensión semántica y generación de texto del Asistente.Los detalles de configuración del agente, incluido su nombre, descripción de función e instrucciones, se muestran claramente en el fragmento de código adjunto.Para enriquecer la funcionalidad y utilidad del agente, integramos el plugin predefinido oficial Generación de imágenes. Esto asegura que el agente pueda generar automáticamente contenido de imagen correspondiente basado en las descripciones de texto recibidas.Puede crear un número ilimitado de asistentes. Sin embargo, las llamadas frecuentes a un solo modelo pueden activar limitación de tasa. Le recomendamos que configure diferentes modelos para sus asistentes según sus casos de uso.Para obtener más información sobre cómo utilizar la API, consulte API de asistentes.
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# Create a new painting assistant using Qwen-Max
painting_assistant = dashscope.Assistants.create(
    model='qwen-max',  # Use the Qwen-Max model for enhanced understanding. Model list: https://www.alibabacloud.com/help/model-studio/getting-started/models
    name='Art Maestro',  # The assistant's name is "Art Maestro"
    description='An AI assistant specializing in painting and art knowledge.',
    instructions='''You are an expert painting assistant. Provide detailed information about painting techniques, art history, and creative guidance.''',
    tools=[
        {
            'type': 'text_to_image',  # A tool for generating images based on descriptions
            'description': 'Use this tool to create visual examples of a painting style, technique, or art concept.'
        }
    ]
)

# Print the assistant's ID to confirm successful creation
print(f"Painting assistant 'Art Maestro' created successfully, ID: {painting_assistant.id}")

Paso 3: Crear un hilo

Un hilo es un concepto clave en la API de Asistentes que representa un contexto de conversación continua.Un hilo le permite crear un hilo de gestión de sesiones cuando un usuario inicia una nueva conversación. El Asistente puede usar el hilo para comprender todo el contexto de la conversación y proporcionar respuestas más coherentes y relevantes.Le recomendamos que:
  • Cree un nuevo hilo para cada nuevo usuario o tema de conversación.
  • Continúe usando el mismo hilo cuando necesite mantener el contexto.
  • Considere crear un nuevo hilo cuando el tema de la conversación cambie significativamente para evitar confusión en el contexto.
En el escenario del asistente de pintura, el hilo puede rastrear la solicitud inicial del usuario, las sugerencias preliminares del Asistente, los comentarios del usuario y el resultado final de la pintura, formando un proceso de creación completo. Esto garantiza la coherencia y trazabilidad de todo el proceso de creación.Para obtener más información sobre cómo utilizar la API, consulte API de hilos.
from http import HTTPStatus
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# Create a new empty thread
thread = dashscope.Threads.create()

# Check if the thread was created successfully
if thread.status_code == HTTPStatus.OK:
    print(f"Thread created successfully. Thread ID: {thread.id}")
    print("You can now start a painting conversation with the AI assistant.")
else:
    print(f"Thread creation failed. Status code: {thread.status_code}")
    print(f"Error code: {thread.code}")
    print(f"Error message: {thread.message}")

# Note: This empty thread can now be used to maintain the context of your painting project discussion,
# including any future messages about ragdoll cats or other painting subjects.

Paso 4: Agregar un mensaje a un hilo

Su entrada se transmite a través de un objeto Message. La API de Asistentes admite el envío de uno o más mensajes a un solo hilo. Al crear un mensaje, considere los siguientes parámetros:
  • El ID único del Thread: thread_id
  • El contenido del mensaje: content
Aunque no existe un límite estricto en la cantidad de tokens que un hilo puede recibir, la cantidad real de tokens pasados al LLM debe cumplir con el límite máximo de longitud de entrada del modelo. Para obtener más información, consulte la documentación oficial de cada modelo de la serie Qwen respecto a la longitud del contexto.En nuestro escenario, enviará el primer mensaje en el hilo a través de un Message: "Por favor, ayúdame a dibujar una imagen de un gato ragdoll". Necesita crear una clase Message. La configuración detallada de los parámetros se proporciona en el fragmento de código adjunto.Para obtener más información sobre cómo utilizar la API, consulte Mensajes.
Después de que se ejecuta el método Messages.create(), este agrega automáticamente el mensaje al hilo y activa el almacenamiento en cola. Esto equivale a completar tanto las operaciones de creación como de envío del mensaje al mismo tiempo, lo cual es el comportamiento predeterminado de la API.
from http import HTTPStatus
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# Create a message to tell the assistant what to do.
message = dashscope.Messages.create(thread.id, content='Please help me draw a picture of a ragdoll cat.')

# Check if the message was created successfully
if message.status_code == HTTPStatus.OK:
    print('Message created successfully! Message ID: %s' % message.id)
else:
    print('Message creation failed. Status code: %s, Error code: %s, Error message: %s' % (message.status_code, message.code, message.message))

Paso 5: Crear y ejecutar una ejecución

Después de que un usuario asigna un mensaje a un hilo específico, puede iniciar una ejecución para activar el Asistente preconfigurado. El asistente utiliza todos los mensajes del hilo como contexto, emplea el modelo especificado y los plugins disponibles para responder inteligentemente a las preguntas del usuario, e inserta las respuestas generadas en la secuencia de mensajes del hilo.En este escenario, realice los siguientes pasos:
  1. Inicialice un objeto run para impulsar al asistente de pintura, pasando el ID del hilo (thread.id) y el ID del asistente (assistant.id).
  2. Utilice el método wait del objeto run (Run.wait) hasta que se complete la ejecución.
  3. Utilice el método de lista de mensajes (Messages.list) para recuperar la imagen del gato mascota dibujada por el asistente.
Esta serie de operaciones garantiza un flujo de procesamiento automatizado para el asistente, desde la recepción de una pregunta hasta la emisión de un resultado.Para obtener más información sobre cómo utilizar la API, consulte API de ejecuciones.
Es posible que muchos usuarios estén utilizando el modelo al mismo tiempo, lo cual puede extender el tiempo de procesamiento. Le recomendamos que espere hasta que el estado muestre "complete" antes de realizar la siguiente operación para garantizar un proceso fluido.
from http import HTTPStatus
import json
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# Create a new run to execute the message
run = dashscope.Runs.create(thread.id, assistant_id=painting_assistant.id)
if run.status_code != HTTPStatus.OK:
    print('Failed to create assistant, Status code: %s, Error code: %s, Error message: %s' % (run.status_code, run.code, run.message))
else:
    print('Assistant created successfully, ID: %s' % run.id)

# Wait for the run to complete or require action
run = dashscope.Runs.wait(run.id, thread_id=thread.id)
if run.status_code != HTTPStatus.OK:
    print('Failed to get run status, Status code: %s, Error code: %s, Error message: %s' % (run.status_code, run.code, run.message))
else:
    print(run)

# Get the thread messages to get the run output
msgs = dashscope.Messages.list(thread.id)
if msgs.status_code != HTTPStatus.OK:
    print('Failed to get messages, Status code: %s, Error code: %s, Error message: %s' % (msgs.status_code, msgs.code, msgs.message))
else:
    print(json.dumps(msgs, default=lambda o: o.__dict__, sort_keys=True, indent=4))

Código completo

  • Salida sin streaming
  • Salida de transmisión
import dashscope
from http import HTTPStatus
import json
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

def check_status(component, operation):
    if component.status_code == HTTPStatus.OK:
        print(f"{operation} successful.")
        return True
    else:
        print(f"{operation} failed. Status code: {component.status_code}, Error code: {component.code}, Error message: {component.message}")
        return False

# 1. Create a painting assistant
painting_assistant = dashscope.Assistants.create(
    # Model list: https://www.alibabacloud.com/help/model-studio/getting-started/models
    model='qwen-max',
    name='Art Maestro',
    description='AI assistant for painting and art knowledge',
    instructions='''Provide information on painting techniques, art history, and creative guidance.
    Use tools for research and image generation.''',
    tools=[
        {'type': 'text_to_image', 'description': 'For creating visual examples'}
    ]
)

if not check_status(painting_assistant, "Assistant creation"):
    exit()

# 2. Create a new thread
thread = dashscope.Threads.create()

if not check_status(thread, "Thread creation"):
    exit()

# 3. Send a message to the thread
message = dashscope.Messages.create(thread.id, content='Please help me draw a picture of a ragdoll cat.')

if not check_status(message, "Message creation"):
    exit()

# 4. Run the assistant on the thread
run = dashscope.Runs.create(thread.id, assistant_id=painting_assistant.id)

if not check_status(run, "Run creation"):
    exit()

# 5. Wait for the run to complete
print("Waiting for the assistant to process the request...")
run = dashscope.Runs.wait(run.id, thread_id=thread.id)

if check_status(run, "Run completion"):
    print(f"Run completed, status: {run.status}")
else:
    print("Run not completed.")
    exit()

# 6. Retrieve and display the assistant's response
messages = dashscope.Messages.list(thread.id)

if check_status(messages, "Message retrieval"):
    if messages.data:
        # Display the content of the last message (the assistant's response)
        last_message = messages.data[0]
        print("\nAssistant's response:")
        print(json.dumps(last_message, ensure_ascii=False, default=lambda o: o.__dict__, sort_keys=True, indent=4))
    else:
        print("No messages found in the thread.")
else:
    print("Failed to retrieve the assistant's response.")

# Tip: This code creates a painting assistant, starts a conversation about how to draw a ragdoll cat,
# and displays the assistant's answer.

Siguientes pasos

Para obtener explicaciones detalladas de los parámetros de los componentes de la API de Asistentes, consulte Referencia de desarrollo de la API de Asistentes.