From 777f4ced10fc821b1448322f304dcf2e14e43811 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antonio=20Vel=C3=A1zquez?= <38739674+antoniovs1029@users.noreply.github.com> Date: Wed, 16 Dec 2020 15:33:41 -0600 Subject: [PATCH] Update Stale docs (#5550) * Updated OnnxMl.md * Updated MlNetMklDeps docs * Typo * typo --- docs/building/MlNetMklDeps/README.md | 115 +++++++++++++---------- src/Microsoft.ML.OnnxConverter/OnnxMl.md | 13 ++- 2 files changed, 77 insertions(+), 51 deletions(-) diff --git a/docs/building/MlNetMklDeps/README.md b/docs/building/MlNetMklDeps/README.md index 0095553cc1..8afca89f2a 100644 --- a/docs/building/MlNetMklDeps/README.md +++ b/docs/building/MlNetMklDeps/README.md @@ -1,54 +1,69 @@ -#Instructions to build a custom DLL from Intel's MKL SDK -ML.NET MKL implementation uses Intel MKL Custom DLL builder to produce a single DLL which contains all of the MKL functions used by it. -To update the DLL, follow the steps below: +# The MlNetMklDeps nuget +ML.NET's repository takes a dependency of the MlNetMklDeps nuget, which contains the MKL binaries of the MKL functions that ML.NET uses. This other nuget is actually also built and managed by the team. In the next section, the steps to create those binaries are described. In this section the contents of the nuget are mentioned. -Windows (32 and 64 bit): -- Ensure you have Intel's MKL SDK installed, you can find it here: https://software.intel.com/en-us/mkl. -- Open an admin command prompt and run the following commands, CAREFULLY INSPECTING THE COMMAND OUTPUT FOR ERRORS. -- TLCROOT should be the root of your TLC_Resources folder. - -Directory layout for nuget file is as follows: +**MlNetMklDeps nuget follows this layout:** * licensing (contains Intel's license.txt they ship MKL with along with any third party licenses) +* MlNetMklDeps.nuspec * runtimes -** linux-x64 -*** native (contains linux binaries) -** osx-x64 -*** native (cntains osx binaries) -** win-x64 -*** native (contains windows x64 binaries) -** win-x86 -*** native (contains windows ia32 binaries) - -##Windows -1. In the Intel install directory, go to compilers_and_libraries\windows\mkl\tools\builder -2. Modify user_example_list file in directory to contain all required functions, that are present in the [mlnetmkl.list -](mlnetmkl.list) file -3. "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" x86 -4. nmake libia32 name=MklImports (add threading=sequential if you are building without openmp) -5. Copy MKL library: copy /Y MklImports.* to the folder that will host the x86 binaries. -6. Copy openmp library: copy /Y ..\..\..\redist\ia32_win\compiler\libiomp5md* to the folder for x86 binaries. -7. del MklImports.* -8. "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64 -9. nmake intel64 name=MklImports (add threading=sequential if you are building without openmp) -10. Copy mkl library: copy /Y MklImports.* to the folder that will host the x64 binaries. -11. Copy openmp library: copy /Y ..\..\..\redist\intel64_win\compiler\libiomp5md* to the folder for x86 binaries. - -##Linux -NOTE: Do not copy the libiomp5 file for Linux builds as this relies on OpenMP to be installed on the system. -1. untar the linux sdk (tar -zxvf name_of_downloaded_file) -2. Run installation script and follow the instuctions in the dialog screens that are presented ./install.sh -3. Go to /opt/intel/mkl/tools/builder. -4. Modify makefile add -Wl,-rpath,'$$ORIGIN' \ -Wl,-z,origin \ after -Wl,--end-group \ -5. Modify user_example_list file in directory to contain all the required functions, that are present in the [mlnetmkl.list](mlnetmkl.list) file -6. Run make intel64 name=libMklImports (add threading=sequential if you are building without openmp) - -##OSX -NOTE: Do not copy the libiomp5 file for OSX builds as this relies on OpenMP to be installed on the system. -1. extract and install the dmg (double-click and drag it in the Applications folder) -2. Go to /opt/mkl/tools/builder. -3. Modify user_example_list file in directory to contain all the required functions, that are present in the [mlnetmkl.list](mlnetmkl.list) file -4. Run make libintel64 name=libMklImports (add threading=sequential if you are building without openmp) -5. Copy libMklImports.dylib from the builder directory to the folder containign the OSX binaries. + * linux-x64 + * native (contains linux binaries) + * osx-x64 + * native (cntains osx binaries) + * win-x64 + * native (contains windows x64 binaries) + * win-x86 + * native (contains windows ia32 binaries) + +The .nuspec can be found on this folder: +https://github.com/dotnet/machinelearning/tree/master/docs/building/MlNetMklDeps + +If actually publishing a new version of MlNetMklDeps, remember to update this other file to document any changes: +https://github.com/dotnet/machinelearning/blob/master/docs/building/MlNetMklDeps/version.md + +# Instructions to build the binaries using Intel's MKL SDK +ML.NET MKL implementation uses Intel MKL Custom Builder to produce the binaries for the functions that we select. Follow the instructions below to produce the binaries for each platform, which will then be added to the MlNetMklDeps nuget described on the previus section. + +**Download Intel MKL SDK** before following the instructions below on each platform: +https://software.intel.com/en-us/mkl + +**NOTE about TLC**: The previous version of this instructions said to set the `TLCROOT` variable to "your TLC_Resources folder", since in ML.NET we don't have a `TLC_Resources` folder this seems to be stale instructions, which aren't needed any more. But it might become relevant if trying to test anything MKL related with TLC. + +## Windows + +1. In the Intel MKL SDK install directory, go to the Builder folder, found in `compilers_and_libraries\windows\mkl\tools\builder` +2. Replace the contents of the `user_example_list` file, found in that folder, with the contents of the [mlnetmkl.list +](mlnetmkl.list) file. +3. Initialize your environment by running the `vcvarsall.bat x86` command found on your Visual Studio installation directory. E.g., it might be found on any path similar to these: + * `"C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" x86` + * `"C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\VC\Auxiliary\Build\vcvarsall.bat" x86` +4. Back to the Builder folder run the following command to create the binary files: +`nmake libia32 name=MklImports`. Add `threading=sequential` if you are building without openmp (**NOTE:** it seems that starting on [PR #2867](https://github.com/dotnet/machinelearning/pull/2867) we always want to build using openmp, so there's no need to use this `threading` flag). This will produce `MklImports.dll, MklImports.dll.manifest, MklImports.exp, and MklImports.lib`. To also create `MklImports.pdb` see the note at the end of this section. +5. Copy the MKLImports files to the folder that will host the binaries inside the nuget: `copy /Y MklImports.*` +6. Also copy the Openmp library found inside the MKL SDK installation folder to the folder with the binaries: `copy /Y ..\..\..\redist\ia32_win\compiler\libiomp5md*` +7. Delete the x86 MklImports files from the Builder folder: `del MklImports.*` +8. Initialize your environment with `vcvarsall.bat amd64`. It should be in the same path as found on step 3. +9. On the Builder folder: `nmake intel64 name=MklImports` (add `threading=sequential` if you are building without openmp) +10. Copy the MKL files to the folder for x64 binaries: `copy /Y MklImports.*` +11. Copy the Openmp library to the folder with the x64 binaries: `copy /Y ..\..\..\redist\intel64_win\compiler\libiomp5md* ` + +**NOTE to create MklImports.pdb:** If the symbols for the built MklImports.dlls are required, add `/DEBUG:FULL /PDB:MklImports.pdb \` on the makefile after `mkl_custom_vers.res \`, in both the `libintel64` and `libia32` targets, to get the symbols for both x86 and x64 binaries. + +## Linux +**NOTE:** Do not copy the libiomp5 file for Linux builds as this relies on OpenMP to be installed on the system. +1. Untar the linux Intel MKL SDK: `tar -zxvf name_of_downloaded_file` +2. Run the installation script and follow the instuctions in the dialog screens that are presented: `./install.sh` +3. Go to the Builder directory found in `/opt/intel/mkl/tools/builder` (it might be in another path, such as `/home/username/intel/compilers_and_libraries/linux/mkl/tools/builder` depending on your installation). +4. Modify the makefile found on the Builder directory: add `-Wl,-rpath,'$$ORIGIN' \ -Wl,-z,origin \` after `-Wl,--end-group \` +5. Modify `user_example_list` file in the Builder directory to contain all the required functions, that are present in the [mlnetmkl.list](mlnetmkl.list) file +6. Run `make intel64 name=libMklImports` (add `threading=sequential` if you are building without openmp) + +## OSX +**NOTE:** Do not copy the libiomp5 file for OSX builds as this relies on OpenMP to be installed on the system. +1. Extract and install the Intel MKL SDK dmg (double-click and drag it in the `Applications` folder) +2. Go to the Builder directory: `/opt/mkl/tools/builder`. +3. Modify user_example_list file in the Builder directory to contain all the required functions, that are present in the [mlnetmkl.list](mlnetmkl.list) file +4. Run `make libintel64 name=libMklImports` (add `threading=sequential` if you are building without openmp) +5. Copy `libMklImports.dylib` from the builder directory to the folder containing the OSX binaries. 6. Fix the id and the rpath running the following commands: - sudo install_name_tool -id "@loader_path/libMklImports.dylib" libMklImports.dylib - sudo install_name_tool -id "@rpath/libMklImports.dylib" libMklImports.dylib + * `sudo install_name_tool -id "@loader_path/libMklImports.dylib" libMklImports.dylib` + * `sudo install_name_tool -id "@rpath/libMklImports.dylib" libMklImports.dylib` \ No newline at end of file diff --git a/src/Microsoft.ML.OnnxConverter/OnnxMl.md b/src/Microsoft.ML.OnnxConverter/OnnxMl.md index 2865daf601..82de12fabc 100644 --- a/src/Microsoft.ML.OnnxConverter/OnnxMl.md +++ b/src/Microsoft.ML.OnnxConverter/OnnxMl.md @@ -1,5 +1,7 @@ # Generate C# code from ONNX proto file +The `machinelearning\src\Microsoft.ML.OnnxConverter\OnnxMl.cs` file needs to be updated anytime the IR version is updated in OnnxRuntime, using the steps below: + 1. Download `onnx-ml.proto3` from https://github.com/onnx/onnx/blob/master/onnx/onnx-ml.proto3 2. Download protobuf C# compiler version 3.0 or greater from https://github.com/google/protobuf/tree/master/csharp @@ -12,4 +14,13 @@ ``` 5. Find-Replace `public` with `internal` in `OnnxMl.cs`, wrap the root class in OnnxMl.cs with `internal class OnnxCSharpToProtoWrapper and append '.OnnxCSharpToProtoWrapper` to `Microsoft.ML.Model.OnnxConverter` namespace prefix whereever there is an error`. -## The proto3 file is current as of 06/01/2018 and generated from onnx-ml.proto3 based on the following commit https://github.com/onnx/onnx/commit/33e9cd4182fe468675241fba4ae8a16c2f0bd82f \ No newline at end of file +## Last time Updated: November 5, 2019 + +The last time the `OnnxMl.cs` file was updated in ML.NET was **November 5, 2019** on PR #4416: +https://github.com/dotnet/machinelearning/pull/4416 + +It used the `onnx-ml.proto3` version of **September 16, 2019**, updated on this PR which used IR version 6: + +https://github.com/onnx/onnx/commit/2fa08b0f0808423293a001768c9436004a90ca86#diff-fd73e60aa058574ba59274f757d42c4e9037414ab99358f3f096a37bd764270c + +As of today, December 11, 2020, the IR is still on version 6, and version 7 hasn't been released yet. \ No newline at end of file