基于 InsForge BaaS 构建 ML 实验追踪器：Python CLI 与本地可视化仪表盘完整指南

基于 InsForge BaaS 构建 ML 实验追踪器：Python CLI 与本地可视化仪表盘完整指南

【免费下载链接】InsForgeThe all-in-one, open-source backend platform for agentic coding. InsForge gives your coding agent database, auth, storage, compute, hosting, and AI gateway to ship full-stack apps end-to-end.项目地址: https://gitcode.com/GitHub_Trending/in/InsForge

本篇技术指南以 InsForge 仓库中的官方示例应用 examples/python-ml-experiment-tracker/README.md 为骨架，完整讲解如何用 InsForge 的认证、数据库与 REST API 快速搭建一个机器学习实验追踪工具。读者将掌握：在本地启动 InsForge、注册登录、通过一条命令记录实验的超参数与指标、使用 CLI 查询运行记录，以及启动一个自动代理 API 请求的本地 Web 仪表盘来对比实验结果。本文同时深入示例源码，剖析其客户端封装、Token 自动刷新、错误处理与代理服务器等底层实现，帮助你把同样的 BaaS 集成模式复用到自己的项目。

一、示例定位：把后端交给 InsForge，让工具保持"薄"

这个示例项目刻意保持极简——它只是一个命令行工具 + 本地 Web 仪表盘的薄壳，真正的后端能力（认证、数据库、REST API）全部由 InsForge 承担。项目的pyproject.toml只有三个运行时依赖：

• click>=8.1：CLI 命令框架；
• httpx>=0.27：异步友好的 HTTP 客户端，用于调用 InsForge API；
• rich>=13.7：终端表格与面板美化。

安装后即可获得一个tracker命令（入口见 pyproject.toml 中[project.scripts]的声明tracker = "tracker.cli:cli"）。

整个数据模型只有两张表：experiments（实验，一组相关 run 的聚合）与runs（单次运行记录）。所有持久化都在 InsForge 管理的 PostgreSQL 中完成，CLI 和仪表盘不保存任何业务数据，只保存登录凭证。

二、前置条件与安装

开始之前需要准备：

• Python 3.10+（pyproject.toml中通过requires-python = ">=3.10"强制约束）；
• Docker，用于在本地运行 InsForge；
• 一个运行在http://localhost:7130上的 InsForge 实例。

安装工具本身只需一条命令：

# 从示例目录执行 cd examples/python-ml-experiment-tracker pip install -e .

pip install -e .会以可编辑模式安装，tracker命令随之进入 PATH，之后对源码的修改会即时生效，方便二次开发。

三、从零开始：四步完成环境初始化

步骤 1：启动 InsForge

所有tracker命令都依赖 InsForge 运行。一个典型的本地启动命令是：

docker run -p 7130:7130 insforge/insforge

注意：确切的 Docker 命令以及数据库 URL、secret key 等环境变量以 InsForge 官方文档为准。如果指向非默认实例，可以在登录时用--server覆盖，详见下文"配置与安全"一节。

步骤 2：注册账号

tracker register # 交互式提示输入邮箱和密码

对应源码位于 tracker/cli.py 的cmd_register，它调用InsForgeClient.register()，向 InsForge 的POST /api/auth/users发起请求创建用户（端点定义见 backend/src/api/routes/auth/index.routes.ts）。成功后提示运行tracker login完成认证。

步骤 3：登录

tracker login # 交互式提示输入邮箱和密码 # 凭证保存到 ~/.config/ml-tracker/config.json

登录调用POST /api/auth/sessions，返回accessToken与refreshToken两个令牌，连同server_url、user_email一起持久化到本地配置文件。

步骤 4：创建数据库表

tracker init

表创建需要 InsForge 的管理员权限，普通应用代码无法直接建表。tracker init的作用是检查experiments与runs两张表是否已存在（源码中REQUIRED_TABLES = ["experiments", "runs"]定义了检查清单）。若缺失，它会打印需要由项目管理员执行的建表 SQL。你可以打开浏览器访问http://localhost:7130进入 InsForge 仪表盘的 SQL 编辑器执行，或通过 InsForge 管理 API 提交：

