Abrufen einer Antwort mit der GenerateAnswer-API und MetadatenGet an answer with the GenerateAnswer API and metadata

Um die vorhergesagte Antwort auf die Frage eines Benutzers zu erhalten, verwenden Sie die GenerateAnswer-API.To get the predicted answer to a user's question, use the GenerateAnswer API. Wenn Sie eine Wissensdatenbank veröffentlichen, werden Informationen zur Verwendung dieser API auf der Seite Veröffentlichen angezeigt.When you publish a knowledge base, you can see information about how to use this API on the Publish page. Sie können die API auch so konfigurieren, dass sie Antworten anhand von Metadatentags filtert, und Sie können die Wissensdatenbank vom Endpunkt aus mit dem Testabfrage-Zeichenfolgenparameter testen.You can also configure the API to filter answers based on metadata tags, and test the knowledge base from the endpoint with the test query string parameter.

QnA Maker ermöglicht es Ihnen, Ihren Frage-Antwort-Paaren Metadaten in Form von Schlüssel-Wert-Paaren hinzuzufügen.QnA Maker lets you add metadata, in the form of key and value pairs, to your pairs of questions and answers. Mit diesen Informationen können Sie Ergebnisse nach Benutzerabfragen filtern und zusätzliche Informationen speichern, die in Folgekonversationen verwendet werden können.You can then use this information to filter results to user queries, and to store additional information that can be used in follow-up conversations. Weitere Informationen finden Sie unter Knowledge Base.For more information, see Knowledge base.

Speichern von Fragen und Antworten mit einer QnA-EntitätStore questions and answers with a QnA entity

Zunächst müssen Sie wissen, wie QnA Maker die Frage-Antwort-Daten speichert.It's important to understand how QnA Maker stores the question and answer data. Die folgende Abbildung zeigt eine QnA-Entität:The following illustration shows a QnA entity:

Illustration einer QnA-Entität

Jede QnA-Entität hat eine eindeutige und dauerhafte ID.Each QnA entity has a unique and persistent ID. Sie können die ID verwenden, um bestimmte QnA-Entitäten zu aktualisieren.You can use the ID to make updates to a particular QnA entity.

Abrufen von Antwortvorhersagen mit der GenerateAnswer-APIGet answer predictions with the GenerateAnswer API

Sie verwenden die GenerateAnswer-API in Ihrem Bot oder Ihrer Anwendung, um Ihre Wissensdatenbank mit einer Benutzerfrage abzufragen und die beste Übereinstimmung aus den Frage-Antwort-Paaren zu erhalten.You use the GenerateAnswer API in your bot or application to query your knowledge base with a user question, to get the best match from the question and answer pairs.

Veröffentlichen am GenerateAnswer-EndpunktPublish to get GenerateAnswer endpoint

Nachdem Sie Ihre Wissensdatenbank im QnA Maker-Portal oder mithilfe der API veröffentlicht haben, können Sie die Details von Ihrem GenerateAnswer-Endpunkt abrufen.After you publish your knowledge base, either from the QnA Maker portal, or by using the API, you can get the details of your GenerateAnswer endpoint.

So rufen Sie Endpunktdetails abTo get your endpoint details:

  1. Melden Sie sich bei https://www.qnamaker.ai an.Sign in to https://www.qnamaker.ai.

  2. Klicken Sie in Meine Wissensdatenbanken für Ihre Wissensdatenbank auf Code anzeigen.In My knowledge bases, select View Code for your knowledge base. Screenshot von „Meine Wissensdatenbanken“Screenshot of My knowledge bases

  3. Rufen Sie Ihre GenerateAnswer-Endpunktdetails ab.Get your GenerateAnswer endpoint details.

    Screenshot der Endpunktdetails

Sie können Ihre Endpunktdetails auch auf der Registerkarte Einstellungen Ihrer Knowledge Base abrufen.You can also get your endpoint details from the Settings tab of your knowledge base.

GenerateAnswer-AnforderungskonfigurationGenerateAnswer request configuration

Sie rufen GenerateAnswer über eine HTTP POST-Anforderung auf.You call GenerateAnswer with an HTTP POST request. Beispielcode, der zeigt, wie GenerateAnswer aufgerufen wird, finden Sie unter Schnellstarts.For sample code that shows how to call GenerateAnswer, see the quickstarts.

Die POST-Anforderung verwendet:The POST request uses:

Die GenerateAnswer-URL weist das folgende Format auf:The GenerateAnswer URL has the following format:

