melog 0.1.0__py3-none-any.whl

melog/__init__.py

@@ -0,0 +1,63 @@
+"""Melog 包入口。"""
+
+from .api import (
+    StepsBar,
+    audio,
+    current,
+    current_bar,
+    error,
+    image,
+    init,
+    log,
+    scalar,
+    set_colors,
+    stepsbar,
+    success,
+    tqdm,
+    warn,
+)
+from .metrics import (
+    Accuracy,
+    AUC,
+    ConfusionMatrix,
+    Count,
+    F1,
+    Last,
+    Mean,
+    Metric,
+    MetricGroup,
+    Precision,
+    Recall,
+    Sum,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "init",
+    "current",
+    "current_bar",
+    "tqdm",
+    "StepsBar",
+    "stepsbar",
+    "scalar",
+    "log",
+    "image",
+    "audio",
+    "success",
+    "error",
+    "warn",
+    "set_colors",
+    "Metric",
+    "MetricGroup",
+    "Mean",
+    "Sum",
+    "Last",
+    "Count",
+    "Accuracy",
+    "Precision",
+    "Recall",
+    "F1",
+    "AUC",
+    "ConfusionMatrix",
+    "__version__",
+]

melog/api/__init__.py

@@ -0,0 +1,122 @@
+"""全局入口与模块级便捷接口。
+
+melog.init() 创建并激活全局共享实例（不返回）；之后项目任意位置
+直接使用本模块定义的模块级接口（melog.scalar / melog.log 等），
+无需持有实例。需要实例本身时用 melog.current() 取回。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Iterable, Optional, Union
+
+from ..core import Melog, current
+from ..metrics import MetricGroup
+from ..tracking.steps_bar import StepsBar
+from ..utils.tqdm import tqdm
+
+__all__ = [
+    "init",
+    "current",
+    "current_bar",
+    "tqdm",
+    "StepsBar",
+    "stepsbar",
+    "scalar",
+    "log",
+    "image",
+    "audio",
+    "success",
+    "error",
+    "warn",
+    "set_colors",
+]
+
+
+def init(log_dir: str = "./melog_runs", web_port: Optional[int] = None, **kwargs: Any) -> None:
+    """创建并激活全局共享的 Melog 实例（melog 的唯一公开入口）。
+
+    不返回实例：入口处调用一次后，项目任意位置直接使用模块级
+    melog.scalar() 等接口（需要实例本身时用 melog.current() 取回）。
+
+    Args:
+        log_dir: 日志保存路径（即 run 目录）：指标 / 媒体 / console.log
+            直接落在其中；重跑同一目录即断点续训（历史曲线接续，
+            重新训练的 epoch 自动覆盖上次中断的重叠数据）。
+        web_port: Web 监听端口；缺省自动选择一个空闲端口。
+        **kwargs: 其余高级参数（enable_web / enable_progress / reduce_op /
+            flush_every / max_plot_points，以及 project 覆盖项目名等）。
+
+    再次调用会用新实例替换当前活动实例。
+    """
+    log_dir = Path(log_dir)
+    kwargs.setdefault("project", log_dir.name)
+    Melog(output_dir=str(log_dir.parent), web_port=web_port, **kwargs)
+
+
+def stepsbar(
+    iterable: Iterable,
+    total: Optional[float] = None,
+    epoch: Optional[int] = None,
+    metrics: Optional[MetricGroup] = None,
+    **kwargs: Any,
+) -> StepsBar:
+    """模块级便捷接口：等价于 ``StepsBar(iterable, ...)``。"""
+    return StepsBar(iterable, total=total, epoch=epoch, metrics=metrics, **kwargs)
+
+
+def scalar(
+    metrics: Union[Dict[str, Any], MetricGroup],
+    advance: int = 0,
+) -> Dict[str, float]:
+    """模块级便捷接口：等价于 ``current().scalar(...)``。"""
+    return current().scalar(metrics, advance=advance)
+
+
+def log(*values: Any, sep: str = " ", end: str = "\n", flush: bool = False) -> None:
+    """模块级便捷接口：等价于 ``current().log(...)``。"""
+    current().log(*values, sep=sep, end=end, flush=flush)
+
+
+def success(*values: Any, sep: str = " ", end: str = "\n", flush: bool = False) -> None:
+    """模块级便捷接口：等价于 ``current().success(...)``。"""
+    current().success(*values, sep=sep, end=end, flush=flush)
+
+
+def error(*values: Any, sep: str = " ", end: str = "\n", flush: bool = False) -> None:
+    """模块级便捷接口：等价于 ``current().error(...)``。"""
+    current().error(*values, sep=sep, end=end, flush=flush)
+
+
+def warn(*values: Any, sep: str = " ", end: str = "\n", flush: bool = False) -> None:
+    """模块级便捷接口：等价于 ``current().warn(...)``。"""
+    current().warn(*values, sep=sep, end=end, flush=flush)
+
+
+def current_bar() -> Optional[tqdm]:
+    """模块级便捷接口：等价于 ``current().current_bar()``。"""
+    return current().current_bar()
+
+
+def image(
+    name: str,
+    data: Any,
+    caption: Optional[str] = None,
+) -> None:
+    """模块级便捷接口：等价于 ``current().image(...)``。"""
+    current().image(name, data, caption=caption)
+
+
+def audio(
+    name: str,
+    data: Any,
+    sr: int = 22050,
+    caption: Optional[str] = None,
+) -> None:
+    """模块级便捷接口：等价于 ``current().audio(...)``。"""
+    current().audio(name, data, sr=sr, caption=caption)
+
+
+def set_colors(colors: Dict[str, str]) -> None:
+    """模块级便捷接口：等价于 ``current().set_colors(...)``。"""
+    current().set_colors(colors)

melog/cli/__init__.py

@@ -0,0 +1,97 @@
+"""命令行入口：melog <path> 快速查看训练日志。
+
+用法：
+    melog runs/exp1/metrics-20260903_101010.melog   # 指定日志文件
+    melog runs/exp1                                 # 指定目录（合并全部会话文件）
+    melog                                           # 缺省在 ./melog_runs 中查找
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+import webbrowser
+from pathlib import Path
+
+from ..web.fs import FileBrowser
+from ..web.loader import LogLoader
+from ..web.server import WebServer
+from ..web.store import MetricStore
+
+
+def _resolve_log_file(path: Path) -> Path:
+    """文件直接用；目录取其中最新的 .melog 日志。"""
+    if path.is_file():
+        return path
+    return FileBrowser.find_latest_log(path)
+
+
+def _load_into_store(store: MetricStore, log_file: Path) -> int:
+    """把日志（同 run 目录的会话文件合并）灌入内存 store，作为静态视图数据源。"""
+    series = LogLoader.parse(log_file)
+    count = 0
+    for name, pts in series.items():
+        for step, value, epoch in pts:
+            store.add(step, {name: value}, epoch)
+            count += 1
+    return count
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="melog",
+        description="Melog 训练日志可视化：melog <.melog 日志文件或目录>",
+    )
+    parser.add_argument(
+        "path", nargs="?", default=None,
+        help=".melog 日志文件或包含它的目录；缺省时在 ./melog_runs 中查找",
+    )
+    parser.add_argument("--host", default="127.0.0.1", help="监听地址（默认 127.0.0.1）")
+    parser.add_argument("--port", type=int, default=8666, help="监听端口（默认 8666）")
+    parser.add_argument("--no-browser", action="store_true", help="不自动打开浏览器")
+    args = parser.parse_args(argv)
+
+    if args.path:
+        target = Path(args.path)
+        if not target.exists():
+            print(f"路径不存在: {target}", file=sys.stderr)
+            return 1
+    else:
+        target = Path("melog_runs")
+        if not target.exists():
+            print("未指定路径，且当前目录下没有 melog_runs/", file=sys.stderr)
+            return 1
+
+    try:
+        log_file = _resolve_log_file(target)
+    except FileNotFoundError as e:
+        print(str(e), file=sys.stderr)
+        return 1
+
+    store = MetricStore()
+    if _load_into_store(store, log_file) == 0:
+        print("文件中没有可解析的指标", file=sys.stderr)
+        return 1
+
+    server = WebServer(store, host=args.host, port=args.port, log_file=str(log_file))
+    server.start()
+
+    print(f"Melog 可视化: {server.url}")
+    print(f"日志文件: {log_file}")
+    print("Ctrl+C 退出")
+    if not args.no_browser:
+        webbrowser.open(server.url)
+
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.stop()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())