A recommendation system in the mill (part 3). Vertex AI Recommendations – Google’s recommendation service

June 2025 | Przegląd Zbożowo-Młynarski (Grain and Milling Review)

Vertex AI Recommendation (sometimes called the Retail API) is a service analogous to Amazon Personalize, offered by Google, directed especially at internet trade. Like AWS Personalize, it is a fully managed service, in which Google is responsible for training and hosting the recommendation models, while we supply the data and call the API in order to obtain recommendations. Google advertises it with the argument that it is the same technology which powers the recommendations in Google products (e.g. YouTube or Google Shopping).

Input data

To launch Vertex AI Recommendation we need two basic things: a product catalogue and data on user activity.

In the Vertex AI Recommendations service (formerly Recommendations AI) the model learns exclusively from so-called user events (events performed by the user). These are categorised in advance; for a typical e-commerce shop Google indicates four key events (priority user event types) – without them the model will not start, or will be of poor quality.

As for the type of user action: detail-page-view says what the user is really looking at; add-to-cart and purchase-complete are the strongest signals of preference; home-page-view gives the context of how many people saw the recommendations at all, it creates the context of exposure – the system knows how many users had a chance to see the recommendations and can distinguish better. The following situations are taken into account: „the user did not click, although they saw” (a negative signal) as distinct from „the user did not click, because no recommendations were shown to them at all” (no signal). Thanks to this the metrics (CTR, conversion) and the process of learning the rankings are more accurate, and the model learns faster which products really attract attention.

In Vertex AI Recommendation, every home-page-view recorded in the User Events stream means that the user saw the shop’s home page – and therefore probably also saw the module with the recommendations, although they did not necessarily click on it.

W-MOSZCZYNSKI pzm 6-25

How to prepare the data

Step 1. Map the application logs onto the four categories above:

• entry to /product/{id} → detail-page-view
• the „Add to cart” action → add-to-cart
• finalisation of the order → purchase-complete (here add revenue, currencyCode, quantity)
• entry to / → home-page-view

These four types of information: detail-page-view + add-to-cart + purchase-complete + home-page-view are the absolute minimum for Vertex AI Recommendations to achieve good quality in an e-commerce scenario.

Step 2. Extract the required columns (timestamp, userId, productId, qty, revenue) in a Spark job and save them, for example, to BigQuery in GCP.

Step 3. Use the BigQuery or Cloud Storage import. Google expects JSON files or a BQ table with the UserEvent schema. It is best to do the import daily, but in our scenario of an internet shop selling flour once a week is enough – on condition that you still supply the four types of events listed above.

What such an example JSON file looks like for a single „Add to cart” event → add-to-cart

Obligatory fields for every event:

• eventType – one of the four events from the list above: detail-page-view, add-to-cart, purchase-complete, home-page-view
• eventTime – a time stamp in RFC 3339 format
• userInfo.userId or visitorId – the identifier of the customer/session
• productEventDetail.productDetails[].id – the identifier of the product from the catalogue.

Step 4. Verify the quality. After the import, in the Vertex AI console go to Data quality → make sure that you have ≥ 100 unique visitorIds for each of detail-page-view, add-to-cart, purchase-complete; otherwise the model may fail to train.

Apart from the 4 events, Vertex AI may also use other information. Google does not guarantee that the ranking models will use these custom attributes, but it permits them in the UserInfo specification – it is therefore worth sending them, especially when the number of classic events is smaller.

An example of additional information for Vertex AI, „propensity for promotions”, which is not a separate eventType.

Where to obtain the said types of files describing customer behaviour?

The JSON files necessary for Vertex AI Recommendations to work are not generated by Google. Vertex AI Recommendations (formerly Recommendations AI) makes available a JSON schema and a public REST API (projects/locations/catalogs/eventStores/userEvents). It is the shop owner or the site administrator who has to collect the logs, convert them into ND-JSON (newline-delimited JSON) rows and load them:

• in real time – by sending every event directly to the userEvents:collect endpoint (POST HTTP),
• in batches, that is, in accordance with our assumptions of an internet shop selling flour – by saving an ND-JSON file in GCP in Cloud Storage or a table in BigQuery, calling the import operation.

The source of the data may be any: the application server, a JavaScript script on the front end, an export from an e-commerce platform, Apache logs, GA4 → BigQuery, etc. Google only requires that every record should have the four required fields (eventType, eventTime, userInfo, productEventDetail).

Is Vertex AI Recommendations „only for Google shops”?

Vertex AI Recommendations is a PaaS service added on to any shop or retail application, provided that:

1. A product catalogue is maintained in the Retail API format (ID, name, categories, price …).
2. User events are supplied consistent with the schema of the 4 events: detail-page-view, add-to-cart, purchase-complete, home-page-view.

The service does not require the shop to be hosted on the Google platform, nor the use of Google Merchant Center, although integration with Merchant Center makes importing the catalogue easier. This solution can therefore be applied to any internet shop. It is enough only to send the proper data in the proper format. In return we will receive recommendations.

How to create and load the catalogue?

