如何在 OptunaHub 上注册您的包

实现自己的功能后，您可以将其注册为 OptunaHub 的包。要将您的包添加到 optunahub-registry 仓库，您需要从您的 fork 创建一个拉取请求（pull request）。您的拉取请求必须符合 贡献指南。

以下是包的目录结构示例。请参阅 模板目录 获取目录结构示例。

package

└── 类别 (samplers, pruners, visualization, or benchmarks)

└── YOUR_PACKAGE_NAME (您需要创建此目录及其内容)

├── YOUR_FEATURE_NAME.py

├── __init__.py

├── README.md

├── LICENSE

├── (example.py, example.ipynb)

├── (requirements.txt)

└── (images)

├── (figure1.png)

└── (numerical_results.png)

已实现的功能应放在相应的目录中，例如，采样器应放在 samplers 目录中。新创建的目录在相应目录中必须具有唯一名称。此唯一标识符是您的包名称，用于加载包，一旦注册就无法更改。包名称必须是有效的 Python 模块名称（例如，请使用“_”而不是“-”），最好是易于搜索的名称。包名称中不禁止使用缩写，但应避免滥用。

创建的目录应包含以下文件

• YOUR_FEATURE_NAME.py: 您的功能实现。

• __init__.py: 初始化文件。此文件必须实现您的功能或从另一个文件（例如 YOUR_FEATURE_NAME.py）导入其实现。

• README.md: 您的包的描述。此文件用于创建 OptunaHub 网页。稍后将解释 README.md 文件的格式。

• LICENSE: 许可证文件。此文件必须包含您的包的许可证。在 OptunaHub 的 alpha 版本中，它应该是 MIT 许可证。

• example.py, example.ipynb: 这是可选的。此文件应包含如何使用您的包的简单示例（例如：Simulated Annealing Sampler 的 example.py）。您可以提供这两种格式的示例。

• requirements.txt: 这是可选的。一个包含您的包的额外依赖项的文件。如果除了 Optuna 和 OptunaHub 之外没有额外的依赖项，则无需创建此文件。

• images: 这是可选的。一个包含图像的目录。在 README.md 中只允许相对引用此目录中的图像，例如 ![Numrical Results](images/numerical_results.png)，不允许使用图像的绝对路径。README.md 中出现的第一个图像将用作缩略图。

所有文件必须通过 linter 和 formatter 检查才能合并到 optunahub-registry 仓库。您可以通过运行 pre-commit 工具进行检查，如下所示。

pip install pre-commit
pre-commit install
pre-commit run  # This will run all checks against currently staged files.

虽然我们建议您编写适当的类型提示，但如果您发现难以符合 mypy，您可以在代码的第一行写入以下指令来跳过检查。

# mypy: ignore-errors

README.md 必须包含以下部分

• 一个 头部 部分，格式如下

  ---
  author: Optuna team
  title: Demo Sampler
  description: Demo Sampler of OptunaHub
  tags: [sampler]
  optuna_versions: [4.0.0]
  license: MIT License
  ---
  

  • author (string): 包的作者。可以是您的姓名或组织名称。

  • title (string): 包的标题。它不应是类/函数名称，而是一个人类可读的名称。例如，Demo Sampler 是一个不错的标题，但 DemoSampler 则不是。

  • description (string): 包的简要描述。它应该是一个包的单句摘要。

  • tags (list[string]): 包的标签。它应该是一个字符串列表。标签必须根据包的类型包含 sampler、visualization、pruner 或 benchmark。您可以根据需要添加其他标签。例如，“[‘sampler’, ‘LLM’]”。

  • optuna_versions (list[string]): 包支持的 Optuna 版本列表。它应该是一个字符串列表。您可以使用 python -c 'import optuna; print(optuna.__version__)' 查找您的 Optuna 版本。

  • license (string): 包的许可证。它应该是一个字符串。例如，MIT License。在当前版本的 OptunaHub 中，许可证必须是 MIT License。

• 一个 摘要 部分，描述您的包的概要。它应该是一个 markdown 段落。此部分将有助于吸引潜在用户使用您的包。

• 一个 API 部分，描述包提供的 API。文档格式是任意的，提供足够的信息（关于类、函数、参数等）以便使用您的包会很有帮助。至少应该在此处列出您实现的重要类/函数名称。

  - `ClassName(*, argment1: argument_type)`
    - `argument1`: Description of `argument1`.
  

• 一个 安装 部分，描述如何安装额外的依赖项（如果需要）。如果您的包包含 requirements.txt，它将位于 https://hub.optuna.org/{category}/{your_package_name}/requirements.txt。然后，可以按如下方式安装包的依赖项。

  $ pip install -r https://hub.optuna.org/{category}/{your_package_name}/requirements.txt
  

• 一个 示例 部分，描述如何使用该包。它应该是一个 python 代码块。它应该包含几行代码片段，展示如何使用该包。如果您想提供一个完整示例，请创建一个单独的文件，如 example.py 并引用它。例如

  ```python
  sampler = DemoSampler()
  study = optuna.create_study(sampler=sampler)
  ```
  See `example.py <path/to/example.py>` for more details.
  

• 一个 其他 部分，描述有关包的补充信息，例如论文引用或原始源代码链接。例如

  - [Original Paper](Link/to/the/original/paper)
  - [Source Code](Link/to/the/source/code)
  

请不要在 README.md 文件中使用 HTML 标签。只允许使用 markdown。出于安全原因，当包在网页上注册时，HTML 标签将被删除。

强烈建议您在提交拉取请求之前确认您的包正常工作（参见 如何在 OptunaHub 中注册前调试您的算法）。

在创建拉取请求之前，请确保 README.md 和 example.py 中的代码示例不包含您的本地目录和/或您 fork 的仓库。诸如 load_local_module("your_package", registry_root=”your_local_directory”) 或 load_module("your_package_name", repo_owner=”your_github_id”, ref=”your_working_branch”) 的代码应改为 load_module("your_package_name")。

您的拉取请求合并后，您的包将在大约 1 小时内通过 OptunaHub 提供。