CREATE TABLE IF NOT EXISTS experiments ( id UUID DEFAULT gen_random_uuid() PRIMARY KEY, name TEXT NOT NULL UNIQUE, description TEXT, created_at TIMESTAMPTZ DEFAULT now() ); CREATE TABLE IF NOT EXISTS runs ( id UUID DEFAULT gen_random_uuid() PRIMARY KEY, experiment_id UUID REFERENCES experiments(id) ON DELETE SET NULL, experiment_name TEXT NOT NULL, run_name TEXT, status TEXT DEFAULT 'completed', params JSONB DEFAULT '{}', metrics JSONB DEFAULT '{}', started_at TIMESTAMPTZ DEFAULT now(), finished_at TIMESTAMPTZ, notes TEXT, created_at TIMESTAMPTZ DEFAULT now() );

建表后再次运行tracker init，看到 "Database ready" 面板即表示表已可访问，可以开始记录实验了。

四、CLI 命令全解

tracker的命令树为：根命令register、login、init、log，以及子命令组runs list、runs get、experiments list、serve。

4.1 认证命令

# 注册新账号 tracker register # 登录（令牌保存到 ~/.config/ml-tracker/config.json） tracker login # 指向非默认的 InsForge 实例 tracker login --server http://my-insforge-host:7130

--server会持久化到配置文件，后续所有命令都使用该地址，无需重复指定。

4.2 记录运行（tracker log）

最简用法——只给实验名和指标：

tracker log -e my-model -m accuracy=0.91 -m loss=0.32

完整用法——超参数、运行标签与备注：

tracker log \ -e bert-finetune \ -r "run-lr1e-4" \ -p learning_rate=1e-4 \ -p batch_size=32 \ -p epochs=5 \ -m accuracy=0.94 \ -m f1=0.93 \ -m val_loss=0.21 \ -n "Warmup schedule, no dropout"

显式指定时间戳（ISO-8601 格式）：

tracker log \ -e nightly-sweep \ --started-at 2024-06-01T01:00:00Z \ --finished-at 2024-06-01T03:42:00Z \ -m rmse=0.045

参数说明（与 tracker/cli.py 中cmd_log的 option 定义一一对应）：

键值对类型推断是这里一个值得注意的细节。CLI 并非简单地把所有值存成字符串：parse_kv_pairs()会按true/false→ 布尔、int可解析 → 整数、float可解析 → 浮点的顺序依次尝试，最后才回落为字符串。因此-p epochs=5存入 JSONB 的是数字5，-m accuracy=0.94存入的是浮点0.94，这保证了仪表盘图表能直接对数值做数学运算。

执行tracker log的完整链路是：get_or_create_experiment()先按name=eq.<实验名>过滤查询experiments表（该查询来自 tracker/client.py 的_list_records，最终打到GET /api/database/records/experiments），不存在则插入；随后create_run()向runs表插入一条记录（POST /api/database/records/runs，携带Prefer: return=representation头以拿到完整的新行）。experiments.name上有UNIQUE约束，源码对插入时可能的唯一键冲突（HTTP 409/422 或错误信息含 "unique"）做了兜底：重试 GET 返回已存在的实验，避免并发创建时报错。

4.3 查看运行（tracker runs）

# 列出全部实验中最近 20 条运行 tracker runs list # 按实验过滤 tracker runs list -e bert-finetune # 更多结果或分页 tracker runs list --limit 50 --offset 50 # 查看某条运行的完整详情（ID 取自 list 输出） tracker runs get a1b2c3d4

runs list的默认--limit为 20、--offset为 0；它按created_at.desc排序返回，终端中用 Rich 表格渲染出 ID、实验名、运行名、状态、参数个数与指标个数。runs get按 UUID 精确过滤，找不到时抛出APIError(404, "NOT_FOUND", ...)。

4.4 查看实验（tracker experiments）

# 列出所有实验 tracker experiments list # 限制条数 tracker experiments list --limit 10

默认--limit为 50，按创建时间倒序。

4.5 检查环境（tracker init）

# 验证必需表存在且可访问 tracker init

在 tracker/cli.py 中，init的实现对两张表各发一次GET /api/database/records/{table}?limit=0，用 404 判定表是否存在——这是典型的"探测式"健康检查，不需要任何管理权限即可执行。

五、本地 Web 仪表盘

仪表盘让你不用离开机器就能可视化运行结果、对比多次实验：

# 启动仪表盘（自动打开浏览器） tracker serve # 自定义端口 tracker serve --port 9000 # 跳过自动打开浏览器 tracker serve --no-browser

