IBX-11401: Describe Gemini embeddings provider (#3120)

* IBX-11401: Describe Gemini embeddings provider

Author: dabrt

docs/ai_actions/ai_actions_guide.md

@@ -163,9 +163,14 @@ With some customization, administrators could use the API to run a batch process
 
 ### Suggesting taxonomy entries
 
-Content editors and product managers can use [taxonomy suggestions](taxonomy.md#taxonomy-suggestions) when assigning tags or product categorie to content items and products.
+Content editors and product managers can use [taxonomy suggestions](taxonomy.md#taxonomy-suggestions) when assigning tags or product categories to content items and products.
 Instead of manually browsing through extensive taxonomy trees, editors can request suggestions based on the content's text fields, such as name and description.
 
+!!! note "Alternative suggestion provider"
+
+    By default, embeddings used by the taxonomy suggestions feature are generated with OpenAI.
+    If you install and configure the [Google Gemini connector](configure_ai_actions.md#install-google-gemini-connector), you can modify the [taxonomy suggestions settings](taxonomy.md#change-embeddings-provider-to-google-gemini) and use Google Gemini as an alternative embeddings provider.
+
 ### Performing advanced image to text analysis
 
 With some additional customization, store managers could benefit from automating part of product management by integrating their [[= product_name =]] with Google Cloud Vision and [PIM](pim_guide.md) by using [[= product_name_connect =]].

docs/ai_actions/configure_ai_actions.md

@@ -8,13 +8,17 @@ month_change: false
 AI Actions are available in [[= product_name =]] regardless of its edition.
 To use this feature you must first configure the built-in service connectors or build your own ones.
 
-!!! note "Next steps"
+Once the framework is configured, before you can start using AI Actions, you can configure access to [[= product_name_base =]]-made service connectors by following the instructions below, or [create your own](extend_ai_actions.md#create-custom-action-handler).
 
-    Once the framework is configured, before you can start using AI Actions, you can configure access to [[= product_name_base =]]-made service connectors by following the instructions below, or [create your own](extend_ai_actions.md#create-custom-action-handler).
+Only then you can restart you application and start [working with the AI Actions feature]([[= user_doc =]]/ai_actions/work_with_ai_actions/).
 
-    Only then you can restart you application and start [working with the AI Actions feature]([[= user_doc =]]/ai_actions/work_with_ai_actions/).
+!!! note "Taxonomy suggestions"
+
+    The default OpenAI or the optional Google Gemini connectors can used by the [Taxonomy suggestions](taxonomy.md#taxonomy-suggestions) feature to generate embeddings for suggesting tags and product categories.
+    After you configure the OpenAI connector, or set up the optional Google Gemini connector and [modify the default taxonomy suggestions settings](taxonomy.md#change-embeddings-provider-to-google-gemini), you can [create AI actions that use the Text to Taxonomy action type]([[= user_doc =]]/ai_actions/work_with_ai_actions/#create-ai-actions-that-control-taxonomy-suggestions).
+    You can also create [your own embedding provider](taxonomy.md#replace-the-embedding-provider).
 
-## Configure access to OpenAI (optional)
+## Configure access to OpenAI
 
 To use the built-in connector with the OpenAI service, you need to create an OpenAI account, [get an API key](https://help.openai.com/en/articles/4936850-where-do-i-find-my-openai-api-key), and make sure that you [set up a billing method](https://help.openai.com/en/articles/9038407-how-can-i-set-up-billing-for-my-account).
 
@@ -32,12 +36,6 @@ The AI actions come with sample AI action configurations to quickly get you star
 
 Based on these examples, which reflect the most common use cases, you can learn to configure your own AI actions with greater ease.
 
-!!! note "Taxonomy suggestions"
-
-    OpenAI connector is also used by the [Taxonomy suggestions](taxonomy.md#taxonomy-suggestions) feature to generate embeddings for suggesting tags and product categories.
-    After you configure the connector, you can [create AI actions that use the Text to Taxonomy action type]([[= user_doc =]]/ai_actions/work_with_ai_actions/#create-ai-actions-that-control-taxonomy-suggestions).
-    You can also create [your own embedding provider](taxonomy.md#replace-the-embedding-provider).
-
 ## Install Anthropic connector [[% include 'snippets/lts-update_badge.md' %]]
 
 Run the following command to install the package:
@@ -187,6 +185,10 @@ When setting up models, make sure that you follow these rules:
 - `default_max_tokens` must not exceed the model’s limit
 - If you use the same model for different action types, settings must be consistent
 
+!!! note "Google Gemini and taxonomy suggestions"
+
+    To use Google Gemini for generating taxonomy suggestions, ensure that you [change the embeddings provider and model setting accordingly](taxonomy.md#change-embeddings-provider-to-google-gemini).
+
 You can now use the Gemini connector in your project.
 
 For more information, see [Extend Gemini connector](extend_ai_actions.md#extend-google-gemini-connector).

docs/content_management/taxonomy/taxonomy.md

@@ -100,7 +100,7 @@ ibexa:
 
 ## Remove orphaned content items
 
-In some rare case, especially in [[= product_name =]] v4.2 and older, when deleting parent of huge subtrees, some Taxonomy entries aren't properly deleted, leaving content items that point to a non-existing parent.
+In some rare case, especially in [[= product_name =]] v4.2 and older, when deleting parent of huge subtrees, some taxonomy entries aren't properly deleted, leaving content items that point to a non-existing parent.
 The command `ibexa:taxonomy:remove-orphaned-content` deletes those orphaned content item.
 It works on a taxonomy passed as an argument, and has two options that act as a protective measure against deleting data by mistake:
 
@@ -132,7 +132,7 @@ When it happens, the `Ibexa\Taxonomy\ActionHandler\TextToTaxonomyActionHandler`
 
 !!! 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 `text-to-taxonomy` handler.
 
 The search engine then compares the generated embedding with the taxonomy path embeddings stored in its index.
 By default, it selects the three best-matching taxonomy paths and presents them to the editor as suggestions.
@@ -145,23 +145,27 @@ However, before you can enable it, make sure the following prerequisites have be
 
 - [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+.
-- [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.
+- [AI Actions](ai_actions.md): To be able to process embeddings, Taxonomy suggestions require that you have the AI Actions configured to support the default [OpenAI](configure_ai_actions.md#configure-access-to-openai) or the optional [Google Gemini](configure_ai_actions.md#install-google-gemini-connector) service.
+
+!!! note "Alternative embeddings provider"
+
+    To use Google Gemini as an alternative embeddings provider, you must also modify the default [taxonomy suggestions settings](taxonomy.md#change-embeddings-provider-to-google-gemini).
 
 #### Enable taxonomy embedding indexing
 
-Enable embedding indexing for taxonomy branches by changing the default setting from `false` to `true`:
+Enable embedding indexing for taxonomy branches by changing the default setting from `false` to `true`.
+Toggle this setting at any time to enable or disable indexing of taxonomy embeddings.
 
-```yaml
+```yaml hl_lines="6"
 ibexa:
-  system:
-    default:
-      taxonomy:
-        search:
-          index_embeddings: true
+    system:
+        default:
+            taxonomy:
+                search:
+                    index_embeddings: true
+                    default_embedding_model: 'text-embedding-ada-002'
 ```
 
-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 search engine.
 
 ``` shell
@@ -220,34 +224,74 @@ Like in the case of the number of suggestions, you can override this setting per
     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
+### Change embedding generation models or embedding provider
 
-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.
+By default, the system comes with a set of OpenAI models that can be used for embedding generation.
+The following example shows these models listed in system configuration, together with a setting that controls what model is used when the editor requests taxonomy suggestions for an item.
+
+Also, here is where you can change the name of the model used by the provider, the embedding's dimensions, and other settings.
 
 ```yaml hl_lines="20"
 ibexa:
     system:
         default:
             embedding_models:
                 text-embedding-3-small:
-                    name: text-embedding-3-small
+                    name: 'text-embedding-3-small'
                     dimensions: 1536
-                    field_suffix: 3small
-                    embedding_provider: ibexa_openai
+                    field_suffix: '3small'
+                    embedding_provider: 'ibexa_openai'
                 text-embedding-3-large:
-                    name: text-embedding-3-large
+                    name: 'text-embedding-3-large'
                     dimensions: 3072
-                    field_suffix: 3large
-                    embedding_provider: ibexa_openai
+                    field_suffix: '3large'
+                    embedding_provider: 'ibexa_openai'
                 text-embedding-ada-002:
-                    name: 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
+                    field_suffix: 'ada002'
+                    embedding_provider: 'ibexa_openai'
+            default_embedding_model: 'text-embedding-ada-002'
 ```
 
-Also, here is where you can change the name of the model used by the provider, the embedding's dimensions, and other settings.
+!!! warning "Change both embedding generation models"
+
+    When you change the default suggestions generation model, ensure that you update the `ibexa.system.default.taxonomy.search.default_embedding_model` setting that is used for taxonomy indexing purposes.
+    Otherwise the taxonomy suggestions feature fails to find matching entries.
+
+#### Change embeddings provider to Google Gemini [[% include 'snippets/lts-update_badge.md' %]] 
+
+Once you have installed and configured the [Google Gemini connector](configure_ai_actions.md#install-google-gemini-connector), you can modify the default configuration to use the `ibexa_gemini` embedding provider and one of the [supported models](https://ai.google.dev/gemini-api/docs/embeddings):
+
+```yaml hl_lines="15 22"
+ibexa:
+    system:
+        default:
+            embedding_models:
+                gemini_embedding_001_1536:
+                    name: 'gemini-embedding-001'
+                    dimensions: 1536
+                    field_suffix: 'gemini_embedding_001_1536_dv'
+                    embedding_provider: 'ibexa_gemini'
+                gemini_embedding_001_3072:
+                    name: 'gemini-embedding-001'
+                    dimensions: 3072
+                    field_suffix: 'gemini_embedding_001_3072_dv'
+                    embedding_provider: 'ibexa_gemini'
+            default_embedding_model: 'gemini_embedding_001_1536'
+
+# ...
+
+            taxonomy:
+                search:
+                    index_embeddings: true
+                    default_embedding_model: 'gemini_embedding_001_1536'
+```
+
+After you make the change:
+
+- Update the [Solr schema](field_type_search.md#configuring-solr) or [Elasticsearch mappings](configure_elasticsearch.md#fine-tune-the-search-results) by adding dynamic field definitions. Ensure that they match the dimensions (for example, 1536 or 3072) and suffixes that you defined above
+- Clear the cache and reindex the search engine
 
 ### Extending Taxonomy suggestions