[Yandex Cloud documentation](../../index.md) > [Tutorials](../index.md) > [Building a data platform](index.md) > Using Yandex Managed Service for Valkey™ with the Search module and Yandex AI Studio models for vector search in a RAG system

# Using Yandex Managed Service for Valkey™ with the Search module and Yandex AI Studio models for vector search in a RAG system

# Using Yandex Managed Service for Valkey™ with the Search module and Yandex AI Studio models for vector search in a RAG system

RAG (retrieval-augmented generation) is an approach where a language model uses information retrieved from a database to answer a user's query.

This tutorial provides an example of a RAG system that uses [Yandex Managed Service for Valkey™](../../managed-valkey/index.md) to store data about people and perform vector search on that data using the [Search](../../managed-valkey/concepts/modules.md#valkey-search) module. [Yandex AI Studio](https://aistudio.yandex.ru/docs/en/ai-studio/concepts/index.html) models are used to generate an embedding for the search query and a response. Yandex Managed Service for Valkey™ and AI Studio work together using MCP.

When processing a search query, the system components work together as follows:

1. The Yandex AI Studio model receives the user's query and calls an MCP tool to search for data.
1. The MCP tool converts the query into an [embedding](https://aistudio.yandex.ru/docs/en/ai-studio/concepts/embeddings.html) using the Yandex AI Studio vector representation model and then sends the embedding to Yandex Managed Service for Valkey™.
1. Yandex Managed Service for Valkey™ runs a vector search using the `Search` module and returns the results to the MCP tool, which then sends them to the language model.
1. The language model analyzes the retrieved data and responds to the user.

This example requires a Unix-like environment and a Yandex Managed Service for Valkey™ cluster running version `9.0` or later.

The source code for the RAG system example is available in the SourceCraft [repository](https://sourcecraft.dev/valkey/webinar-260624-rag-example).

To set up your RAG system, follow these steps:

1. [Set up your infrastructure](#infra).
1. [Set up a testing environment](#prepare-test-environment).
1. [Prepare your test data and upload them to Yandex Managed Service for Valkey™](#prepare-test-data).
1. [Test the test data in Yandex Managed Service for Valkey™](#check-test-data).
1. [Run a search in the RAG system](#test-rag-search).

If you no longer need the resources you created, [delete them](#clear-out).


## Getting started {#before-you-begin}

Sign up for Yandex Cloud and create a [billing account](../../billing/concepts/billing-account.md):
1. Navigate to the [management console](https://console.yandex.cloud) and log in to Yandex Cloud or create a new account.
1. On the **[Yandex Cloud Billing](https://center.yandex.cloud/billing/accounts)** page, make sure you have a billing account linked and it has the `ACTIVE` or `TRIAL_ACTIVE` [status](../../billing/concepts/billing-account-statuses.md). If you do not have a billing account, [create one](../../billing/quickstart/index.md) and [link](../../billing/operations/pin-cloud.md) a cloud to it.

If you have an active billing account, you can create or select a [folder](../../resource-manager/concepts/resources-hierarchy.md#folder) for your infrastructure on the [cloud page](https://console.yandex.cloud/cloud).

[Learn more about clouds and folders here](../../resource-manager/concepts/resources-hierarchy.md).


### Required paid resources {#paid-resources}

* Yandex Managed Service for Valkey™ cluster: use of computing resources allocated to hosts, storage and backup size (see [Yandex Managed Service for Valkey™ pricing](../../managed-valkey/pricing.md)).
* AI assistant: number of request and response tokens (see [Yandex AI Studio pricing](https://aistudio.yandex.ru/docs/en/ai-studio/pricing.html)). You start paying for the assistant as soon as you activate it.
* Public IP addresses if public access is enabled for cluster hosts (see [Yandex Virtual Private Cloud pricing](../../vpc/pricing.md)).


## Set up your infrastructure {#infra}

{% list tabs group=instructions %}

- Manually {#manual}

  1. [Create a cloud network](../../vpc/operations/network-create.md) named `demo-network`.

      When creating a network, three subnets in different availability zones are created automatically.

  1. In `demo-network`, [create a security group](../../vpc/operations/security-group-create.md) named `valkey-sg` for the Yandex Managed Service for Valkey™ cluster and [add](../../vpc/operations/security-group-add-rule.md) the following inbound rule to the group to allow internet access to the cluster:

      * **Port range**: `6380`.
      * **Protocol**: `TCP`.
      * **Destination name**: `Address range`.
      * **IPv4 CIDR**: `0.0.0.0/0`.

  1. [Create a Yandex Managed Service for Valkey™](../../managed-valkey/operations/cluster-create.md) cluster of any suitable configuration with the following settings:

      * **Version**: `9.0` or higher.
      * **Network**: `demo-network`.
      * **Security group**: `valkey-sg`.
      * **TLS support**: Enabled.

      When creating your cluster, enable host public access and add the `Search` module.
    
      {% note info %}
      
      Public access to cluster hosts is required if you plan to connect to the cluster via the internet. This connection option is simpler and is recommended for the purposes of this guide. You can connect to non-public hosts as well but only from Yandex Cloud virtual machines located in the same cloud network as the cluster.
      
      {% endnote %}

- Using Terraform {#tf}
  
  1. If you do not have Terraform yet, [install it](../infrastructure-management/terraform-quickstart.md#install-terraform).
  1. [Get the authentication credentials](../infrastructure-management/terraform-quickstart.md#get-credentials). You can add them to environment variables or specify them later in the provider configuration file.
  1. [Configure and initialize a provider](../infrastructure-management/terraform-quickstart.md#configure-provider). Instead of manually creating the provider configuration file, you can [download it](https://github.com/yandex-cloud-examples/yc-terraform-provider-settings/blob/main/provider.tf).
  1. Place the configuration file in a separate working directory and [specify the parameter values](../infrastructure-management/terraform-quickstart.md#configure-provider). If you have not added the authentication credentials to environment variables, specify them in the configuration file.
  1. Download the [valkey-rag-search.tf](https://github.com/yandex-cloud-examples/yc-valkey-mcp-rag-search/blob/main/valkey-rag-search.tf) configuration file to your current working directory. This file describes:

      * [Network](../../vpc/concepts/network.md#network).
      * [Subnets](../../vpc/concepts/network.md#subnet).
      * [Security group](../../vpc/concepts/security-groups.md).
      * Yandex Managed Service for Valkey™ cluster with public access to its hosts and the `Search` module.

        {% note info %}
        
        Public access to cluster hosts is required if you plan to connect to the cluster via the internet. This connection option is simpler and is recommended for the purposes of this guide. You can connect to non-public hosts as well but only from Yandex Cloud virtual machines located in the same cloud network as the cluster.
        
        {% endnote %} 

  1. Specify the following in the configuration file:
        
      * `network_name`: Network name.
      * `sg_name`: Security group name.
      * `valkey_cluster_name`: Cluster name.
      * `valkey_password`: Password to access the cluster.

  1. Validate your Terraform configuration using this command:

      ```bash
      terraform validate
      ```

      Terraform will display any configuration errors detected in your files.

  1. Create the required infrastructure:

      1. Run this command to view the intended changes:
      
         ```bash
         terraform plan
         ```
      
         If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
      
      1. If everything looks correct, apply the changes:
      
         1. Run this command:
      
            ```bash
            terraform apply
            ```
      
         1. Confirm updating the resources.
         1. Wait for the operation to complete.

      All the required resources will be created in the specified folder. You can check resource availability and their settings in the [management console](https://console.yandex.cloud).

{% endlist %}


## Set up a testing environment {#prepare-test-environment}

1. [Install Python](https://www.python.org/) `3.11` or higher.
1. [Install Git](https://git-scm.com/downloads).
1. [Create a service account](../../iam/operations/sa/create.md#create-sa) named `sa-ai` and assign the [ai.languageModels.user](https://aistudio.yandex.ru/docs/en/ai-studio/security/index.html#languageModels-user) role to it for using Yandex AI Studio models.
1. [Create an API key](../../iam/operations/authentication/manage-api-keys.md) for the `sa-ai` service account.
1. [Clone](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/repo-clone) the SourceCraft repository with the example source code to your local computer:

    ```bash
    git clone https://git@git.sourcecraft.dev/valkey/webinar-260624-rag-example.git
    ```

1. Navigate to the repository directory:
    
    ```bash
    cd webinar-260624-rag-example
    ```

1. Set up the example environment:

    1. Install the dependencies:

        ```bash
        make install
        ```

    1. Activate the virtual environment:

        ```bash
        source .venv/bin/activate
        ```

1. Configure the Yandex Managed Service for Valkey™ and Yandex AI Studio access settings:

    1. Use the `.env.example` template to create a file named `.env`:

        ```bash
        cp .env.example .env
        ```

    1. Open the `.env` file in a text editor, such as `vim`:

        ```bash
        vim .env
        ```
    
    1. In the file, specify the following settings:
        
        * **YDS_API_KEY**: API key value.
        * **YDS_FOLDER_ID**: [Yandex Cloud folder](../../resource-manager/concepts/resources-hierarchy.md#folder) ID you can get with the [list of folders in the cloud](../../resource-manager/operations/folder/get-id.md).
        * **VALKEY_USERNAME**: `default`.
        * **VALKEY_PASSWORD**: Password to access the Yandex Managed Service for Valkey™ cluster.

        Sample file:

        ```text
        # Yandex AI Studio credentials
        # Get an API key: https://yandex.cloud/en/docs/ai-studio/operations/get-api-key
        YDS_API_KEY=AQVN1TpRw9tkjhKtj6R0mRgmHLvMsj84********
        YDS_FOLDER_ID=b1g4unjqq856********
        
        # Valkey auth (leave empty for local unauthenticated Valkey)
        VALKEY_USERNAME=default
        VALKEY_PASSWORD=********
        ```

1. Configure the Yandex Managed Service for Valkey™ cluster's connection settings:

    1. Open the `config.yaml` file in a text editor, such as `vim`:

        ```bash
        vim config.yaml
        ```

    1. Under `valkey`, specify the following:

        * **host**: `c-<cluster_ID>.rw.mdb.yandexcloud.net`.
            
          You can get the cluster ID with the [list of clusters in the folder](../../managed-valkey/operations/cluster-list.md#list-clusters).
        
        * **Port**: `6380`.
        * **db**: `0`.
        * **ssl**: `true`.

        Here is an example of the `valkey` section:

        ```yaml
        # Valkey connection settings
        valkey:
          host: "c-c9qlvmr5h2g9********.rw.mdb.yandexcloud.net"
          port: 6380
          db: 0
          # username + password read from .env: VALKEY_USERNAME, VALKEY_PASSWORD
          # SSL toggle for managed Valkey
          ssl: true
        ```

    In addition to the Yandex Managed Service for Valkey™ cluster's connection settings, the `config.yaml` file also contains settings for the following:
    
    * Yandex AI Studio models.
    * Index and vector search in Yandex Managed Service for Valkey™.
    * MCP server.
    * Orchestrator.
    * Language model's system prompt.
    * Logging.

    To make this example work, you only need to configure the Yandex Managed Service for Valkey™ cluster's connection settings. You can leave the other settings unchanged.


## Prepare your test data and upload it to Yandex Managed Service for Valkey™ {#prepare-test-data}

Run the following commands in the `webinar-260624-rag-example` repository directory:

1. Create a file named `data/people.json` with your test data:

    ```bash
    rag-demo generate -n 10
    ```

    Result:

    ```text
    Wrote 10 people to data/people.json
    ```

1. Upload the test data to Yandex Managed Service for Valkey™:

    ```bash
    rag-demo index
    ```

    This will create the `idx_people` index for your test data in the Yandex Managed Service for Valkey™ cluster.

    Result:

    ```text
      indexed person 1: Alice Smith
      indexed person 2: John Doe
      indexed person 3: Maria Garcia
      indexed person 4: Wei Zhang
      indexed person 5: James Brown
      indexed person 6: Priya Patel
      indexed person 7: Lars Nilsson
      indexed person 8: Olivia Wilson
      indexed person 9: Hassan Ali
      indexed person 10: Sophie Martin
    Loaded 10 people into index idx_people
    ```


## Test the test data in Yandex Managed Service for Valkey™ {#check-test-data}
    
1. Connect to the Yandex Managed Service for Valkey™ cluster database:

    {% list tabs group=instructions %}

    - Using `valkey-cli` {#with-valkey-cli}
      
      1. Navigate to the directory you want to download the Valkey™ distribution to.

      1. Download the correct Valkey™ [version](https://github.com/valkey-io/valkey/releases), then build and install it with TLS support:

          ```bash
          wget https://github.com/valkey-io/valkey/archive/refs/tags/<version>.tar.gz && \
          tar -xzvf <version>.tar.gz && \
          cd valkey-<version> && \
          make BUILD_TLS=yes && \
          sudo make install && \
          sudo cp ./src/valkey-cli /usr/bin/
          ```
      
      1. Obtain an SSL certificate:
        
          ```bash
          mkdir -p ~/.redis && \
          wget "https://storage.yandexcloud.net/cloud-certs/CA.pem" \
               --output-document ~/.redis/YandexInternalRootCA.crt && \
          chmod 0655 ~/.redis/YandexInternalRootCA.crt
          ```
          
          The certificate will be saved to the `~/.redis/YandexInternalRootCA.crt` file.
          
      1. Connect to the cluster:
          
          * For non-sharded clusters, run this command:

            ```bash
            valkey-cli \
                -h c-<cluster_ID>.rw.mdb.yandexcloud.net \
                -a <password> \
                -p 6380 \
                --tls \
                --cacert ~/.redis/YandexInternalRootCA.crt
            ```

            You can get the cluster ID with the [list of clusters in the folder](../../managed-valkey/operations/cluster-list.md#list-clusters).

          * For sharded clusters, run this command:
          
            ```bash
            valkey-cli \
                -h <FQDN_of_master_host_in_target_shard> \
                -c \
                -a <password> \
                -p 6380 \
                --tls \
                --cacert ~/.redis/YandexInternalRootCA.crt
            ```

            To learn how to get a host’s FQDN, see [FQDNs of Valkey™ hosts](../../managed-valkey/operations/connect/fqdn.md).

    - Using `redis-cli` {#with-redis-cli}

      1. Install `redis-cli`:

          ```bash
          sudo apt update && sudo apt install --yes redis-tools
          ```
            
      1. Obtain an SSL certificate:
        
          ```bash
          mkdir -p ~/.redis && \
          wget "https://storage.yandexcloud.net/cloud-certs/CA.pem" \
               --output-document ~/.redis/YandexInternalRootCA.crt && \
          chmod 0655 ~/.redis/YandexInternalRootCA.crt
          ```
          
          The certificate will be saved to the `~/.redis/YandexInternalRootCA.crt` file.

      1. Connect to the cluster:

          * For non-sharded clusters, run this command:

            ```bash
            redis-cli \
                -h c-<cluster_ID>.rw.mdb.yandexcloud.net \
                -a <password> \
                -p 6380 \
                --tls \
                --cacert ~/.redis/YandexInternalRootCA.crt
            ```

            You can get the cluster ID with the [list of clusters in the folder](../../managed-valkey/operations/cluster-list.md#list-clusters).

          * For sharded clusters, run this command:

            ```bash
            redis-cli \
                -h <FQDN_of_master_host_in_target_shard> \
                -c \
                -a <password> \
                -p 6380 \
                --tls \
                --cacert ~/.redis/YandexInternalRootCA.crt
            ```

            To learn how to get a host’s FQDN, see [FQDNs of Valkey™ hosts](../../managed-valkey/operations/connect/fqdn.md).

    - Using Yandex WebSQL {#with-websql}

      Before connecting, [enable](../../managed-valkey/operations/update.md#change-additional-settings) [Yandex WebSQL](../../websql/index.md) access in the cluster settings.

      To connect to a database using Yandex WebSQL:

      1. In the [management console](https://console.yandex.cloud), select the folder containing the cluster.
      1. [Navigate](../../console/operations/select-service.md#select-service) to **Yandex Managed Service for&nbsp;Valkey™**.
      1. Click the name of your cluster and select the **WebSQL** tab.
      1. Click **Go to WebSQL** in the top-right corner of the page.
    
    {% endlist %}
  
1. Get information about the `idx_people` index:

    ```bash
    FT.INFO idx_people
    ```

    Verify the parameter values in the output:
    
    * **num_docs**: `10`.
    * **state**: `ready`.

1. Get a list of keys in the cluster:

    ```bash
    KEYS *
    ```

    Result:

    ```text
    1) "person:1"
    2) "person:2"
    3) "person:3"
    4) "person:4"
    5) "person:5"
    6) "person:9"
    7) "person:id_counter"
    8) "person:6"
    9) "person:7"
    10) "person:8"
    11) "person:10"
    ```

    Where `person:id_counter` is the service key that stores the ID counter value.

1. View the `person:1` key data:

    ```bash
    HGETALL person:1
    ```


## Run a search in the RAG system {#test-rag-search}

Run the following commands in the `webinar-260624-rag-example` repository directory:

1. Run a search for `Who works with Kubernetes?`:

    ```bash
    rag-demo ask "Who works with Kubernetes?"
    ```

    Result:

    ```text
    Lars Nilsson works with Kubernetes. He is a site reliability engineer in Stockholm, Sweden, responsible for keeping large Kubernetes clusters healthy.
    ```

    Along with the model's response, the output shows detailed information on the query execution. To hide this information, specify `console_level: "WARNING"` in the `logging` section of the `config.yaml` file. The output will then include a summary of the query execution and the model's final response.

1. Run a search for `Who is into running?`:

    ```bash
    rag-demo ask "Who is into running?"
    ```

    Result:

    ```text
    Among the people found, **Wei Zhang** (38 years old, Tokyo, Japan) is into running and trains for marathons.
    ```


## Delete the resources you created {#clear-out}

Some resources are not free of charge. Delete the resources you no longer need to avoid paying for them:

{% list tabs group=instructions %}

- Manually {#manual}

  [Delete the Yandex Managed Service for Valkey™ cluster](../../managed-valkey/operations/cluster-delete.md).

- Using Terraform {#tf}

  1. In the terminal window, go to the directory containing the infrastructure plan.
  
      {% note warning %}
  
      Make sure the directory has no Terraform manifests with the resources you want to keep. Terraform deletes all resources that were created using the manifests in the current directory.
  
      {% endnote %}
  
  1. Delete resources:
  
      1. Run this command:
  
          ```bash
          terraform destroy
          ```
  
      1. Confirm deleting the resources and wait for the operation to complete.
  
      All the resources described in the Terraform manifests will be deleted.

{% endlist %}