• 默认监听http://127.0.0.1:8765；
• 将/api/*请求原样代理到 InsForge，并自动附加Authorization: Bearer <accessToken>头；
• 自动处理 Token 刷新：上游返回 401 时，代理会用 refresh token 调POST /api/auth/sessions换新令牌并回写配置文件，再重放原请求；
• 用Ctrl+C停止。

重要：启动仪表盘前必须先tracker login，否则所有 API 请求都会返回认证错误。serve命令在未登录时也会启动，但会在终端打出黄色警告面板，仪表盘页面顶部会显示 "Not logged in" 的提示横幅。

仪表盘功能点

仪表盘前端是单文件 tracker/static/index.html，通过同源代理调用/api/database/records/runs?limit=100&order=created_at.desc与/api/database/records/experiments?limit=50&order=created_at.desc拉取数据，提供：

• 运行总览表：实验名、运行名、状态徽章（completed绿色 /running蓝色 /failed红色）、参数与指标摘要、开始时间；数值指标统一保留 4 位小数展示；
• 实验筛选器：按实验名下钻，URL 不变、纯前端过滤；
• 指标折线图：选中某个实验且至少有 2 条同时含accuracy与loss的运行记录时，用 Chart.js 绘制双 Y 轴折线图——accuracy 在左轴（蓝色），loss 在右轴（红色），X 轴标签取运行名（无则用 UUID 前 8 位）；
• 自动刷新：默认每 30 秒轮询一次，可手动关闭。

六、配置与安全机制

配置文件

CLI 的配置存放在~/.config/ml-tracker/config.json，由 tracker/config.py 管理，结构如下：

{ "server_url": "http://localhost:7130", "access_token": "...", "refresh_token": "...", "user_email": "you@example.com" }

• 默认服务器地址为http://localhost:7130；
• 登录时可用--server覆盖并持久化；
• 写入使用原子写：先写临时文件再replace，并以0o600权限保护令牌数据（save_config中os.open(..., 0o600)），避免其他用户读取凭证。

令牌生命周期

客户端 tracker/client.py 中的_request封装了完整生命周期：所有请求自动附加 Bearer 令牌；当收到 401 时，_refresh_token()用 refresh token 调POST /api/auth/sessions换新，成功后通过update_tokens()写回磁盘并自动重放一次原请求；若 refresh 也失败，则clear_tokens()清空本地令牌并提示重新登录。仪表盘代理在 tracker/serve.py 中实现了同样的逻辑，并用线程锁保证并发请求下只触发一次刷新。

错误处理约定

handle_errors装饰器把异常统一翻译为 stderr 上的 Rich 红色面板并以退出码 1 结束：AuthError提示登录、APIError显示 HTTP 状态码与错误信息、httpx.ConnectError提示 "Is InsForge running at <server_url>?"、超时与网络错误各有对应文案。这让命令行工具在任何失败场景下都有明确的用户反馈。

七、底层 API 集成模式速览

这个示例本质上是 InsForge BaaS 三大能力的集成样板，源码路径均可直接查阅：

可复用的集成要点：令牌双 Token + 401 自动刷新重放、records API 的 PostgREST 风格过滤语法（eq.前缀与order=col.desc）、以及Prefer: return=representation头在插入后直接拿回整行数据——这三种模式足以支撑大部分"CLI/脚本 + InsForge 后端"的工具类项目。

八、常见问题排查

• Connection refused. Is InsForge running at ...?：InsForge 未启动，或--server指向的地址/端口不对，检查 Docker 容器状态。
• Auth error: Not logged in. Run tracker login first.：配置文件缺失或令牌被清空，重新tracker login。
• Session expired. Run tracker login again.：refresh token 已失效（例如服务端轮换了密钥），需要重新登录获取新令牌。
• 仪表盘显示 "Cannot reach the local proxy server"：tracker serve进程已退出，重新启动即可。
• 仪表盘显示 502 "Cannot connect to InsForge"：代理能连但上游 InsForge 不可达，确认 InsForge 容器仍在运行。
• tracker init提示 Missing tables：执行文中建表 SQL（需管理员权限），再次运行tracker init验证。

结语

从 examples/python-ml-experiment-tracker/README.md 这份示例可以看出，借助 InsForge 的认证、数据库与 REST API，一个功能完整的 ML 实验追踪工具只需少量 Python 代码即可落地：CLI 负责记录与查询，本地代理仪表盘负责可视化对比，认证、存储与并发全部交由 BaaS 处理。无论你是想复刻这套工具，还是学习把 InsForge 集成进自己的 Python 项目，本文覆盖的命令、SQL、配置与源码路径都能作为直接起点。

【免费下载链接】InsForgeThe all-in-one, open-source backend platform for agentic coding. InsForge gives your coding agent database, auth, storage, compute, hosting, and AI gateway to ship full-stack apps end-to-end.项目地址: https://gitcode.com/GitHub_Trending/in/InsForge