Create and manage a Smart Snippet model

This is for:

In this article

Prerequisites
Create a Smart Snippet model
Delete a Smart Snippet model
Review active model information
Reference

Coveo Machine Learning (Coveo ML) Smart Snippet models provide users with answers to their queries by displaying a snippet of the most relevant result item directly on their results list.

Note

Coveo ML Smart Snippet models don’t learn from usage analytics events to provide answers to user queries (see How Does Coveo ML Smart Snippets Work?).

Prerequisites

To take advantage of Coveo ML Smart Snippets, make sure that:

You have the required privileges to create Smart Snippet models.
The items you want the model to extract snippets from use the value of the permanentid field as their unique identifier.
The content you want the model to use is optimized.
The search interfaces in which you want to integrate the model are properly configured.

Note

If an item includes a multi-value field, the model learns only on the first value of the field. This is done to ensure accuracy. If an item includes a multi-value field, convert the field to a single-value field, and then rebuild the model. Otherwise, be aware that only the first value in a multi-value field is used for learning purposes.

Optimize the content

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

If your web page doesn’t contain Google structured data, and the questions contained on the web page aren’t formatted using HTML headers (<h> tags), you can use the pre-conversion IPE extension script to specify CSS selectors to identify questions and answers in an HTML item.
If the content you want the model to use resides in specific fields, and that this content isn’t properly configured to be optimally used by the model (e.g., the item doesn’t contain JSON-LD, or well-formatted HTML) you can use the post-conversion IPE extension script to specify fields whose content will be identified as questions and answers, and converted in JSON-LD format.

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>

Note

Smart 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 (i.e., 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.

Example

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>"}
]

Coveo ML Smart Snippets ignores the content that appears within the following tags:
- <script>
- <style>
- <form>
- <table>
- <img>
- <input>
By default, when a Coveo ML Smart Snippet model finds identical headers in both the JSON-LD and the HTML content, only those found in the JSON-LD are retained. This behavior can be changed by using the parsingMode advanced model JSON parameter.

CSS properties to exclude

When configuring a Coveo ML Smart Snippet model, you can specify CSS selectors to exclude from the model learning process. This means that content that appears within these elements won’t be considered by the algorithm when extracting snippets.

Example

In your support website, you have a common .navigation_bar CSS class used for the styling of your navigation bar. Since you don’t want the model to use this content for its learning process, you specify the .navigation_bar class to ignore content matching this selector.

Configure the search interface

Your search interface must be configured to leverage Coveo’s ML Smart Snippets. Refer to Configure a search interface for Smart Snippets for more information about configuration using the Coveo JavaScript Search Framework and Coveo Headless library.

Create a Smart Snippet model

Note

A Smart Snippet model can’t be edited once it’s created. Instead, you can create a new model with the required changes.

Depending on whether models have already been created in your Coveo organization:
- If your Coveo organization doesn’t contain any models, on the Models (platform-ca | platform-eu | platform-au) page, click the Smart Snippets card, and then click Create model.
- If your Coveo organization already contains models, on the Models (platform-ca | platform-eu | platform-au) page, click Add model, and then click the Smart Snippets card.
Under Name, enter a meaningful display name for the model, and then click Next.
In the Learn from section, in the dropdown menu, select the sources that contain the items from which you want the model to extract relevant snippets of content.

Note

If your Coveo organization includes multiple indexes, the model can learn only from sources that are linked to the default index.

A Coveo ML Smart Snippet model returns snippets of content for HTML items only.
(Optional) In the Apply additional filters section, you can specify a condition to segment the content on which the model should base its training.
Click Next.

(Optional) You can further refine the content that must be used by the model to extract snippets by scoping specific document types and content fields. By default, the model uses content from the body HTML of an item.

In the Document type is dropdown menu, select a document type such as Knowledge, Documentation, or WebPage that should be used to refine the index items that must be used by the model. When specifying a specific document type, items of other document types will be ignored by the model.

Example

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 is dropdown menu so that the model uses only items whose documenttype field value is Knowledge.

Leading practice

Click the Preview documents button to view the index items that are available for the model to extract snippets from. When clicking this button, the Content Browser (platform-ca | platform-eu | platform-au) page opens and contains a query that filters the content to display only the items that meet the requirements and selected filters (i.e., selected sources and document types).

In the Field(s) containing HTML content dropdown menu, select the fields containing the content that the model must use.

