Assistenten einrichten

Die Beispielanwendung, die wir in erstellen, implementiert mehrere einfache Funktionen, um zu veranschaulichen, wie eine Clientanwendung mit watsonx Assistantinteragiert. Der Anwendungscode erfasst Eingaben und sendet sie an einen Assistenten, der Antworten sendet, die die Anwendung dem Benutzer anzeigt.

Um dieses Beispiel selbst zu testen, müssen Sie zunächst den einfachen Beispielassistenten einrichten, zu dem der Client eine Verbindung herstellt:

1. Laden Sie die JSON-Dateifür Aktionen herunter.
2. Erstellen Sie einen Assistenten.
3. Öffnen Sie im neuen Assistenten die globalen Aktionseinstellungen. Rufen Sie die Registerkarte Upload/Download auf und importieren Sie die Aktionen aus der heruntergeladenen Datei.

Die Beispielaktionen umfassen eine Aktion Kunden grüßen, die nach dem Namen des Kunden fragt, sowie einfache Aktionen zum Erstellen und Stornieren von Zulassungen.

Serviceinformationen abrufen

Damit Sie auf die REST-APIs von watsonx Assistant zugreifen können, muss Ihre Anwendung in der Lage sein, sich bei IBM Cloud® zu authentifizieren und eine Verbindung zum Assistenten in der Umgebung herzustellen, in der sie bereitgestellt wird. Kopieren Sie die Dienstanmeldeinformationen und die Umgebungs-ID und fügen Sie sie in Ihren Anwendungscode ein. Sie benötigen auch die URL für den Standort Ihrer Dienstinstanz (z. B. https://api.us-south.assistant.watson.cloud.ibm.com).

So finden Sie diese Informationen:

1. Rufen Sie die Seite Umgebungen auf und wählen Sie die Umgebung aus, zu der Sie eine Verbindung herstellen wollen.

2. Klicken Sie auf das Symbol Einstellungen , um die Umgebungseinstellungen zu öffnen.

3. Wählen Sie API-Details, um Details für die Umgebung anzuzeigen, einschließlich der URL Dienstinstanz und der Umgebungs-ID. Den API-Schlüssel finden Sie über den Link im Abschnitt Serviceberechtigungsnachweise.

Mit dem Service 'watsonx Assistant' kommunizieren

Die Interaktion mit dem watsonx Assistant-Service über Ihre Clientanwendung ist einfach. Wir beginnen mit einem Beispiel, das eine Verbindung zum Dienst herstellt, eine einzelne leere Nachricht sendet und die Ausgabe auf der Konsole ausgibt:

// Example 1: Creates service object, sends initial message, and
// receives response.

const AssistantV2 = require('ibm-watson/assistant/v2');
const { IamAuthenticator } = require('ibm-watson/auth');

// Create Assistant service object.
const assistant = new AssistantV2({
  version: '2021-11-27',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}', // replace with API key
  }),
  url: '{url}', // replace with URL
});

const assistantId = '{environment_id}'; // replace with environment ID

// Start conversation with empty message
messageInput = {
  messageType: 'text',
  text: '',
};
sendMessage(messageInput);

// Send message to assistant.
function sendMessage(messageInput) {
  assistant
    .messageStateless({
      assistantId,
      input: messageInput,
    })
    .then(res => {
      processResult(res.result);
    })
    .catch(err => {
      console.log(err); // something went wrong
    });
}

// Process the result.
function processResult(result) {
  // Print responses from actions, if any. Supports only text responses.
  if (result.output.generic) {
    if (result.output.generic.length > 0) {
      result.output.generic.forEach( response => {
        if (response.response_type == 'text') {
          console.log(response.text);
        }
      });
    }
  }
}

# Example 1: Creates service object, sends initial message, and
# receives response.

from ibm_watson import AssistantV2
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

# Create Assistant service object.
authenticator = IAMAuthenticator('{apikey}') # replace with API key
assistant = AssistantV2(
    version = '2021-11-27',
    authenticator = authenticator
)
assistant.set_service_url('{url}') # replace with service instance URL
assistant_id = '{environment_id}' # replace with environment ID

# Start conversation with empty message.
result = assistant.message_stateless(
    assistant_id,
).get_result()

# Print responses from actions, if any. Supports only text responses.
if result['output']['generic']:
    for response in result['output']['generic']:
        if response['response_type'] == 'text':
            print(response['text'])

