Skip to main content

Getting started with Assistant API (Deprecated)

L'Assistant API fournit un ensemble d'outils de développement facilitant la gestion des messages de conversation et l'appel d'outils. Cette rubrique prend pour exemple la création d'un assistant de dessin à partir de zéro afin de vous familiariser rapidement avec les méthodes de codage de base de l'Assistant API.

L'Assistant API est en cours de dépréciation. Migrez vers l'API Responses comme alternative. L'API Responses intègre plusieurs outils natifs et prend en charge la gestion du contexte sur plusieurs tours de conversation.

Processus type

Voici le processus typique pour construire une application d'agent (Assistant) :
  1. Créer un Assistant : lors de la création, sélectionnez un modèle, fournissez des instructions et ajoutez des outils, tels qu'un interpréteur de code et l'appel de fonctions.
  2. Créer un Thread : lorsqu'un utilisateur initie une conversation, créez un thread de session pour suivre l'historique des échanges.
  3. Envoyer un message au Thread : ajoutez le message de l'utilisateur à la conversation.
  4. Démarrer un Run : exécutez l'assistant sur le thread de session. L'assistant analyse le message, appelle les outils ou services appropriés, génère une réponse et vous la retourne.

Scénario d'exemple

Les modèles de génération de texte ne peuvent pas produire d'images par eux-mêmes. Un modèle spécifique de conversion texte-image est généralement nécessaire pour transformer du texte en images. Une application d'agent créée avec l'Assistant API peut optimiser automatiquement les termes descriptifs fournis par l'utilisateur, appeler un outil texte-image pour générer des images de haute qualité. Par exemple, pour obtenir une image réaliste d'un chat domestique, il suffit de fournir une description sommaire. L'assistant de dessin affine alors automatiquement le prompt et le transmet directement à l'outil texte-image pour réaliser efficacement la tâche de création visuelle.

Procédure

Les étapes suivantes détaillent la procédure en Python pour le mode de sortie non streaming. Pour consulter le code complet des SDK Python et Java couvrant les modes streaming et non-streaming, reportez-vous à la section Code complet à la fin de cette rubrique.
image

Étape 1 : Préparer l'environnement de développement

  • Demander l'autorisation d'utiliser des plugins : demandez d'abord l'autorisation d'utiliser le plugin Image Generation. Accédez à la page Plug-ins dans la console Model Studio et cliquez sur Apply for Plug-in sur la carte correspondante.
  • Interpréteur Python : l'Assistant API nécessite Python 3.9 ou version ultérieure. Vérifiez votre version de Python. Pour installer une version spécifique, consultez Download Python.
  • SDK DashScope : nous vous recommandons d'utiliser la dernière version du SDK DashScope. Utilisez la commande située à droite pour vérifier votre version. Pour installer une version précise du SDK DashScope, utilisez pip.
  • Clé API : l'Assistant API requiert une clé API Alibaba Cloud Model Studio. Vous pouvez obtenir une clé API ici. Lors de votre première utilisation du SDK DashScope, configurez la clé API en tant que variable d'environnement afin d'éviter toute exposition d'informations sensibles. Pour plus d'informations, consultez Configurer la clé API en tant que variable d'environnement.
# 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

Étape 2 : Créer un Assistant

Après avoir importé le SDK Dashscope, utilisez la méthode create de la classe Assistant pour créer un agent Assistant. Ce processus implique la définition des paramètres clés suivants :
  • model : nom du grand modèle de langage, utilisé pour configurer le LLM de l'agent
  • name : nom de l'agent, servant à l'identifier
  • description : description de la fonction de l'agent
  • instructions : directives en langage naturel définissant le rôle et la tâche de l'agent
  • tools : liste des outils configurés pour l'agent
Dans notre exemple, l'objectif est de construire un Assistant spécialisé dans le dessin. Étant donné que l'outil texte-image exige une compréhension linguistique avancée, nous choisissons Qwen-Max comme modèle de raisonnement afin d'améliorer les capacités de compréhension sémantique et de génération de texte de l'Assistant.Les détails de configuration de l'agent, incluant son nom, la description de sa fonction et ses instructions, apparaissent clairement dans l'extrait de code ci-joint.Afin d'enrichir les fonctionnalités et l'utilité de l'agent, nous intégrons le plugin officiel préconstruit Image Generation. Cela permet à l'agent de générer automatiquement le contenu visuel correspondant aux descriptions textuelles reçues.Vous pouvez créer un nombre illimité d'Assistants. Toutefois, des appels fréquents à un même modèle risquent de déclencher une limitation de débit. Nous vous recommandons de configurer différents modèles pour vos Assistants en fonction de leurs cas d'utilisation.Pour plus d'informations sur l'utilisation de l'API, consultez Assistants API.
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/en/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}")

