Skip to content

Commit 6513c28

Browse files
reiasereiase
committed
refactor: update README and README.zh.md for clarity and consistency
- Revised sections in both English and Chinese README files to enhance clarity, including the quick start guide and parameter management features. - Corrected minor typographical errors, such as "tunning" to "tuning." - Improved formatting and organization of content for better readability. - Added a new section on behavior guarantees to outline key features and error handling.
1 parent ff50351 commit 6513c28

2 files changed

Lines changed: 121 additions & 65 deletions

File tree

‎README.md‎

Lines changed: 46 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -27,59 +27,56 @@ python -m hyperparameter.examples.quickstart --define greet.name=Alice --enthusi
2727

2828
# Inspect params and defaults
2929
python -m hyperparameter.examples.quickstart -lps
30-
python -m hyperparameter.examples.quickstart -ep greet.name
31-
32-
# Running from source? Use module mode or install editable
33-
# python -m hyperparameter.examples.quickstart
34-
# or: pip install -e .
35-
```
36-
37-
## Why Hyperparameter?
38-
39-
### 🚀 Unmatched Performance (vs Hydra)
40-
41-
Hyperparameter is built on a high-performance Rust backend, making it significantly faster than pure Python alternatives like Hydra, especially in inner-loop parameter access.
42-
43-
| Method | Time (1M iters) | Speedup (vs Hydra) |
44-
| :--- | :--- | :--- |
45-
| **HP: Injected (Native Speed)** | **0.0184s** | **856.73x** 🚀 |
46-
| **HP: Dynamic (Optimized)** | **2.4255s** | **6.50x** ⚡️ |
47-
| **Hydra (Baseline)** | 15.7638s | 1.00x |
48-
49-
> Benchmark scenario: Accessing a nested parameter `model.layers.0.size` 1,000,000 times in a loop.
50-
> See `benchmark/` folder for reproduction scripts.
51-
52-
### ✨ Zero-Dependency Schema Validation
53-
54-
Hyperparameter supports structural validation using standard Python type hints without introducing heavy dependencies (like Pydantic or OmegaConf).
55-
56-
```python
57-
from dataclasses import dataclass
58-
import hyperparameter as hp
59-
60-
@dataclass
61-
class AppConfig:
62-
host: str
63-
port: int
64-
debug: bool = False
65-
66-
# Validates types and converts automatically: "8080" -> 8080 (int)
67-
cfg = hp.config("config.toml", schema=AppConfig)
68-
```
69-
70-
## Key Features
30+
python -m hyperparameter.examples.quickstart -ep greet.name
31+
32+
# Running from source? Use module mode or install editable
33+
# python -m hyperparameter.examples.quickstart
34+
# or: pip install -e .
35+
```
36+
37+
## Why Hyperparameter?
38+
39+
### 🚀 Unmatched Performance (vs Hydra)
40+
41+
Hyperparameter is built on a high-performance Rust backend, making it significantly faster than pure Python alternatives like Hydra, especially in inner-loop parameter access.
42+
43+
| Method | Time (1M iters) | Speedup (vs Hydra) |
44+
| :--- | :--- | :--- |
45+
| **HP: Injected (Native Speed)** | **0.0184s** | **856.73x** 🚀 |
46+
| **HP: Dynamic (Optimized)** | **2.4255s** | **6.50x** ⚡️ |
47+
| **Hydra (Baseline)** | 15.7638s | 1.00x |
48+
49+
> Benchmark scenario: Accessing a nested parameter `model.layers.0.size` 1,000,000 times in a loop.
50+
> See `benchmark/` folder for reproduction scripts.
51+
52+
### ✨ Zero-Dependency Schema Validation
53+
54+
Hyperparameter supports structural validation using standard Python type hints without introducing heavy dependencies (like Pydantic or OmegaConf).
55+
56+
```python
57+
from dataclasses import dataclass
58+
import hyperparameter as hp
59+
60+
@dataclass
61+
class AppConfig:
62+
host: str
63+
port: int
64+
debug: bool = False
65+
66+
# Validates types and converts automatically: "8080" -> 8080 (int)
67+
cfg = hp.config("config.toml", schema=AppConfig)
68+
```
69+
70+
## Key Features
7171

7272
### For Python Users
7373

