8 Managing AI Services

Retail Analytics and Planning solutions leverage certain common AI services which need to be configured and maintained by customer administrators in order to enable them for business users. Review this chapter to understand the available services and manage their configurations.

Customer Documents for Retrieval-Augmented Generation

In the AI chat interfaces found throughout the Analytics and Planning applications, it is possible to ask general questions about application workflows, configurations, errors, and other details where the answers may be found somewhere in Oracle documentation. Retrieval-Augmented Generation (RAG) enhances AI answers to questions by retrieving relevant information before generating a response. In addition to the service’s shared knowledge base, you can provide your organization’s own documents so the AI can use them when answering your users’ questions. When users ask questions through the chat interface, the service searches your document content together with the shared documentation that applies to your service.

The workflow for leveraging this service has three main steps:

  1. Upload PDF documents to your designated File Transfer Services (FTS) Object Storage path.
  2. Monitor ingestion through the vectorization status REST API.
  3. Test the new content in the chat interface once ingestion is complete.

The service handles security scanning, document processing, indexing, and retrieval automatically.

Upload Documents

File transfer services (FTS) are leveraged for document uploads through Object Storage. For a basic understanding of FTS, refer to the Managing File Transfers chapter of this document. Before you begin, obtain the following from your service administrator or implementation team:

  • Your Object Storage bucket and authorized FTS upload access
  • Your designated document path
  • The service host and tenant identifier for the status API
  • Access to the chat interface for your RAP application(s)

Your designated Object Storage path follows this format:

rais/vector_db/version/<version>/appl/<appCode>/module/<moduleCode>/tenant/<customerTenantId>/

Replace the placeholder values in the path with exact values provided for your environment. Uploading outside this path prevents the document from being picked up for your tenant’s RAG content. The paths are application and version-specific, which means you must upload your latest documentation set for each major product release that gets applied in your RAP environment (hot fixes do not affect this process). If you do not upload new documents after an upgrade, the chat interface will no longer return data from your documents and will default back to standard Oracle documentation.

Example path:

rais/vector_db/version/26.1.201.0/appl/ap/module/ap/tenant/fgta435gtc4590fn/

After upload, FTS automatically scans the document for security concerns. Because the RAG process requires PDF files, the primary purpose of the scan is to detect malware or other malicious content embedded inside the file. The scan may also fail if the file is corrupt and cannot be accessed, or if the file is password-protected. If anything is found, the file will fail the scan and cannot be loaded into the Oracle servers. Documents that pass the scan are transferred to the RAG ingestion area and prepared for search.

Monitor File Status

Once the files are accepted into the platform, they must be vectorized and added to the AI services database. Use the vectorization status REST API to check whether your uploaded documents are ready for RAG. The API format is:

POST
https://<host>/<tenant>/app/rgbucommongenai/retailaiservices/filesVectorizationStatus

Example API URL:

https://rgbu.gbua.eu-frankfurt-1.oci.oraclecloud.com/fgta435gtc4590fn/app/rgbucommongenai/retailaiservices/filesVectorizationStatus

Example payload for the message body:

{{
{"appName": "ap","module": "ap","version": "26.1.201.0"}
}}

Continue checking the status until it returns COMPLETED.

Status Message Meaning Next action
In progress or other non-completed status The document is still being processed. Wait and check again.
COMPLETED The document has been indexed and is available to RAG. Test it in the chat interface.

Processing includes breaking the document into searchable sections, creating embeddings, and updating the vector index. Completion time can vary based on scheduled processing intervals and document volume. The process to load files runs every 60 minutes so it is not expected to take more than 1 to 2 hours to load a document, unless the document is exceptionally large and then it may require more processing time.

Verify Chat Results

Once the documents have completed the upload process, you may begin asking questions about their content from the specific AI chat interface associated with the upload, such as the ones in AP or MFP applications. Follow these guidelines for verifying the document contents are correctly being used:

  • Ask a question whose answer is clearly contained in the uploaded document.
  • Use specific terminology, names, procedures, or values from the document.
  • Confirm that the response is accurate and useful for your intended audience.
  • Test a few alternative phrasings to ensure users can find the information naturally.
  • Start with a question that is not likely to be answered by the shared knowledge base alone.

Deleting Documents

There is a separate API available for removing documents from Object Storage. The API format is:

DELETE
https://<host>/<tenant>/app/rgbucommongenai/retailaiservices/deleteFilesInOS

Example API URL:

https://rgbu.gbua.eu-frankfurt-1.oci.oraclecloud.com/fgta435gtc4590fn/app/rgbucommongenai/retailaiservices/deleteFilesInOS

Example payload for the message body:

{{
{"appName": "ap","module": "ap","version": "26.1.201.0","fileName": "<filename to be deleted>"}
}}

Use your environment’s service host and tenant identifier. After deletion, confirm through your normal validation process that the document is no longer available through the chat interface. Only delete documents that your organization no longer wants available for RAG retrieval.

Frequently Asked Questions

Question: How does the model used for the chat interface resolve differences between the Oracle and customer-provided documentation?

Answer: The customer’s documentation, once transformed and loaded into our database, is combined with the base documentation’s data. At this point there is no functional difference between base and custom documents, all information is retrieved based on standard LLM techniques for identifying the most relevant information for the user’s question and forming a natural-language response. The response may contain data from multiple sources, and it cannot verify the accuracy of the response if two documents provide conflicting answers to a question.

Question: How do I know which document was used to answer a question?

Answer: In the current implementation, the model can return details on the base Oracle Retail document that was used in a response, but not the custom documents.

Question: Can I control who can see data from certain documents, or who can see information on certain topics such as a specific UI screen or workflow that not all users can access?

Answer: No, the documentation uploaded to the RAG database becomes available to all users who have access to the chat interface. Do not upload sensitive or restricted information that should not be available to all users of the application.

Question: What are the customer’s responsibilities for maintaining this feature after they begin using one or more Retail applications?

Answer: The customer is responsible for uploading documents for each product release, verifying the quality of chat responses on their documentation, and deleting old documents if they become outdated or irrelevant.

Question: What suggestions can be given for managing this process in a live production environment?

Answer: Both document uploads and deletion can be automated from the customer’s own servers by incorporating the Rest API calls into scripts, AI tools, or other integration software. The customer could place new documents into a shared location, periodically poll that location for changes, and upload the documents to Oracle. For chat validation, prepare a standard set of questions which can be asked after every major update and log the responses for future reference, so quality and accuracy can be monitored over longer periods of time and applied back into the custom documents.