Étape 3 : Créer un Thread

Un Thread est un concept fondamental de l'Assistant API représentant un contexte de conversation continu.Le Thread permet de créer un fil de gestion de session lorsqu'un utilisateur entame une nouvelle conversation. L'Assistant exploite ce Thread pour appréhender l'ensemble du contexte et fournir des réponses plus cohérentes et pertinentes.Nous vous recommandons les pratiques suivantes :
  • Créez un nouveau Thread pour chaque nouvel utilisateur ou nouveau sujet de conversation.
  • Continuez à utiliser le même Thread lorsque vous devez maintenir le contexte.
  • Envisagez la création d'un nouveau Thread si le sujet de conversation change radicalement, afin d'éviter toute confusion contextuelle.
Dans le scénario de l'assistant de dessin, le Thread permet de suivre la demande initiale de l'utilisateur, les suggestions préliminaires de l'Assistant, les retours de l'utilisateur et le résultat final du dessin, formant ainsi un processus de création complet. Cela assure la cohérence et la traçabilité de l'ensemble du processus créatif.Pour plus d'informations sur l'utilisation de l'API, consultez Threads API.
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.

Étape 4 : Ajouter un message à un Thread

Votre saisie est transmise via un objet Message. L'Assistant API prend en charge l'envoi d'un ou plusieurs messages à un même Thread. Lors de la création d'un Message, tenez compte des paramètres suivants :
  • L'ID unique du Thread : thread_id
  • Le contenu du message : content
Bien qu'il n'y ait pas de limite stricte quant au nombre de tokens qu'un Thread peut recevoir, le nombre réel de tokens transmis au LLM doit respecter la longueur maximale d'entrée du modèle. Pour plus de détails, consultez la documentation officielle de chaque modèle de la série Qwen concernant la longueur du contexte.Dans notre scénario, vous envoyez le premier message du Thread via un Message : « Please help me draw a picture of a ragdoll cat. » Vous devez instancier une classe Message. Les paramètres détaillés sont fournis dans l'extrait de code ci-joint.Pour plus d'informations sur l'utilisation de l'API, consultez Messages.
Une fois la méthode Messages.create() exécutée, elle ajoute automatiquement le message au thread et déclenche sa mise en file d'attente. Cela équivaut à effectuer simultanément les opérations de création et d'envoi du message, ce qui constitue le comportement par défaut de l'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))

Étape 5 : Créer et exécuter un Run

Une fois qu'un utilisateur a attribué un message à un Thread spécifique, vous pouvez démarrer un Run pour activer l'Assistant préconfiguré. L'assistant utilise tous les messages du thread comme contexte, exploite le modèle spécifié et les plugins disponibles pour répondre intelligemment aux questions de l'utilisateur, puis insère les réponses générées dans la séquence de messages du thread.Dans ce scénario, effectuez les étapes suivantes :
  1. Initialisez un objet run pour piloter l'assistant de dessin, en passant l'ID du thread (thread.id) et l'ID de l'assistant (assistant.id).
  2. Utilisez la méthode wait de l'objet run (Run.wait) jusqu'à la fin de l'exécution.
  3. Utilisez la méthode de liste des messages (Messages.list) pour récupérer l'image du chat dessinée par l'assistant.
Cette série d'opérations garantit un flux de traitement automatisé pour l'assistant, depuis la réception d'une question jusqu'à la production d'un résultat.Pour plus d'informations sur l'utilisation de l'API, consultez Runs API.
De nombreux utilisateurs pouvant solliciter le modèle simultanément, le temps de traitement peut s'en trouver allongé. Nous vous recommandons de patienter jusqu'à ce que le statut affiche « complete » avant d'effectuer l'opération suivante, afin d'assurer un déroulement fluide.
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))

Code complet

  • Non-streaming output
  • Streaming output
python
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/en/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.

Étapes suivantes

Pour obtenir des explications détaillées sur les paramètres des composants de l'Assistant API, consultez Référence de développement de l'Assistant API.