Skip to content

Commit

Permalink
Update Documentation for CoreML Backend
Browse files Browse the repository at this point in the history
This commit updates the documentation in the `CoreML_Backend.md` file to reflect the changes in the KataGo model versions and includes necessary adjustments for downloading and linking models. Key changes include:

- Updated the download links for the binary models to the latest version `v1.15.1-coreml2`, replacing the previous version `v1.13.2-coreml2`.
- Updated the symbolic links to reflect the new model filenames corresponding to the latest releases.
- Adjusted benchmark, GTP, and analysis command examples to use the new binary model filenames.
- Replaced the outdated human-trained CoreML model download link with the updated model from `v1.15.1-coreml2`.
- Enhanced clarity on linking the human-trained CoreML model in the run directory.
- Reintroduced the section for updating the human-trained CoreML model, including instructions for downloading the checkpoint and converting it to a CoreML model.

These changes ensure that the documentation provides accurate and up-to-date instructions for utilizing the CoreML backend with the latest models available.
  • Loading branch information
ChinChangYang committed Jul 27, 2024
1 parent f88412d commit 0b8ac4a
Showing 1 changed file with 29 additions and 25 deletions.
54 changes: 29 additions & 25 deletions docs/CoreML_Backend.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,15 +37,15 @@ Executing these commands compiles KataGo in the `cpp/build` directory.
## Download the KataGo model
Acquire the KataGo model in binary format suitable for the Metal backend:
```
wget https://github.com/ChinChangYang/KataGo/releases/download/v1.13.2-coreml2/kata1-b18c384nbt-s8341979392-d3881113763.bin.gz
wget https://github.com/ChinChangYang/KataGo/releases/download/v1.13.2-coreml2/KataGoModel19x19fp16v14s8341979392.mlpackage.zip
unzip KataGoModel19x19fp16v14s8341979392.mlpackage.zip
wget https://github.com/ChinChangYang/KataGo/releases/download/v1.15.1-coreml2/kata1-b18c384nbt-s9996604416-d4316597426.bin.gz
wget https://github.com/ChinChangYang/KataGo/releases/download/v1.15.1-coreml2/KataGoModel19x19fp16v14s9996604416.mlpackage.zip
unzip KataGoModel19x19fp16v14s9996604416.mlpackage.zip
```

## Organizing Binary and CoreML Model
Optionally, relocate the binary model to the run directory. However, it is essential to link the CoreML model in the run directory to ensure its accessibility by the CoreML backend:
```
ln -s KataGoModel19x19fp16v14s8341979392.mlpackage KataGoModel19x19fp16.mlpackage
ln -s KataGoModel19x19fp16v14s9996604416.mlpackage KataGoModel19x19fp16.mlpackage
```

## Utilization of KataGo
Expand All @@ -55,23 +55,23 @@ KataGo can be operated in several modes, thanks to its extensive command options

To conduct a benchmark, use the `benchmark` command, specify the binary model location, and apply the `coreml_example.cfg` configuration:
```
./katago benchmark -model kata1-b18c384nbt-s8341979392-d3881113763.bin.gz -config ../configs/misc/coreml_example.cfg -t 32 -v 1600
./katago benchmark -model kata1-b18c384nbt-s9996604416-d4316597426.bin.gz -config ../configs/misc/coreml_example.cfg -t 16 -v 1600
```
This command activates the benchmark mode utilizing both Metal and CoreML backends.

**GTP**

For running the GTP protocol, utilize the `gtp` command, specify the binary model location, and use the `coreml_example.cfg` configuration:
```
./katago gtp -model kata1-b18c384nbt-s8341979392-d3881113763.bin.gz -config ../configs/misc/coreml_example.cfg
./katago gtp -model kata1-b18c384nbt-s9996604416-d4316597426.bin.gz -config ../configs/misc/coreml_example.cfg
```
This enables the GTP protocol leveraging Metal and CoreML backends.

**Analysis**

Activate the analysis engine with the `analysis` command, specify the binary model location, and use the `coreml_analysis.cfg` configuration:
```
./katago analysis -model kata1-b18c384nbt-s8341979392-d3881113763.bin.gz -config ../configs/misc/coreml_analysis.cfg
./katago analysis -model kata1-b18c384nbt-s9996604416-d4316597426.bin.gz -config ../configs/misc/coreml_analysis.cfg
```
This initiates the analysis mode, taking advantage of both Metal and CoreML backends.

Expand Down Expand Up @@ -144,27 +144,17 @@ wget https://github.com/lightvector/KataGo/releases/download/v1.15.0/b18c384nbt-
- Download the human-trained CoreML model:

```
wget https://github.com/ChinChangYang/KataGo/releases/download/v1.15.1-coreml1/KataGoModel19x19fp16meta1.mlpackage.zip
unzip KataGoModel19x19fp16meta1.mlpackage.zip
wget https://github.com/ChinChangYang/KataGo/releases/download/v1.15.1-coreml2/KataGoModel19x19fp16v15m1humanv0.mlpackage.zip
unzip KataGoModel19x19fp16v15m1humanv0.mlpackage.zip
```

Place the models in the run directory where the katago executable is built.

## Updating the Human-trained CoreML Model

- Download the checkpoint file
It is essential to link the human-trained CoreML model in the run directory to ensure its accessibility by the CoreML backend:

```
wget https://github.com/lightvector/KataGo/releases/download/v1.15.0/b18c384nbt-humanv0.ckpt
ln -s KataGoModel19x19fp16v15m1humanv0.mlpackage KataGoModel19x19fp16m1.mlpackage
```

- Convert the checkpoint file to a CoreML model:

```
python python/convert_coreml_pytorch.py -checkpoint b18c384nbt-humanv0.ckpt -use-swa
```

This will output the CoreML model directory KataGoModel19x19fp16meta1.mlpackage, tailored for the CoreML backend.
Place the models in the run directory where the katago executable is built.

## Configuring Multi-Threaded Metal and CoreML Execution

Expand All @@ -184,9 +174,23 @@ These configuration settings instruct the KataGo to utilize two threads for exec
- Run the following command:

```
./katago gtp -model <model_name>.bin.gz -human-model b18c384nbt-humanv0.bin.gz -config ../configs/misc/gtp_human5k_coreml.cfg
./katago gtp -model kata1-b18c384nbt-s9996604416-d4316597426.bin.gz -human-model b18c384nbt-humanv0.bin.gz -config ../configs/misc/gtp_human5k_coreml.cfg
```

Replace `<model_name>` with the actual model name, such as `kata1-b18c384nbt-s8341979392-d3881113763`.

Note: Make sure that the human-trained CoreML model is in the same directory as the katago executable.

## Updating the Human-trained CoreML Model

- Download the checkpoint file

```
wget https://github.com/lightvector/KataGo/releases/download/v1.15.0/b18c384nbt-humanv0.ckpt
```

- Convert the checkpoint file to a CoreML model:

```
python python/convert_coreml_pytorch.py -checkpoint b18c384nbt-humanv0.ckpt -use-swa
```

This will output the CoreML model directory KataGoModel19x19fp16m1.mlpackage, tailored for the CoreML backend.

0 comments on commit 0b8ac4a

Please sign in to comment.