Note

Example

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.

(Optional) You can specify additional document types and content fields by clicking and selecting the desired values in the Document type is and Field(s) containing HTML content dropdown menus.
Click Next.
(Optional) In the List the CSS properties to exclude section, you can specify CSS selectors to exclude from the model learning process.
Click Next.
In the Summary section, review your Coveo ML Smart Snippet model configuration.
Click Add model.
You can then associate the model with a pipeline to take advantage of the model in a search interface.

Once the model has been created, you cannot modify its configuration. If necessary, however, you can modify its name.

If you have the Enterprise edition, group this Smart Snippet model and your other implementation resources together in a project. See Manage projects.

Delete a Smart Snippet model

You must dissociate a model from all its associated query pipelines before deleting it. Models aren’t automatically dissociated from pipelines when they’re deleted.

On the Models (platform-ca | platform-eu | platform-au) page, click the ML model that you want to delete, and then click More > Delete in the Action bar.
In the Delete a Model panel that appears, click Delete model.

Review active model information

On the Models (platform-ca | platform-eu | platform-au) page, click the desired model (must be Active), and then click Open in the Action bar (see Reviewing Coveo Machine Learning model information).

Reference

"Apply Additional Filters" section

In this section, you can optionally specify a condition to segment the content on which the model should base its training.

Example

You want the Coveo ML Smart Snippet model to base its training only on items for which the collection field have the FAQ value.

Therefore, in the Apply additional filters section, you enter collection is equal to FAQ.

To specify an additional filter

In the Apply additional filters section, click .
In the Add a Condition panel that opens, in the Field name input, enter the name of the field that you want to use to segment content.
In the Select an operator dropdown menu, select the desired operator.
In the Value input, enter the value of the field on which you want to segment the content.
Click Add filter.

"Status" column

On the Models (platform-ca | platform-eu | platform-au) page of the Administration Console, the Status column indicates the current state of your Coveo ML models.

When inspecting the Status column, a given model is either in the Active or Inactive state. Additional information can be displayed depending on the model’s current state.

The following table lists the possible model statuses, their definitions, and their status colors as shown in the Administration Console:

Status	Definition	Status color
Active	The model is active and available.
Inactive	The model isn’t available.
Update in queue	Waiting to process a scheduled update or configuration change.
Updating	The model is being rebuilt based on a new configuration.
Waiting	The model is in the building queue.
Building	The model is currently being processed.
Degraded	The model is active, but has some limitations. Additional information is available in the Error section of a model (see Review model information).
Failed	The model couldn’t be built with the requested configuration. Additional information is available in the Error section of a model (see Review model information).
Update failed	The model couldn’t be updated with the requested configuration.
Error	An error prevented the model from being built successfully.
Archived	The model was archived because it hasn’t been queried for at least 60 days. Learn more on archived models.

Status

Definition

Status color

Active

The model is active and available.

Inactive

The model isn’t available.

Update in queue

Waiting to process a scheduled update or configuration change.

Updating

The model is being rebuilt based on a new configuration.

Waiting

The model is in the building queue.

Building

The model is currently being processed.

Degraded

The model is active, but has some limitations. Additional information is available in the Error section of a model (see Review model information).

Failed

The model couldn’t be built with the requested configuration. Additional information is available in the Error section of a model (see Review model information).

Update failed

The model couldn’t be updated with the requested configuration.

Error

An error prevented the model from being built successfully.

Archived

The model was archived because it hasn’t been queried for at least 60 days.
Learn more on archived models.

Required privileges

By default, members with the required privileges can view and edit elements of the Models (platform-ca | platform-eu | platform-au) page.

The following table indicates the privileges required for members to manage Coveo Smart Snippets models (see Manage privileges and Privilege reference).

Action	Service - Domain	Required access level
View models	Machine Learning - Models Organization - Organization Search - Query pipelines	View
Manage models	Organization - Organization Search - Query pipelines	View
Machine Learning - Models	Edit
At least one of the following privileges: Machine Learning - Allow content preview Search - View all content	Enable / Allowed

Action

Service - Domain

Required access level

View models

Machine Learning - Models
Organization - Organization
Search - Query pipelines

View

Manage models

Organization - Organization
Search - Query pipelines

View

Machine Learning - Models

Edit

At least one of the following privileges:

Machine Learning - Allow content preview
Search - View all content

Enable / Allowed