7-3 Setting Up Unity ML-Agents On MacOS

本章要來介紹在MacOS電腦上安裝Unity ML-Agents的方法，在文章開始前順帶一提，前一章有Windows電腦上的安裝教學，使用Anaconda這套工具，一樣也有MacOS的版本，如有興趣的話可參考上一篇教學：
7-2 Setting Up Unity ML-Agents On Windows

https://3dactionrpg.blogspot.com/2018/07/7-2-setting-up-unity-ml-agents-on.html

本章則打算使用virtualenv 安裝。virtualenv會和其它 Python 項目開發隔離的虛擬 Python 環境，在同一台機器上不會干擾也不會被其它程序影響。要開始使用 TensorFlow，你只需要「啟動」 virtualenv 環境。virtualenv 提供了一個安全可靠的 TensorFlow 安裝和運行機制。

首先，我列出使用Unity ML-Agents會需要的安裝包及其依賴包，方便一些人可能比較喜歡用自己習慣的方式安裝。

Python 3.6
tensorflow==1.7.1
Pillow>=4.2.1
matplotlib
numpy>=1.11.0
jupyter
pytest>=3.2.2
docopt
pyyaml
protobuf==3.5.2
grpcio==1.11.0

Jupyter Notebook

Jupyter Notebook是一個開源的Web應用程序，可以讓你創建和共享包含實時代碼，方程式，可視化和說明文本的文檔。用途包括：數據清理與轉換，數值模擬，統計建模，機器學習等等。

NumPy

NumPy是Python語言的開源數學擴展庫。支持高級大量的維度數組與矩陣運算，此外也針對數組運算提供大量的數學函數庫。

Pillow

Pillow是PIL（Python Imaging Library，Python圖像庫）的一個分支，提供了對於開發者許多比較友好和直觀的功能。

Docopt

docopt是Python的命令行參數解析器，其基於多年來用於描述程序界面的幫助信息而設計的，因此可以給開發者清晰的輸出體驗。

TensorFlow

TensorFlow是現今非常流行的使用數據流圖進行數值計算的開源軟件庫。圖中的節點代表數學運算，而圖中的邊則代表在這些節點之間傳遞的多維數組（張量）。這種靈活的架構可讓你使用一個 API 將計算工作部署到桌面設備、服務器或者移動設備中的一個或多個 CPU 或 GPU。 TensorFlow 最初是由Google 機器智能研究部門的Google Brain 團隊中的研究人員和工程師開發的，用於進行機器學習和深度神經網絡研究，但它是一個非常基礎的系統，因此也可以應用於眾多其他領域。

安裝Python

以上簡單介紹完畢，接下來，我將以我自己的方式教大家安裝這些套件。首先我們到Python的官網下載3.6版本的安裝檔。

安裝成功以後，能在該資料夾位置找到3.6版本的Python：/Library/Frameworks/Python.framework/Versions。你可以看到我還有安裝其他版本的Python，多個版本是可以共存使用的，待會我會將特定版本的Python轉移到Virtualenv。

安裝virtualenv

接著安裝virtualenv，輸入指令pip3 install --upgrade virtualenv。

接著使用Python 3.6創建虛擬環境，輸入指令：
virtualenv --system-site-packages -p /Library/Frameworks/Python.framework/Versions/3.6/bin/python3.6 ~/tensorflow

請注意，參數-p的後面就是指剛剛的安裝位置。~/tensorflow則是我創建虛擬環境的資料夾位置，你可以自由更換。

接著啟動虛擬環境，輸入指令source ~/tensorflow/bin/activate，你應該可以看見命令指示符的前面出現tensorflow字樣。

可以輸入指令python3 --version，確認目前的Python版本是否為3.6。

解除virtualenv
輸入指令deactive變成解除virtualenv環境，原本的在命令指示符前面的tensorflow字樣就消失了。

移除virtualenv
輸入指令rm -r ~/tensorflow，就能直接移除整個virtualenv環境，非常方便吧！

下載ML-Agent專案

啟動完成以後，我要使用ML-Agent官方提供的快速安裝包，直接幫我把所需要的依賴包安裝好。所以，我們先使用git clone下載官方專案。Github專案地址：https://github.com/Unity-Technologies/ml-agents

另外開一個新的Command視窗，進入自己放Unity專案的資料夾，然後輸入指令git clone https://github.com/Unity-Technologies/ml-agents.git。

下載完成後的資料如下圖所示。

接著，回到原本已經啟動虛擬環境的視窗，輸入指令：cd /Users/datastar/Documents/Unity\ Project/ml-agents/python。會進入ML-Agents提供的Python相關資料夾。

安裝TensorFlow
再來，下一步是安裝TensorFlow，輸入指令：pip install tensorflow。

如果你出現如下圖的錯誤訊息。
Could not find a version that satisfies the requirement tensorflow (from versions: )
No matching distribution found for tensorflow

有可能是某些問題造成找不到適合的版本，你可以用手動的方式下載安裝TensorFlow。舉例，我要在Mac OS X 安裝1.4.0版本的TensorFlow，並且適用於Python3，那麼下載網址就會是：https://storage.googleapis.com/tensorflow/mac/cpu/tensorflow-1.4.0-py3-none-any.whl

