.. _migrate:

Migrate Feature Vectors to a Different Neural Network Model
==============================================================

This section is about how to migrate object feature vectors to another neural network model.

.. seealso::

  :ref:`sf-api-migrate options <migration-config>`.

To migrate to a different neural network model, do the following:

#. Create a backup of the Tarantool-based feature vector database in any directory of your choice, for example, ``/opt/ffserver/dumps``.

   .. code::

      docker exec -it sf-api bash -c "mkdir dumps; cd dumps && /storage-api-dump -config /sf-api.yaml"
      docker cp sf-api-:/dumps /opt/ffserver

#. Create new shards that will host regenerated feature vectors.

   #. Navigate to the directory for stored data (for example, ``/opt/ffserver/data/tnt``) and find out the number of shards by counting the number of directories.

      .. note::
         There are two shards in the example below.

      .. code::

         cd /opt/ffserver/data/tnt

         ls -l

         shard-001
         shard-002

   #. Create directories that will host files of the new shards.

      .. code::

         sudo mkdir -p shard-01{1..2}/{index,snapshots,xlogs}

#. Open the ``/opt/ffserver/configs/extraction-api.yaml`` configuration file and replace the extraction models with the new ones in the emben parameters (``body_emben``, ``car_emben`` and ``face_emben``), depending on the object types you want to migrate.


   .. important::
      Be sure to choose the right acceleration type for each model, matching the acceleration type of ``extraction-api``: CPU or GPU. Be aware that ``extraction-api`` on CPU can work only with CPU-models, while ``extraction-api`` on GPU supports both CPU- and GPU-models.

   .. code::

      sudo vi /opt/ffserver/configs/extraction-api.yaml

   .. rubric:: CPU

   .. code::

      extractors:
        ...
        models:
          ...
           face_emben:
              default:
                model: face/<new_model_face>.cpu.fnk
           ...

   .. rubric:: GPU

   .. code::

      extractors:
        ...
        models:
          ...
           face_emben:
              default:
                model: face/<new_model_face>.gpu.fnk


#. Create new ``tntapi`` containers for each new shard. To do that, copy the ``docker run`` command of the existing service and replace the name of the shard and the path to the shard in the ``--volume`` flag.

   .. code::

    docker run -tid --name tnt-new-1 --restart always --network server \
        --env CFG_LISTEN_HOST=0.0.0.0 \
        --env CFG_NTLS=ntls:3133 \
        --env TT_LISTEN=0.0.0.0:32001 \
        --env TT_MEMTX_MEMORY=$((1024 * 1024 * 1024)) \
        --volume /opt/ffserver/tnt/001-new:/opt/ntech/var/lib/tarantool/default \
        docker.int.ntl/ntech/universe/tntapi:ffserver-12.240830.2

   Use environment environment and configuration flags:

   * ``CFG_LISTEN_HOST=0.0.0.0``: host to public HTTP API.
   * ``CFG_NTLS=ntls:3133``: host and port of the ``ntls`` server.
   * ``TT_LISTEN=0.0.0.0:32001``: binary host/port, used for admin operations and replication.
   * ``TT_MEMTX_MEMORY=$((1024 * 1024 * 1024))``: the maximum memory usage in bytes.
   * ``/opt/ffserver/tnt/``: the directory on the host to store ``tntapi`` data.

#. Create a default ``sf-api-migrate`` configuration file. You can find its default content :download:`here <_scripts/sf-api-migrate.yaml>`.

   .. code::

      docker run --rm -ti --entrypoint "/sf-api-migrate" docker.int.ntl/ntech/universe/sf-api:ffserver-12.240830.2 \
          --config-template > /opt/ffserver/configs/sf-api-migrate.yaml

   * ``/opt/ffserver/configs/``: the directory on the host to store the configuration file.

#. In the ``storage-api-from`` section, specify the old shards to migrate the data from.

   .. code::

      storage-api-from: # current location of the gallery
        ...
        shards:
          - master: http://tnt-old-1:8001/v2/
            slaves: []
          - master: http://tnt-old-2:8001/v2/
            slaves: []
        ...


#. In the ``storage-api-to`` section, specify the new shards that will host migrated data.

   .. code::

      storage-api-to:
        ...
        shards:
          - master: http://tnt-new-1:8001/v2/
            slaves: []
          - master: http://tnt-new-2:8001/v2/
            slaves: []
        ...


#. Run the ``sf-api-migrate`` utility with the configuration file.

   .. code::

        docker run --rm -ti --network server --entrypoint "/sf-api-migrate" \
            --volume /opt/ffserver/configs/sf-api-migrate.yaml:/sf-api-migrate.yaml \
            docker.int.ntl/ntech/universe/sf-api:ffserver-12.240830.2 \
            --config /sf-api-migrate.yaml \

   Use docker options:

   * ``--network``: connect a container to a network, named ``server``.

   Use configuration flags:

   * ``--volume /opt/ffserver/configs/sf-api-migrate.yaml:/sf-api-migrate.yaml``: mount the configuration file from the directory on the host into the container.
   * ``--config /sf-api-migrate.yaml``: provide path to the ``sf-api-migrate.yaml`` configuration file.

   .. note::
      The migration process can take up a significant amount of time if there are many features of object vectors in the ``tntapi`` database.


#. Open the ``/opt/ffserver/configs/sf-api.yaml`` configuration file and adjust the shards ports, subject to the new shards settings.

   .. code::

      sudo vi /opt/ffserver/configs/sf-api.yaml

   .. code::

      storage-api:
        ...
        shards:
        - master: http://tnt-new-1:8001/v2/
          slaves: []
        - master: http://tnt-new-2:8002/v2/
          slaves: []

#. To make sure that the migration was successful, send a request to the ``sf-api``:

   .. code:: bash

      GET /v3/galleries/:objtype/:gallery

   The ``emben_model`` field of the response must specify the model ``<new_model_face>`` to which the migration was performed, for example:

   .. code:: bash

      HTTP/1.1 200 OK
      Content-Type: application/json
      X-Request-Id: SF:NZfBDUu0
      Date: Thu, 06 Jun 2024 09:41:01 GMT
      Content-Length: 83

      {"name":"hello","emben_model":"nectarine_m_160","emben_size":160,"objects":100114}