Der erste Schritt besteht darin, ein Dienstobjekt zu erstellen, eine Art Wrapper für den Dienst watsonx Assistant.

Sie verwenden das Serviceobjekt, um Eingaben an den Service zu senden und Ausgaben des Services zu empfangen. Wenn Sie ein Serviceobjekt erstellen, geben Sie den API-Schlüssel für die Authentifizierung und die Version der verwendeten watsonx Assistant-API an.

In diesem Node.js-Beispiel ist das Serviceobjekt eine Instanz von AssistantV2, die in der Variablen assistant gespeichert ist. Die Watson-SDKs für andere Sprachen stellen funktional entsprechende Mechanismen für die Instanziierung eines Serviceobjekts bereit.

In diesem Python-Beispiel ist das Serviceobjekt eine Instanz von watson_developer_cloud.AssistantV2, die in der Variablen assistant gespeichert ist. Die Watson-SDKs für andere Sprachen stellen funktional entsprechende Mechanismen für die Instanziierung eines Serviceobjekts bereit.

Nachdem Sie das Dienstobjekt erstellt haben, verwenden wir es, um eine Nachricht an den Assistenten zu senden, indem wir die zustandslose Methode message verwenden. In diesem Beispiel ist die Nachricht leer. Die Aktion Kunden grüßen soll ausgelöst werden, um die Konversation zu starten, sodass kein Eingabetext erforderlich ist. Anschließend werden alle Textantworten ausgegeben, die im Array generic in der zurückgegebenen Ausgabe zurückgegeben werden.

Verwenden Sie den Befehl node <filename.js>, um die Beispielanwendung auszuführen.

Verwenden Sie den Befehl python3 <filename.py>, um die Beispielanwendung auszuführen.

Hinweis: Stellen Sie sicher, dass Sie die Watson SDK for Node.js mit npm install ibm-watson installieren.

Hinweis: Stellen Sie sicher, dass Sie das Watson SDK für Python installieren, indem Sie pip install --upgrade ibm-watson oder easy_install --upgrade ibm-watson verwenden.

Unter der Annahme, dass alles wie erwartet funktioniert, gibt der Assistent die Ausgabe des Assistenten zurück, die die Anwendung dann auf der Konsole ausgibt:

Welcome to the watsonx Assistant example. What's your name?

Diese Ausgabe gibt an, dass wir mit dem Assistenten kommuniziert und die Begrüßungsnachricht empfangen haben, die durch die Aktion Kunden begrüßen angegeben wird. Aber wir haben noch keine Möglichkeit, die Frage des Assistenten zu beantworten.

Benutzereingabe wird verarbeitet

Damit Benutzereingaben verarbeitet werden können, müssen Sie in Ihrer Anwendung eine Benutzerschnittstelle hinzufügen. In diesem Beispiel halten wir es einfach und verwenden die Standardeingabe und -ausgabe. Sie können das Node.js-Modul 'prompt-sync' verwenden. (Sie können prompt-sync mit npm install prompt-sync installieren) Sie können die Funktion Python 3 input verwenden.

// Example 2: Adds user input.

const prompt = require('prompt-sync')();
const AssistantV2 = require('ibm-watson/assistant/v2');
const { IamAuthenticator } = require('ibm-watson/auth');

// Create Assistant service object.
const assistant = new AssistantV2({
  version: '2021-11-27',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}', // replace with API key
  }),
  url: '{url}', // replace with URL
});

const assistantId = '{environment_id}'; // replace with environment ID

// Start conversation with empty message
messageInput = {
  messageType: 'text',
  text: '',
};
sendMessage(messageInput);

// Send message to assistant.
function sendMessage(messageInput) {
  assistant
    .messageStateless({
      assistantId,
      input: messageInput,
    })
    .then(res => {
      processResult(res.result);
    })
    .catch(err => {
      console.log(err); // something went wrong
    });
}

// Process the result.
function processResult(result) {

  // Print responses from actions, if any. Supports only text responses.
  if (result.output.generic) {
    if (result.output.generic.length > 0) {
      result.output.generic.forEach( response => {
        if (response.response_type === 'text') {
          console.log(response.text);
        }  
      });
    }
  }

  // Prompt for the next round of input unless skip_user_input is true.
  let newMessageFromUser = '';
  if (result.context.global.system.skip_user_input !== true) {
    newMessageFromUser = prompt('>> ');
  }

  if (newMessageFromUser !== 'quit') {
    newMessageInput = {
      messageType: 'text',
      text: newMessageFromUser,
    }
    sendMessage(newMessageInput);
  }
}

