Learn about the integration of Semantic Search and Conversational Search in Oracle WebCenter Content.

Learn about the integration of Semantic Search in WebCenter Content (available on Marketplace) using Oracle Database 23ai. This database version introduces support for embedding generation within the database, enhancing contextual understanding for more accurate document search results. A Hybrid index is created in the database to support the semantic search.

Prerequisites

  1. WebCenter Content (on Marketplace) should be configured with Oracle Text Search (OTS).
  2. The Oracle Database configured with WebCenter Content must be version 23ai.

Enabling Smart Content Component

  1. Log in to WebCenter Content as an administrator.
  2. Navigate to Administration, Admin Server, Component Manager, and then Advanced Component Manager.
  3. Select the SmartContent component and click Enable.
  4. Restart the server once the component is enabled.
  1. Log in to WebCenter Content as an administrator.
  2. Navigate to Administration, Admin Server, and General Configuration.
  3. Add the following flags in the Additional Configuration Variables section.
IsDataBaseHybridSearchEnabled=True
SemanticSearchSupport=true
  1. Restart the server

Hybrid search feature flag

Configuration

1. Deploying Embedding model to the Database

ONNX (short for Open Neural Network Exchange) is an open-source format designed to represent deep learning models. It aims to provide interoperability between different deep learning frameworks, allowing models trained in one framework to be used in another without the need for extensive conversion or retraining.

  1. Generate the ONNX file using the Oracle OML4Py utility before deploying it to the database.
  2. Upload this file to the object storage. Once uploaded, if the ATPDB has access to the bucket, use the URL from the object details or create a pre-authenticated URL. ONNX model uploaded to object storage
  3. Log in to the ATP Database as an administrator or a user with administrative privileges.
  4. Give required privileges to the database user used for WebCenter Content. For example in this case DEV_OCS
GRANT DB_DEVELOPER_ROLE TO DEV_OCS;
GRANT CREATE MINING MODEL TO DEV_OCS;
CREATE DIRECTORY STAGING AS 'STAGE';
GRANT READ ON DIRECTORY STAGING TO DEV_OCS;
GRANT WRITE ON DIRECTORY STAGING TO DEV_OCS;
GRANT EXECUTE ON DBMS_CLOUD TO DEV_OCS;
  1. Switch the user to DEV_OCS
  2. Make sure to create required credentials first. Download the model from the object storage using the URL created earlier. In the case of pre-authenticated URL, credentials are not required.
BEGIN
  DBMS_CLOUD.GET_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-ashburn-1.oraclecloud.com/p/M2TafXIXNZLRSjD7kSWoGJphT9_Ry5ewlgGsAVyywvj7qcPuC4QXo1w5HP-BzGhr/n/axcmmdmzqtqb/b/ATPDB-bucket/o/paraphrase-multilingual-mpnet-base-v2.onnx%20paraphrase-multilingual-mpnet-base-v2.onnx',
     directory_name => 'staging',
     file_name => 'paraphrase-multilingual-mpnet-base-v2.onnx'
);
END;/
  1. Validate if the model is downloaded
SELECT * FROM TABLE(DBMS_CLOUD.LIST_FILES('staging'));
  1. Load the ONNX model
BEGIN
  DBMS_VECTOR.LOAD_ONNX_MODEL(
  'staging',
  'paraphrase-multilingual-mpnet-base-v2.onnx',
  'multilingual',
  json('{"function":"embedding","input":{"input":["DATA"]}}'));
END;/
  1. Validate if the model is loaded
SELECT MODEL_NAME, MINING_FUNCTION,
ALGORITHM, ALGORITHM_TYPE, round(MODEL_SIZE/1024/1024) MB FROM user_mining_models;
  1. Validate the model
SELECT TO_VECTOR(VECTOR_EMBEDDING( MULTILINGUAL USING 'Hello' as data)) AS embedding

2. Configuring the model to WebCenter Content

  1. Log in to WebCenter Content as an administrator.

  2. Navigate to Administration, SmartContent, and then Hybrid Search Configuration. Provide the following values in the configuration screen.

    Name Description
    EmbeddingModelName Name of the model loaded in the Database.
    Number of words per chunk A limit on the maximum size of each chunk. Chunking will be done based on number of words.
    Each model can have a different token limit. Text longer than the token limit will be truncated to fit within this limit by the model
    Overlap percentage per chunk Helps logically split related text (such as sentences) by including a portion of the preceding chunk’s text. Valid values range from 5% to 20% of the chunk’s word count.
    Parallelism Specify the degree of parallelism to use for Hybrid index creation.

3. Configuring Semantic Search properties

On the same page, configure the semantic search properties. These properties determine how search results are generated.

