<figure>
<img src="docs/assets/vizier_logo2.png" width=20% align="right"/>
</figure>
# Open Source Vizier: Reliable and Flexible Black-Box Optimization.
[](https://badge.fury.io/py/google-vizier)
[](https://github.com/google/vizier/actions/workflows/ci.yml?query=branch%3Amain)
[**Google AI Blog**](https://ai.googleblog.com/2023/02/open-source-vizier-towards-reliable-and.html)
| [**Getting Started**](#getting_started)
| [**Documentation**](#documentation)
| [**Installation**](#installation)
| [**Citing and Highlights**](#citing_vizier)
## What is Open Source (OSS) Vizier?
[OSS Vizier](https://arxiv.org/abs/2207.13676) is a Python-based service for black-box optimization and research, based on [Google Vizier](https://dl.acm.org/doi/10.1145/3097983.3098043), one of the first hyperparameter tuning services designed to work at scale.
<figure>
<p align="center" width=65%>
<img src="docs/assets/oss_vizier_service.gif"/>
<br>
<em><b>OSS Vizier's distributed client-server system. Animation by Tom Small.</b></em>
</p>
</figure>
## Getting Started <a name="getting_started"></a>
As a basic example for users, below shows how to tune a simple objective using all flat search space types:
```python
from vizier.service import clients
from vizier.service import pyvizier as vz
# Objective function to maximize.
def evaluate(w: float, x: int, y: float, z: str) -> float:
return w**2 - y**2 + x * ord(z)
# Algorithm, search space, and metrics.
study_config = vz.StudyConfig(algorithm='DEFAULT')
study_config.search_space.root.add_float_param('w', 0.0, 5.0)
study_config.search_space.root.add_int_param('x', -2, 2)
study_config.search_space.root.add_discrete_param('y', [0.3, 7.2])
study_config.search_space.root.add_categorical_param('z', ['a', 'g', 'k'])
study_config.metric_information.append(vz.MetricInformation('metric_name', goal=vz.ObjectiveMetricGoal.MAXIMIZE))
# Setup client and begin optimization. Vizier Service will be implicitly created.
study = clients.Study.from_study_config(study_config, owner='my_name', study_id='example')
for i in range(10):
suggestions = study.suggest(count=2)
for suggestion in suggestions:
params = suggestion.parameters
objective = evaluate(params['w'], params['x'], params['y'], params['z'])
suggestion.complete(vz.Measurement({'metric_name': objective}))
```
## Documentation <a name="documentation"></a>
OSS Vizier's interface consists of [three main APIs](https://oss-vizier.readthedocs.io/en/latest/guides/index.html):
* [**User API:**](https://oss-vizier.readthedocs.io/en/latest/guides/index.html#for-users) Allows a user to optimize their blackbox objective and optionally setup a server for distributed multi-client settings.
* [**Developer API:**](https://oss-vizier.readthedocs.io/en/latest/guides/index.html#for-developers) Defines abstractions and utilities for implementing new optimization algorithms for research and to be hosted in the service.
* [**Benchmarking API:**](https://oss-vizier.readthedocs.io/en/latest/guides/index.html#for-benchmarking) A wide collection of objective functions and methods to benchmark and compare algorithms.
Additionally, it contains [advanced API](https://oss-vizier.readthedocs.io/en/latest/advanced_topics/index.html) for:
* [**Tensorflow Probability:**](https://oss-vizier.readthedocs.io/en/latest/advanced_topics/index.html#tensorflow-probability) For writing Bayesian Optimization algorithms using Tensorflow Probability and Flax.
* [**PyGlove:**](https://oss-vizier.readthedocs.io/en/latest/advanced_topics/index.html#pyglove) For large-scale evolutionary experimentation and program search using OSS Vizier as a distributed backend.
Please see OSS Vizier's [ReadTheDocs documentation](https://oss-vizier.readthedocs.io/) for detailed information.
## Installation <a name="installation"></a>
**Quick start:** For tuning objectives using our state-of-the-art JAX-based Bayesian Optimizer, run:
```bash
pip install google-vizier[jax]
```
### Advanced Installation
**Minimal installation:** To install only the core service and client APIs from `requirements.txt`, run:
```bash
pip install google-vizier
```
**Full installation:** To support all algorithms and benchmarks, run:
```bash
pip install google-vizier[all]
```
**Specific installation:** If you only need a specific part "X" of OSS Vizier, run:
```bash
pip install google-vizier[X]
```
which installs add-ons from `requirements-X.txt`. Possible options:
* `requirements-jax.txt`: Jax libraries shared by both algorithms and benchmarks.
* `requirements-tf.txt`: Tensorflow libraries used by benchmarks.
* `requirements-algorithms.txt`: Additional repositories (e.g. EvoJAX) for algorithms.
* `requirements-benchmarks.txt`: Additional repositories (e.g. NASBENCH-201) for benchmarks.
* `requirements-test.txt`: Libraries needed for testing code.
**Developer installation:** To install up to the latest commit, run:
```bash
pip install google-vizier-dev[X]
```
Check if all unit tests work by running `run_tests.sh` after a full installation. OSS Vizier requires Python 3.10+, while client-only packages require Python 3.8+.
## Citing and Highlights <a name="citing_vizier"></a>
<ins>**Citing Vizier:**</ins> Please consider citing the appropriate paper(s): [Algorithm](https://arxiv.org/abs/2408.11527), [OSS Package](https://arxiv.org/abs/2207.13676), and [Google System](https://dl.acm.org/doi/10.1145/3097983.3098043) if you found any of them useful.
<ins>**Highlights:**</ins> We track [notable users](https://oss-vizier.readthedocs.io/en/latest/highlights/applications.html) and [media attention](https://oss-vizier.readthedocs.io/en/latest/highlights/media.html) - let us know if OSS Vizier was helpful for your work.
Thanks!
```bibtex
@article{gaussian_process_bandit,
author = {Xingyou Song and
Qiuyi Zhang and
Chansoo Lee and
Emily Fertig and
Tzu-Kuo Huang and
Lior Belenki and
Greg Kochanski and
Setareh Ariafar and
Srinivas Vasudevan and
Sagi Perel and
Daniel Golovin},
title = {The Vizier Gaussian Process Bandit Algorithm},
journal = {Google DeepMind Technical Report},
year = {2024},
eprinttype = {arXiv},
eprint = {2408.11527},
}
@inproceedings{oss_vizier,
author = {Xingyou Song and
Sagi Perel and
Chansoo Lee and
Greg Kochanski and
Daniel Golovin},
title = {Open Source Vizier: Distributed Infrastructure and API for Reliable and Flexible Black-box Optimization},
booktitle = {Automated Machine Learning Conference, Systems Track (AutoML-Conf Systems)},
year = {2022},
}
@inproceedings{google_vizier,
author = {Daniel Golovin and
Benjamin Solnik and
Subhodeep Moitra and
Greg Kochanski and
John Karro and
D. Sculley},
title = {Google Vizier: {A} Service for Black-Box Optimization},
booktitle = {Proceedings of the 23rd {ACM} {SIGKDD} International Conference on
Knowledge Discovery and Data Mining, Halifax, NS, Canada, August 13
- 17, 2017},
pages = {1487--1495},
publisher = {{ACM}},
year = {2017},
url = {https://doi.org/10.1145/3097983.3098043},
doi = {10.1145/3097983.3098043},
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/google/vizier",
"name": "google-vizier-dev",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ai machine learning hyperparameter blackbox optimization framework",
"author": "Vizier Team",
"author_email": "oss-vizier-dev@google.com",
"download_url": "https://files.pythonhosted.org/packages/66/a9/40dbd6ff3762e7803cefa1fb460d2f868a17c9680c5ec0f207f64e625e49/google-vizier-dev-0.1.20.dev20241218191044.tar.gz",
"platform": null,
"description": "<figure>\n<img src=\"docs/assets/vizier_logo2.png\" width=20% align=\"right\"/>\n</figure>\n\n# Open Source Vizier: Reliable and Flexible Black-Box Optimization.\n[](https://badge.fury.io/py/google-vizier)\n[](https://github.com/google/vizier/actions/workflows/ci.yml?query=branch%3Amain)\n\n\n [**Google AI Blog**](https://ai.googleblog.com/2023/02/open-source-vizier-towards-reliable-and.html)\n| [**Getting Started**](#getting_started)\n| [**Documentation**](#documentation)\n| [**Installation**](#installation)\n| [**Citing and Highlights**](#citing_vizier)\n\n## What is Open Source (OSS) Vizier?\n[OSS Vizier](https://arxiv.org/abs/2207.13676) is a Python-based service for black-box optimization and research, based on [Google Vizier](https://dl.acm.org/doi/10.1145/3097983.3098043), one of the first hyperparameter tuning services designed to work at scale.\n\n<figure>\n<p align=\"center\" width=65%>\n<img src=\"docs/assets/oss_vizier_service.gif\"/>\n <br>\n <em><b>OSS Vizier's distributed client-server system. Animation by Tom Small.</b></em>\n</p>\n</figure>\n\n## Getting Started <a name=\"getting_started\"></a>\nAs a basic example for users, below shows how to tune a simple objective using all flat search space types:\n\n```python\nfrom vizier.service import clients\nfrom vizier.service import pyvizier as vz\n\n# Objective function to maximize.\ndef evaluate(w: float, x: int, y: float, z: str) -> float:\n return w**2 - y**2 + x * ord(z)\n\n# Algorithm, search space, and metrics.\nstudy_config = vz.StudyConfig(algorithm='DEFAULT')\nstudy_config.search_space.root.add_float_param('w', 0.0, 5.0)\nstudy_config.search_space.root.add_int_param('x', -2, 2)\nstudy_config.search_space.root.add_discrete_param('y', [0.3, 7.2])\nstudy_config.search_space.root.add_categorical_param('z', ['a', 'g', 'k'])\nstudy_config.metric_information.append(vz.MetricInformation('metric_name', goal=vz.ObjectiveMetricGoal.MAXIMIZE))\n\n# Setup client and begin optimization. Vizier Service will be implicitly created.\nstudy = clients.Study.from_study_config(study_config, owner='my_name', study_id='example')\nfor i in range(10):\n suggestions = study.suggest(count=2)\n for suggestion in suggestions:\n params = suggestion.parameters\n objective = evaluate(params['w'], params['x'], params['y'], params['z'])\n suggestion.complete(vz.Measurement({'metric_name': objective}))\n```\n\n## Documentation <a name=\"documentation\"></a>\nOSS Vizier's interface consists of [three main APIs](https://oss-vizier.readthedocs.io/en/latest/guides/index.html):\n\n* [**User API:**](https://oss-vizier.readthedocs.io/en/latest/guides/index.html#for-users) Allows a user to optimize their blackbox objective and optionally setup a server for distributed multi-client settings.\n* [**Developer API:**](https://oss-vizier.readthedocs.io/en/latest/guides/index.html#for-developers) Defines abstractions and utilities for implementing new optimization algorithms for research and to be hosted in the service.\n* [**Benchmarking API:**](https://oss-vizier.readthedocs.io/en/latest/guides/index.html#for-benchmarking) A wide collection of objective functions and methods to benchmark and compare algorithms.\n\nAdditionally, it contains [advanced API](https://oss-vizier.readthedocs.io/en/latest/advanced_topics/index.html) for:\n\n* [**Tensorflow Probability:**](https://oss-vizier.readthedocs.io/en/latest/advanced_topics/index.html#tensorflow-probability) For writing Bayesian Optimization algorithms using Tensorflow Probability and Flax.\n* [**PyGlove:**](https://oss-vizier.readthedocs.io/en/latest/advanced_topics/index.html#pyglove) For large-scale evolutionary experimentation and program search using OSS Vizier as a distributed backend.\n\nPlease see OSS Vizier's [ReadTheDocs documentation](https://oss-vizier.readthedocs.io/) for detailed information.\n\n## Installation <a name=\"installation\"></a>\n**Quick start:** For tuning objectives using our state-of-the-art JAX-based Bayesian Optimizer, run:\n\n```bash\npip install google-vizier[jax]\n```\n\n### Advanced Installation\n**Minimal installation:** To install only the core service and client APIs from `requirements.txt`, run:\n\n```bash\npip install google-vizier\n```\n\n**Full installation:** To support all algorithms and benchmarks, run:\n\n```bash\npip install google-vizier[all]\n```\n\n**Specific installation:** If you only need a specific part \"X\" of OSS Vizier, run:\n\n```bash\npip install google-vizier[X]\n```\n\nwhich installs add-ons from `requirements-X.txt`. Possible options:\n\n* `requirements-jax.txt`: Jax libraries shared by both algorithms and benchmarks.\n* `requirements-tf.txt`: Tensorflow libraries used by benchmarks.\n* `requirements-algorithms.txt`: Additional repositories (e.g. EvoJAX) for algorithms.\n* `requirements-benchmarks.txt`: Additional repositories (e.g. NASBENCH-201) for benchmarks.\n* `requirements-test.txt`: Libraries needed for testing code.\n\n**Developer installation:** To install up to the latest commit, run:\n\n```bash\npip install google-vizier-dev[X]\n```\n\nCheck if all unit tests work by running `run_tests.sh` after a full installation. OSS Vizier requires Python 3.10+, while client-only packages require Python 3.8+.\n\n## Citing and Highlights <a name=\"citing_vizier\"></a>\n<ins>**Citing Vizier:**</ins> Please consider citing the appropriate paper(s): [Algorithm](https://arxiv.org/abs/2408.11527), [OSS Package](https://arxiv.org/abs/2207.13676), and [Google System](https://dl.acm.org/doi/10.1145/3097983.3098043) if you found any of them useful.\n\n<ins>**Highlights:**</ins> We track [notable users](https://oss-vizier.readthedocs.io/en/latest/highlights/applications.html) and [media attention](https://oss-vizier.readthedocs.io/en/latest/highlights/media.html) - let us know if OSS Vizier was helpful for your work.\n\nThanks!\n\n```bibtex\n@article{gaussian_process_bandit,\n author = {Xingyou Song and\n Qiuyi Zhang and\n Chansoo Lee and\n Emily Fertig and\n Tzu-Kuo Huang and\n Lior Belenki and\n Greg Kochanski and\n Setareh Ariafar and\n Srinivas Vasudevan and\n Sagi Perel and\n Daniel Golovin},\n title = {The Vizier Gaussian Process Bandit Algorithm},\n journal = {Google DeepMind Technical Report},\n year = {2024},\n eprinttype = {arXiv},\n eprint = {2408.11527},\n}\n\n@inproceedings{oss_vizier,\n author = {Xingyou Song and\n Sagi Perel and\n Chansoo Lee and\n Greg Kochanski and\n Daniel Golovin},\n title = {Open Source Vizier: Distributed Infrastructure and API for Reliable and Flexible Black-box Optimization},\n booktitle = {Automated Machine Learning Conference, Systems Track (AutoML-Conf Systems)},\n year = {2022},\n}\n\n@inproceedings{google_vizier,\n author = {Daniel Golovin and\n Benjamin Solnik and\n Subhodeep Moitra and\n Greg Kochanski and\n John Karro and\n D. Sculley},\n title = {Google Vizier: {A} Service for Black-Box Optimization},\n booktitle = {Proceedings of the 23rd {ACM} {SIGKDD} International Conference on\n Knowledge Discovery and Data Mining, Halifax, NS, Canada, August 13\n - 17, 2017},\n pages = {1487--1495},\n publisher = {{ACM}},\n year = {2017},\n url = {https://doi.org/10.1145/3097983.3098043},\n doi = {10.1145/3097983.3098043},\n}\n```\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Open Source Vizier: Distributed service framework for blackbox optimization and research.",
"version": "0.1.20.dev20241218191044",
"project_urls": {
"Homepage": "https://github.com/google/vizier"
},
"split_keywords": [
"ai",
"machine",
"learning",
"hyperparameter",
"blackbox",
"optimization",
"framework"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5f5133e50fed34e079bfe8606224c5e15db80a0162c385fb9143ad52b0c9e25f",
"md5": "4337bb23083438d50e2f38269bf0567c",
"sha256": "63bc21b9e7a47dee2667b48f7c5673aa75cb07699dba6d78e798527bb0d8d859"
},
"downloads": -1,
"filename": "google_vizier_dev-0.1.20.dev20241218191044-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4337bb23083438d50e2f38269bf0567c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 797661,
"upload_time": "2024-12-18T19:10:48",
"upload_time_iso_8601": "2024-12-18T19:10:48.096329Z",
"url": "https://files.pythonhosted.org/packages/5f/51/33e50fed34e079bfe8606224c5e15db80a0162c385fb9143ad52b0c9e25f/google_vizier_dev-0.1.20.dev20241218191044-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "66a940dbd6ff3762e7803cefa1fb460d2f868a17c9680c5ec0f207f64e625e49",
"md5": "00d6dda6b2c1ddbe46b441ac6a3c725e",
"sha256": "d47e9c7a2813e0f9d521552a65b551cf10e9485b312718878f622ead134e8776"
},
"downloads": -1,
"filename": "google-vizier-dev-0.1.20.dev20241218191044.tar.gz",
"has_sig": false,
"md5_digest": "00d6dda6b2c1ddbe46b441ac6a3c725e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 514278,
"upload_time": "2024-12-18T19:10:50",
"upload_time_iso_8601": "2024-12-18T19:10:50.914356Z",
"url": "https://files.pythonhosted.org/packages/66/a9/40dbd6ff3762e7803cefa1fb460d2f868a17c9680c5ec0f207f64e625e49/google-vizier-dev-0.1.20.dev20241218191044.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-18 19:10:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "google",
"github_project": "vizier",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "attrs",
"specs": [
[
">=",
"23.1.0"
]
]
},
{
"name": "absl-py",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.21.5"
]
]
},
{
"name": "protobuf",
"specs": [
[
">=",
"3.6"
]
]
},
{
"name": "portpicker",
"specs": [
[
">=",
"1.3.1"
]
]
},
{
"name": "grpcio",
"specs": [
[
">=",
"1.35.0"
]
]
},
{
"name": "grpcio-tools",
"specs": [
[
">=",
"1.35.0"
]
]
},
{
"name": "googleapis-common-protos",
"specs": [
[
">=",
"1.56.4"
]
]
},
{
"name": "sqlalchemy",
"specs": [
[
">=",
"1.4"
]
]
}
],
"lcname": "google-vizier-dev"
}
JSON