# Example 2: Adds user input.

from ibm_watson import AssistantV2
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

# Create Assistant service object.
authenticator = IAMAuthenticator('{apikey}') # replace with API key
assistant = AssistantV2(
    version = '2021-11-27',
    authenticator = authenticator
)
assistant.set_service_url('{url}') # replace with service instance URL
assistant_id = '{environment_id}' # replace with environment ID

# Initialize with empty value to start the conversation.
message_input = {
    'message_type:': 'text',
    'text': ''
    }

context = None

# Main input/output loop
while message_input['text'] != 'quit':

    # Send message to assistant.
    result = assistant.message_stateless(
        assistant_id,
        input = message_input,
        context=context
    ).get_result()
    context = response['context']

    # Print responses from actions, if any. Supports only text responses.
    if result['output']['generic']:
        for response in result['output']['generic']:
            if response['response_type'] == 'text':
                print(response['text'])

    # Prompt for the next round of input unless skip_user_input is True.
    if not result['context']['global']['system'].get('skip_user_input', False):
        user_input = input('>> ')
        message_input = {
            'text': user_input
        }

Diese Version der Anwendung beginnt wie die vorherige mit dem Senden einer leeren Nachricht an den Assistenten, um den Dialog zu starten.

Die Funktion processResult() zeigt den Text aller Antworten an, die vom Assistenten empfangen werden. Anschließend wird die nächste Runde der Benutzereingabe angefordert.

Anschließend wird der Text aller Antworten angezeigt, die vom Assistenten empfangen werden, und es wird zur Eingabe der nächsten Benutzereingabe aufgefordert.

Im Beispiel wird nach der globalen Kontextvariablen skip_user_input gesucht und nur dann zur Benutzereingabe aufgefordert, wenn diese Variable nicht auf true Truegesetzt ist. Die Variable skip_user_input wird vom Assistenten in einigen Situationen festgelegt, in denen keine Benutzereingabe erforderlich ist (z. B. wenn der Assistent einen externen Service aufgerufen hat, aber weiterhin auf das Ergebnis wartet). Es hat sich bewährt, diese Prüfung immer vorzunehmen, bevor Sie zur Eingabe von Benutzereingaben auffordern.

Da wir eine Möglichkeit zum Beenden des Dialogs benötigen, überwacht die Client-App auch den Literalbefehl quit, um anzugeben, dass das Programm beendet werden soll.

Aber etwas stimmt immer noch nicht:

Welcome to the watsonx Assistant example. What's your name?
>> Robert
I'm afraid I don't understand. Please rephrase your question.
>> I want to make an appointment.
What day would you like to come in?
>> Thursday
I'm afraid I don't understand. Please rephrase your question.
>>

Der Assistent beginnt mit der richtigen Begrüßung, aber er versteht nicht, wenn Sie ihm Ihren Namen mitteilen. Und wenn Sie ihm sagen, dass Sie einen Termin vereinbaren möchten, wird die richtige Aktion ausgelöst; aber auch hier versteht es nicht, wenn Sie die Folgefrage beantworten.

Der Grund dafür ist, dass wir die zustandslose Methode message verwenden, was bedeutet, dass es in der Verantwortung unserer Client-Anwendung liegt, die Zustandsinformationen für die Konversation zu erhalten. Da wir noch nichts tun, um den Zustand zu erhalten, sieht der Assistent jede Benutzereingabe als erste Runde einer neuen Unterhaltung an. Da es keine Erinnerung hat, eine Frage zu stellen, versucht es, Ihre Antwort als neue Frage oder Anfrage zu interpretieren.

Status verwalten

Die Statusinformationen für Ihr Gespräch werden über den Kontext gepflegt. Der Kontext ist ein Objekt, das zwischen Ihrer Anwendung und dem Assistenten hin- und hergereicht wird und Informationen speichert, die im Laufe der Konversation erhalten und aktualisiert werden können. Da die statusunabhängige message-Methode verwendet wird, speichert der Assistent den Kontext nicht. Daher liegt es in der Verantwortung der Clientanwendung, den Kontext von einem Turnus des Dialogs bis zum nächsten zu verwalten.