如果是在Mac OS X上安裝 Python 2.7 對應的1.2.1版本的Tensorflow，網址是：
https://storage.googleapis.com/tensorflow/mac/cpu/tensorflow-1.2.1-py2-none-any.whl

好的，上述的舉例應該足以讓你了解了，所以我接下來輸入下列的指令進行安裝
pip3 install --upgrade \ https://storage.googleapis.com/tensorflow/mac/cpu/tensorflow-1.7.1-py3-none-any.whl

但是我在安裝1.7.1版本的Tensorflow出現如下圖的問題，Failed building wheel for grpcio。

後來，我將MacOS從10.12.6 (Sierra) 升級到10.13.5 (High Sierra)，再輸入指令pip install grpcio，便能安裝成功。安裝成功後，記得再重新安裝1.7.1版本的TensorFlow。看到訊息：Successfully installed tensorboard-1.7.0 tensorflow-1.7.1，代表安裝成功。

如果你在安裝grpcio時，遇到更多奇怪的問題，可以參考底下的網址，也許能夠解決你的問題：https://github.com/tensorflow/tensorflow/issues/17369

快速安裝ML-Agent需要的依賴包
好的，接著請確認資料夾位置在ML-Agent官方提供的Python資料夾，然後輸入指令pip install .。輸入該指令可以自動安裝需要的依賴包。但你有可能會看見下列的錯誤訊息：
Could not find a version that satisfies the requirement tensorflow==1.7.1 (from unityagents==0.4.0) (from versions: )
No matching distribution found for tensorflow==1.7.1 (from unityagents==0.4.0)

該問題我們已經遇過了，所以我們才再上面手動安裝好了TensorFlow，此時我們打開資料夾內的setup.py檔案，可以看見程式使用requiremens.txt紀錄要安裝的依賴包。我們打開requiremens.txt，並將第一行的tensorflow==1.7.1刪除。

此時再次輸入指令pip install .
這時便能順利安裝其他依賴包了。

OK，進行到這邊，你已經完成了環境安裝了，接下來要使用官方範例測試訓練效果啦！

安裝TensorFlowSharp插件
接下來，打開Unity，然後打開ml-agents底下的unity-environment專案，這是官方提供的範例。接著要安裝TensorFlowSharp插件，你可以從以下這兩個官方提供的連結下載插件：
AWS S3連結，百度盤連結

Import完TensorFlowSharp插件以後，開啟Build Settings，開啟Player Settings。

這邊有兩個選項，建議勾選Run In Background，這樣在跑訓練的時候，就算做其他的事情，也不會讓訓練停止。然後將Display Resolution Dialog設定為Disabled，才不會每次執行時跳出螢幕解析度的詢問視窗。

然後我們開啟一個最簡單的範例，在Examples/3D Ball/Scenes底下的3DBall。

設定Brain Type並輸出

從場景中找到Ball3DBrain物件。將Brain Type設定為External，這是要在外部訓練的模式。

然後回到PlayerSettings，將Product Name設定為ML-Agent-3DBall，這個名稱請依自己的需求進行變更。然後Build專案。

找到放置專案的資料夾。

回到終端機，輸入指令jupyter notebook Basics.ipynb，這是要用來設定一些參數的。

這時應該會自動啟動瀏覽器，然後跳出下列畫面。請修改env_name內的值，將其和你輸出的應用程式名稱對應，此範例為ML-Agent-3DBall。

開始外部訓練
接著輸入指令：
python learn.py ~/Documents/Unity\ Project/ml-agents/unity-environment/ML-Agent-3DBall/ML-Agent-3DBall.app --train

learn.py是ML-Agent的Python資料夾內提供的腳本，後面接Unity應用程式的路徑，以及告知訓練的參數--train。

這時就會自動啟動我們剛剛輸出的應用程式，開始進行訓練了。

這邊有一個重點！我卡了很久，就是訓練的時候，Python跟Unity應用程式之間的溝通出問題，跳出下列錯誤：
UnityAgentsException: The Communicator was unable to connect. Please make sure the External process is ready to accept communication with Unity.

或者，在終端機上跳出下列錯誤：

unityagents.exception.UnityTimeOutException: The Unity environment took too long to respond. Make sure that :
The environment does not need user interaction to launch
The Academy and the External Brain(s) are attached to objects in the Scene

The environment and the Python interface have compatible versions.

會發生這種問題的原因很多：
1. 你忘記將Brain Type設定為External
2. 或者是你使用的Mac OS系統，而系統內建的防火牆擋住了通訊，詳情請參閱下列網站，了解如何解除：
https://support.apple.com/en-us/HT201642
3. 最後這點才是我真正的解法！記住，你從Github上下載的ml-agents，他們用哪個版本的Unity，你最好也使用那個版本進行編譯！

如圖，我用的是ml-agents v0.4，然後專案顯示的版本是2018.1.0。結果，我出錯的時候用的版本是2017.2.0f3。我的建議是，若為了省麻煩，建議一定用跟開發團隊相同的版本，比較不容易出錯，畢竟他們也無法完全解決每個Unity版本有可能發生的所有問題。