Name Description Comment
Aggregation Function Select a function to aggregate vector scores from different chunks within a document for ranking. The aggregator parameter specifies the function used to combine vector scores for each document. They offer flexibility in ranking documents based on vector scores, allowing you to choose the method that best aligns with your application’s requirements.Available options:
•AVG: Calculates the average vector score of all chunks in a document. This method provides a balanced view of the document’s overall relevance, considering the collective importance of its sections.
•MAX: Selects the highest vector score among all chunks within a document. This approach emphasizes the most relevant chunk, ensuring that a document with at least one highly pertinent section ranks higher.
•MEDIAN: Determines the median vector score from the document’s chunks. By focusing on the middle value, this function reduces the impact of outliers, offering a robust measure of central relevance.
•BONUSMAX: Similar to the MAX function but applies an additional weighting factor to the highest score. This function not only considers the top chunk but also boosts its influence, highlighting documents with exceptionally relevant sections.
•WINAVG: Computes a weighted moving average of the chunk scores. This method assigns varying weights to chunks, typically giving more importance to certain sections based on predefined criteria, resulting in a nuanced relevance assessment.
•ADJBOOST: Applies adjusted boosting to the chunk scores, enhancing the influence of specific chunks based on their characteristics. This function allows for customized ranking adjustments, tailoring the relevance scoring to specific needs.
•MAXAVGMED: Combines the MAX, AVG, and MEDIAN scores to produce a composite relevance score. This multifaceted approach ensures that the ranking considers various aspects of the document’s content, providing a comprehensive relevance assessment.
Threshold Score The minimum score required for a document to be considered a result for the search prompt. The threshold parameter sets a minimum vector similarity score that a document must meet to be included in the search results. This helps filter out less relevant documents by ensuring only those with a similarity score above the specified threshold are considered.

Configuration page

4. Hybrid index creation on existing documents

  1. Once the Index creation configuration is updated, a background process starts. It performs the following tasks:
    1. Validate the embedding model and other parameters provided by the user
    2. Create a database preference specifying the index type as IVF, model name, and text chunking by words.
    3. A table is created and a hybrid index is created using the above preference.
    4. Document metadata and extracted content is copied to the new table.
    5. Status of the hybrid index update will be monitored and updated.
  2. An alert banner is displayed until the hybrid index had processed all the existing assets Hybrid Index Build in Progress page
  3. Click on the alert banner to view Status of the hybrid index. Note, until the index build is complete, semantic search may show inconsistent results. Hybrid Index Build Status page
  4. User can cancel the index build by clicking on the Cancel index build. This stops the copy of the metadata and extracted content to the new table created but it cannot stop the database background processing of the index once the data copy is done.
  5. Once the hybrid index completes the processing of the assets, the banner is removed Hybrid Index Build Complete page

5. Cleanup of the hybrid index

To update the embedding model, the user can click on Clean Up Data and Hybrid Index in the configuration page. This action removes the existing hybrid index and associated data. The user can then specify the name of the new embedding model and update the configuration. The system will create new embeddings for existing documents using the updated model.

Performing a Semantic Search in Redwood UI

Follow these steps to perform a semantic search:

  1. Switch to AI Search

    • Navigate to the Redwood UI search page.
    • Click on the dropdown menu next to the search title.
    • Select AI Search from the available options.

REDWOOD UI SEARCH PAGE

  1. Enter a Natural Language Query

    • In the search bar, type a full sentence or question describing what you are looking for.
      Example: “What are the key document management capabilities provided by WebCenter Content?”
    • Press Enter to initiate the search.

    REDWOOD UI AI SEARCH LANDING PAGE

  2. The system will display documents that contain semantically similar content. Results are ranked by relevance to your query, ensuring the most relevant documents appear first.

    REDWOOD UI AI SEARCH RESULTS PAGE

Note

  1. Support for adding new metadata, full rebuild with text extraction will be added in the future

Conversational Search enables users to chat with documents stored in WebCenter Content using natural language queries. It supports interactive question-answering, document summarization, and context-aware responses, allowing users to extract relevant information from documents efficiently.

Prerequisites

  1. Complete the above sections on Semantic Search, which are common for Conversational Search as well. These include:

  1. We support OCI Generative AI as your AI provider. To use OCI Generative AI, your tenancy must be subscribed to a region that supports Generative AI. For a list of supported regions, refer to the Oracle Generative AI Documentation . Additionally, if you are using a non-default domain, you may need to enable region replication. Learn more in Replicating an Identity Domain to Multiple Regions.

  2. Set the required policies to obtain access to all Generative AI resources. See Getting Access to Generative AI to know more about Generative AI policies. If you’re new to policies, see Getting Started with Policies and Common Policies.

To get access to all Generative AI resources in the entire tenancy, use the following policy:

allow group <your-group-name> to manage generative-ai-family in tenancy

To get access to all Generative AI resources in your compartment, use the following policy:

allow group <your-group-name> to manage generative-ai-family in compartment <your-compartment-name>

or

allow any-user to manage generative-ai-family in compartment <your-compartment-name>

Note your-compartment-name refers to any compartment where you want to grant access. This could be: Any compartment in your tenancy, or A specific compartment that hosts your database or other related resources.

Configuration

  1. Log in to the ATP Database as an administrator or a user with administrative privileges.
  2. Give required privileges to the database user used for WebCenter Content. For example in this case DEV_OCS
GRANT DB_DEVELOPER_ROLE TO DEV_OCS;