Der Kontext enthält eine Sitzungs-ID für jede Konversation und einen Zähler, der bei jeder Runde der Konversation inkrementiert wird. Der Assistent aktualisiert den Kontext und gibt ihn mit jeder Antwort zurück. Aber unsere vorherige Version des Beispiels hat den Kontext nicht beibehalten, daher gingen diese Aktualisierungen verloren und jede Eingaberunde schien der Anfang einer neuen Konversation zu sein. Wir können dies beheben, indem wir den Kontext speichern und ihn jedes Mal an den Assistenten zurücksenden.

Der Kontext kann nicht nur unseren Platz in der Konversation beibehalten, sondern auch Aktionsvariablen enthalten, die andere Daten speichern, die Sie zwischen Ihrer Anwendung und dem Assistenten hin- und herleiten möchten. Sie können z. B. dauerhafte Daten einfügen, die Sie während der gesamten Konversation beibehalten möchten (z. B. den Namen oder die Kontonummer eines Kunden), oder andere Daten, die Sie verfolgen möchten (z. B. den Inhalt eines Warenkorbs oder die Präferenzen des Benutzers).

// Example 3: Preserves context to maintain state.

const prompt = require('prompt-sync')();
const AssistantV2 = require('ibm-watson/assistant/v2');
const { IamAuthenticator } = require('ibm-watson/auth');

// Create Assistant service object.
const assistant = new AssistantV2({
  version: '2021-11-27',
  authenticator: new IamAuthenticator({
    apikey: '{apikey}', // replace with API key
  }),
  url: '{url}', // replace with URL
});

const assistantId = '{environment_id}'; // replace with environment ID

// Start conversation with empty message
messageInput = {
  messageType: 'text',
  text: '',
};
context = {};
sendMessage(messageInput);

// Send message to assistant.
function sendMessage(messageInput, context) {
  assistant
    .messageStateless({
      assistantId,
      input: messageInput,
      context: context,
    })
    .then(res => {
      processResult(res.result);
    })
    .catch(err => {
      console.log(err); // something went wrong
    });
}

// Process the result.
function processResult(result) {

  let context = result.context;

  // Print responses from actions, if any. Supports only text responses.
  if (result.output.generic) {
    if (result.output.generic.length > 0) {
      result.output.generic.forEach( response => {
        if (response.response_type === 'text') {
          console.log(response.text);
        }  
      });
    }
  }

  // Prompt for the next round of input unless skip_user_input is true.
  let newMessageFromUser = '';
  if (result.context.global.system.skip_user_input !== true) {
    newMessageFromUser = prompt('>> ');
  }

  if (newMessageFromUser !== 'quit') {
    newMessageInput = {
      messageType: 'text',
      text: newMessageFromUser,
    }
    sendMessage(newMessageInput, context);
  }
}

# Example 3: Preserves context to maintain state.

from ibm_watson import AssistantV2
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

# Create Assistant service object.
authenticator = IAMAuthenticator('{apikey}') # replace with API key
assistant = AssistantV2(
    version = '2021-11-27',
    authenticator = authenticator
)
assistant.set_service_url('{url}') # replace with service instance URL
assistant_id = '{environment_id}' # replace with environment ID

# Initialize with empty message to start the conversation.
message_input = {
    'message_type:': 'text',
    'text': ''
    }
context = {}

# Initialize with empty message to start the conversation.
message_input = {
    'message_type:': 'text',
    'text': ''
    }
context = {}

# Main input/output loop
while message_input['text'] != 'quit':

    # Send message to assistant.
    result = assistant.message_stateless(
        assistant_id,
        input = message_input,
        context = context
    ).get_result()

    context = result['context']

    # Print responses from actions, if any. Supports only text responses.
    if result['output']['generic']:
        for response in result['output']['generic']:
            if response['response_type'] == 'text':
                print(response['text'])

    # Prompt for the next round of input unless skip_user_input is True.
    if not result['context']['global']['system'].get('skip_user_input', False):
        user_input = input('>> ')
        message_input = {
            'text': user_input
        }

Die einzige Änderung gegenüber dem vorherigen Beispiel besteht darin, dass wir jetzt den vom Assistenten empfangenen Kontext in einer Variablen mit der Bezeichnung context speichern und ihn bei der nächsten Benutzereingabe zurücksenden:

Die einzige Änderung gegenüber dem vorherigen Beispiel besteht darin, dass wir jetzt den vom Assistenten empfangenen Kontext in einer Variablen mit der Bezeichnung context speichern und ihn bei der nächsten Benutzereingabe zurücksenden:

  assistant
    .messageStateless({
      assistantId,
      input: messageInput,
      context: context,
    })

