Create and manage a Smart Snippet model

This is for:

Developer System Administrator

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:

Note

If an item includes a multi-value field, the model learns only on the first value of the field. If an item includes a multi-value field, change 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 (for example, 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 (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.
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>"}
]
Important

  • 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

  1. Depending on whether models have already been created in your Coveo organization:

  2. Click Next.

  3. In the Learn from section, select the content that the model will use. You can select the source(s) and apply additional filters using the Standard configuration, or use Advanced mode to define a custom filter expression.

    Important

    You’ll lose the current mode settings when you switch between Standard and Advanced mode.
    Tip

    The Data volume preview section shows the impact of your settings on the data that’s available to the model.

    • In the Standard tab:

      1. In the Sources 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.
        Important

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

      2. (Optional) In the Apply filters on dataset section, you can specify a condition to segment the content on which the model should base its training.

        Example

        You want the model to base its training only on items for which the collection field has the FAQ value.

        Therefore, you add a collection is equal to FAQ condition.

        1. Click Add filter(s).

        2. In the Field name input, enter the name of the field that you want to use to segment the dataset.

        3. In the Select an operator dropdown menu, select the desired operator.

        4. In the Value input, enter the value of the field on which you want to segment the dataset.

        5. Click Apply.

    • In the Advanced tab:

      1. Enter a custom filter expression using Coveo query syntax.

      2. Click Apply.

  4. Click Next.

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

    1. Click Add a content field.

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

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

      Note

      If an item includes a multi-value field, the model learns only on the first value of the field. If an item includes a multi-value field, change 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.
      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.

  6. Click Next.

  7. (Optional) In the CSS properties to exclude section, click Add a CSS selector to specify CSS selectors to exclude from the model learning process.

  8. Click Next.

  9. In the Name your model input, enter a meaningful display name for the model, and then click Start building.

  10. You can then associate the model with a pipeline to take advantage of the model in a search interface.

Edit a Smart Snippet model

  1. On the Models (platform-ca | platform-eu | platform-au) page, click the model you want to edit, and then click Edit in the Action bar.

  2. On the subpage that opens, select the Configuration tab.

  3. In the upper-right corner, click Edit.

  4. Under Name, edit the model’s display name.

  5. In the Learn from section, select the content that the model will use. You can select the source(s) and apply additional filters using the Standard configuration, or use Advanced mode to define a custom filter expression.

    Important

    You’ll lose the current mode settings when you switch between Standard and Advanced mode.
    Tip

    The Data volume preview section shows the impact of your settings on the data that’s available to the model.

    • In the Standard tab:

      1. In the Sources 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.
        Important

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

      2. (Optional) In the Apply filters on dataset section, you can specify a condition to segment the content on which the model should base its training.

        Example

        You want the model to base its training only on items for which the collection field has the FAQ value.

        Therefore, you add a collection is equal to FAQ condition.

        1. Click Add filter(s).

        2. In the Field name input, enter the name of the field that you want to use to segment the dataset.

        3. In the Select an operator dropdown menu, select the desired operator.

        4. In the Value input, enter the value of the field on which you want to segment the dataset.

        5. Click Apply.

    • In the Advanced tab:

      1. Enter a custom filter expression using Coveo query syntax.

      2. Click Apply.

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

    1. Click Add a content field.

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

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

      Note

      If an item includes a multi-value field, the model learns only on the first value of the field. If an item includes a multi-value field, change 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.
      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.

  7. (Optional) In the CSS properties to exclude section, click Add a CSS selector to specify CSS selectors to exclude from the model learning process.

  8. Click Save.

Tip

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

Important

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

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

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

The following table lists the possible model statuses and their definitions:

Status Definition Status icon

Active

The model is active and available.

check-circle

Build in progress

The model is currently building.

target16px

Inactive

The model isn’t ready to be queried, such as when a model was recently created or the organization is offline.
Click See more details for additional information (see Review model information).

warningtriangle

Limited

Build issues exist that may affect model performance.
Click See more details for additional information (see Review model information).

warningtriangle

No query pipeline

The model isn’t associated with a query pipeline.
Click Associate with a query pipeline to go to the Query Pipelines page.

warningtriangle

No case assist configuration

The model isn’t associated with a case assist configuration.
Click Associate with a case assist configuration to go to the Case Assist page.

warningtriangle

Soon to be archived

The model will soon be archived because it hasn’t been queried for an extended period of time.
Click Delete to remove the model.
Learn more about archived models.

warningtriangle

Error

An error prevented the model from being built successfully.
If it’s a temporary system error, check back soon. Otherwise, click See more details for additional information (see Review model information).

critical

Archived

The model was archived because it hasn’t been queried for at least 30 days.
Click Delete to remove the model.
Learn more about archived models.

n/a

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

Machine Learning - Allow content preview

Enable

Content - Sources

View All

Content - Fields

View