Use another knowledge store provider
Edit on GitHubThe knowledge store is the system that keeps the passages of the documents and their vectors and finds the passages that answer a question. By default, Storefront Assistant uses an Amazon Bedrock knowledge base. If your project cannot use AWS, or already runs another vector database or managed search service, you can replace the knowledge store with two plugins. You change no core module.
Prerequisites
Install Storefront Assistant document semantic search. You can skip the AWS steps of the installation.
What the core does and what the store does
The core keeps the parts that are the same for all knowledge stores. A knowledge store adds only the parts that are specific to it:
| CORE, NO CHANGE | YOUR KNOWLEDGE STORE |
|---|---|
The publisher, the knowledge_document.index queue, and the spy_knowledge_document table |
Setup: check and configure the store |
| The document sources and the download of the files | Indexing: turn the raw file into passages and vectors, and save them |
| The size limit, the content hash, the retries, and the status | Deletion: delete the passages of a document |
| The deletion of the documents of removed sources | Status: tell if a document is ready for the search |
The scope resolvers, the product_knowledge_search tool, and the passage filter |
Search: find the passages that are closest to the question, inside the given document keys |
The core sends the raw file and its MIME type to the store. The core has no text extraction and no chunking. If your store needs text, your store plugin must extract the text from PDF and Office files, split the text into passages, and create the vectors with an embedding model. A managed service that parses and embeds the files itself needs less code.
The two extension points
| EXTENSION POINT | LAYER | METHODS | REGISTERED IN |
|---|---|---|---|
SprykerFeature\Zed\AiCommerce\Dependency\KnowledgeStore\KnowledgeStorePluginInterface |
Zed | setupStore(), indexDocument(), deleteDocuments(), refreshDocumentStatuses(), getMaxDocumentSize(), isConfigured() |
Pyz\Zed\AiCommerce\AiCommerceDependencyProvider::getKnowledgeStorePlugin() |
SprykerFeature\Client\AiCommerce\Dependency\KnowledgeSearch\KnowledgeSearchPluginInterface |
Client | searchDocuments() |
Pyz\Client\AiCommerce\AiCommerceDependencyProvider::getKnowledgeSearchPlugin() |
Each stack takes one plugin. The two plugins must use the same store: Zed writes to it, and the Client reads from it in Yves and Glue. When the plugins use different stores, the search finds nothing, and no error shows it.
1) Implement the knowledge store plugin
Implement KnowledgeStorePluginInterface in Zed. The following table describes the contract of each method:
| METHOD | CALLED BY | MUST DO |
|---|---|---|
setupStore() |
knowledge-document:setup |
Check and configure the store, for example create an index. A second run must not change what is already correct. When the store is not configured, return isSkipped = true with the reason in messages. KnowledgeStoreSetupRequestTransfer.sourceTypes has the source types of all registered source plugins: return an error when the store cannot accept one of them. Return the steps that ran in steps, and set knowledgeStoreName. |
indexDocument() |
The queue worker | Replace the document {sourceType}:{sourceIdentifier} in the store with the content of KnowledgeDocumentContentTransfer. Return the status indexed when the store has the document, or processing when the store indexes it later. On failure, return isSuccessful = false with errors, and set isTemporaryFailure = true when a retry can succeed. |
deleteDocuments() |
The queue worker, for deleted sources | Delete the documents of KnowledgeDocumentCollectionTransfer.knowledgeDocuments. A document that the store does not have is not an error. |
refreshDocumentStatuses() |
knowledge-document:status:refresh |
Read the store status of each processing document. Return each document with the status indexed, processing, or failed, and set errorMessage for a failed document. A store that indexes synchronously and always returns indexed from indexDocument() can return the documents unchanged. |
getMaxDocumentSize() |
The queue worker | Return the largest document in bytes that the store accepts. The core does not download more than this size, and a larger document gets the status failed. |
isConfigured() |
The publisher, the queue worker, and knowledge-document:reindex |
Return true when the store is configured and can accept the documents of the source type in $sourceType. Otherwise, return false: the core then does not queue, download, or index the documents of the source type, and knowledge-document:reindex reports that the store is not configured. Do not connect to the store in this method, because the core calls it for each batch of events and for each queue message. |
In the error response of deleteDocuments() and refreshDocumentStatuses(), set isTemporaryFailure = false when a retry cannot succeed, for example a configuration error. The core then does not send the document to the queue again.
KnowledgeDocumentContentTransfer has the following data for indexDocument():
| FIELD | CONTENT |
|---|---|
content |
The raw bytes of the file. |
mimeType |
The MIME type, for example application/pdf or text/markdown. |
knowledgeDocumentSource.sourceType, knowledgeDocumentSource.sourceIdentifier |
The parts of the document key. |
knowledgeDocumentSource.documentName |
The name that the assistant shows as the source. |
knowledgeDocumentSource.localeName |
The locale of the document, or null for all locales. Save * for all locales, so that the search can filter by locale. |
knowledgeDocumentSource.metadata |
Optional scalar metadata of the source. |
src/Pyz/Zed/AcmeKnowledgeStore/Communication/Plugin/AiCommerce/AcmeKnowledgeStorePlugin.php
<?php
namespace Pyz\Zed\AcmeKnowledgeStore\Communication\Plugin\AiCommerce;
use Generated\Shared\Transfer\KnowledgeDocumentCollectionResponseTransfer;
use Generated\Shared\Transfer\KnowledgeDocumentCollectionTransfer;
use Generated\Shared\Transfer\KnowledgeDocumentContentTransfer;
use Generated\Shared\Transfer\KnowledgeDocumentIndexResponseTransfer;
use Generated\Shared\Transfer\KnowledgeStoreSetupRequestTransfer;
use Generated\Shared\Transfer\KnowledgeStoreSetupResponseTransfer;
use Spryker\Zed\Kernel\Communication\AbstractPlugin;
use SprykerFeature\Zed\AiCommerce\Dependency\KnowledgeStore\KnowledgeStorePluginInterface;
/**
* @method \Pyz\Zed\AcmeKnowledgeStore\Business\AcmeKnowledgeStoreFacadeInterface getFacade()
* @method \Pyz\Zed\AcmeKnowledgeStore\AcmeKnowledgeStoreConfig getConfig()
*/
class AcmeKnowledgeStorePlugin extends AbstractPlugin implements KnowledgeStorePluginInterface
{
public function setupStore(KnowledgeStoreSetupRequestTransfer $knowledgeStoreSetupRequestTransfer): KnowledgeStoreSetupResponseTransfer
{
return $this->getFacade()->setupStore($knowledgeStoreSetupRequestTransfer);
}
public function indexDocument(
KnowledgeDocumentContentTransfer $knowledgeDocumentContentTransfer
): KnowledgeDocumentIndexResponseTransfer {
return $this->getFacade()->indexDocument($knowledgeDocumentContentTransfer);
}
public function deleteDocuments(
KnowledgeDocumentCollectionTransfer $knowledgeDocumentCollectionTransfer
): KnowledgeDocumentCollectionResponseTransfer {
return $this->getFacade()->deleteDocuments($knowledgeDocumentCollectionTransfer);
}
public function refreshDocumentStatuses(
KnowledgeDocumentCollectionTransfer $knowledgeDocumentCollectionTransfer
): KnowledgeDocumentCollectionResponseTransfer {
return $this->getFacade()->refreshDocumentStatuses($knowledgeDocumentCollectionTransfer);
}
public function getMaxDocumentSize(): int
{
return $this->getConfig()->getMaxDocumentSize();
}
public function isConfigured(string $sourceType): bool
{
return $this->getConfig()->isConfigured($sourceType);
}
}
The facade and the business models in the example belong to your module. Use the shipped BedrockKnowledgeBaseKnowledgeStorePlugin and its business models in SprykerFeature\Zed\AiCommerce\Business\BedrockKnowledgeBase as the reference.
Save the passages with metadata
The search filters the passages by the metadata of their document. Save the following values with each passage:
| VALUE | USED FOR |
|---|---|
The document key, {sourceType}:{sourceIdentifier} |
The filter by the document scope, the replacement of a document, and the deletion of a document. |
| The source type | The filter by source_types. |
The locale, or * for all locales |
The filter by the locale of the customer. |
| The document name | The filter by document_name and the source that the assistant names. |
Use the document key as the ID of the document in the store, so that a new version of a document replaces all passages of the old version.
2) Implement the knowledge search plugin
Implement KnowledgeSearchPluginInterface::searchDocuments() in the Client. The method gets KnowledgeSearchCriteriaTransfer and returns KnowledgePassageCollectionTransfer.
The conditions are in KnowledgeSearchCriteriaTransfer.knowledgeSearchConditions:
| CONDITION | DESCRIPTION |
|---|---|
queryText |
The search phrase. Required. |
documentKeys |
The document keys of the scope. The search must return only passages of these documents. |
ids |
Optional passage IDs. |
sourceTypes |
Optional source types. |
locales |
The locale of the customer and *. |
documentName |
Optional name of one document. |
The maximum number of passages is KnowledgeSearchCriteriaTransfer.pagination.limit. The core asks for more passages than it returns, because its passage filter removes duplicates and short passages. For details, see getKnowledgeDocumentCandidateMultiplier() in Search settings.
The method must do the following:
- Require
queryTextandpagination.limit. - Require at least one value in
documentKeysorids. Never search the whole store: the document keys are the access check of the customer. - Apply all set conditions with AND.
- Return at most
pagination.limitpassages, ordered by score, highest first. - Set
documentKey,sourceType,documentName,content, andscoreon eachKnowledgePassageTransfer. The core removes passages whosedocumentKeyis not in the scope, and reads the source identifier from the document key. - Set
isSuccessful = trueon success, also when no passage matches. - Return
isSuccessful = falsewith errors when the criteria are not valid or the store fails. Do not throw an exception. The core then tells the AI model that the document search is not available.
src/Pyz/Client/AcmeKnowledgeStore/Plugin/AiCommerce/AcmeKnowledgeSearchPlugin.php
<?php
namespace Pyz\Client\AcmeKnowledgeStore\Plugin\AiCommerce;
use Generated\Shared\Transfer\KnowledgePassageCollectionTransfer;
use Generated\Shared\Transfer\KnowledgeSearchCriteriaTransfer;
use Spryker\Client\Kernel\AbstractPlugin;
use SprykerFeature\Client\AiCommerce\Dependency\KnowledgeSearch\KnowledgeSearchPluginInterface;
/**
* @method \Pyz\Client\AcmeKnowledgeStore\AcmeKnowledgeStoreFactory getFactory()
*/
class AcmeKnowledgeSearchPlugin extends AbstractPlugin implements KnowledgeSearchPluginInterface
{
public function searchDocuments(KnowledgeSearchCriteriaTransfer $knowledgeSearchCriteriaTransfer): KnowledgePassageCollectionTransfer
{
return $this->getFactory()
->createAcmePassageReader()
->getKnowledgePassageCollection($knowledgeSearchCriteriaTransfer);
}
}
The search runs on each tool call in Yves and Glue, so keep it fast. Use the shipped BedrockKnowledgeBaseKnowledgeSearchPlugin and its classes in SprykerFeature\Client\AiCommerce\BedrockKnowledgeBase as the reference.
3) Register the plugins
Replace the Bedrock plugins with your plugins in both dependency providers:
src/Pyz/Zed/AiCommerce/AiCommerceDependencyProvider.php
<?php
namespace Pyz\Zed\AiCommerce;
use Pyz\Zed\AcmeKnowledgeStore\Communication\Plugin\AiCommerce\AcmeKnowledgeStorePlugin;
use SprykerFeature\Zed\AiCommerce\AiCommerceDependencyProvider as SprykerFeatureAiCommerceDependencyProvider;
use SprykerFeature\Zed\AiCommerce\Dependency\KnowledgeStore\KnowledgeStorePluginInterface;
class AiCommerceDependencyProvider extends SprykerFeatureAiCommerceDependencyProvider
{
protected function getKnowledgeStorePlugin(): KnowledgeStorePluginInterface
{
return new AcmeKnowledgeStorePlugin();
}
}
src/Pyz/Client/AiCommerce/AiCommerceDependencyProvider.php
<?php
namespace Pyz\Client\AiCommerce;
use Pyz\Client\AcmeKnowledgeStore\Plugin\AiCommerce\AcmeKnowledgeSearchPlugin;
use SprykerFeature\Client\AiCommerce\AiCommerceDependencyProvider as SprykerFeatureAiCommerceDependencyProvider;
use SprykerFeature\Client\AiCommerce\Dependency\KnowledgeSearch\KnowledgeSearchPluginInterface;
class AiCommerceDependencyProvider extends SprykerFeatureAiCommerceDependencyProvider
{
protected function getKnowledgeSearchPlugin(): KnowledgeSearchPluginInterface
{
return new AcmeKnowledgeSearchPlugin();
}
}
The document source plugins, the scope resolver plugins, the product_knowledge_search tool, and the search settings do not change. You can remove the BEDROCK_KNOWLEDGE_BASE_* configuration.
Clear the caches:
console cache:class-resolver:build
console cache:empty-all
4) Set up the store and index the documents
-
Set up the store:
console knowledge-document:setup -v -
Queue all documents.
--forceclears the content hash, so that every document is sent to the new store:console knowledge-document:reindex --force -
Process the queue:
console queue:worker:start --stop-when-empty -
If your store returns
processing, save the final status. The scheduler job also runs this command every five minutes:console knowledge-document:status:refresh
- Make sure that all rows of
spy_knowledge_documenthave the statusindexed. - On a product page that has a manual, ask the assistant a question that only the manual answers. The answer names the manual as the source.
- Ask the same question for a product that the customer cannot see in the current store. The assistant gets no passages.
Evaluate the search quality
A new store, a new embedding model, or a new chunking changes which passages the assistant gets. Evaluate the search before you use the new store in production:
- Make a set of questions with the expected document keys and the expected answer strings. Check each answer string against the source document.
- Include text facts, procedures, the second locale of your shop, facts that are only in images, paraphrases, near-identical documents of product variants, and questions without an answer in a document.
- Send the questions through the same search as the tool, with the product scope. Without a product scope, the scope resolver returns no documents.
- For each question, record if an expected answer string is in the result, its rank, the duplicate passages, and the latency.
- Compare the new store with the old store: the answer at rank 1, the answer in the top 3, and the answer in the result.
Then tune the search settings of the Client AiCommerceConfig. For details, see Search settings.
Thank you!
For submitting the form