Create and Manage a Smart Snippets Model

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

Prerequisites

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

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

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>The Coveo Smart Snippets feature provides 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 the Coveo ML Smart Snippets feature doesn’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.

  • If your web page doesn’t contain Google structured data, and the questions contained in 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.

In a given item, the 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>

  • <ul>

  • <li>

  • <p>

  • <b>

  • <i>

  • <em>

  • <span>

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 Snippets 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 parameter when updating the model configuration through the Update the information of a model operation of the Machine Learning API.

CSS Properties to Exclude

When configuring a Coveo ML Smart Snippets 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 the Search Interface for more information about configuration using the Coveo JavaScript Search Framework and Coveo Headless Library.

Create a Smart Snippets Model

  1. On the Models page, in the upper-right corner, click Add Model to open the Add a Machine Learning Model panel.

  2. Under Name, enter a meaningful display name for the model.

  3. Under Model type, select Smart Snippets, and then click Next.

  4. In the Learn from section, in the drop-down menu, select the sources that contain the items from which you want the model to extract relevant snippets of content.

    A Coveo ML Smart Snippets model returns snippets of content for HTML items only.

  5. Click Next.

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

      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 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 drop-down menu, select the fields containing the content that the model must use.

      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 drop-down menu so that the model uses only the content that appears in the sf_case_details_c field when extracting the document.

  7. (Optional) You can specify additional document types and content fields by clicking plus button and selecting the desired values in the Document type is and Field(s) containing HTML content drop-down menus.

  8. Click Next.

  9. (Optional) In the List the CSS properties to exclude section, you can specify CSS selectors to exclude from the model learning process.

  10. Click Next.

  11. In the Summary section, review your Coveo ML Smart Snippets model configuration.

  12. Click Add model.

  13. 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.

Delete a Smart Snippets 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.

  1. On the Models page, click the ML model that you want to delete.

  2. In the Action bar, click More, and then click Delete.

  3. In the Delete a Model panel that appears, click Delete model.

Review Active Model Information

On the Models page, click the desired model (must be Active), and then in the Action bar, click Open (see Reviewing Coveo Machine Learning Model Information).

Reference

"Status" Column

On the Models 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.

status column

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 Coveo Machine Learning 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 Coveo Machine Learning Model Information).
Update failed The model couldn't be updated with the requested configuration.
Error An error prevented the model from being built successfully.

Required Privileges

By default, members of the Administrators built-in group can manage Coveo ML CC models.

The following table indicates the privileges required to manage Coveo CC models (see Manage Privileges and Privilege Reference).

Action Service - Domain Required access level

View models

Machine Learning - Models

Search - Query pipelines

View

Manage models

At least one of the following privileges:

  • Machine Learning - Allow content preview

  • Search - View all content

Enable / Allowed

Machine Learning - Models

Edit

Search - Query pipelines

View

What's Next for Me?