response = assistant.message_stateless(
    assistant_id,
    input = message_input,
    context = context
).get_result()

Dies stellt sicher, dass der Kontext von einer Runde zur nächsten verwaltet wird, weshalb der Service 'watsonx Assistant' nicht mehr bei jeder Runde davon ausgeht, dass es sich um die erste Runde handelt:

Welcome to the watsonx Assistant example. What's your name?
>> Robert
Hi, Robert! How can I help you?
>> I want to make an appointment.
What day would you like to come in?
>> Next Monday
What time works for you?
>> 10 AM
OK, Robert. You have an appointment for 10:00 AM on Sep 12. See you then!

Erfolgreich! Die Anwendung verwendet jetzt den Service watsonx Assistant, um Eingaben in natürlicher Sprache zu verstehen, und zeigt die entsprechenden Antworten an.

Dieses einfache Beispiel veranschaulicht, wie Sie eine angepasste Client-App für die Kommunikation mit dem Assistenten erstellen können. Eine reale Anwendung verwendet eine ausgereiftere Benutzerschnittstelle und kann mit anderen Anwendungen, z. B. einer Kundendatenbank oder anderen Geschäftssystemen, integriert werden. Außerdem müssten mehr Daten an den Assistenten gesendet werden, z. B. eine Benutzer-ID, um jeden einzelnen Benutzer zu identifizieren. Aber die Grundprinzipien für die Interaktion der Anwendung mit dem Service 'watsonx Assistant' bleiben dieselben.

Fragen klären

Wenn Ihr Assistent feststellt, dass mehrere Aktionen die Anforderung eines Kunden erfüllen können, kann er automatisch eine Klärung anfordern. Weitere Informationen finden Sie unter Fragen klären.

Um klärende Fragen in Ihren angepassten Client aufzunehmen, müssen Sie folgende Schritte ausführen:

• Optionen für Klärungsvorschläge anzeigen, die von der message-API zurückgegeben werden
• Rufen Sie die message-API in der nächsten Runde mit Nutzdaten auf, die der Vorschlagsoption entsprechen, die ein Kunde zur Beantwortung der klärenden Frage ausgewählt hat. Wenn Sie den Aufruf nicht implementieren, funktionieren autolearning und nicht erkannte Anforderungen zum Abrufen von Aktionsempfehlungen verwenden nicht ordnungsgemäß.

Jeder Klärungsvorschlag enthält Folgendes:

• Eine Bezeichnung, die dem Kunden angezeigt wird
• Ein Wert, der die Eingabe angibt, die an den Assistenten gesendet wird, wenn der Benutzer den entsprechenden Vorschlag auswählt

Gehen Sie wie folgt vor, um Klärungsvorschläge in Ihrer Anwendung zu implementieren:

1. Verwenden Sie das Objekt value.input aus dem ausgewählten Vorschlag als nächste Runde der Nachrichteneingabe, anstatt ein neues Eingabeobjekt zu erstellen. Der Assistent antwortet dann, indem er die Aktion auslöst, die der Vorschlagsoption zum Starten zugeordnet ist.

2. Überprüfen Sie mithilfe Ihres angepassten Clients auf der Seite Analysieren, ob Sie dies ordnungsgemäß implementiert haben. Geben Sie eine Eingabe ein, die eine Klärung auslöst, und klicken Sie dann auf die Option Keine der oben genannten Optionen. Wenn Sie die Anforderung in Dialoge anzeigen, stellen Sie sicher, dass die Benutzeranforderung, die die Klärung eingeleitet hat, mit Nicht erkannt markiert ist, was darauf hinweist, dass Ihr Client die Klärungseingabe ordnungsgemäß an Ihren Assistenten sendet.

Verwendung der v1-Laufzeit-API

Die API der Version 2 ist die empfohlene Methode zum Erstellen einer Laufzeitclientanwendung, die mit dem watsonx Assistant-Service kommuniziert. Einige ältere Anwendungen verwenden jedoch möglicherweise weiterhin die v1-Laufzeit-API, die eine ähnliche Methode zum Senden von Nachrichten an den Arbeitsbereich innerhalb eines Dialogskills enthält. Wenn Ihre Anwendung die v1 Laufzeit-API verwendet, kommuniziert sie direkt mit dem Arbeitsbereich und umgeht die Fähigkeiten des Assistenten zur Orchestrierung und Statusverwaltung.

Weitere Informationen über die Methode v1 /message und den Kontext finden Sie in der API-Referenz v1.