# Установка

ML-Agents Toolkit состоит из нескольких компонентов:

- Специальный пакет Unity ([`com.unity.ml-agents`](https://github.com/Unity-Technologies/ml-agents/tree/main/com.unity.ml-agents))
с Unity C# SDK, который будет интегрирован в Unity сцену.

- Три Python пакета:
  - ([`mlagents`](https://github.com/Unity-Technologies/ml-agents/tree/main/ml-agents)) - пакет с алгоритмами машинного обучения,
  которые позволяют обучить искусственный интеллект. Большинству пользователей ML-Agents достаточно напрямую установить mlagents.
  - ([`mlagents_envs`](https://github.com/Unity-Technologies/ml-agents/tree/main/ml-agents-envs) содержит Python
  API для взаимодействия с Unity сценой. Этот пакет управляет передачей данных между Unity сценой и алгоритмами
  машинного обучения, реализованных на Python. Пакет mlagents зависит от mlagents_envs.
  - ([`gym_unity`](https://github.com/Unity-Technologies/ml-agents/tree/main/gym-unity)) - позволяет обернуть вашу сцену
  в Unity в среду OpenAI Gym.
- Unity [Project](https://github.com/Unity-Technologies/ml-agents/tree/main/Project),
содержащий [примеры сцены](https://github.com/Unity-Technologies/ml-agents/blob/main/docs/Learning-Environment-Examples.md),
где реализованы различные возможности ML-Agents для наглядности.

Итого, чтобы установить и использовать ML-Agents, вам нужно:
- Установить Unity (2022.3 или более позднюю версию)
- Установить Python (3.8.13 или более позднюю версию)
- Клонировать этот репозиторий (Опционально)
  - __Примечание:__ если вы не склонируете репозиторий, тогда у вас не будет доступа к примерам и конфигурациям обучения.
  Также, раздел "Начало работы" подразумевает, что вы сделали клон репозитория.
- Установить пакет `com.unity.ml-agents` Unity
- Установить пакет `mlagents` Python

### Установка **Unity 2022.3** или более поздней версии

[Загрузите](https://unity3d.com/get-unity/download) и установите движок Unity.
Мы очень рекомендуем установить Unity через Unity Hub, так как последний позволяет управлять разными версиями движка.

### Установка **Python 3.8.13** или более поздней версии

Мы рекомендуем [установить](https://www.python.org/downloads/) Python 3.8.
Если вы используете Windows, пожалуйста, установите x86-64 версию, а не x86.
Если у вас нет системы управления пакетами `pip3` для Python, пожалуйста,
воспользуйтесь [этими инструкциями](https://packaging.python.org/guides/installing-using-linux-tools/#installing-pip-setuptools-wheel-with-linux-package-managers)
для ее установки. И хотя мы более не поддерживаем установку пакетов для Anaconda на Windows,
инструкция все еще доступна - [Windows Anaconda Installation (Deprecated)](Installation-Anaconda-Windows.md)

### Клонирование репозитория ML-Agents Toolkit (Опционально)

Теперь, когда вы установили Unity и Python, вы можете начать установку пакетов.
Для этого не обязательно клонировать репозиторий, но если вы хотите протестировать
наши примеры, сделать это будет необходимо (некоторые наши уроки и гайды этого требуют)

```sh
git clone --branch release_7 https://github.com/Unity-Technologies/ml-agents.git
```
Флаг `--branch release_7` установит последную стабильную рабочую версию.
Если ее не набрать, установится мастер версия, которая, возможно, будет работать нестабильно.

#### Продвинутая локальная установка для разработки

Вам нужно будет склонировать репозиторий, если вы планируете вносить изменения
или что-то добавлять в ML-Agents для своих целей. Или вы планируете сделать
эти изменения общедоступными, пожалуйста, склонируйте main branch
(без флага `--branch release_7` в команде выше).
Далее см. [гайд про публикацию правок](https://github.com/Unity-Technologies/ml-agents/blob/main/com.unity.ml-agents/CONTRIBUTING.md).

### Установка пакета `com.unity.ml-agents` для Unity
Unity ML-Agents C# SDK это пакет Unity. Вы можете установить его прямо из пакетного менеджера,
Unity Package Manager. Пожалуйста, убедитесь, что вы нажали 'Preview Packages' в 'Advanced',
чтобы найти этот пакет.

**ОБРАТИТЕ ВНИМАНИЕ:** Если вы не видите пакет ML-Agents в Package Manager,
пожалуйста, следуйте шагам, написанных [ниже](#продвинутая-локальная-установка-для-разработки-1)

#### Продвинутая локальная установка для разработки

Вы можете добавить самостоятельно com.unity.ml-agents (из репозитория, который вы склонировали)
к вашему проекту:
1. `Меню Window` -> `Package Manager`.
1. В `Package Manaer` кликнете на кнопку “+”.
1. Выберите `Add package from disk`...
1. Зайдите в папку `com.unity.ml-agents`
1. Выберите файл `package.json`.

**ПРИМЕЧАНИЕ:** В Unity 2018.4 кпопка `+` находится внизу справа около списка пакетов.
А в Unity 2019.3 она - сверху слева.

<p align="center">
  <img src="https://raw.githubusercontent.com/Unity-Technologies/ml-agents/main/docs/images/unity_package_manager_window.png"
       alt="Unity Package Manager Window"
       height="300"
       border="10" />
  <img src="https://raw.githubusercontent.com/Unity-Technologies/ml-agents/main/docs/images/unity_package_json.png"
     alt="package.json"
     height="300"
     border="10" />
</p>

Если вы собираетесь протестировать примеры из нашей документации, просто откройте папку `Projects` в Unity и вперед!

### Установка пакета `mlagents` Python

Установка `mlagents` Python требует установки и других Python пакетов, от которых зависит `mlagents`.
Поэтому если у вас установлены их более ранние версии, могут быть ошибки установки.
Чтобы этого избежать, мы рекомендуем использовать Python Virtual Environments.
Virtual Environments позволяет управлять ранее установленными версиями так,
что для одного проекта будут одни зависимости, а для другого - другие на каждой
из операционных систем - Mac / Windows / Linux.
Гайд по [Virtual Environments](https://github.com/Unity-Technologies/ml-agents/blob/main/docs/Using-Virtual-Environment.md).

Чтобы установить `mlagents` Python, активируйте вашу виртуальную среду
и выполните следующее в командной строке:

```sh
pip3 install mlagents
```

Обратите внимание, что эта команда установит `mlagents`,
используя PyPi, а не из клонированного репозитория.
Если установка прошла успешно, вы сможете выполнить
команду `mlagents-learn --help`, после
исполнения которой вы увидите набор доступных команд `mlagents-learn`.
Устанавливая mlagents, вы также устанавливаете и все то, на базе чего он сделан -
см. [setup.py file](https://github.com/Unity-Technologies/ml-agents/blob/main/ml-agents/setup.py).
В том числе [TensorFlow](https://github.com/Unity-Technologies/ml-agents/blob/main/docs/Background-TensorFlow.md)
(требует поддержки CPU w/ AVX).

#### Продвинутая локальная установка для разработки
Если вы хотите снести изменения в пакеты `mlagents` или `mlagents_envs`,
вам следует установить их из клонированного репозитория, а не через PyPi.
Установить и тот и другой пакет нужно будет по отдельности.
Перейдите к корень репозитория, выполните следующие команды:

```sh
pip3 install -e ./ml-agents-envs
pip3 install -e ./ml-agents
```

Выполняя команды с суффиксом `с -e`, вы вносите изменения в файлы Python напрямую.
Важно: установить данные пакеты надо ровно в таком порядке, как это указано выше,
так как `mlagents` зависит от `mlagents_envs`. В ином случае  `mlagents_envs`
будут загружены и установлены через PyPi.

### Следующие шаги

Гайд ["Начало работы"](https://github.com/Unity-Technologies/ml-agents/tree/main/docs/localized/RU/docs/Начало-работы.md)
содержит в себе серию коротких обучающих уроков по настройке ML-Agents внутри Unity
и запуск предобученной модели, а также уроки по созданию и дополнению сцен,
где будет обучаться ваш агент.

### Помощь

Если у вас возникли трудности с ML-Agents, пожалуйста, обратитесь к [FAQ](https://github.com/Unity-Technologies/ml-agents/blob/main/docs/FAQ.md)
и к странице [Limitations](https://github.com/Unity-Technologies/ml-agents/blob/main/docs/Limitations.md).
Если это не решило вашу проблему, создайте запрос [здесь](https://github.com/Unity-Technologies/ml-agents/issues),
предоставив информацию о операционной системе, версии Python и сообщение об ошибки (если оно есть).