https://{QnA-Maker-endpoint}/knowledgebases/{knowledge-base-ID}/generateAnswer

Denken Sie daran, die HTTP-Header-Eigenschaft von Authorization auf folgenden Wert festzulegen: die Zeichenfolge EndpointKey mit einem nachgestellten Leerzeichen, gefolgt von dem Endpunktschlüssel, der sich auf der Seite Einstellungen befindet.Remember to set the HTTP header property of Authorization with a value of the string EndpointKey with a trailing space then the endpoint key found on the Settings page.

Ein JSON-Beispieltext sieht folgendermaßen aus:An example JSON body looks like:

{
    "question": "qna maker and luis",
    "top": 6,
    "isTest": true,
    "scoreThreshold": 30,
    "rankerType": "" // values: QuestionOnly
    "strictFilters": [
    {
        "name": "category",
        "value": "api"
    }],
    "userId": "sd53lsY="
}

Weitere Informationen zu „rankerType“ finden Sie hier.Learn more about rankerType.

Der vorherige JSON-Code forderte nur Antworten an, die 30 % oder mehr über dem Schwellenwert liegen.The previous JSON requested only answers that are at 30% or above the threshold score.

GenerateAnswer-AntworteigenschaftenGenerateAnswer response properties

Die Antwort ist ein JSON-Objekt, das alle Informationen enthält, die Sie benötigen, um die Antwort sowie die nächste Reaktion in der Unterhaltung, falls verfügbar, anzuzeigen.The response is a JSON object including all the information you need to display the answer and the next turn in the conversation, if available.

{
    "answers": [
        {
            "score": 38.54820341616869,
            "Id": 20,
            "answer": "There is no direct integration of LUIS with QnA Maker. But, in your bot code, you can use LUIS and QnA Maker together. [View a sample bot](https://github.com/Microsoft/BotBuilder-CognitiveServices/tree/master/Node/samples/QnAMaker/QnAWithLUIS)",
            "source": "Custom Editorial",
            "questions": [
                "How can I integrate LUIS with QnA Maker?"
            ],
            "metadata": [
                {
                    "name": "category",
                    "value": "api"
                }
            ]
        }
    ]
}

Der vorherige JSON-Code gab eine Antwort mit dem Punktestand 38,5 % zurück.The previous JSON responded with an answer with a score of 38.5%.

Verwenden von QnA Maker mit einem Bot in C#Use QnA Maker with a bot in C#

Das Bot-Framework bietet mit der getAnswer-API Zugriff auf die Eigenschaften von QnA Maker:The bot framework provides access to the QnA Maker's properties with the getAnswer API:

using Microsoft.Bot.Builder.AI.QnA;
var metadata = new Microsoft.Bot.Builder.AI.QnA.Metadata();
var qnaOptions = new QnAMakerOptions();

metadata.Name = Constants.MetadataName.Intent;
metadata.Value = topIntent;
qnaOptions.StrictFilters = new Microsoft.Bot.Builder.AI.QnA.Metadata[] { metadata };
qnaOptions.Top = Constants.DefaultTop;
qnaOptions.ScoreThreshold = 0.3F;
var response = await _services.QnAServices[QnAMakerKey].GetAnswersAsync(turnContext, qnaOptions);

Der vorherige JSON-Code forderte nur Antworten an, die 30 % oder mehr über dem Schwellenwert liegen.The previous JSON requested only answers that are at 30% or above the threshold score.

Verwenden von QnA Maker mit einem Bot in Node.jsUse QnA Maker with a bot in Node.js

Das Bot-Framework bietet mit der getAnswer-API Zugriff auf die Eigenschaften von QnA Maker:The bot framework provides access to the QnA Maker's properties with the getAnswer API:

const { QnAMaker } = require('botbuilder-ai');
this.qnaMaker = new QnAMaker(endpoint);

// Default QnAMakerOptions
var qnaMakerOptions = {
    ScoreThreshold: 0.30,
    Top: 3
};
var qnaResults = await this.qnaMaker.getAnswers(stepContext.context, qnaMakerOptions);

Der vorherige JSON-Code forderte nur Antworten an, die 30 % oder mehr über dem Schwellenwert liegen.The previous JSON requested only answers that are at 30% or above the threshold score.

Verwenden von Metadaten zum Filtern von Antworten nach benutzerdefinierten MetadatentagsUse metadata to filter answers by custom metadata tags