7474
- **Pythonic Syntax:** Define hyperparameters using keyword argument syntax;
75-
76-
- **Intuitive Scoping:** Control parameter scope through `with` statement;
77-
78-
- **Configuration File:** Easy to load parameters from config files (JSON/TOML/YAML) with composition and interpolation support;
79-
80-
- **Zero-Overhead Validation:** Optional schema validation using standard Python type hints;
75+
- **Intuitive Scoping:** Control parameter scope through `with` statement;
76+
- **Configuration File:** Easy to load parameters from config files (JSON/TOML/YAML) with composition and interpolation support;
77+
- **Zero-Overhead Validation:** Optional schema validation using standard Python type hints;
8178

82-
### For Rust and C++ Users
79+
### For Rust and C++ Users
8380

8481
- **High-Performance Backend:** Hyperparameter is implemented in Rust, providing a robust and high-performance backend for hyperparameter management. Access hyperparameters in Rust and C++ with minimal overhead, making it ideal for ML and system developers who prioritize performance.
8582

@@ -288,7 +285,7 @@ fn foo() {
288285

289286
## More Examples
290287

291-
### [parameter tunning for researchers](examples/sparse_lr/README.md)
288+
### [parameter tuning for researchers](examples/sparse_lr/README.md)
292289

293290
This example demonstrates how to use hyperparameter in research projects, and make experiments reproducible.
294291

‎README.zh.md‎

Lines changed: 75 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -12,27 +12,77 @@
1212
<strong>Make configurable AI applications. Build for Python/Rust hackers.</strong>
1313
</p>
1414

15-
`Hyperparameter` 是一个多功能超参数管理库，旨在简化机器学习算法和系统开发中超参数的管理和控制。专为机器学习系统（MLSYS）开发者设计，超参数提供了一个统一的解决方案，侧重于在Python中易于使用、在Rust和C++中高性能访问，并提供了一组宏，以实现无缝超参数管理。
15+
`Hyperparameter` 是一个多功能超参数管理库，旨在简化机器学习算法和系统开发中超参数的管理和控制。专为 AI 研究人员和机器学习系统（MLSYS）开发者设计，Hyperparameter 提供了一个统一的解决方案，侧重于在 Python 中易于使用、在 Rust 和 C++ 中高性能访问，并提供了一组宏以实现无缝超参数管理。
16+
17+
## 5分钟尝鲜
18+
19+
```bash
20+
pip install hyperparameter
21+
22+
# 运行现成的演示
23+
python -m hyperparameter.examples.quickstart
24+
25+
# 尝试 @hp.param CLI：从命令行覆盖默认值
26+
python -m hyperparameter.examples.quickstart --define greet.name=Alice --enthusiasm=3
27+
28+
# 检查参数和默认值
29+
python -m hyperparameter.examples.quickstart -lps
30+
python -m hyperparameter.examples.quickstart -ep greet.name
31+
32+
# 从源码运行？使用模块模式或安装为可编辑模式
33+
# python -m hyperparameter.examples.quickstart
34+
# 或者: pip install -e .
35+
```
36+
37+
## 为什么选择 Hyperparameter?
38+
39+
### 🚀 无与伦比的性能 (vs Hydra)
40+
41+
Hyperparameter 基于高性能 Rust 后端构建，使其比 Hydra 等纯 Python 替代方案快得多，特别是在内循环参数访问中。
42+
43+
| Method | Time (1M iters) | Speedup (vs Hydra) |
44+
| :--- | :--- | :--- |
45+
| **HP: Injected (Native Speed)** | **0.0184s** | **856.73x** 🚀 |
46+
| **HP: Dynamic (Optimized)** | **2.4255s** | **6.50x** ⚡️ |
47+
| **Hydra (Baseline)** | 15.7638s | 1.00x |
48+
49+
> 基准测试场景：在循环中访问嵌套参数 `model.layers.0.size` 1,000,000 次。
50+
> 参见 `benchmark/` 文件夹获取复现脚本。
51+
52+
### ✨ 零依赖 Schema 校验
53+
54+
Hyperparameter 支持使用标准 Python 类型提示进行结构校验，无需引入重型依赖（如 Pydantic 或 OmegaConf）。
55+
56+
```python
57+
from dataclasses import dataclass
58+
import hyperparameter as hp
59+
60+
@dataclass
61+
class AppConfig:
62+
host: str
63+
port: int
64+
debug: bool = False
65+
66+
# 自动校验类型并转换："8080" -> 8080 (int)
67+
cfg = hp.config("config.toml", schema=AppConfig)
68+
```
1669

1770
## 主要特性
1871

19-
### 针对Python用户
72+
### 针对 Python 用户
2073

21-
- **Pythonic语法：** 使用keyword参数语法定义超参数；
22-
23-
- **直观的作用域：** 通过`with`语句控制参数的作用域；
24-
25-
- **强大的配置加载：** 支持 JSON/TOML/YAML 多文件组合加载 (Composition) 与变量插值 (Interpolation)；
74+
- **Pythonic 语法：** 使用关键字参数语法定义超参数；
75+
- **直观的作用域：** 通过 `with` 语句控制参数的作用域；
76+
- **强大的配置加载：** 支持 JSON/TOML/YAML 多文件组合加载 (Composition) 与变量插值 (Interpolation)；
77+
- **零开销校验：** 支持可选的基于 Python Type Hints 的 Schema 校验；
2678

27-
- **零开销校验：** 支持可选的基于 Python Type Hints 的 Schema 校验；
28-
29-
### 针对Rust和C++用户
79+
### 针对 Rust 和 C++ 用户
3080

31-
- **高性能后端：** 超参数在Rust中实现，提供了强大且高性能的超参数管理后端。在Rust和C++中以最小开销访问超参数，非常适合注重性能的ML和系统开发者。
81+
- **高性能后端：** Hyperparameter 在 Rust 中实现，提供了强大且高性能的超参数管理后端。在 Rust 和 C++ 中以最小开销访问超参数，非常适合注重性能的 ML 和系统开发者。
3282

33-
- **参数管理宏：** 超参数为Rust和C++用户提供了一组宏。这些宏模仿了Python的`with`语句，并遵循特定于语言的作用域规则。
83+
- **参数管理宏：** Hyperparameter 为 Rust 和 C++ 用户提供了一组宏。这些宏模仿了 Python 的 `with` 语句，并遵循特定于语言的作用域规则。
3484

35-
- **编译时哈希：** Rust和C++接口都利用了超参数名称的编译时哈希，降低了运行时哈希计算的开销。
85+
- **编译时哈希：** Rust 和 C++ 接口都利用了超参数名称的编译时哈希，降低了运行时哈希计算的开销。
3686

3787
## 快速开始
3888

@@ -177,7 +227,7 @@ fn main() {
177227

178228
### 命令行应用
179229

180-
在命令行应用中，通常使用命令行参数（例如，`-D, --define`）定义超参数，并在命令行上控制超参数。以下是Python和Rust中的示例：
230+
在命令行应用中，通常使用命令行参数（例如，`-D, --define`）定义超参数，并在命令行上控制超参数。以下是 Python 和 Rust 中的示例：
181231

182232
#### Python
183233

@@ -235,10 +285,19 @@ fn foo() {
235285

236286
## 更多示例
237287

238-
### [parameter tunning for researchers](examples/sparse_lr/README.md)
288+
### [parameter tuning for researchers](examples/sparse_lr/README.md)
239289

240290
该示例演示了如何在研究项目中使用超参数，并使实验可重现。
241291

242292
### [experiment tracing for data scientists](examples/mnist/README.md)
243293

244-
该示例展示了使用超参数进行实验管理，并通过mlflow.tracing进行结果追踪。
294+
该示例展示了使用超参数进行实验管理，并通过 mlflow.tracing 进行结果追踪。
295+
296+
## 行为保证 (语义契约)
297+
298+
- **键与哈希 (Keys & hashing):** 键使用 `.` 进行嵌套，保留大小写，并且在 Python/Rust/C++ 中使用相同的 UTF-8 输入和种子进行哈希；非法字符将报错。
299+
- **读取优先级 (Read precedence):** 当前线程的最内层作用域 > 父作用域向外 > 冻结的全局快照 > 用户默认值。写入仅影响当前作用域，并在退出时回滚。
300+
- **默认值与缺失 (Defaults vs. missing):** 只有缺失的键才会回退到默认值；显式的 `None`/`False`/`0` 被视为存在的值。类型转换规则 (bool/int/float/str) 在各语言间保持一致；无效值使用尽力而为的转换，否则回退到提供的默认值（无静默随机值）。
301+
- **线程与 `frozen()` (Threads & `frozen()`):** 每个线程从冻结的全局快照开始；变异保持在线程内，直到调用 `frozen()`，它原子地更新全局快照。全局变异在 Python 后端受到锁保护，与 Rust 语义匹配。
302+
- **错误模型 (Error model):** 读取未定义的键且无默认值会引发键错误；后端加载失败会回退到 Python 后端，无嘈杂的回溯信息；类型错误无静默失败。
303+
- **多进程注意 (Multiprocess notice):** 跨进程一致性需要共享后端（例如，Rust 后端或用户提供的存储适配器）；内置的 Python 后端仅保护线程，不保护进程。

0 commit comments

Comments
 (0)