From 123454cbb4c927b4d4152d8abcd4ea9af5472404 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Fri, 23 Jan 2026 09:42:10 +0100 Subject: [PATCH 1/9] IBX-10998: Document Gemini connector --- docs/ai_actions/ai_actions_guide.md | 2 +- docs/ai_actions/configure_ai_actions.md | 108 ++++++++++++++++++++++++ docs/ai_actions/extend_ai_actions.md | 61 +++++++++++++ 3 files changed, 170 insertions(+), 1 deletion(-) diff --git a/docs/ai_actions/ai_actions_guide.md b/docs/ai_actions/ai_actions_guide.md index 9c4fa86ba0..3b1ac01406 100644 --- a/docs/ai_actions/ai_actions_guide.md +++ b/docs/ai_actions/ai_actions_guide.md @@ -12,7 +12,7 @@ Wherever you look, artificial intelligence becomes more and more important by en AI Actions is an extensible solution for integrating features provided by AI services into your workflows, all managed through a user-friendly interface. Out-of-the-box, AI Actions solution includes two essential components: a framework package and an OpenAI connector package. -The Anthropic connector is also available - as an [LTS update](editions.md#lts-updates). +The Anthropic and Gemini connectors are also available - as [LTS updates](editions.md#lts-updates). AI Actions can integrate with [[[= product_name_connect =]]]([[= connect_doc =]]/general/ibexa_connect/), to give you an opportunity to build complex data transformation workflows without having to rely on custom code. From the developer's perspective, the integration removes the burden of maintaining third-party AI handlers, and accelerates the deployment of AI-based solutions. diff --git a/docs/ai_actions/configure_ai_actions.md b/docs/ai_actions/configure_ai_actions.md index 7c64f9e344..0be4277e2b 100644 --- a/docs/ai_actions/configure_ai_actions.md +++ b/docs/ai_actions/configure_ai_actions.md @@ -77,6 +77,114 @@ ibexa_connector_anthropic: ``` You can now use the Anthropic connector in your project. +## Install Google Gemini connector [[% include 'snippets/lts-update_badge.md' %]] + +Run the following command to install the package: + +``` bash +composer require ibexa/connector-gemini +``` + +This command adds the feature code, including basic handlers that let you refine text or generate alternative text for images. + +### Get API key + +To use the connector with the Gemini services, you need to create an account, set up billing, enable Gemini API and get an API key. + +#### Create the Google Cloud project + +1. Sign in to the [Google Cloud Console](https://console.cloud.google.com/). +1. In the top bar, click **Default Gemini Project** to open a project picker. +1. Click **New project** and provide project details: + 1. Add project name, for example, "My project". + 1. Modify the automatically generated **Project ID** if necessary. + 1. Select location: choose your organization. +1. Click **Create**. + +#### Configure billing + +1. Navigate to the Google Cloud Console's **Billing** page. +1. If you do not have one, click **Add billing account** and add a payment method. +1. In **Your projects** tab, locate your project, and in it's line, from the **Actions** menu, select **Change billing**. +1. Select your active billing account, and click **Set account**. + +#### Enable the Gemini API + +1. Navigate to the Google Cloud Console's **APIs & Services** page. +1. From the left-hand menu, select **Library** and search for the Generative Language API. +1. In the API's details page, click **Enable**. + +#### Generate the API key + +1. Go to [Google AI Studio](https://aistudio.google.com/app/api-keys)'s **API keys** page, and click **Create API key**. +1. Provide a name for the API key, select "My project" from a list of projects and click **Create key**. +1. Back inn the **API keys** list, in your project's line, copy the API key. + +### Set API key in configuration + +Then, in the root folder of your project, modify the `.env` file: add an `GEMINI_API_KEY` variable and populate its value with the API key that you got from the AI service. + +```bash +###> ibexa/connector-gemini ### +GEMINI_API_KEY= +###< ibexa/connector-gemini ### +``` + +!!! note "Different API keys for different SiteAccesses" + + If there are multiple SiteAccesses in your installation, you can set different API keys for each SiteAccess. + To do it, set the keys under the `ibexa.system.` [configuration key](configuration.md#configuration-files), like so: + + ```yaml + ibexa: + system: + default: + connector_gemini: + gemini: + api_key: '%env(GEMINI_API_KEY)%' + base_url: 'https://generativelanguage.googleapis.com/v1beta/' + ``` + +### Configure default models + +By default, when reaching out for responses, the Gemini connector uses the Gemini Pro [model](https://ai.google.dev/gemini-api/docs/models) for text refinement and Gemini Flash model for alternative text generation. +Users can override this setting at runtime when they [edit or create an AI action]([[= user_doc =]]/ai_actions/work_with_ai_actions/#edit-existing-ai-actions). +You can also change the default values globally. +To do it, in `config/packages` folder, create a YAML file similar to this example: + +```yaml + ibexa_connector_gemini: + text_to_text: + models: + gemini-pro-latest: + label: 'Gemini Pro Latest' + max_tokens: 4096 + gemini-flash-latest: + label: 'Gemini Flash Latest' + max_tokens: 4096 + default_model: gemini-pro-latest + default_max_tokens: 4096 # must be <= the model’s max_tokens + default_temperature: 0.8 + image_to_text: + models: + gemini-flash-latest: + label: 'Gemini Flash Latest' + max_tokens: 4096 + default_model: gemini-flash-latest + default_max_tokens: 4096 + default_temperature: 1.0 +``` + +When setting up models, make sure that you follow these rules: + +- `default_model` must reference a configured model +- `default_max_tokens` must not exceed the model’s limit +- If you use the same model for different action types, settings must be consistent + +You can now use the Gemini connector in your project. + +For more information, see [Extend AI actions](extend_ai_actions.md#extend-gemini-connector). + ## Configure access to [[= product_name_connect =]] First, get the credentials by contacting [Ibexa Support](https://support.ibexa.co). diff --git a/docs/ai_actions/extend_ai_actions.md b/docs/ai_actions/extend_ai_actions.md index 5674155151..75404b80b8 100644 --- a/docs/ai_actions/extend_ai_actions.md +++ b/docs/ai_actions/extend_ai_actions.md @@ -374,3 +374,64 @@ See [configuring assets from main project files](importing_assets_from_bundle.md Your custom Action Type is now fully integrated into the back office UI and can be used by the Editors. ![Transcribe Audio Action Type integrated into the back office](img/transcribe_audio.png "Transcribe Audio Action Type integrated into the back office") + +## Extend Gemini connector [[% include 'snippets/lts-update_badge.md' %]] + +The Gemini connector provides several extension points that allow you to customize available models, behavior, validation, and response handling, while remaining compatible with the AI Actions framework. + +The connector builds Gemini requests in an options provider and formats responses through a response formatter. +Both components can be replaced or extended to customize how requests are constructed and how responses are normalized. + +### Add or customize models + +You can register additional Gemini models or customize existing ones by extending the connector’s model [configuration](configure_ai_actions.md#configure-default-models). + +Extend the models map by defining: + +- a human-readable label +- a `max_tokens` limit + +Optionally, you can set the default model that would be used for the action type that you're modifying, the default allowed tokens limit and the default temperature. +Default values must stay within the limits supported by the [Gemini API](https://ai.google.dev/gemini-api/docs/models). + +### Add a custom action handler + +To introduce a new Gemini-based AI action: + +1. Create a handler that extends `Ibexa\Contracts\ConnectorAi\Action\AbstractActionHandler`. +1. Register the handler in `services/ai_action_handlers.yaml`. +1. Provide supporting components as needed: + - a prompt factory + - a form type for configuration + - validators for action options + +This follows the same extension mechanism as other [custom AI actions](#create-custom-action-handler). + +### Add custom response formatting + +To change how Gemini responses are post-processed or normalized: + +1. Implement the `GeminiResponseFormatterInterface` class. +1. Alias your implementation in the service container to override the default formatter. + +### Add custom validation + +Add extra validation rules for Gemini action configuration options by tagging custom validators: + +- For `text-to-text` actions: + + ``` yaml + ibexa.connector_ai.action_configuration.options.validator.gemini_text_to_text + ``` + +- For `image-to-text` actions: + + ``` yaml + ibexa.connector_ai.action_configuration.options.validator.gemini_image_to_text + ``` + +### Replace the Gemini client impplementation + +To get full control over the low-level API communication without modifying the connector itself, you can swap the Gemini client implementation enetirely with your own: + +- Use dependency injection to bind your own implementation to `Ibexa\ConnectorGemini\Client\GeminiClientInterface`. From 1c74adaa94be1f3f07e857c46de1bde42432c839 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Fri, 23 Jan 2026 13:25:04 +0100 Subject: [PATCH 2/9] Update docs/ai_actions/extend_ai_actions.md Co-authored-by: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com> --- docs/ai_actions/extend_ai_actions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ai_actions/extend_ai_actions.md b/docs/ai_actions/extend_ai_actions.md index 75404b80b8..6f5d2ae40b 100644 --- a/docs/ai_actions/extend_ai_actions.md +++ b/docs/ai_actions/extend_ai_actions.md @@ -432,6 +432,6 @@ Add extra validation rules for Gemini action configuration options by tagging cu ### Replace the Gemini client impplementation -To get full control over the low-level API communication without modifying the connector itself, you can swap the Gemini client implementation enetirely with your own: +To get full control over the low-level API communication without modifying the connector itself, you can swap the Gemini client implementation entirely with your own: - Use dependency injection to bind your own implementation to `Ibexa\ConnectorGemini\Client\GeminiClientInterface`. From 1b1d23f3497bb7f6dd4736ef55a2ea18c496d526 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Mon, 26 Jan 2026 15:30:57 +0100 Subject: [PATCH 3/9] Implement reviewer comments --- docs/ai_actions/configure_ai_actions.md | 18 +++++++++--------- docs/ai_actions/extend_ai_actions.md | 6 +++--- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/ai_actions/configure_ai_actions.md b/docs/ai_actions/configure_ai_actions.md index 0be4277e2b..424ec2337c 100644 --- a/docs/ai_actions/configure_ai_actions.md +++ b/docs/ai_actions/configure_ai_actions.md @@ -105,7 +105,7 @@ To use the connector with the Gemini services, you need to create an account, se 1. Navigate to the Google Cloud Console's **Billing** page. 1. If you do not have one, click **Add billing account** and add a payment method. -1. In **Your projects** tab, locate your project, and in it's line, from the **Actions** menu, select **Change billing**. +1. In **Your projects** tab, locate your project, and in its line, from the **Actions** menu, select **Change billing**. 1. Select your active billing account, and click **Set account**. #### Enable the Gemini API @@ -113,8 +113,8 @@ To use the connector with the Gemini services, you need to create an account, se 1. Navigate to the Google Cloud Console's **APIs & Services** page. 1. From the left-hand menu, select **Library** and search for the Generative Language API. 1. In the API's details page, click **Enable**. - -#### Generate the API key + +#### Generate the API key 1. Go to [Google AI Studio](https://aistudio.google.com/app/api-keys)'s **API keys** page, and click **Create API key**. 1. Provide a name for the API key, select "My project" from a list of projects and click **Create key**. @@ -138,11 +138,11 @@ GEMINI_API_KEY= ```yaml ibexa: system: - default: - connector_gemini: - gemini: - api_key: '%env(GEMINI_API_KEY)%' - base_url: 'https://generativelanguage.googleapis.com/v1beta/' + default: + connector_gemini: + gemini: + api_key: '%env(GEMINI_API_KEY)%' + base_url: 'https://generativelanguage.googleapis.com/v1beta/' # Google Gemini's API endpoint ``` ### Configure default models @@ -163,7 +163,7 @@ To do it, in `config/packages` folder, create a YAML file similar to this exampl label: 'Gemini Flash Latest' max_tokens: 4096 default_model: gemini-pro-latest - default_max_tokens: 4096 # must be <= the model’s max_tokens + default_max_tokens: 4096 # Must be <= the model’s max_tokens default_temperature: 0.8 image_to_text: models: diff --git a/docs/ai_actions/extend_ai_actions.md b/docs/ai_actions/extend_ai_actions.md index 75404b80b8..eb4be44aba 100644 --- a/docs/ai_actions/extend_ai_actions.md +++ b/docs/ai_actions/extend_ai_actions.md @@ -394,7 +394,7 @@ Extend the models map by defining: Optionally, you can set the default model that would be used for the action type that you're modifying, the default allowed tokens limit and the default temperature. Default values must stay within the limits supported by the [Gemini API](https://ai.google.dev/gemini-api/docs/models). -### Add a custom action handler +### Add a custom Action Handler To introduce a new Gemini-based AI action: @@ -411,7 +411,7 @@ This follows the same extension mechanism as other [custom AI actions](#create-c To change how Gemini responses are post-processed or normalized: -1. Implement the `GeminiResponseFormatterInterface` class. +1. Implement the `GeminiResponseFormatterInterface` interface. 1. Alias your implementation in the service container to override the default formatter. ### Add custom validation @@ -430,7 +430,7 @@ Add extra validation rules for Gemini action configuration options by tagging cu ibexa.connector_ai.action_configuration.options.validator.gemini_image_to_text ``` -### Replace the Gemini client impplementation +### Replace the Gemini client implementation To get full control over the low-level API communication without modifying the connector itself, you can swap the Gemini client implementation enetirely with your own: From c01701721e16cefa4c75664764d1a4a5eeec7491 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Tue, 27 Jan 2026 13:43:57 +0100 Subject: [PATCH 4/9] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Marek Nocoń --- docs/ai_actions/configure_ai_actions.md | 2 +- docs/ai_actions/extend_ai_actions.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ai_actions/configure_ai_actions.md b/docs/ai_actions/configure_ai_actions.md index 424ec2337c..80b8e760f1 100644 --- a/docs/ai_actions/configure_ai_actions.md +++ b/docs/ai_actions/configure_ai_actions.md @@ -118,7 +118,7 @@ To use the connector with the Gemini services, you need to create an account, se 1. Go to [Google AI Studio](https://aistudio.google.com/app/api-keys)'s **API keys** page, and click **Create API key**. 1. Provide a name for the API key, select "My project" from a list of projects and click **Create key**. -1. Back inn the **API keys** list, in your project's line, copy the API key. +1. Back in the **API keys** list, in your project's line, copy the API key. ### Set API key in configuration diff --git a/docs/ai_actions/extend_ai_actions.md b/docs/ai_actions/extend_ai_actions.md index 89327358bc..ce5429e9c6 100644 --- a/docs/ai_actions/extend_ai_actions.md +++ b/docs/ai_actions/extend_ai_actions.md @@ -411,7 +411,7 @@ This follows the same extension mechanism as other [custom AI actions](#create-c To change how Gemini responses are post-processed or normalized: -1. Implement the `GeminiResponseFormatterInterface` interface. +1. Implement the `Ibexa\ConnectorGemini\Response\GeminiResponseFormatterInterface` interface. 1. Alias your implementation in the service container to override the default formatter. ### Add custom validation From b3bfe14d5d96f121e7ccf2fc47d65f5267e05e38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Tue, 27 Jan 2026 17:54:40 +0100 Subject: [PATCH 5/9] Add RN entry --- docs/ai_actions/configure_ai_actions.md | 2 +- docs/ai_actions/extend_ai_actions.md | 2 +- docs/ibexa_products/editions.md | 1 + docs/release_notes/ibexa_dxp_v5.0.md | 10 ++++++++++ 4 files changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/ai_actions/configure_ai_actions.md b/docs/ai_actions/configure_ai_actions.md index 80d46f9645..8b924d6864 100644 --- a/docs/ai_actions/configure_ai_actions.md +++ b/docs/ai_actions/configure_ai_actions.md @@ -189,7 +189,7 @@ When setting up models, make sure that you follow these rules: You can now use the Gemini connector in your project. -For more information, see [Extend AI actions](extend_ai_actions.md#extend-gemini-connector). +For more information, see [Extend Gemini connector](extend_ai_actions.md#extend-google-gemini-connector). ## Configure access to [[= product_name_connect =]] diff --git a/docs/ai_actions/extend_ai_actions.md b/docs/ai_actions/extend_ai_actions.md index ce5429e9c6..e6976f7bc8 100644 --- a/docs/ai_actions/extend_ai_actions.md +++ b/docs/ai_actions/extend_ai_actions.md @@ -375,7 +375,7 @@ Your custom Action Type is now fully integrated into the back office UI and can ![Transcribe Audio Action Type integrated into the back office](img/transcribe_audio.png "Transcribe Audio Action Type integrated into the back office") -## Extend Gemini connector [[% include 'snippets/lts-update_badge.md' %]] +## Extend Google Gemini connector [[% include 'snippets/lts-update_badge.md' %]] The Gemini connector provides several extension points that allow you to customize available models, behavior, validation, and response handling, while remaining compatible with the AI Actions framework. diff --git a/docs/ibexa_products/editions.md b/docs/ibexa_products/editions.md index bbc686efa5..be01207d3d 100644 --- a/docs/ibexa_products/editions.md +++ b/docs/ibexa_products/editions.md @@ -67,4 +67,5 @@ The features brought by LTS Updates become standard parts of the next LTS releas | Feature | [[= product_name_headless =]] | [[= product_name_exp =]] | [[= product_name_com =]] | |-----------------|-----------------|-----------------|-----------------| | [Anthropic connector](configure_ai_actions.md#install-anthropic-connector) | ✔ | ✔ | ✔ | +| [Google Gemini connector](configure_ai_actions.md#install-google-gemini-connector) | ✔ | ✔ | ✔ | | [Integrated help](integrated_help.md) | ✔ | ✔ | ✔ | diff --git a/docs/release_notes/ibexa_dxp_v5.0.md b/docs/release_notes/ibexa_dxp_v5.0.md index 074b312180..26db48efd8 100644 --- a/docs/release_notes/ibexa_dxp_v5.0.md +++ b/docs/release_notes/ibexa_dxp_v5.0.md @@ -10,6 +10,16 @@ month_change: false
+[[% set version = 'v5.0.6' %]] + +[[= release_note_entry_begin("Google Gemini connector " + version, '2026-02-03', ['Headless', 'Experience', 'Commerce', 'LTS Update', 'New feature']) =]] + +This release introduces a new AI connector that allows you to integrate [AI Actions](ai_actions.md) with [Google Gemini](https://gemini.google/overview/#what-gemini-is). + +For more information, see how to [install and configure the Google Gemini connector](configure_ai_actions.md#install-google-gemini-connector). + +[[= release_note_entry_end() =]] + [[% set version = 'v5.0.5' %]] [[= release_note_entry_begin("Ibexa DXP " + version, '2026-01-15', ['Headless', 'Experience', 'Commerce']) =]] From 544addfa3f31ae73776344cec40bffc9e8675fbd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Fri, 10 Apr 2026 18:44:45 +0200 Subject: [PATCH 6/9] IBX-11401: Describe Gemini embeddings provider (#3120) * IBX-11401: Describe Gemini embeddings provider --- docs/ai_actions/ai_actions_guide.md | 7 +- docs/ai_actions/configure_ai_actions.md | 22 ++--- docs/content_management/taxonomy/taxonomy.md | 94 ++++++++++++++------ 3 files changed, 87 insertions(+), 36 deletions(-) diff --git a/docs/ai_actions/ai_actions_guide.md b/docs/ai_actions/ai_actions_guide.md index fd648717e6..9d1fcb9ed9 100644 --- a/docs/ai_actions/ai_actions_guide.md +++ b/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 =]]. diff --git a/docs/ai_actions/configure_ai_actions.md b/docs/ai_actions/configure_ai_actions.md index 8b924d6864..079d0c68a7 100644 --- a/docs/ai_actions/configure_ai_actions.md +++ b/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). diff --git a/docs/content_management/taxonomy/taxonomy.md b/docs/content_management/taxonomy/taxonomy.md index f145915bd8..da66dcb036 100644 --- a/docs/content_management/taxonomy/taxonomy.md +++ b/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,9 +224,12 @@ 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: @@ -230,24 +237,61 @@ ibexa: 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 From 4a207ee86cb03f009da1c1ba26f815d36e9672b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20D=C4=85browski?= <64841871+dabrt@users.noreply.github.com> Date: Tue, 14 Apr 2026 11:06:03 +0200 Subject: [PATCH 7/9] Remove the RN entry --- docs/release_notes/ibexa_dxp_v5.0.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/release_notes/ibexa_dxp_v5.0.md b/docs/release_notes/ibexa_dxp_v5.0.md index 26db48efd8..074b312180 100644 --- a/docs/release_notes/ibexa_dxp_v5.0.md +++ b/docs/release_notes/ibexa_dxp_v5.0.md @@ -10,16 +10,6 @@ month_change: false
-[[% set version = 'v5.0.6' %]] - -[[= release_note_entry_begin("Google Gemini connector " + version, '2026-02-03', ['Headless', 'Experience', 'Commerce', 'LTS Update', 'New feature']) =]] - -This release introduces a new AI connector that allows you to integrate [AI Actions](ai_actions.md) with [Google Gemini](https://gemini.google/overview/#what-gemini-is). - -For more information, see how to [install and configure the Google Gemini connector](configure_ai_actions.md#install-google-gemini-connector). - -[[= release_note_entry_end() =]] - [[% set version = 'v5.0.5' %]] [[= release_note_entry_begin("Ibexa DXP " + version, '2026-01-15', ['Headless', 'Experience', 'Commerce']) =]] From 4e5a374e574d4e1ae4452c8b859fd0c914ec45dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Tue, 14 Apr 2026 14:26:54 +0200 Subject: [PATCH 8/9] Fied broken link --- docs/search/embeddings_reference/embeddings_reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/search/embeddings_reference/embeddings_reference.md b/docs/search/embeddings_reference/embeddings_reference.md index 5ca5bbc737..a9c2e6b67c 100644 --- a/docs/search/embeddings_reference/embeddings_reference.md +++ b/docs/search/embeddings_reference/embeddings_reference.md @@ -78,7 +78,7 @@ ibexa: default_embedding_model: text-embedding-ada-002 ``` -For a real-life example of embedding models configuration, see [Taxonomy suggestions](taxonomy.md#change-the-embedding-generation-model). +For a real-life example of embedding models configuration, see [Taxonomy suggestions](taxonomy.md#change-embedding-generation-models-or-embedding-provider). - [EmbeddingConfigurationInterface](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Search-Embedding-EmbeddingConfigurationInterface.html) allows access to the embedding model configuration in the system (for example, list of available models, default model name, default provider, field suffix, and so on) From 58f5d5f43fbc1aa14100270fff4abde46569b1df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Noco=C5=84?= Date: Tue, 14 Apr 2026 14:27:09 +0200 Subject: [PATCH 9/9] Fixed event page name --- docs/api/event_reference/event_reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/event_reference/event_reference.md b/docs/api/event_reference/event_reference.md index 5f4bff1cec..389db92df3 100644 --- a/docs/api/event_reference/event_reference.md +++ b/docs/api/event_reference/event_reference.md @@ -19,7 +19,7 @@ For example, copying a content item is connected with two events: `BeforeCopyCon [[= cards([ "api/event_reference/ai_action_events", "api/event_reference/cart_events", - "api/event_reference/catalog_events", + "api/event_reference/product_catalog_events", "api/event_reference/collaboration_events", "api/event_reference/content_events", "api/event_reference/content_type_events",