Durch das Hinzufügen von Metadaten können Sie die Antworten nach diesen Metadatentags filtern.Adding metadata allows you to filter the answers by these metadata tags. Fügen Sie die Metadatenspalte aus dem Menü Ansichtsoptionen hinzu.Add the metadata column from the View Options menu. Fügen Sie Ihrer Wissensdatenbank Metadaten hinzu, indem Sie auf das Metadatensymbol + klicken, um ein Metadatenpaar hinzuzufügen.Add metadata to your knowledge base by selecting the metadata + icon to add a metadata pair. Dieses Paar besteht aus einem Schlüssel und einen Wert.This pair consists of one key and one value.

Screenshot: Hinzufügen von Metadaten

Filtern von Ergebnissen mit „strictFilters“ nach MetadatentagsFilter results with strictFilters for metadata tags

Betrachten Sie die Benutzerfrage „When does this hotel close?“ (Wann schließt dieses Hotel?); die Absicht zielt auf das Restaurant „Paradise“ ab.Consider the user question "When does this hotel close?", where the intent is implied for the restaurant "Paradise."

Da nur Ergebnisse für das Restaurant „Paradise“ erforderlich sind, können Sie im GenerateAnswer-Aufruf einen Filter für die Metadaten zum Restaurantnamen festlegen.Because results are required only for the restaurant "Paradise", you can set a filter in the GenerateAnswer call on the metadata "Restaurant Name". Dies wird im folgenden Beispiel veranschaulicht:The following example shows this:

{
    "question": "When does this hotel close?",
    "top": 1,
    "strictFilters": [
      {
        "name": "restaurant",
        "value": "paradise"
      }]
}

Verwenden von Frage und Antwortergebnis zum Beibehalten des UnterhaltungskontextsUse question and answer results to keep conversation context

Die Antwort auf den GenerateAnswer-Aufruf enthält die entsprechenden Metadateninformationen des übereinstimmenden Frage-Antwort-Paars.The response to the GenerateAnswer contains the corresponding metadata information of the matched question and answer pair. Sie können diese Informationen in Ihrer Clientanwendung verwenden, um den Kontext der vorherigen Unterhaltung für die Verwendung in späteren Unterhaltungen zu speichern.You can use this information in your client application to store the context of the previous conversation for use in later conversations.

{
    "answers": [
        {
            "questions": [
                "What is the closing time?"
            ],
            "answer": "10.30 PM",
            "score": 100,
            "id": 1,
            "source": "Editorial",
            "metadata": [
                {
                    "name": "restaurant",
                    "value": "paradise"
                },
                {
                    "name": "location",
                    "value": "secunderabad"
                }
            ]
        }
    ]
}

Nur Fragen nach Textübereinstimmungen durchsuchenMatch questions only, by text

Standardmäßig durchsucht QnA Maker Fragen und Antworten.By default, QnA Maker searches through questions and answers. Wenn Sie nur Fragen durchsuchen möchten, um eine Antwort zu generieren, verwenden Sie RankerType=QuestionOnly im POST-Text der GenerateAnswer-Anforderung.If you want to search through questions only, to generate an answer, use the RankerType=QuestionOnly in the POST body of the GenerateAnswer request.

Sie können mit isTest=false die veröffentlichte Wissensdatenbank oder mit isTest=true die Testwissensdatenbank durchsuchen.You can search through the published kb, using isTest=false, or in the test kb using isTest=true.

{
  "question": "Hi",
  "top": 30,
  "isTest": true,
  "RankerType":"QuestionOnly"
}

Häufige HTTP-FehlerCommon HTTP errors

CodeCode ErklärungExplanation
2xx2xx ErfolgSuccess
400400 Die Parameter der Anforderung sind fehlerhaft, da die erforderlichen Parameter nicht vorhanden, falsch formatiert oder zu groß sindRequest's parameters are incorrect meaning the required parameters are missing, malformed, or too large
400400 Der Text der Anforderung ist fehlerhaft, da der JSON-Code nicht vorhanden, falsch formatiert oder zu groß istRequest's body is incorrect meaning the JSON is missing, malformed, or too large
401401 Ungültiger SchlüsselInvalid key
403403 Verboten – Sie verfügen nicht über die richtigen BerechtigungenForbidden - you do not have correct permissions
404404 KB nicht vorhandenKB doesn't exist
410410 Diese API ist veraltet und nicht mehr verfügbar.This API is deprecated and is no longer available

Nächste SchritteNext steps

Die Seite Veröffentlichen enthält auch Informationen zum Generieren einer Antwort mit Postman oder cURL.The Publish page also provides information to generate an answer with Postman or cURL.