From 81b965c393429a2c65b91b597e41f6e3621c26df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Fri, 28 Nov 2025 19:35:50 +0100 Subject: [PATCH 01/10] IBX-11003: Describe taxonomy suggestions in developer doc --- docs/content_management/taxonomy/taxonomy.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/content_management/taxonomy/taxonomy.md b/docs/content_management/taxonomy/taxonomy.md index 23e4663465..ad26207339 100644 --- a/docs/content_management/taxonomy/taxonomy.md +++ b/docs/content_management/taxonomy/taxonomy.md @@ -112,3 +112,18 @@ The following example first lists the orphaned content items for taxonomy `tags` php bin/console ibexa:taxonomy:remove-orphaned-content tags --dry-run php bin/console ibexa:taxonomy:remove-orphaned-content tags --force ``` + +## Taxonomy suggestions + +Once the feature is enabled, with taxonomy suggestions, editors can pick from suggestions generated by an AI service based on selected fields like the product's or content item's name and description instead of having to manually browse through taxonomy trees and selecting [product categories]([[= user_doc =]]pim/work_with_product_categories/#assign-product-categories-by-editing-product-details) or [tags]([[= user_doc =]]/content_management/create_edit_content_items/#add-taxonomy-entries). + +Taxonomy suggestions build on existing [AI Actions](ai_actions_guide.md) functionality. +The `TaxonomyEmbeddingFieldProvider` uses an existing taxonomy tree as reference, generating an embedding for each path in the taxonomy tree, a multi-dimensional vector aka. embedding is generated and stored in the search index. + +When the editor creates or edits a content item or a product, they can request that the application suggests tags or product categories to be associated with the item. +When it happens, the `TextToTaxonomyActionHandler` requests that an embedding is generated based on selected fields such as name and description. +The text fields, whose values are used as source for the embedding generation, are defined when you create an [AI action](https://doc.ibexa.co/projects/userguide/en/latest/ai_actions/work_with_ai_actions/#create-ai-actions-that-use-ibexa-connect) that uses the `openai-text-to-taxonomy-entries handler`. + +The search engine then compares the generated embedding with the taxonomy path embeddings stored in its index. +It selects the three best-matching taxonomy paths and presents them to the editor as suggestions. +The user can accept the suggestions, reject them, or request a new set of suggestions directly from the user interface. From 1676481b841b43d671360737386dfd09d091fed0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Mon, 1 Dec 2025 15:47:24 +0100 Subject: [PATCH 02/10] IBX-11002: Configure Taxonomy suggestions --- docs/content_management/taxonomy/taxonomy.md | 120 ++++++++++++++++++- 1 file changed, 116 insertions(+), 4 deletions(-) diff --git a/docs/content_management/taxonomy/taxonomy.md b/docs/content_management/taxonomy/taxonomy.md index ad26207339..0bd48bdf00 100644 --- a/docs/content_management/taxonomy/taxonomy.md +++ b/docs/content_management/taxonomy/taxonomy.md @@ -115,15 +115,127 @@ php bin/console ibexa:taxonomy:remove-orphaned-content tags --force ## Taxonomy suggestions -Once the feature is enabled, with taxonomy suggestions, editors can pick from suggestions generated by an AI service based on selected fields like the product's or content item's name and description instead of having to manually browse through taxonomy trees and selecting [product categories]([[= user_doc =]]pim/work_with_product_categories/#assign-product-categories-by-editing-product-details) or [tags]([[= user_doc =]]/content_management/create_edit_content_items/#add-taxonomy-entries). +Once the feature is [enabled](#enable-taxonomy-suggestions), with taxonomy suggestions, editors can pick from suggestions generated by an AI service based on selected fields like the product's or content item's name and description instead of having to manually browse through taxonomy trees and selecting [product categories]([[= user_doc =]]pim/work_with_product_categories/#assign-product-categories-by-editing-product-details) or [tags]([[= user_doc =]]/content_management/create_edit_content_items/#add-taxonomy-entries). Taxonomy suggestions build on existing [AI Actions](ai_actions_guide.md) functionality. -The `TaxonomyEmbeddingFieldProvider` uses an existing taxonomy tree as reference, generating an embedding for each path in the taxonomy tree, a multi-dimensional vector aka. embedding is generated and stored in the search index. +The `Ibexa\Taxonomy\Embedding\TaxonomyEmbeddingFieldProvider` uses an existing taxonomy tree as reference, generating an embedding for each path in the taxonomy tree, a multi-dimensional vector aka. embedding is generated and stored in the search index. + +For performance reasons, embeddings for the taxonomy tree entries are generated only in two cases: + +- when the database is reindexed, for example, after you enable the feature +- when an individual taxonomy entry is created or modified, it's vector is updated When the editor creates or edits a content item or a product, they can request that the application suggests tags or product categories to be associated with the item. -When it happens, the `TextToTaxonomyActionHandler` requests that an embedding is generated based on selected fields such as name and description. -The text fields, whose values are used as source for the embedding generation, are defined when you create an [AI action](https://doc.ibexa.co/projects/userguide/en/latest/ai_actions/work_with_ai_actions/#create-ai-actions-that-use-ibexa-connect) that uses the `openai-text-to-taxonomy-entries handler`. +When it happens, the `Ibexa\Taxonomy\ActionHandler\TextToTaxonomyActionHandler` requests that an embedding is generated based on selected fields such as, for example, name and description. + +!!! note "Field selection" + + You select the actual text fields, whose values are used as source for the embedding generation, when you create an [AI action](https://doc.ibexa.co/projects/userguide/en/latest/ai_actions/work_with_ai_actions/#create-ai-actions-that-use-ibexa-connect) that uses the `openai-text-to-taxonomy-entries handler`. The search engine then compares the generated embedding with the taxonomy path embeddings stored in its index. It selects the three best-matching taxonomy paths and presents them to the editor as suggestions. The user can accept the suggestions, reject them, or request a new set of suggestions directly from the user interface. + +### Enable taxonomy suggestions + +Taxonomy suggestions are built into the product and do not require additional installation. +However, before you can enable it, make sure the following prerequisites have been fulfilled: + +- [Search engine](search_engines.md): Taxonomy suggestions require a search engine that supports vector search. +The feature has been tested to work with Elasticsearch or Solr 9.8.1+ with KNN enabled. +- [AI Actions](ai_actions.md): To be able to process embeddings, Taxonomy suggestions require that you have the [AI Actions installed and configured](install_ai_actions.md#configure-access-to-openai-optional) to support the OpenAI service. + +#### Enable taxonomy embedding indexing + +Enable embedding indexing for taxonomy branches by changing the default setting from `false` to `true`: + +```yaml +ibexa: + system: + default: + taxonomy: + search: + index_embeddings: true +``` + +Toggle this setting at any time to enable or disable taxonomy suggestions. + +If you are happy with the default settings, clear the cache and reindex the database. + +```shell +php bin/console ibexa:reindex +``` + +```shell +php bin/console cache:clear +``` + +#### Configure AI action + +Once you enable the Taxonomy suggestions feature, you must [configure an AI action]([[= user_doc =]]/ai_actions/work_with_ai_actions/#create-new-ai-actions) that handles the generation of embeddings for newly created or edited content items or products. + +That's where you decide which exact fields from which content type should be used as input for embedding generation, how many suggestions are being presenter to the editor, and so on. + +After ce you do it, your users are be able to assign tags and/or product categories by using suggestions provided by an AI engine. + +### Customize taxonomy suggestions + +You can modify the default behavior of the Taxonomy suggestions model by changing various settings. + +#### Change the embedding model + +By default, the system comes with a set of OpenAI models listed in its configuration, and a setting that allows you to choose one that should be used with the Taxonomy suggestions feature. + +```yaml hl_lines="20" +ibexa: + system: + default: + embedding_models: + text-embedding-3-small: + name: text-embedding-3-small + dimensions: 1536 + field_suffix: 3small + embedding_provider: ibexa_openai + text-embedding-3-large: + name: text-embedding-3-large + dimensions: 3072 + field_suffix: 3large + embedding_provider: ibexa_openai + text-embedding-ada-002: + name: text-embedding-ada-002 + dimensions: 1536 + field_suffix: ada002 + embedding_provider: ibexa_openai + default_embedding_model: text-embedding-ada-002 +``` + +Here is where you can change the name of the mode used by the provider, the embedding's dimensions, and other settings. + +#### Change the number of suggestions + +By default, the system returns three suggestions. +You can change the default number if needed by altering the following setting: + + +```yaml hl_lines="4" +ibexa: + taxonomy: + text_to_taxonomy: + default_suggested_taxonomies_limit: 5 +``` + +You can also override this setting per AI Action through its configuration form. + +### Extending Taxonomy suggestions + +#### Replace the embedding provider + +By default, the system uses the `ibexa_openai` connector. +You can add your own embedding provider if needed. To do it: + + - Implement the `EmbeddingProviderInterface` + - Register the service with the `ibexa.embedding_provider` tag + +#### Extend the AI action form + +You can extend the `TextToTaxonomyOptionsType` AI action form by inheriting from `AbstractActionConfigurationOptions`. From 1204dba2f7d52af8b9bce61477ceb62100a5485d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Mon, 1 Dec 2025 16:34:55 +0100 Subject: [PATCH 03/10] Fix broken links --- docs/content_management/taxonomy/taxonomy.md | 25 ++++++++++---------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/content_management/taxonomy/taxonomy.md b/docs/content_management/taxonomy/taxonomy.md index 0bd48bdf00..4108a31e26 100644 --- a/docs/content_management/taxonomy/taxonomy.md +++ b/docs/content_management/taxonomy/taxonomy.md @@ -115,7 +115,7 @@ php bin/console ibexa:taxonomy:remove-orphaned-content tags --force ## Taxonomy suggestions -Once the feature is [enabled](#enable-taxonomy-suggestions), with taxonomy suggestions, editors can pick from suggestions generated by an AI service based on selected fields like the product's or content item's name and description instead of having to manually browse through taxonomy trees and selecting [product categories]([[= user_doc =]]pim/work_with_product_categories/#assign-product-categories-by-editing-product-details) or [tags]([[= user_doc =]]/content_management/create_edit_content_items/#add-taxonomy-entries). +Once the feature is [enabled](#enable-taxonomy-suggestions), with taxonomy suggestions, editors can pick from suggestions generated by an AI service based on selected fields like the product's or content item's name and description instead of having to manually browse through taxonomy trees and selecting [product categories]([[= user_doc =]]/pim/work_with_product_categories/#assign-product-categories-by-editing-product-details) or [tags]([[= user_doc =]]/content_management/create_edit_content_items/#add-taxonomy-entries). Taxonomy suggestions build on existing [AI Actions](ai_actions_guide.md) functionality. The `Ibexa\Taxonomy\Embedding\TaxonomyEmbeddingFieldProvider` uses an existing taxonomy tree as reference, generating an embedding for each path in the taxonomy tree, a multi-dimensional vector aka. embedding is generated and stored in the search index. @@ -123,27 +123,27 @@ The `Ibexa\Taxonomy\Embedding\TaxonomyEmbeddingFieldProvider` uses an existing t For performance reasons, embeddings for the taxonomy tree entries are generated only in two cases: - when the database is reindexed, for example, after you enable the feature -- when an individual taxonomy entry is created or modified, it's vector is updated +- when an individual taxonomy entry is created or modified, it's embedding is updated When the editor creates or edits a content item or a product, they can request that the application suggests tags or product categories to be associated with the item. When it happens, the `Ibexa\Taxonomy\ActionHandler\TextToTaxonomyActionHandler` requests that an embedding is generated based on selected fields such as, for example, name and description. !!! note "Field selection" - You select the actual text fields, whose values are used as source for the embedding generation, when you create an [AI action](https://doc.ibexa.co/projects/userguide/en/latest/ai_actions/work_with_ai_actions/#create-ai-actions-that-use-ibexa-connect) that uses the `openai-text-to-taxonomy-entries handler`. + You select the actual text fields, whose values are used as source for the embedding generation, when you create an [AI action](https://doc.ibexa.co/projects/userguide/en/latest/ai_actions/work_with_ai_actions/#create-ai-actions-that-use-ibexa-connect) that uses the `openai-text-to-taxonomy-entries` handler. The search engine then compares the generated embedding with the taxonomy path embeddings stored in its index. It selects the three best-matching taxonomy paths and presents them to the editor as suggestions. The user can accept the suggestions, reject them, or request a new set of suggestions directly from the user interface. -### Enable taxonomy suggestions +### Enable Taxonomy suggestions Taxonomy suggestions are built into the product and do not require additional installation. However, before you can enable it, make sure the following prerequisites have been fulfilled: - [Search engine](search_engines.md): Taxonomy suggestions require a search engine that supports vector search. The feature has been tested to work with Elasticsearch or Solr 9.8.1+ with KNN enabled. -- [AI Actions](ai_actions.md): To be able to process embeddings, Taxonomy suggestions require that you have the [AI Actions installed and configured](install_ai_actions.md#configure-access-to-openai-optional) to support the OpenAI service. +- [AI Actions](ai_actions.md): To be able to process embeddings, Taxonomy suggestions require that you have the [AI Actions configured](configure_ai_actions.md#configure-access-to-openai-optional) to support the OpenAI service. #### Enable taxonomy embedding indexing @@ -178,13 +178,13 @@ That's where you decide which exact fields from which content type should be use After ce you do it, your users are be able to assign tags and/or product categories by using suggestions provided by an AI engine. -### Customize taxonomy suggestions +### Customize Taxonomy suggestions You can modify the default behavior of the Taxonomy suggestions model by changing various settings. -#### Change the embedding model +#### Change the embedding generation model -By default, the system comes with a set of OpenAI models listed in its configuration, and a setting that allows you to choose one that should be used with the Taxonomy suggestions feature. +By default, the system comes with a set of OpenAI models listed in its configuration, and a setting that allows you to choose the default model that should be used with the Taxonomy suggestions feature. ```yaml hl_lines="20" ibexa: @@ -209,14 +209,13 @@ ibexa: default_embedding_model: text-embedding-ada-002 ``` -Here is where you can change the name of the mode used by the provider, the embedding's dimensions, and other settings. +Also, here is where you can change the name of the model used by the provider, the embedding's dimensions, and other settings. #### Change the number of suggestions By default, the system returns three suggestions. You can change the default number if needed by altering the following setting: - ```yaml hl_lines="4" ibexa: taxonomy: @@ -224,7 +223,7 @@ ibexa: default_suggested_taxonomies_limit: 5 ``` -You can also override this setting per AI Action through its configuration form. +You can also override this setting per AI action by editing its configuration. ### Extending Taxonomy suggestions @@ -233,8 +232,8 @@ You can also override this setting per AI Action through its configuration form. By default, the system uses the `ibexa_openai` connector. You can add your own embedding provider if needed. To do it: - - Implement the `EmbeddingProviderInterface` - - Register the service with the `ibexa.embedding_provider` tag +- Implement the `EmbeddingProviderInterface` +- Register the service with the `ibexa.embedding_provider` tag #### Extend the AI action form From 23b1ae7f306af0a823b7acf659f45da868fb4ec6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Mon, 1 Dec 2025 17:06:34 +0100 Subject: [PATCH 04/10] Add default fields to configuration --- docs/content_management/taxonomy/taxonomy.md | 51 ++++++++++++++------ 1 file changed, 36 insertions(+), 15 deletions(-) diff --git a/docs/content_management/taxonomy/taxonomy.md b/docs/content_management/taxonomy/taxonomy.md index 4108a31e26..12e33b055c 100644 --- a/docs/content_management/taxonomy/taxonomy.md +++ b/docs/content_management/taxonomy/taxonomy.md @@ -182,7 +182,40 @@ After ce you do it, your users are be able to assign tags and/or product categor You can modify the default behavior of the Taxonomy suggestions model by changing various settings. -#### Change the embedding generation model +#### Change default number of suggestions + +By default, the system returns three suggestions. +You can change the default number if needed by altering the following setting: + +```yaml hl_lines="4" +ibexa: + taxonomy: + text_to_taxonomy: + default_suggested_taxonomies_limit: 5 +``` + +You can also override this setting per AI action by editing its configuration. + +#### Change default fields parsed when generating suggestions + +The following setting decides which fields are used to generate suggestions by default. +You can change the default setting, if needed. + +```yaml hl_lines="6,7,8" +ibexa: + system: + default: + content_type_field_type_groups: + configurations: + vectorizable_fields: + - ezstring + - eztext +``` + +This way you can limit field selection to meaningful text fields and avoid unsupported field types. +Like in the case of the number of suggestions, you can override this setting per AI action by editing its configuration. + +### Change the embedding generation model By default, the system comes with a set of OpenAI models listed in its configuration, and a setting that allows you to choose the default model that should be used with the Taxonomy suggestions feature. @@ -211,22 +244,10 @@ ibexa: Also, here is where you can change the name of the model used by the provider, the embedding's dimensions, and other settings. -#### Change the number of suggestions - -By default, the system returns three suggestions. -You can change the default number if needed by altering the following setting: - -```yaml hl_lines="4" -ibexa: - taxonomy: - text_to_taxonomy: - default_suggested_taxonomies_limit: 5 -``` - -You can also override this setting per AI action by editing its configuration. - ### Extending Taxonomy suggestions +You can extend the feature by replacing the default code by exploring one of the following ideas. + #### Replace the embedding provider By default, the system uses the `ibexa_openai` connector. From bdd7b1097f27a64cc3e42fb4651e73841e90bc35 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Tue, 2 Dec 2025 10:18:43 +0100 Subject: [PATCH 05/10] Remove the mention of KNN, which comes as default in Solr 9. --- docs/content_management/taxonomy/taxonomy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content_management/taxonomy/taxonomy.md b/docs/content_management/taxonomy/taxonomy.md index 12e33b055c..49c41768ef 100644 --- a/docs/content_management/taxonomy/taxonomy.md +++ b/docs/content_management/taxonomy/taxonomy.md @@ -142,7 +142,7 @@ Taxonomy suggestions are built into the product and do not require additional in However, before you can enable it, make sure the following prerequisites have been fulfilled: - [Search engine](search_engines.md): Taxonomy suggestions require a search engine that supports vector search. -The feature has been tested to work with Elasticsearch or Solr 9.8.1+ with KNN enabled. +The feature has been tested to work with Elasticsearch or Solr 9.8.1+. - [AI Actions](ai_actions.md): To be able to process embeddings, Taxonomy suggestions require that you have the [AI Actions configured](configure_ai_actions.md#configure-access-to-openai-optional) to support the OpenAI service. #### Enable taxonomy embedding indexing From 75f759184d2062b8187cca50b7b2329435e2db33 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Tue, 2 Dec 2025 14:45:23 +0100 Subject: [PATCH 06/10] Fix a link that leads to user documentation --- docs/content_management/taxonomy/taxonomy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content_management/taxonomy/taxonomy.md b/docs/content_management/taxonomy/taxonomy.md index 49c41768ef..242c75afa8 100644 --- a/docs/content_management/taxonomy/taxonomy.md +++ b/docs/content_management/taxonomy/taxonomy.md @@ -172,7 +172,7 @@ php bin/console cache:clear #### Configure AI action -Once you enable the Taxonomy suggestions feature, you must [configure an AI action]([[= user_doc =]]/ai_actions/work_with_ai_actions/#create-new-ai-actions) that handles the generation of embeddings for newly created or edited content items or products. +Once you enable the Taxonomy suggestions feature, you must [configure an AI action]([[= user_doc =]]/ai_actions/work_with_ai_actions/#create-ai-actions-that-control-taxonomy-suggestions) that handles the generation of embeddings for newly created or edited content items or products. That's where you decide which exact fields from which content type should be used as input for embedding generation, how many suggestions are being presenter to the editor, and so on. From 5ddbd03ab1eed052f2d21dbb9876a77ed8ef4089 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Wed, 3 Dec 2025 14:41:04 +0100 Subject: [PATCH 07/10] Apply suggestions from code review Co-authored-by: Mikolaj Adamczyk --- docs/content_management/taxonomy/taxonomy.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/content_management/taxonomy/taxonomy.md b/docs/content_management/taxonomy/taxonomy.md index 242c75afa8..0a71ecda3d 100644 --- a/docs/content_management/taxonomy/taxonomy.md +++ b/docs/content_management/taxonomy/taxonomy.md @@ -133,7 +133,7 @@ When it happens, the `Ibexa\Taxonomy\ActionHandler\TextToTaxonomyActionHandler` You select the actual text fields, whose values are used as source for the embedding generation, when you create an [AI action](https://doc.ibexa.co/projects/userguide/en/latest/ai_actions/work_with_ai_actions/#create-ai-actions-that-use-ibexa-connect) that uses the `openai-text-to-taxonomy-entries` handler. The search engine then compares the generated embedding with the taxonomy path embeddings stored in its index. -It selects the three best-matching taxonomy paths and presents them to the editor as suggestions. +By default, it selects the three best-matching taxonomy paths and presents them to the editor as suggestions. The user can accept the suggestions, reject them, or request a new set of suggestions directly from the user interface. ### Enable Taxonomy suggestions @@ -158,7 +158,7 @@ ibexa: index_embeddings: true ``` -Toggle this setting at any time to enable or disable taxonomy suggestions. +Toggle this setting at any time to enable or disable indexing of taxonomy embeddings. If you are happy with the default settings, clear the cache and reindex the database. @@ -176,7 +176,7 @@ Once you enable the Taxonomy suggestions feature, you must [configure an AI acti That's where you decide which exact fields from which content type should be used as input for embedding generation, how many suggestions are being presenter to the editor, and so on. -After ce you do it, your users are be able to assign tags and/or product categories by using suggestions provided by an AI engine. +After you do it, your users are be able to assign tags and/or product categories by using suggestions provided by an AI engine. ### Customize Taxonomy suggestions From 8d93bcc6974a5dd0167bfecab7385aaf3424595b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Thu, 4 Dec 2025 10:28:01 +0100 Subject: [PATCH 08/10] Review suggestions --- docs/content_management/taxonomy/taxonomy.md | 21 +++++++++----------- 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/docs/content_management/taxonomy/taxonomy.md b/docs/content_management/taxonomy/taxonomy.md index 0a71ecda3d..66155e56e0 100644 --- a/docs/content_management/taxonomy/taxonomy.md +++ b/docs/content_management/taxonomy/taxonomy.md @@ -118,7 +118,7 @@ php bin/console ibexa:taxonomy:remove-orphaned-content tags --force Once the feature is [enabled](#enable-taxonomy-suggestions), with taxonomy suggestions, editors can pick from suggestions generated by an AI service based on selected fields like the product's or content item's name and description instead of having to manually browse through taxonomy trees and selecting [product categories]([[= user_doc =]]/pim/work_with_product_categories/#assign-product-categories-by-editing-product-details) or [tags]([[= user_doc =]]/content_management/create_edit_content_items/#add-taxonomy-entries). Taxonomy suggestions build on existing [AI Actions](ai_actions_guide.md) functionality. -The `Ibexa\Taxonomy\Embedding\TaxonomyEmbeddingFieldProvider` uses an existing taxonomy tree as reference, generating an embedding for each path in the taxonomy tree, a multi-dimensional vector aka. embedding is generated and stored in the search index. +The `Ibexa\Contracts\Taxonomy\Embedding\TaxonomyEmbeddingFieldProviderInterface` service uses an existing taxonomy tree as reference, generating an embedding for each path in the taxonomy tree and storing it in the search index. For performance reasons, embeddings for the taxonomy tree entries are generated only in two cases: @@ -160,14 +160,11 @@ ibexa: Toggle this setting at any time to enable or disable indexing of taxonomy embeddings. -If you are happy with the default settings, clear the cache and reindex the database. +If you are happy with the default settings, clear the cache and reindex the search engine. -```shell -php bin/console ibexa:reindex -``` - -```shell +``` shell php bin/console cache:clear +php bin/console ibexa:reindex ``` #### Configure AI action @@ -187,7 +184,7 @@ You can modify the default behavior of the Taxonomy suggestions model by changin By default, the system returns three suggestions. You can change the default number if needed by altering the following setting: -```yaml hl_lines="4" +``` yaml hl_lines="4" ibexa: taxonomy: text_to_taxonomy: @@ -201,15 +198,15 @@ You can also override this setting per AI action by editing its configuration. The following setting decides which fields are used to generate suggestions by default. You can change the default setting, if needed. -```yaml hl_lines="6,7,8" +``` yaml hl_lines="6-8" ibexa: system: default: content_type_field_type_groups: configurations: vectorizable_fields: - - ezstring - - eztext + - ibexa_string + - ibexa_text ``` This way you can limit field selection to meaningful text fields and avoid unsupported field types. @@ -258,4 +255,4 @@ You can add your own embedding provider if needed. To do it: #### Extend the AI action form -You can extend the `TextToTaxonomyOptionsType` AI action form by inheriting from `AbstractActionConfigurationOptions`. +You can extend the `TextToTaxonomyOptionsType` AI action form by inheriting from `Ibexa\Bundle\Taxonomy\Form\Type\AbstractActionConfigurationOptions`. From f9eefc4ed69fb36ed731fed102d73f7b04af465a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Thu, 4 Dec 2025 11:16:27 +0100 Subject: [PATCH 09/10] Reworded example --- docs/content_management/taxonomy/taxonomy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content_management/taxonomy/taxonomy.md b/docs/content_management/taxonomy/taxonomy.md index 66155e56e0..3fc6dd9047 100644 --- a/docs/content_management/taxonomy/taxonomy.md +++ b/docs/content_management/taxonomy/taxonomy.md @@ -122,7 +122,7 @@ The `Ibexa\Contracts\Taxonomy\Embedding\TaxonomyEmbeddingFieldProviderInterface` For performance reasons, embeddings for the taxonomy tree entries are generated only in two cases: -- when the database is reindexed, for example, after you enable the feature +- when the search engine is reindexed, for example, right after you enable the feature and run the `ibexa:reindex` command - when an individual taxonomy entry is created or modified, it's embedding is updated When the editor creates or edits a content item or a product, they can request that the application suggests tags or product categories to be associated with the item. From cd0a9ec9a06da6ccad99b0ef6b983e2bc67027ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Thu, 4 Dec 2025 11:42:37 +0100 Subject: [PATCH 10/10] Added tip --- docs/content_management/taxonomy/taxonomy.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/content_management/taxonomy/taxonomy.md b/docs/content_management/taxonomy/taxonomy.md index 3fc6dd9047..d143658417 100644 --- a/docs/content_management/taxonomy/taxonomy.md +++ b/docs/content_management/taxonomy/taxonomy.md @@ -212,6 +212,11 @@ ibexa: This way you can limit field selection to meaningful text fields and avoid unsupported field types. Like in the case of the number of suggestions, you can override this setting per AI action by editing its configuration. +!!! tip + + When selecting the input data for embedding creation, it's recommended to include only the essential information and limit the number of tokens sent. + Otherwise, the embedding models can generate values that don't correspond closely to the actual meaning of the input. + ### Change the embedding generation model By default, the system comes with a set of OpenAI models listed in its configuration, and a setting that allows you to choose the default model that should be used with the Taxonomy suggestions feature.