You extract the data from your product database (Spark SQL in Synapse):

An example of a minimal record of a JSON file for a single product in the Retail API format

Every row must be a correct JSON object without newline characters.

• Minimum requirements: id, title, categories.
• Recommended commercial fields: priceInfo, availability, description, tags, attributes (any own characteristics, e.g. „gluten-free”, „organically certified”).

An example of a rich record of a JSON file for a single product in the Retail API format

The data have to be exported into the ND-JSON format and then imported into Vertex AI.

The typical path of data integration with Vertex AI

1. Export of data: events (view, add-to-cart, purchase) are extracted from the server application logs, the transactional database or GA4.
2. Transformation: in Spark, Dataflow or Python the data are converted into ND-JSON consistent with the Retail UserEvent.
3. Import: once a week importUserEvents is run from a file in Cloud Storage – in batch, or sent by streaming during the user’s session (collect API).
4. Training: Vertex AI automatically retrains the model when a new batch of events appears, or according to a schedule.
5. Retrieval of recommendations: the shop application calls the predict endpoint, giving the userId or visitorId and – optionally – the context (e.g. the product being viewed).

The Vertex AI Recommendations model works for every hosted e-commerce shop, on condition that two requirements are met: a catalogue is supplied and the user events are correctly formatted.

What does the cooperation of GCP with the shop’s website look like?

From my work with the GCP cloud it appears that this environment likes to work in real time and not in a batch system. This means that the shop from our example is permanently connected by the API protocol to Vertex AI Recommendations. Such cooperation of the shop with the Google cloud would look more or less like this.

The customer’s page calls to the cloud: „User ID:12345. It is 17:13 and they are just looking at the home page at product XYZ. What is worth showing them now?” That is, the page sends a package of JSON data with three things: who, when, what context.

In reply Vertex sends back a list of a few product identifiers, BC, XZ and BZ, arranged from „the most certainly on target” to „they might like this one too”. Vertex attaches a marker – the attributionToken – something like a badge saying „this list concerns query number 987”.

The shop receives this and displays the proposals to the customer: it converts the product IDs BC, XZ and BZ into the picture, the name and the price of the flour from the database; it shows them to the customer.

The shop observes how the customer reacted and reports to Vertex AI what happened. The shop sends Vertex a short note: „the list with token 987 has been displayed”.

If the customer clicked on the recommended product or bought it, the shop sends a second note: „the customer clicked on/bought product BZ from list 987”.

Thanks to this the cloud knows which suggestions were on target and which were not. This information is the basis for the model’s learning. The model learns so as to hit the target better next time. So the whole pipeline comes down to the exchange of protocols through an internet API:

• Query (give me recommendations)
• Reply (list of products + token)
• Reports (displayed, clicked, bought, with the token)

Summary

Google Cloud Vertex AI Recommendations is a ready-made engine which itself learns and serves product suggestions. All the shop’s work comes down to two technical obligations. First, the offer is described once – every product goes into an ND-JSON file with an identifier, a name, a category, a price and possible additional characteristics. Later, in a regular (e.g. weekly) rhythm, a second stream of data has to be generated: a simple list of user events saved in the same JSON format. Every line says that on a particular day and hour user X viewed a product page, added it to the basket or finalised a purchase. These two files are dropped into Cloud Storage or BigQuery, and Vertex AI itself recognises what is the catalogue and what is the history of behaviour, and trains the model without further interference.

When the site needs recommendations, the shop server sends a small HTTP query to the predict interface: „it’s me, user 123, I am looking at the home page – what will you recommend to me?”. The cloud sends back a neat list of product identifiers sorted according to relevance, plus a special token which has to be sent back when the customer sees the list, clicks or buys. This token allows Google to understand which suggestions turned out to be effective. The system itself analyses hundreds of such signals and from time to time (most often every few hours, but if need be once a week is enough) refreshes its own model so that the next lists are more accurate.

From the point of view of the e-commerce team, the whole of the artificial intelligence is located in a closed box. There is no need – and no possibility – to change the architecture of the network or to select hyperparameters. The human being plays the role of a supplier of well-formatted files and a caretaker of a simple API. This approach is ideal when speed of implementation and a minimum of ML code count, but it does not allow in-depth experiments or the inclusion of non-standard features directly in the model. Everything that happens after the data have been uploaded remains invisible, and the effects arrive in the form of ready-made lists of products. If, therefore, what is needed is pure convenience – „upload the files and forget” – Vertex AI Recommendations will meet expectations; if, on the other hand, the goal is full control over the algorithm and room for research, a more open solution has to be chosen, e.g. one’s own pipeline in Azure ML or Amazon Personalize.

Wojciech Moszczyński

Wojciech Moszczyński — graduate of the Department of Econometrics and Statistics of Nicolaus Copernicus University in Toruń; specialist in econometrics, finance, data science, and management accounting. He specializes in the optimization of production and logistics processes. He conducts research in the area of the development and application of artificial intelligence. For years he has been engaged in the popularization of machine learning and data science in business environments.