Smart Snippets deployment overview
Smart Snippets deployment overview
To provide relevant snippets of content in a search results list, Coveo Machine Learning (Coveo ML) Smart Snippets models require the content they use to be formatted in a certain way. This article provides best practices for properly scoping, formatting, and testing the content you want the model to use.
Step 1: Scope the content
To optimize the output of a Coveo ML Smart Snippet model, we strongly recommend that you first identify the content that the model must use. This will help you better understand how to configure the model.
Item language value
Coveo Smart Snippet models return snippets of content only for items whose language
field value is English
.
HTML content
Coveo Smart Snippet models only return snippets of content for items that contain content in HTML format. Therefore, you should ensure that the content that you want to use for creating the model contains HTML elements.
Leading practice
You can use the Content Browser (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console to verify the items that are available for the model. For example, you select the My Source source and HTML File file type to find the items from the My Source source that can be used as input by the model. |
When checking the items that could be usable by the model in the Content Browser (platform-ca | platform-eu | platform-au), the number of items that match your requirements may differ from the number of items you’ll see when inspecting the Item count section of your model’s model building statistics. During the build process, the model can ignore some items because they either contain invalid HTML, or no snippets could be extracted from the parsed HTML. |
permanentid field
The items from which you want the model to extract snippets must use the value of the permanentid
field as their unique identifier.
Leading practice
You can use the Content Browser (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console and check an item’s proprieties to verify whether an item uses the |
Document types
When you inspect the items that the model can use (that is, items containing the required HTML tags in a given source), you may notice that many of these items are available, but not all of them are relevant for the model.
When configuring a Coveo ML Smart Snippet model, you can optionally target certain document types that must be used by the model. This allows you to further narrow the content that the model will use as an input.
The content you want the model to extract resides in a Salesforce source. This content is available in items whose documenttype
has the Knowledge
value. Therefore, you select Knowledge
in the Document type dropdown menu so that the model uses only items whose documenttype
field value is Knowledge
.
In the Content Browser (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console, you can verify the items that would be available for the model by scoping the items that have the Knowledge
value for the documenttype
field. For example, you can use a field query to scope the documents as follows:
Content fields
When you inspect the items that the model can use (that is, items of a specific document type containing the required HTML tags in a given source), you may notice that these items contain multiple fields that embed HTML content. The content of some of these fields may not be relevant and you may not want the model to use it.
When configuring a Coveo ML Smart Snippet model, you can optionally target certain fields to be used by the model.
This allows you to further narrow the content that the model will use as an input.
If you don’t mention specific fields, the model will use the value of the item body
field by default.
The content you want the model to extract resides in a Salesforce source. The relevant information, formatted in HTML, is located in a custom field named sf_case_details_c
.
Therefore, you select the sf_case_details_c
field in the Field(s) containing HTML content dropdown menu so that the model uses only the content that appears in the sf_case_details_c
field when extracting the document.
In the Content Browser (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console, you can verify the items that contain the sf_case_details_c
field.
For example, you can use a field query to scope items of the My Salesforce Source source whose documenttype
value is Knowledge
and that contains the sf_case_details_c
field as follows:
Step 2: Optimize the content
Now that you’ve targeted the content that must be used by the model, you must ensure that this content is properly configured.
Coveo ML Smart Snippets establish correlations between the headers appearing in result items and user queries. Therefore, your content must be configured accordingly.
For optimal results, we recommend that you use Google structured data in JSON-LD format in the <head>
of the HTML items that must be used by the model to extract snippets.
The following code sample shows a simple HTML markup that contains JSON-LD formatted content within the <head>
:
<html>
<head>
<title>Example Site - Frequently Asked Questions(FAQ)</title>
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity":[{
"@type": "Question",
"name": "What is Smart Snippets?",
"acceptedAnswer": {
"@type": "Answer",
"text": "<p>Coveo Smart Snippet models provide users with answers to their queries directly on the results page by displaying a snippet of the most relevant result item. This allows users to quickly find answers without having to open links from the results page.</p>"]
}
</script>
</head>
<body>
</body>
</html>
However, Coveo ML Smart Snippets will also work with raw HTML. When using this approach, it must be noted that Coveo ML Smart Snippet models don’t exclude navigation menus, featured content, or any other peripheral content in an item. To help the algorithm identify this type of content, you should specify CSS properties to exclude.
Notes
|
HTML supported tags
In an item, a Smart Snippet model takes the content that appears within the following tags into consideration when they’re attached to the last header (<h>
tag) in a header stack:
-
<br>
-
<ol>
NoteSmart Snippet models support the
start
attribute in<ol>
tags -
<ul>
-
<li>
-
<p>
-
<b>
-
<i>
-
<em>
-
<span>
-
<a>
Notes-
For a snippet to correctly render the hyperlink, the URL value used in the
href
attribute must be absolute and use a secure scheme (that is,https://
). -
When a user clicks an inline link displayed on a snippet, the
openSmartSnippetInlineLink
click event is logged. This can be useful to report on the usage of links dipslayed in snippets.
-
Considering a page that is configured as follows:
<body>
<h1>FAQ</h1>
<h2>Synchronizing Speedbit Watches</h2>
<p>The procedure differs depending on the device with which you want to synchronize your watch.</p>
<h3>Synchronizing a Speedbit Watch With a Smartphone</h3>
<p>Procedure to synchronize your Speedbit watch with your smartphone.</p>
<h3>Synchronizing a Speedbit Watch With a Computer</h3>
<p>Procedure to synchronize your Speedbit watch with your computer.</p>
</body>
The model would process the page as follows:
[
{"headers": ["FAQ", "Synchronizing Speedbit Watches", "Synchronizing a Speedbit Watch With a Smartphone"], "excerpt": "<p>Procedure to synchronize your Speedbit watch with your smartphone.</p>"},
{"headers": ["FAQ", "Synchronizing Speedbit Watches", "Synchronizing a Speedbit Watch With a Computer"], "excerpt": "<p>Procedure to synchronize your Speedbit watch with your computer.</p>"}
]
|
Step 3: Create the model
Now that you have scoped the content that must be used by the model and your content is properly formatted, you can create your Coveo ML Smart Snippet model and configure it as desired.
See Create a Smart Snippet model for instructions on how to create a Coveo ML Smart Snippet model.
Review the model build information
Now that your model is created and is Active, you can verify whether the model is able to provide snippets of content.
The Get detailed information about a specific model call of the Machine Learning Models API allows you to obtain detailed information about your Coveo ML Smart Snippet model, such as:
-
The number of items it can use to extract snippets of content.
-
The number of HTML headers it can target to find related content.
-
The average length of the snippets it extracted.
-
The total number of snippets that the model can provide.
When performing this API call, you should receive a response that contains a modelBuildingStats
object as follows:
"modelBuildingStats": {
"documentCount": 2688,
"headerCount": 11239,
"meanSnippetLength": 104.94903911094738,
"snippetCount": 16287
}
Step 4: Associate the model with the desired query pipeline
Now that your model is created, you must associate the model with the query pipeline to which the traffic of the desired search interface is directed.
See Associate a Smart Snippet model with a query pipeline for instructions on how to associate your model with a query pipeline.
Step 5: Configure the search interface
Now that your model is configured, and associated with the query pipeline to which the traffic of the desired search interface is directed, you must configure the search interface to include the components that will allow the model to render its output.
See Configure a search interface for Smart Snippets for instructions.
Step 6: Test the model
Now that your model is configured and your search interface is set up to display the model’s output, you can test the model to ensure that everything works as expected.
You can test the model on a search interface that contains the required components, and for which the traffic is directed to the query pipeline that you associated with your Coveo ML Smart Snippet model.
Perform a query that would likely trigger a snippet to appear in the search results.
You scope an item for your model from which to extract snippets.
It contains a header that reads When exactly is a model retrained?
.
When you perform the query When is a model retrained
, you see the following:
You can also inspect the request to the Search API to get detailed information about the model’s output for a given query.
-
Access a search interface which contains the required components, and in which the traffic is directed to the query pipeline that you associated with your Coveo ML Smart Snippet model.
-
In the search box, perform a query that would likely trigger a snippet to appear in the search results.
-
In the network monitoring tool, under the Name column, select the latest request to the Search API. The request path should contain
/rest/search/v2
. -
Select the Preview tab.
-
Find and expand the
questionAnswer
property. It provides detailed information about the model’s output for this specific query. This property won’t appear if the model can’t provide snippets for the current query.
Access your browser’s network monitoring tool
-
Open your web browser’s developer tools.
NoteThe examples in this article use the Google Chrome developer tools. For browser-specific information, see:
-
Select the Network tab.
Search API response reference
This section provides reference information about the response provided by the Search API for the questionAnswer
property.
The following snippet displays a Search API response when snippets are found. As you can see, the response is divided into two sections. One listing information about the main snippet, and another listing information about the related questions:
{
"questionAnswer": {
"answerFound": "boolean",
"question": "string",
"answerSnippet": "string",
"documentId": {
"contentIdKey": "string",
"contentIdValue": "string"
},
"score": "int32",
"relatedQuestions": [
{
"question": "string",
"answerSnippet": "string",
"documentId": {
"contentIdKey": "string",
"contentIdValue": "string"
},
"score": "int32"
}
]
}
}
answerFound
(boolean)
Whether snippets were found for the query.
This property evaluates to |
Main snippet
question
(string)
The text representing the header attached to the content of the main snippet.
answerSnippet
(string)
The text corresponding to the main snippet.
documentId
(object)
The contentIdKey
and contentIdValue
of the item containing the main snippet.
contentIdKey
(string)
The content identifier key.
Typically, permanentid
or urihash
.
contentIdValue
(string)
The content identifier value.
score
(integer [int32])
The relevance score computed for the main snippet based on the query.
Related questions
relatedQuestions
(object)
An object representing the information available for each related question listed for the query.
question
(string)
The header attached to the content of the related question.
answerSnippet
(string)
The text corresponding to the answer of the corresponding related question.
documentId
(object)
The contentIdKey
and contentIdValue
of the item containing the related question.
contentIdKey
(string)
The content identifier key.
Typically, permanentid
or urihash
.
contentIdValue
(string)
The content identifier value.
score
(integer [int32])
The relevance score computed for the related question based on the query.