GRANT EXECUTE ON DBMS_CLOUD_AI TO DEV_OCS;

  1. Grant connect privilege to the user for allowing connection to the host, using the DBMS_NETWORK_ACL_ADMIN procedure. This example uses * to allow any host. However, you can explicitly specify the host that you want to connect to.

    BEGIN
DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
host => '*',
ace => xs$ace_type(privilege_list => xs$name_list('connect'),
principal_name => 'DEV_OCS',
principal_type => xs_acl.ptype_db));
END;
/

  2. Set proxy if one exists

    EXEC UTL_HTTP.SET_PROXY('<proxy-hostname>:<proxy-port>');

  3. Switch the user to DEV_OCS to set up credentials to enable access to the OCI Generative AI REST provider. You use the credential helper procedures CREATE_CREDENTIAL and DROP_CREDENTIAL to securely manage credentials in the database. These procedures are available with both the DBMS_VECTOR and DBMS_VECTOR_CHAIN PL/SQL packages. Refer to this document for details.

Generative AI requires the following authentication parameters:

   { 
   "user_ocid"       : "<user_ocid>",
   "tenancy_ocid"    : "<tenancy_ocid>",
   "compartment_ocid": "<compartment_ocid>",
   "private_key"     : "<private_key>",
   "fingerprint"     : "<fingerprint>" 
   }

As a DEV_OCS user, execute the following command to create and store an OCI credential (OCI_CRED).The credential name will be used later when configuring Conversational Search properties.

declare
jo json_object_t;
begin
jo := json_object_t();
jo.put('user_ocid','<user_ocid>');
jo.put('tenancy_ocid','<tenancy_ocid>');
jo.put('private_key','<private_key>');
jo.put('fingerprint','<fingerprint>');
jo.put('compartment_ocid','<compartment_ocid>');
dbms_vector_chain.create_credential(
 credential_name   => 'OCI_CRED',
 params            => json(jo.to_string));
end;
/

Parameter Descriptions:

The created credential (OCI_CRED) can be validated using the following SQL statement.This query utilizes the DBMS_VECTOR_CHAIN.UTL_TO_GENERATE_TEXT function and should be executed as the DEV_OCS user. The provider URL depends on the region you are using. Below are examples for the US Chicago and UK London regions. For more details on supported regions, refer to the official documentation:

Provider URLs by Region:

If you are using a Dedicated AI Cluster, use the custom inference endpoint URL from the OCI console, located in the ‘Dedicated AI Clusters’ section under Generative AI.

The response from the LLM for the provided query will be displayed in the result.

SQL Query for Credential Validation:

SELECT dbms_vector_chain.utl_to_generate_text(
  'What is Oracle Text?',
  json('{
    "provider"       : "OCIGenAI",
    "credential_name": "OCI_CRED",
    "url"            : "https://inference.generativeai.uk-london-1.oci.oraclecloud.com/20231130/actions/chat",
    "model"          : "meta.llama-3.3-70b-instruct",
    "chatRequest"    : {
                        "maxTokens": 256
                       }
  }')
) AS generated_text FROM dual;

In case ,you receive error ORA-20002: The provider returned an error: The required information to complete authentication was not provided or was incorrect.,refer to the troubleshooting section for resolution.

Configuring Conversational Search Properties

  1. Log in to WebCenter Content as an administrator.
  2. Navigate to Administration, SmartContent, and then Hybrid Search Configuration. In the page displayed, configure conversational search properties.
Name Description
Provider Supported REST provider that you want to access to generate text. OCI Generative AI (ocigenai) is supported as a provider.
Credential Name Name of the credential.Holds authentication credentials to enable access to your provider for making REST API calls. Set the credential name as OCI_CRED, which was created earlier.
Url Enter the endpoint URL of the provider. For On-Demand Serving, use a region-specific URL (e.g., US Chicago: https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/chat). For a Dedicated AI Cluster, enter the custom inference endpoint URL which you can find in the OCI console.
Model Select the text generation model from the dropdown list.
Maximum Input Tokens Set the maximum input tokens for summarization. Allowed range: 1 to 128,000. Ensure space for output tokens within the model’s context limit.
Maximum Output Tokens The maximum number of tokens the model can generate per response. Estimate about four characters per token. The limit depends on your inference mode (on-demand: up to 4,000; dedicated: varies by model configuration).
Threshold Score Minimum confidence score required before including results in the context for LLM queries.

Configuration page

The Test Connection button can be used to validate the connection to the LLM provider using the provided credentials, model name, and endpoint URL.

Performing a Conversational Search in Redwood UI

Conversing with a Document:

Open the Document in Redwood UI Viewer

Access the Chat Panel

Interact with the Chat Assistant

This enables AI-powered conversation search within documents for quick insights and summaries.

Chat properties panel

Troubleshooting: Common Issues and Solutions

  1. ORA-20002 Authentication Error when Invoking Generative AI APIs. Error Message:
ORA-20002: The provider returned an error: The required information to complete authentication was not provided or was incorrect.

Possible Causes & Solutions:

Region Subscription & Replication:

IAM Policies Validation:

Credential & Authentication Issues: